DataCube Operations

Module Overview

This module contains functions for processing datacubes. The methods are dynamically added to the DataCube class in its __init__ method. Therefore, they can be used as standalone functions or as methods of the DataCube class.

Functions

wizard._core.datacube_ops.remove_spikes(dc, threshold=6500, window=5)[source]

Remove cosmic spikes from each pixel’s spectral data.

This function computes the modified z-score for each pixel’s spectral vector, identifies spikes where the score exceeds the threshold, and replaces spike values with the local mean within a sliding window along the spectrum.

Parameters:

  • dc (DataCube) – The input DataCube with shape (v, x, y), where v is the number of spectral bands.

  • threshold (int, optional) – Threshold for spike detection via modified z-score, defaults to 6500.

  • window (int, optional) – Window size (in spectral channels) for mean replacement of spikes, defaults to 5.

Returns:

A new DataCube instance with spikes removed per-pixel.

Return type:

DataCube

Raises:

ValueError – If window is not in the range [1, number of spectral bands].

Notes

  • The original DataCube is not modified in place; es wird eine Kopie zurückgegeben.

  • Die Modifizierte z-Score-Berechnung erwartet Input mit Form (n_samples, n_features).

  • Parallelisierung beschleunigt die Einzelpixel-Bearbeitung.

Examples

>>> import wizard
>>> dc = wizard.read("example.fsm")
>>> dc.remove_spikes(threshold=6500, window=5)
wizard._core.datacube_ops.remove_background(dc, threshold=50, style='dark')[source]

Remove background from images in a DataCube.

Uses an external algorithm (rembg). The first image in the DataCube is processed to generate a mask, which is then applied to all images to remove the background.

Parameters:

  • dc (DataCube) – DataCube containing the image stack.

  • threshold (int, optional) – Threshold value to define the background from the alpha mask, defaults to 50. Pixels with alpha < threshold are considered background.

  • style (str, optional) – Style of background removal, ‘dark’ or ‘bright’, defaults to ‘dark’. If ‘dark’, background pixels are set to 0. If ‘bright’, background pixels are set to the max value of the cube.y

Returns:

DataCube with the background removed.

Return type:

DataCube

Raises:

ValueError – If style is not ‘dark’ or ‘bright’.

Examples

>>> import wizard
>>> dc = wizard.read("example.fsm")
>>> dc.remove_background(threshold=50, style='bright') # or style 'dark'
wizard._core.datacube_ops.resize(dc, x_new, y_new, interpolation='linear')[source]

Resize the DataCube to new x and y dimensions. dc.shape is v,x,y

Resizes each 2D slice (x, y) of the DataCube using the specified interpolation method.

Interpolation methods:

  • linear: Bilinear interpolation (ideal for enlarging).

  • nearest: Nearest neighbor interpolation (fast but blocky).

  • area: Pixel area interpolation (ideal for downscaling).

  • cubic: Bicubic interpolation (high quality, slower).

  • lanczos: Lanczos interpolation (highest quality, slowest).

Parameters:

  • dc (DataCube) – The DataCube instance to be resized.

  • x_new (int) – The new width (x-dimension).

  • y_new (int) – The new height (y-dimension).

  • interpolation (str, optional) – Interpolation method, defaults to ‘linear’. Options: ‘linear’, ‘nearest’, ‘area’, ‘cubic’, ‘lanczos’.

Returns:

The DataCube is modified in-place.

Return type:

None

Raises:

ValueError – If the interpolation method is not recognized.

Examples

>>> import wizard
>>> dc = wizard.read("example.fsm")
>>> dc.resize(x_new=500, y_new=500)
wizard._core.datacube_ops.baseline_als(dc, lam=1000000, p=0.01, niter=10)[source]

Apply Adaptive Smoothness (ALS) baseline correction.

Iterates through each pixel (spectrum) in the DataCube and subtracts the baseline calculated by the spec_baseline_als function.

Parameters:

  • dc (DataCube) – The input DataCube.

  • lam (float, optional) – The smoothness parameter for ALS, defaults to 1000000. Larger lambda makes the baseline smoother.

  • p (float, optional) – The asymmetry parameter for ALS, defaults to 0.01. Value between 0 and 1. Controls how much the baseline is pushed towards the data (0 for minimal, 1 for maximal).

  • niter (int, optional) – The number of iterations for the ALS algorithm, defaults to 10.

Returns:

The DataCube with baseline correction applied.

Return type:

DataCube

Examples

>>> import wizard
>>> dc = wizard.read("example.fsm")
>>> dc.baseline_als(lam=1e6, p=.001, niter=10)
wizard._core.datacube_ops.merge_cubes(dc1, dc2, register=False)[source]

