Area detector¶

The AreaDetector interfaces with the Axis Photonique 2-D detector via BCSz. ExposureQuality reports over/under-exposure from check_exposure.

class resonance.api.core.det.ExposureQuality(overexposed: bool, underexposed: bool, suggested_exposure_seconds: float | None)[source]¶

Bases: object

Quality assessment of a single detector exposure.

overexposed¶

True when the number of saturated pixels exceeds the configured threshold.

Type:: bool

underexposed¶

True when the number of dark pixels exceeds the configured threshold.

Type:: bool

suggested_exposure_seconds¶

Recommended exposure time, or None when no suggestion is available.

Type:: float or None

class resonance.api.core.det.AreaDetector(conn: BCSz.BCSServer, *, name: str = 'Axis Photonique')[source]¶

Bases: object

Interface to the Axis Photonique 2-D area detector via BCSz.

Parameters:

conn (BCSz.BCSServer) – Active BCSz server connection.
name (str, optional) – Instrument name registered in BCSz, defaults to Axis Photonique.

Examples

>>> image = await bl.detector.acquire(exposure_seconds=0.1)
>>> print(image.shape)
(1024, 1024)
>>> quality = bl.detector.check_exposure(image)
>>> print(quality)
ExposureQuality(overexposed=False, underexposed=False, suggested_exposure_seconds=None)
>>> descriptor = bl.detector.describe()
>>> print(descriptor)
{'dtype': 'int32', 'source': 'detector', 'external': True, 'shape': [1024, 1024]}

async acquire(exposure_seconds: float) → ndarray | None[source]¶

Trigger an exposure and return the acquired image.

Parameters:: exposure_seconds (float) – Integration time in seconds.
Returns:: 2-D int32 array of shape (height, width), or None if the acquisition reported failure.
Return type:: np.ndarray or None

Notes

The shutter is detector-driven; no plan-level shutter wrapping is required around this call.

check_exposure(image: ndarray, *, over_threshold: int = 200000, over_pixel_count: int = 500, under_threshold: int = 50, under_pixel_count: int = 950000) → ExposureQuality[source]¶

Assess whether an image is over- or under-exposed.

Parameters:

image (np.ndarray) – 2-D detector image.
over_threshold (int, optional) – Pixel value above which a pixel is considered saturated.
over_pixel_count (int, optional) – Minimum number of saturated pixels required to flag overexposure.
under_threshold (int, optional) – Pixel value below which a pixel is considered dark.
under_pixel_count (int, optional) – Minimum number of dark pixels required to flag underexposure.

Returns:

Dataclass with overexposed, underexposed, and suggested_exposure_seconds fields.

Return type:

ExposureQuality

Notes

The pixel-count heuristic mirrors the sst-rsoxs GreatEyes thresholds used for automated exposure quality decisions.

describe() → dict[str, Any][source]¶

Return a data_keys-compatible descriptor dict for use in RunWriter.open_stream.

Returns:: Dictionary with keys dtype, source, external, and shape. shape reflects the last successfully acquired image dimensions, or an empty list when no image has been acquired yet.
Return type:: dict[str, Any]

async is_ready() → bool[source]¶

Return whether the instrument driver is running and the detector is ready.

Uses BCSz GetInstrumentDriverStatus for the configured instrument name.

Returns:: True if the driver is running and the detector can accept acquisitions.
Return type:: bool

async setup(*, timeout: float = 30.0, poll_interval: float = 0.5) → None[source]¶

Ensure the detector driver is started and ready for acquisition.

Starts the instrument driver via BCSz if not already running, then waits until is_ready() is True or timeout is reached.

Parameters:

timeout (float, optional) – Maximum time in seconds to wait for the driver to become ready. Default 30.0.
poll_interval (float, optional) – Seconds between readiness checks. Default 0.5.

Raises:

TimeoutError – If the driver did not report ready within timeout seconds.