Image processing¶
See calibration and deskew, deconvolution, and fusion for the physical conventions around these source-documented functions.
Calibration¶
Convert raw camera counts to nonnegative float32 intensities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw
|
ndarray
|
Uint16 image or volume. Leading dimensions are independent images. |
required |
camera_offset
|
float
|
Electronic background in ADU. |
required |
camera_conversion
|
float
|
Calibrated intensity per ADU, including QE when required by the caller. |
required |
detector_x_offset
|
int
|
First detector column of a cropped acquisition. |
0
|
apply_stage_scan_gain
|
bool
|
Divide by the measured qi2lab detector-X response after clipping. |
False
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Calibrated float32 data with the input shape. The input is unchanged. |
Apply illumination correction independently of camera calibration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
calibrated
|
ndarray
|
Float32 image or volume after camera correction and empty-tile checks. |
required |
illumination
|
ndarray
|
Float32 detector profile broadcastable to the image shape. |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
Float32 intensities divided by the profile. Neither input is modified. |
Geometry and interpolation¶
Convert stage positions to image-placement coordinates.
Positions may be YX or ZYX. In both cases Y is the penultimate axis. OPM physical stage motion is opposite motion of the sample in laboratory Z, while stage Y motion is opposite image Y. These placement-coordinate transforms never flip image pixels or the acquired scan axis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
positions
|
Sequence[Sequence[float]] | ndarray
|
Stage positions in YX or ZYX order. |
required |
reverse_y
|
bool
|
Whether to reverse the stage-derived image-Y placement coordinate. |
True
|
reverse_z
|
bool
|
Whether to convert physical stage Z into the opposite laboratory-Z placement coordinate. Ignored for two-dimensional YX positions. |
True
|
opm_angle_deg
|
float | None
|
Retained for compatibility. The illumination angle affects deskewing, not placement of the resulting orthogonal tiles. Stage Z motion must not introduce an additional image-Y translation. |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Independent float64 coordinates suitable for tile placement. |
Generate shape of orthogonal interpolation output array.
This function automatically pads the YX dimensions to be
an integer divisible by divisible_by.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_shape
|
Sequence[int]
|
shape of oblique array |
required |
theta
|
float
|
angle relative to coverslip |
30.0
|
distance
|
float
|
step between image planes along coverslip |
0.4
|
pixel_size
|
float
|
in-plane camera pixel size in OPM coordinates |
0.115
|
crop_after_deskew
|
bool
|
Remove the lateral triangular deskew margins from the output shape. |
True
|
divisible_by
|
int
|
Pad output YX dimensions to multiples of this integer. |
4
|
Returns:
| Name | Type | Description |
|---|---|---|
output_shape |
list[int]
|
Deskewed ZYX dimensions, including YX padding. |
pad_y |
int
|
Added rows along laboratory Y. |
pad_x |
int
|
Added columns along laboratory X. |
crop_y |
int
|
Rows removed from each end of laboratory Y before padding. |
Deskew oblique data into a float32 laboratory volume.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
ArrayLike
|
Image stack in scan, detector-Y, detector-X order. |
required |
theta
|
float
|
Acquisition angle relative to the coverslip, in degrees. |
30.0
|
distance
|
float
|
Distance between scan planes in micrometers. |
0.4
|
pixel_size
|
float
|
In-plane camera pixel size in micrometers. |
0.115
|
reverse_deskewed_z
|
bool
|
Reverse the laboratory Z axis after interpolation. |
False
|
divisible_by
|
int
|
Pad Y and X to multiples of this integer. |
4
|
downsample_factor
|
int
|
Average this many laboratory Z planes; the default remains two. |
2
|
zero_initialized
|
bool
|
Use a zero-filled allocation; False writes every voxel explicitly for chunks. |
True
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Float32 ZYX volume with sampling
|
PSFs and RLGC¶
Create OPM PSF in skewed coordinates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
em_wvl
|
float
|
emission wavelength in microns |
required |
pixel_size_um
|
float
|
pixel size in microns |
0.115
|
scan_axis_step_um
|
float
|
step size in microns |
0.4
|
theta_deg
|
float
|
OPM tilt angle in degrees. |
30.0
|
pz
|
float
|
distance above coverslip in microns |
0.0
|
plot
|
bool
|
whether to plot the PSF |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
skewed_psf |
ndarray
|
OPM PSF in skewed coordinates |
Generate a central optical-plane kernel with the existing lateral mask.
The solver normalizes the kernel after masking.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
em_wvl
|
float
|
Emission wavelength in micrometers. |
required |
pixel_size_um
|
float
|
Camera-plane pixel size in micrometers. |
0.115
|
pz
|
float
|
Emitter depth above the coverslip in micrometers. |
15.0
|
plot
|
bool
|
Retained for API compatibility; plotting is not performed. |
False
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Masked central PSF plane in ZYX order with a singleton Z dimension. |
Richardson-Lucy Gradient Consensus deconvolution.
The multiplicative update and consensus sign rule follow the local expansion-processing reference. Initialization backprojects the measured image. Stopping compares successive predictions against the same fresh split, preventing changes in the split itself from triggering rollback. Fractional counts are split without favoring either half.
OPM retains per-axis PSF halos and 2/3/5/7-smooth FFT padding. Symmetric input padding is applied once; padded values participate in the loop.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
2D or 3D image to be deconvolved. 2D input is treated as a single-z stack internally. |
required |
psf
|
ndarray
|
2D or 3D point-spread function. This PSF is padded and transformed on the GPU to form the forward and adjoint OTFs internally. |
required |
gpu_id
|
int
|
Which GPU to use. |
0
|
safe_mode
|
bool
|
Compare observation-to-prediction KLD against the same fresh halves. If True, stop when either half worsens; otherwise require both halves. |
True
|
limit
|
float
|
Minimum fraction of pixels that must be updated per iteration before early stopping is triggered. |
0.001
|
max_delta
|
float
|
Maximum allowed relative update magnitude before early stopping is triggered. |
0.001
|
pad_yx
|
bool
|
If True, pad Y/X by the PSF support and expand them to FFT-friendly sizes. Z is always padded by the PSF support. Padding is removed before returning the result. |
True
|
rng_seed
|
int or None
|
Seed for the per-iteration 50:50 data split. Set to None for nondeterministic splits. |
42
|
normalize_psf
|
bool
|
If True, normalize the PSF to unit sum before deconvolution. Set False only for diagnostics that intentionally preserve PSF scale. |
True
|
release_memory
|
bool
|
If True, release GPU memory pools after each call. Set False when calling in tight loops to avoid allocator thrashing. |
True
|
logger
|
Logger or None
|
Optional logger for per-iteration RLGC diagnostics. |
None
|
log_prefix
|
str
|
Structured prefix prepended to every emitted log line. |
""
|
max_iterations
|
int
|
Upper bound on consensus updates when stochastic stopping has not fired. |
100
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Deconvolved 3D image (float32). A 2D input is returned as a single-z stack. |
Fusion¶
Estimate channel gains shared by all XY tiles at each depth.
Sample registered overlaps only between distinct depths acquired at the same XY stage position. Fit robust log intensity ratios separately for each channel and time point, anchoring the first connected depth. Store gains and provenance for fusion without modifying source tiles. Planar acquisitions and acquisitions with one depth retain unit gains.
Returns:
| Type | Description |
|---|---|
None
|
Gains and provenance are stored on this instance. |