Indexing pipeline

Indexing converts intensity measurements on a detector into one or more candidate crystal orientations. lauelab performs this work in three stages and returns their outputs together in a FrameResult.

Inputs and outputs

A complete orientation-indexing call needs:

• A two-dimensional numpy.uint16 detector frame

• A geometry that maps detector pixels into the 34-ID-E laboratory frame

• A crystal description with a unit cell and space group

• Peak-search and indexing parameters, or their defaults

The frame can be an in-memory NumPy array or a supported 34-ID-E HDF5 file. You can omit the crystal to run only peak search and pixel-to-q conversion.

The result contains fitted peaks, frame statistics, and any indexed patterns. It also records the frame shape, detector region, grouping, depth, metadata, and elapsed times needed to interpret the processing call.

Peak search

Peak search starts from detector intensities. It detects candidate regions, fits each accepted peak, and returns subpixel positions and fit measurements. The configurable inputs control the intensity threshold, fit region, accepted size and residual, separation, peak model, smoothing, and maximum count.

An absolute threshold is used by default. Set PeakParams.threshold to None to derive a threshold from frame statistics and threshold_ratio.

Peak coordinates are zero-based (x, y) values in the supplied frame. A NumPy image uses [y, x] indexing, so image[y, x] addresses the pixel at coordinate (x, y).

See Peak search for stage details and Parameters for configuration.

Pixel-to-q conversion

The geometry stage maps each fitted frame coordinate to its full-detector position. It applies the frame’s start and group, then uses the selected detector geometry to calculate a unit scattering vector named qhat.

A geometry can contain more than one detector. The selected index identifies a physical detector slot in the geometry file, not its ordinal position among active detectors.

The returned qhat values use the 34-ID-E laboratory convention implemented by the geometry conversion. See Pixel-to-q conversion for the transformation and the limits of the currently verified coordinate description.

Crystal indexing

When you supply a crystal and the frame contains at least two peaks, the orientation indexer compares the measured scattering-vector directions with reflections calculated from the crystal description. It can return zero, one, or multiple candidate patterns.

Each Pattern contains an orientation, reciprocal-lattice information, assigned Miller indices, and zero-based indices back into the frame’s peak array. No returned pattern is a valid outcome, not an exception.

See Crystal indexing for supported algorithm details.

In-process execution

The preferred API calls the native library in the Python process. It does not start a subprocess or create intermediate peak, pixel-to-q, and indexing text files.

Detector frame
    |
    v
Peak search
    |
    v
Pixel-to-q conversion <--- Detector geometry
    |
    v
Crystal indexing <--------- Crystal description
    |
    v
FrameResult --------------> LaueGo XML (explicit export)

Native memory is released before FrameResult is returned. Peak and pattern data are copied into NumPy arrays owned by Python.

One frame or many

Use index_frame() for a one-off call. It creates a temporary Indexer and retains the image by default.

Use Indexer when frames share configuration. Indexer.index() processes one frame. Indexer.index_many() processes an iterable sequentially, preserves order, and does not retain images by default.

Failure model

The in-process API distinguishes three failure classes:

• InputError reports invalid configuration, detector selection, frame data, or metadata.

• MemoryError reports a native allocation failure.

• IndexingError reports a native numerical or internal failure.

A frame with no peaks or no indexed patterns is a successful result. Check n_peaks, n_patterns, and indexed instead of treating an empty result as an exception.