Merge two DataCubes into a single DataCube, with optional registration.

If both datacubes are already registered and the register flag is True, the function will sample up to 10 random spectral layers from dc2, attempt to register each to the first layer of dc1, choose the transform with the lowest mean-squared-error alignment, then apply that best transform to all layers of dc2 before merging.

Parameters:

  • dc1 (DataCube) – The first DataCube (used as reference).

  • dc2 (DataCube) – The second DataCube to be merged into the first.

  • register (bool, optional) – If True (default), registration will be attempted if both cubes are marked as registered.

Returns:

A new DataCube containing merged spatial and spectral data.

Return type:

DataCube

Raises:

NotImplementedError – If the cubes have mismatched spatial dimensions and cannot be merged, or if wavelengths overlap without being purely indices.

Examples

>>> import wizard
>>> dc_a = wizard.read('example.fsm')
>>> dc_b = wizard.read('another_file.csv')
>>> dc_a.merge_cubes(dc_b)
wizard._core.datacube_ops.inverse(dc)[source]

Invert the DataCube values.

This operation is useful for converting between transmission and reflectance data, or similar inversions. The formula applied is: tmp = cube * -1 tmp += -tmp.min() The data type of the cube is preserved if it’s ‘uint16’ or ‘uint8’ after temporary conversion to ‘float16’ for calculation.

Parameters:

dc (DataCube) – The DataCube to invert.

Returns:

The DataCube with inverted values.

Return type:

DataCube

Examples

>>> import wizard
>>> dc = wizard.read('example.fsm')
>>> dc.inverse()
wizard._core.datacube_ops.register_layers_simple(dc, max_features=5000, match_percent=0.1)[source]

Align images within a DataCube using simple feature-based registration.

Each layer in the DataCube is aligned to the first layer (index 0) using ORB feature detection and homography estimation via _feature_registration.

Parameters:

  • dc (DataCube) – The DataCube whose layers are to be registered.

  • max_features (int, optional) – Maximum number of keypoint regions to detect, defaults to 5000.

  • match_percent (float, optional) – Percentage of keypoint matches to consider for homography, defaults to 0.1 (10%).

Returns:

The DataCube with layers registered.

Return type:

DataCube

Examples

>>> import wizard
>>> dc = wizard.read('example.fsm')
>>> dc.register_layers_simple()
wizard._core.datacube_ops.register_layers_best(dc, ref_layer=0, max_features=5000, match_percent=0.1, rot_thresh=20.0, scale_thresh=1.1)[source]

Align DataCube layers with robust registration.

Aligns each slice of dc.cube to a reference layer. It uses feature-based registration primarily. If feature-based registration yields a degenerate homography (based on rotation and scale thresholds) or fails, it falls back to Canny-based edge registration. Failed alignments are retried once.

Parameters:

  • dc (DataCube) – The DataCube to process.

  • ref_layer (int, optional) – Index of the reference layer, defaults to 0.

  • max_features (int, optional) – Maximum features for ORB, defaults to 5000.

  • match_percent (float, optional) – Match percentage for ORB, defaults to 0.1.

  • rot_thresh (float, optional) – Rotation threshold (degrees) for homography validation, defaults to 20.0.

  • scale_thresh (float, optional) – Scale threshold for homography validation, defaults to 1.1. Checks if max_scale <= scale_thresh and min_scale >= 1/scale_thresh.

Returns:

The DataCube with aligned layers.

Return type:

DataCube

Raises:

RuntimeError – If alignment fails for a layer after retry.

Examples

>>> import wizard
>>> dc = wizard.read('example.fsm')
>>> dc.register_layers_best()
wizard._core.datacube_ops.remove_vignetting_poly(dc, axis=1, slice_params=None)[source]

Remove vignetting using polynomial fitting along a specified axis.

Calculates the mean along the specified axis (1 for rows, 2 for columns) for each spectral layer, fits a polynomial to this mean profile (after Savitzky-Golay smoothing), and subtracts this fitted profile from the corresponding rows/columns of the layer to correct for vignetting.

Parameters:

  • dc (DataCube) – The DataCube instance to process.

  • axis (int, optional) – The axis along which to calculate the mean and apply correction. 1 for correcting along rows (profile used for columns), 2 for correcting along columns (profile used for rows). Defaults to 1.

  • slice_params (dict, optional) – Dictionary for slicing behavior before mean calculation. Keys: "start" (int), "end" (int), "step" (int). Defaults to full slice with step 1.

Returns:

The processed DataCube with vignetting removed.

Return type:

DataCube

Raises:

