Geometry#

Detector indices are physical slots from the geometry file. They are not ordinal positions among active detectors, and slots may be sparse.

Load Geometry#

lauelab.indexing.load_geometry(path)[source]#

Load detector geometry for reuse.

Parameters:

path (str | Path) – Path to a Laue geometry XML file.

Returns:

Geometry – Parsed detector geometry backed by native state.

Raises:

  • ValueError – If the detector geometry is invalid.

  • ImportError – If the native liblaue library is unavailable.

Return type:

Geometry

Parsed Geometry#

class lauelab.indexing.Geometry(path)[source]#

Parsed detector geometry retained for repeated in-process conversion.

Parameters:

path (str | Path) – Path to a Laue geometry XML file. Only detector geometry is loaded by this public interface.

Raises:

  • ValueError – If the detector declarations are malformed, incomplete, duplicated, or contain invalid dimensions or physical parameters.

  • ImportError – If the native liblaue library is unavailable.

Notes

Detector indices are physical slots from the geometry file, not ordinal positions among active detectors. Slots may therefore be sparse.

property detector_count: int#

Number of active detectors in the geometry.

property wire: WireGeometry | None#

Wire geometry, or None when the file has no wire section.

find_detector(detector_id)[source]#

Find the physical slot for a detector identifier.

Parameters:

detector_id (str) – Exact detector identifier from the geometry file.

Returns:

int – Physical detector slot, or -1 if the identifier is absent.

Return type:

int

detector(detector_index=0)[source]#

Return metadata for an active detector slot.

Parameters:

detector_index (int) – Physical detector slot from the geometry file.

Returns:

DetectorGeometry – Validated detector dimensions and identity.

Raises:

ValueError – If the slot is outside the supported range or is inactive.

Return type:

DetectorGeometry

pixels_to_q(peaks, *, detector_index=0, start=(0, 0), group=(1, 1), depth=None)[source]#

Convert peak coordinates to unit scattering vectors.

Parameters:

  • peaks (numpy.ndarray) – Array-like peak coordinates with shape (n, 2). Columns are zero-based (x, y) coordinates in the supplied frame.

  • detector_index (int) – Physical detector slot from the geometry file.

  • start (tuple[int, int]) – Zero-based detector (x, y) origin of the frame.

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

  • depth (float | None) – Optional finite sample depth in micrometres passed to the geometry calculation.

Returns:

numpy.ndarray – Unit scattering vectors with shape (n, 3) and float64 dtype.

Raises:

  • ValueError – If coordinates, region parameters, depth, or detector selection are invalid.

  • RuntimeError – If native pixel-to-q conversion fails.

Return type:

numpy.ndarray

Notes

Grouped coordinates are mapped to the center of the corresponding detector-pixel group before bounds validation and conversion.

class lauelab.indexing.DetectorGeometry(nx, ny, size_x, size_y, detector_id, translation, rotation_vector, rotation)[source]#

Validated metadata for one detector in a geometry file.

Parameters:

  • nx (int) – Detector dimensions in unbinned pixels.

  • ny (int) – Detector dimensions in unbinned pixels.

  • size_x (float) – Detector dimensions in micrometres.

  • size_y (float) – Detector dimensions in micrometres.

  • detector_id (str) – Detector identifier stored in the geometry file.

  • translation (numpy.ndarray) – Detector-frame translation vector in micrometres.

  • rotation_vector (numpy.ndarray) – Axis-angle rotation vector in radians.

  • rotation (numpy.ndarray) – Rotation matrix from detector coordinates to beamline coordinates.

Notes

Instances are returned by Geometry.detector(). Detector slots may be sparse, so a detector’s physical slot cannot be inferred from Geometry.detector_count.

pixel_to_lab(pixels)[source]#

Convert full-detector pixels to beamline coordinates.

Parameters:

pixels (numpy.ndarray) – Zero-based pixel coordinates with shape (..., 2) in (x, y) order.

Returns:

numpy.ndarray – Beamline coordinates in micrometres with shape (..., 3).

Return type:

numpy.ndarray

q_to_pixel(q, *, depth=None, on_detector=False)[source]#

Project reciprocal-space vectors onto this detector.

Invalid rays and, when requested, off-detector intersections are returned as NaN coordinates.

Parameters:

  • q (numpy.ndarray) – Reciprocal-space vectors with shape (..., 3).

  • depth (float | None) – Sample depth in micrometres. None places the source at the beamline origin.

  • on_detector (bool) – Replace intersections outside the detector with NaN.

Returns:

numpy.ndarray – Zero-based full-detector (x, y) coordinates with shape (..., 2).

Return type:

numpy.ndarray

class lauelab.indexing.WireGeometry(diameter_um, F_um, origin_um, axis, axis_rotated, rotation, rotation_magnitude_deg)[source]#

Wire geometry in micrometres and beamline rotation conventions.

Geometry.detector() returns an immutable metadata record containing the selected detector’s pixel dimensions, physical dimensions, pose, and identifier. Physical dimensions and translation use micrometres. The axis-angle rotation vector uses radians.

Geometry.wire returns immutable wire metadata when the geometry file contains a complete wire section, or None otherwise. Diameter, F, and origin use micrometres; the rotation magnitude uses degrees.