Processing pipeline

This page describes exactly what the processing service does to turn frames into a calibrated spectral cube.

Cube layout

A cube is a 3-D array \(I_{b,r,c}\) with bands \(b\), rows \(r\) and columns \(c\), stored band-sequentially (bands, rows, cols), plus the list of wavelengths, one per band. Every step below works on one band image \(I_b\) at a time, unless stated otherwise.

Order of operations

The steps you enable run in this fixed order:

flowchart LR
    A[Frames / imported file] --> B[Destriping] --> C[White/dark correction] --> D[Normalize] --> E[Band crop] --> F[Downsample] --> G[ROI crop] --> H[Cube]

Steps 1–3 run for each band. Steps 4–6 change the cube's shape.

1. Destriping

Push-broom and scanning detectors often add a constant offset to whole columns, which shows up as vertical stripes. For each band:

1. Take the median of every column: \(m_c = \operatorname{median}_r I_{r,c}\).
2. Smooth that profile with a Savitzky-Golay filter (Window \(w\), polynomial Order \(p\); defaults \(w=5,\ p=2\)) to get \(\tilde m_c\).
3. Subtract the difference from every pixel in the column:

\[ I'_{r,c} = I_{r,c} - \left(m_c - \tilde m_c\right) \]

Smooth variation across columns is real signal and is kept. Only the column-to-column jitter is removed.

2. White/dark (radiometric) correction

This converts raw detector counts into relative reflectance, using a white reference \(W\) (a bright, uniform target) and a dark reference \(D\) (source blocked):

\[ R_{r,c} = \max\!\left(0,\ k \cdot \frac{I_{r,c} - D_{r,c}}{W_{r,c} - D^{W}_{r,c}}\right) \]

• \(D^{W}\) is the dark frame for the white reference, and \(k\) is the exposure ratio between sample and reference.
• The pipeline currently uses the single dark reference you supply for both (\(D^{W} = D\)) and assumes equal exposure (\(k = 1\)). Record your references with the same settings as the sample.
• Pixels where \(|W - D^W| < 10^{-10}\) are set to 0 to avoid dividing by zero.
• Negative values are clipped to 0.

3. Normalization

Each band is rescaled independently to \([0, 1]\):

\[ I'_{r,c} = \frac{I_{r,c} - \min(I)}{\max(I) - \min(I)} \]

A constant band, with range below \(10^{-10}\), becomes all zeros.

4. Band cropping

Keeps band indices from min to max (inclusive) and drops the rest, together with their wavelengths. Use it to remove noisy bands at the edges of the laser's tuning range.

5. Downsampling

With factor \(n > 1\), every \(n \times n\) block of pixels is replaced by its mean. The cube shrinks to \(\lfloor rows/n \rfloor \times \lfloor cols/n \rfloor\). This speeds up analysis of large images and slightly reduces noise.

6. ROI crop

When row and column bounds are set, the cube is cropped to that rectangle.

Reference implementation

The calibration steps follow the approach used by napari-sediment for hyperspectral sediment imaging, adapted for streaming QCL data.