Processing#

The preferred API either indexes one frame with index_frame or reuses an Indexer across frames that share configuration.

One-Off Indexing#

lauelab.indexing.index_frame(frame, *, geometry, crystal=None, peak_params=None, index_params=None, detector_index=0, detector_id=None, cosmic_filter=False, start=(0, 0), group=(1, 1), depth=None, mask=None, metadata=None, keep_image=True)[source]#

Index one frame with a temporary Indexer.

Parameters:

  • frame (np.ndarray | str | Path) – Two-dimensional uint16 NumPy array or path to a supported HDF5 frame.

  • geometry (str | Path | Geometry) – Parsed detector geometry or path to a geometry XML file.

  • crystal (str | Path | Crystal | None) – Crystal description or crystal XML path. If None, peak search and pixel-to-q conversion run without orientation indexing.

  • peak_params (PeakParams | None) – Peak-search configuration. Defaults to PeakParams.

  • index_params (IndexParams | None) – Orientation-indexing configuration. Defaults to IndexParams.

  • detector_index (int) – Physical detector slot in the geometry. This is not the ordinal position among active detectors.

  • detector_id (str | None) – Detector identifier to select instead of detector_index.

  • cosmic_filter (bool) – Value recorded in XML output for cosmic-ray filtering provenance. This option does not apply an additional Python-side filter.

  • start (tuple[int, int]) – Full-detector ROI origin and pixel grouping in (x, y) order.

  • group (tuple[int, int]) – Full-detector ROI origin and pixel grouping in (x, y) order.

  • depth (float | None) – Sample depth in micrometres, or None for the beamline origin.

  • mask (np.ndarray | None) – Optional mask matching the frame shape. Nonzero pixels are excluded.

  • metadata (FrameMetadata | Mapping[str, object] | None) – Optional frame metadata object or mapping.

  • keep_image (bool) – Retain the contiguous input image in the returned result.

Returns:

FrameResult – A self-contained frame result. The input image is retained by default.

Raises:

  • InputError – If configuration, detector selection, or frame input is invalid.

  • MemoryError – If a native stage cannot allocate required memory.

  • IndexingError – If a native numerical or internal indexing stage fails.

Return type:

FrameResult

Notes

Construct Indexer directly when processing multiple frames so parsed geometry and crystal state can be reused.

Reusable Indexer#

class lauelab.indexing.Indexer(geometry, crystal=None, *, peak_params=None, index_params=None, detector_index=0, detector_id=None, cosmic_filter=False)[source]#

Reusable in-process Laue frame indexer.

Peak search, pixel-to-q conversion, and crystal indexing run through the native library without subprocesses or per-frame intermediate text files.

Parameters:

  • geometry (str | Path | Geometry) – Parsed detector geometry or path to a geometry XML file.

  • crystal (str | Path | Crystal | None) – Crystal description or crystal XML path. If None, frames are peak searched and converted to q space without orientation indexing.

  • peak_params (PeakParams | None) – Peak-search configuration. Defaults to PeakParams.

  • index_params (IndexParams | None) – Orientation-indexing configuration. Defaults to IndexParams.

  • detector_index (int) – Physical detector slot in the geometry. This is not the ordinal position among active detectors.

  • detector_id (str | None) – Detector identifier to select instead of detector_index.

  • cosmic_filter (bool) – Value recorded in XML output for cosmic-ray filtering provenance. This option does not apply an additional Python-side filter.

Raises:

  • InputError – If parameters or detector selection are invalid.

  • ValueError – If a geometry or crystal description is invalid.

  • ImportError – If the native indexing library is unavailable.

Notes

Reuse one instance for frames that share geometry, crystal, detector, and processing parameters. Calls to index() on one instance are safe from concurrent Python threads. Each call owns its result storage, and native diagnostic output uses thread-local state.

Use replace() to create a separately validated instance with changed configuration.

index(frame, *, start=(0, 0), group=(1, 1), depth=None, mask=None, metadata=None, keep_image=True)[source]#

Process one NumPy frame or HDF5 file without subprocesses.

Parameters:

  • frame (np.ndarray | str | Path) – Two-dimensional uint16 NumPy array or path to a supported HDF5 frame.

  • start (tuple[int, int]) – Zero-based detector (x, y) origin for an in-memory frame.

  • group (tuple[int, int]) – Positive detector-pixel grouping factors as (x, y).

  • depth (float | None) – Optional finite sample depth in micrometres passed to pixel-to-q conversion.

  • mask (np.ndarray | None) – Array with the same shape as frame. Values are converted to a boolean uint8 mask and passed to native peak search, where nonzero pixels are masked.

  • metadata (FrameMetadata | Mapping[str, object] | None) – Experiment metadata for XML output. Explicit values override metadata loaded from an HDF5 file.

  • keep_image (bool) – Retain the contiguous input image in the returned result’s image attribute.

Returns:

FrameResult – A self-contained result whose native backing allocations have already been released.

Raises:

  • InputError – If the frame, region, mask, metadata, or selected detector is invalid.

  • KeyError – If a required HDF5 image dataset is missing.

  • OSError – If an HDF5 input file cannot be opened.

  • MemoryError – If a native stage cannot allocate required memory.

  • IndexingError – If a native numerical or internal stage fails.

Return type:

FrameResult

Notes

For HDF5 input, detector start and group values from the file take precedence over method arguments when present. A retained image can alias a contiguous array supplied by the caller. Native peak search uses a separate working copy, so smoothing does not modify that array.

Frame statistics exclude masked pixels and always describe the raw input image. Smoothing applies only to peak detection and fitting. Under automatic thresholding, a frame with no unmasked nonzero pixels returns a valid empty result with threshold_used set to NaN.

Native code can write diagnostics to stdout or stderr before Python raises an exception.

index_many(frames, *, keep_images=False)[source]#

Index frames in order while reusing parsed configuration.

Parameters:

  • frames (Iterable[np.ndarray | str | Path]) – Iterable of two-dimensional uint16 arrays or supported HDF5 paths.

  • keep_images (bool) – Retain each input image in its result. Defaults to False to limit batch memory use.

Returns:

list[FrameResult] – Results in the same order as the input iterable.

Raises:

  • InputError – If a frame or its metadata is invalid.

  • MemoryError – If a native stage cannot allocate required memory.

  • IndexingError – If a native numerical or internal stage fails.

Return type:

list[FrameResult]

Notes

Frames are processed sequentially. Processing stops on the first exception.

replace(**changes)[source]#

Create an indexer with selected configuration values replaced.

Parameters:

**changes – Constructor arguments to replace. Supported names are geometry, crystal, peak_params, index_params, detector_index, detector_id, and cosmic_filter.

Returns:

Indexer – A new, independently validated indexer.

Raises:

  • TypeError – If an unknown constructor argument is supplied.

  • InputError – If replacement parameters or detector selection are invalid.

Return type:

Indexer

Notes

Native geometry and crystal state is constructed for the new instance; it is not shared with the original indexer.

write_many_xml(results, path)[source]#

Write multiple results to one LaueGo XML document.

Parameters:

  • results (Iterable[FrameResult]) – Frame results written in iteration order.

  • path (str | Path) – Destination XML file. An existing file is replaced.

Raises:

  • RuntimeError – If any result has no XML snapshot.

  • OSError – If the destination cannot be written.