Detector Pixel Units#

MoDaCor treats detector pixels as dimensionless detector-coordinate units. Pint’s built-in pixel, pixels, px, and related display/CSS pixel definitions are removed from the application unit registry during startup, then redefined as aliases of a named dimensionless detector pixel unit.

Rationale#

Detector element coordinates are array indices. Treating them as Pint units made metadata hard to reason about because values such as detector pitch became mm/pixel even though the stored number is simply a physical length of one detector element. The old model also leaked into signal units such as count/px, which mixed detector sampling with physical dimensional analysis.

The current contract keeps unit handling physical:

  • detector element indices and beam-center coordinates are dimensionless,

  • unit strings such as pixel, pixels, px, css_pixel, dot, pel, and picture_element are accepted as detector-coordinate aliases,

  • detector element sizes are lengths, for example m, mm, or um,

  • solid angle outputs are sr,

  • masks, index maps, and names such as pixel_index remain detector-element concepts and may use either dimensionless or a pixel alias.

This deliberately replaces Pint’s display/CSS interpretation of pixel-like unit names. In MoDaCor, px does not mean a CSS length.

Migration#

The preferred metadata style is still to store physical quantities in physical units and detector indices as dimensionless values:

Old unit string

New unit string

mm/pixel

mm

m/pixel

m

count/px

count

counts/pixel/second

counts/second

The numeric values do not change for detector pitch or detector element size. For example, a stored pitch value of 0.172 with old units mm/pixel becomes the same value 0.172 with units mm.

For compatibility with existing metadata, pixel denominators are also accepted and cancel as dimensionless factors:

  • 0.172 mm/pixel converts to 0.172 mm,

  • 5 count/px converts to 5 count,

  • 10 counts/pixel/second converts to 10 counts/second.

BaseData.is_dimensionless checks Pint compatibility rather than exact unit equality, so a BaseData stored with pixel units is considered dimensionless. Calling BaseData.to_dimensionless() normalizes compatible named units such as pixel to Pint’s plain dimensionless unit without changing the numerical values or uncertainties.

External pipeline repositories should prefer updating SAXSess and MOUSE-style metadata sources to plain length units for detector pitch, but stale mm/pixel-style metadata remains parseable.