ValueError – If the DataCube is empty or axis is not 1 or 2.

Examples

>>> import wizard
>>> dc = wizard.read('example.fsm')
>>> params = {"start":25, "end":50}
>>> dc.remove_vignetting_poly(slice_params=params, axis=2)
wizard._core.datacube_ops.remove_vignetting(dc, sigma=50, clip=True, epsilon=1e-06)[source]

Remove vignetting from a hyperspectral DataCube.

Corrects vignetting in each spectral band by estimating a smooth background using Gaussian blur and then performing flat-field correction. The background is normalized by its mean before correction.

Parameters:

  • dc (DataCube) – The input DataCube (bands, height, width).

  • sigma (float, optional) – Standard deviation for Gaussian blur, controlling smoothness. Larger sigma means coarser background estimation. Defaults to 50.

  • clip (bool, optional) – If True and the original DataCube dtype is integer, clip output values to the valid range of that integer type. Defaults to True.

  • epsilon (float, optional) – A small constant to add to the background before division to prevent division by zero errors. Defaults to 1e-6.

Returns:

The DataCube with vignetting corrected. The output cube has the same shape and dtype as the input.

Return type:

DataCube

Examples

>>> import wizard
>>> dc = wizard.read('example.fsm')
>>> dc.remove_vignetting()
wizard._core.datacube_ops.upscale_datacube_edsr(dc, scale, model_path)[source]

Upscale the spatial dimensions of a DataCube using the EDSR super-resolution model.

This function applies the EDSR (Enhanced Deep Super-Resolution) model from OpenCV’s dnn_superres module to each spectral slice of the given DataCube. Since EDSR expects a 3-channel input, each single-band slice is duplicated across three channels before processing. The output slices are then reassembled into a new DataCube with upscaled spatial dimensions.

Parameters:

  • dc (DataCube) – An instance of the DataCube class. Must have attributes: - datacube.cube: numpy array of shape (v, x, y) - datacube.wavelength: list of length v

  • scale (int) – The upscaling factor (e.g., 2, 3, or 4) supported by the EDSR model.

  • model_path (str) – Filesystem path to the pretrained EDSR .pb model file (e.g., “EDSR_x4.pb”).

Returns:

A new DataCube instance whose .cube has shape (v, x * scale, y * scale) and the same .wavelength list.

Return type:

DataCube

Raises:

  • FileNotFoundError – If the specified model_path does not exist or is unreadable.

  • cv2.error – If OpenCV fails to load the model or perform upsampling.

  • ValueError – If the scale is not one of the factors supported by the loaded model.

Notes

  • Requires opencv-contrib-python>=4.3.0.

  • Processing is done slice-by-slice and may be slow for large cubes.

  • Memory usage grows by approximately scale^2.

Examples

>>> import wizard
>>> dc = wizard.read("hyperspectral.fsm")
>>> dc.upscale_datacube_edsr(scale=4, model_path="EDSR_x4.pb")
>>> print(dc.cube.shape)
(v, x*4, y*4)
wizard._core.datacube_ops.upscale_datacube_espcn(dc, scale, model_path)[source]

Upscale the spatial dimensions of a DataCube using the ESPCN super-resolution model.

This function applies the ESPCN (Efficient Sub-Pixel Convolutional Neural Network) model from OpenCV’s dnn_superres module to each spectral slice of the given DataCube. Since ESPCN expects a 3-channel input, each single-band slice is duplicated across three channels before processing. The output slices are then reassembled into a new DataCube with upscaled spatial dimensions.

Parameters:

  • dc (DataCube) – An instance of the DataCube class. Must have attributes: - .cube: numpy array of shape (v, x, y) - .wavelength: list of length v

  • scale (int) – The upscaling factor (2, 3, or 4) supported by the ESPCN model.

  • model_path (str) – Filesystem path to the pretrained ESPCN .pb model file (e.g., “ESPCN_x3.pb”).

Returns:

A new DataCube instance whose .cube has shape (v, x * scale, y * scale) and the same .wavelength list.

Return type:

DataCube

Raises:

  • FileNotFoundError – If the specified model_path does not exist.

  • ValueError – If scale is not in {2, 3, 4}.

  • cv2.error – If OpenCV fails to load the model or perform upsampling.

Notes

  • Requires opencv-contrib-python>=4.3.0.

  • Processing is done slice-by-slice and may be slow for large cubes.

  • Memory usage grows by approximately scale**2.

Examples

>>> import wizard
>>> dc = wizard.read("test.fsm")
>>> dc.upscale_datacube_espcn(scale=3, model_path="ESPCN_x3.pb")
>>> print(dc.cube.shape)
(v, x*3, y*3)