pyM301 - Python M301 Fingerprint Capture Library

pyM301 is a Python library for working with the Lumidigm M301 USB desktop fingerprint reader. It reproduces the capture flow exposed by the original utilities so you can script composite preview images and ANSI-378 templates without reverse engineering the HID SDK.

Device Reference

• Lumidigm M-Series product page: https://www.hidglobal.com/products/lumidigm-m-series-usb-desktop-readers
• Tested against the M301 variant using PyUSB for device access

Capabilities

• M301Scanner class wraps discovery, capture, and status polling via PyUSB
• CLI (pym301) mirrors the hardware workflow for capturing composite images and templates
• PNG encoding stays within the Python standard library and preserves the nominal 500-DPI metadata
• Conversion helpers operate on saved capture buffers for offline analysis

Installation

python -m pip install .

The library targets Python 3.7+ and depends on pyusb. On Linux you may need udev rules so the current user can access the USB device.

To work on the project locally:

python -m pip install -e .[dev]

Command Line Usage

The bridge script python pym301.py -v -d capture connects to the scanner, captures both artefacts, and—when neither --composite-out nor --template-out is provided—stores them as fingerprint.png (or fingerprint.raw when --composite-format raw is selected) and template.bin in the current directory.

Explicit output paths override the defaults:

pym301 capture --artefact both --composite-out preview.png --template-out enrolment.bin

Add --composite-format raw to keep the unprocessed byte payload instead of writing a PNG preview.

When the NFIQ2 CLI is installed and visible on PATH, pym301 capture automatically computes the quality score and actionable metrics for any captured composite preview. Provide a custom executable via --with-nfiq2=/path/to/nfiq2, or opt out entirely with --without-nfiq2. Add -v/--verbose if you want the full CSV column dump in addition to the human-readable summary.

Available subcommands:

• capture: Acquire a composite preview, ANSI-378 template, or both
• status: Poll the scanner status for a fixed window
• convert: Turn a saved capture buffer into a PNG preview for offline analysis
• nfiq translate <png>: Run the NFIQ2 CLI on a saved image and print the interpreted metrics

Run pym301 <subcommand> --help for the complete option list.

Library Examples

Assemble a configuration command

>>> from pym301 import build_set_config, ConfigParams
>>> command = build_set_config(
...     ConfigParams.DEFAULT_ROI_WIDTH,
...     ConfigParams.DEFAULT_ROI_HEIGHT,
...     ConfigParams.DEFAULT_OUTPUT_WIDTH,
...     ConfigParams.DEFAULT_OUTPUT_HEIGHT,
...     ConfigParams.DEFAULT_IMAGE_MODE,
... )
>>> len(command)
82
>>> command[:3]
b'\rVM'

Encode a PNG preview offline

>>> from pym301.images import encode_png
>>> width, height = 2, 2
>>> pixels = bytes([0, 255, 255, 0])
>>> png_bytes = encode_png(pixels, width=width, height=height)
>>> png_bytes[:8]
b'\x89PNG\r\n\x1a\n'
>>> start = png_bytes.index(b'pHYs') + 4
>>> import struct
>>> struct.unpack('>IIB', png_bytes[start:start + 9])
(19685, 19685, 1)

Full hardware capture (requires an attached M301)

>>> from pathlib import Path  # doctest: +SKIP
>>> from pym301 import M301Scanner  # doctest: +SKIP
>>> scanner = M301Scanner(verbose=True)  # doctest: +SKIP
>>> if scanner.connect():  # doctest: +SKIP
...     try:
...         scanner.initialize()
...         image, template, dims = scanner.perform_capture("both")
...         if image and dims:
...             scanner.write_png("preview.png", image, *dims)
...         if template:
...             Path("template.bin").write_bytes(template)
...     finally:
...         scanner.disconnect()

For offline work, the pym301.images.convert_capture helper turns raw capture buffers into PNG previews without touching the hardware.

Development

• Run the unit tests with python -m pytest
• Formatting and import settings follow the project configuration in pyproject.toml
• Set PYM301_WITH_HARDWARE=1 and run python -m pytest -m hardware to exercise the optional hardware integration doctest

Governance

Contributions are covered by the Bounded Contribution Policy. Changes are licensed under the MIT License.