Geometry#

class cdiutils.Geometry(sample_circles=None, detector_circles=None, detector_axis0_orientation=None, detector_axis1_orientation=None, beam_direction=None, sample_surface_normal=None, name=None, is_cxi=True)[source]#

Bases: object

Beamline diffractometer geometry configuration.

Defines coordinate system conventions, motor circle orientations, and detector pixel directions for BCDI experiments. Critical for accurate coordinate transformations between detector, laboratory, and reciprocal space frames.

The CXI convention is used by default:

  • Xcxi: outboard direction (perpendicular to beam)

  • Ycxi: vertical (pointing up)

  • Zcxi: along beam (away from source)

  • data storage follows (Zcxi, Ycxi, Xcxi) ordering.

The XU (xrayutilities) convention can also be used:

  • Xxu: along beam (away from source)

  • Yxu: outboard direction (perpendicular to beam)

  • Zxu: vertical (pointing up)

  • data storage follows (Xxu, Yxu, Zxu) ordering.

sample_circles#

Sample rotation axes as list of two CXI directions (e.g., ["x-", "y-"] for eta, phi at ID01).

detector_circles#

Detector rotation axes as list of two CXI directions.

detector_axis0_orientation#

CXI direction for detector’s first pixel axis (rows).

detector_axis1_orientation#

CXI direction for detector’s second pixel axis (columns).

beam_direction#

Beam propagation direction as 3-element list in CXI frame. Always [1, 0, 0] (along Zcxi).

sample_surface_normal#

Normal vector to sample surface. [0, 1, 0] for horizontal mounting (surface up), [0, 0, -1] for vertical (ID01 style).

name#

Beamline identifier (e.g., “ID01”, “P10”).

is_cxi#

If True, geometry uses CXI convention. If False, uses xrayutilities (XU) convention.

See also

SpaceConverter: Uses Geometry for coordinate transformations. Coordinate Systems and Transformations: Detailed explanation of CXI/XU conventions.

Attributes

Methods

__init__(sample_circles=None, detector_circles=None, detector_axis0_orientation=None, detector_axis1_orientation=None, beam_direction=None, sample_surface_normal=None, name=None, is_cxi=True)[source]#

Initialise geometry configuration.

Parameters:

  • sample_circles (list | None) – List of sample rotation axes as CXI directions. Defaults to ["x-", "y-"].

  • detector_circles (list | None) – List of detector rotation axes as CXI directions. Defaults to ["y-", "x-"].

  • detector_axis0_orientation (str | None) – CXI direction for detector pixel axis 0. Defaults to "y-".

  • detector_axis1_orientation (str | None) – CXI direction for detector pixel axis 1. Defaults to "x+".

  • beam_direction (list | None) – Beam propagation vector in CXI frame. Defaults to [1, 0, 0].

  • sample_surface_normal (list | None) – Normal vector to sample surface. Defaults to [0, 1, 0] (horizontal mounting).

  • name (str | None) – Beamline name. Defaults to None.

  • is_cxi (bool) – If True, uses CXI convention. If False, uses XU convention. Defaults to True.

to_dict()[source]#

Serialise geometry configuration to dictionary.

Returns:

Dictionary containing all geometry attributes.

Return type:

dict

classmethod from_dict(data)[source]#

Create geometry instance from dictionary.

Parameters:

data (dict) – Dictionary with geometry parameters.

Returns:

New Geometry instance.

Return type:

Geometry

classmethod from_setup(beamline=None, beamline_setup=None, sample_orientation=None, sample_surface_normal=None)[source]#

Create geometry from beamline name.

Factory method providing pre-configured geometries for supported beamlines. Automatically sets correct motor orientations and detector pixel directions.

Parameters:

  • beamline (str | None) –

    Beamline identifier (case-insensitive). Supported values:

    • "ID01", "ID01SPEC", "ID01BLISS": ESRF ID01

    • "P10", "P10EH2": PETRA III P10

    • "SIXS2019", "SIXS2022": SOLEIL SIXS (specify year)

    • "NanoMAX": MAX IV NanoMAX

    • "CRISTAL": SOLEIL CRISTAL

    • "ID27": ESRF ID27

  • beamline_setup (str | None) – Deprecated. Use beamline instead.

  • sample_orientation (str | None) –

    Sample mounting style:

    • "horizontal" or "h": surface normal pointing up (default)

    • "vertical" or "v": surface normal along beam (ID01 style)

  • sample_surface_normal (list | None) – Explicit surface normal vector. Overrides sample_orientation if provided.

Returns:

Configured Geometry instance for the beamline.

Raises:

  • ValueError – If beamline not provided.

  • NotImplementedError – If beamline not supported.

Return type:

Geometry

Examples

>>> geometry = Geometry.from_setup(beamline="id01")
>>> geometry.sample_orientation
'horizontal'

>>> geometry = Geometry.from_setup(
...     beamline="id01",
...     sample_orientation="vertical"
... )
property sample_orientation: str | None#

‘horizontal’ or ‘vertical’.

The sample is considered: - ‘horizontal’ when its surface normal is along the -Ycxi or Ycxi, i.e. pointing up/down. - ‘vertical’ when its surface normal is along the -Xcxi or Xcxi.

Type:

Returns the sample mounting orientation

cxi_to_xu()[source]#

Convert CXI convention to XU convention in-place.

Transforms all coordinate system attributes (sample circles, detector circles, orientations) from CXI to xrayutilities convention. Sets is_cxi to False after conversion.

Note

This is automatically called by SpaceConverter during initialisation if needed. Users rarely call this directly.

static swap_convention(data)[source]#

Swap CXI and XU coordinate conventions.

Swaps the last two axes to convert between conventions:

  • CXI ordering: (Zcxi, Ycxi, Xcxi)

  • XU ordering: (Xxu, Yxu, Zxu)

Physical correspondence:

  • Zcxi = Xxu: beam direction (away from source)

  • Ycxi = Zxu: vertical (pointing up)

  • Xcxi = Yxu: outboard (perpendicular to beam)

Both are right-handed. The beam direction (axis 0) requires no swapping as [1,0,0] is identical in both conventions.

Parameters:

data (ndarray | list | tuple) – Array, list, or tuple to swap. Can be a 3-element vector or a 3D array.

Returns:

Data with swapped convention. Type matches input.

Raises:

TypeError – If data is not a 3D array, list, or tuple.

Return type:

ndarray | list | tuple

Example

>>> # convert amplitude array from CXI to XU
>>> amplitude_xu = Geometry.swap_convention(amplitude_cxi)
>>> # convert vector [Zcxi, Ycxi, Xcxi] to [Xxu, Yxu, Zxu]
>>> vec_xu = Geometry.swap_convention([1.0, 2.0, 3.0])
>>> vec_xu
[1.0, 3.0, 2.0]

See Also#

SpaceConverter : Coordinate transformations using Geometry BcdiPipeline : Full pipeline using Geometry configuration