Custom Python Analysis

Overview

The Custom Python Analysis workspace connects IDCubePro to an external Python installation and allows Python code to operate directly on the current hyperspectral cube.

Python can be used for numerical analysis, image processing, machine learning, statistics, dimensionality reduction, segmentation, visualization, and custom research workflows.

IDCubePro automatically provides the current dataset to Python and can display Python-generated results inside IDCubePro. A processed cube can also be transferred back into IDCubePro as the new working dataset.

Data Available to Python

The following variables are automatically available to Python scripts:

• cube — hyperspectral data arranged as rows × columns × spectral bands.
• wavelengths — one-dimensional spectral wavelength vector.
• metadata — dataset metadata made available to the Python workspace.

Python Environment

IDCubePro uses an external Python installation on the computer. When the Python Analysis Center opens, IDCubePro detects the active interpreter and checks the scientific packages used by the Python bridge.

The environment result is cached during the current IDCubePro session so reopening the Python Analysis Center is fast.

Use Check Python to force a fresh environment scan, especially after installing, removing, or changing Python packages.

Python Packages

Core packages:

• NumPy
• SciPy

Standard scientific packages:

• Matplotlib
• pandas
• scikit-learn
• scikit-image

Optional extended packages may include:

• OpenCV
• tifffile
• h5py
• openpyxl
• nibabel
• statsmodels

If a required or recommended package is missing or cannot be imported, IDCubePro can offer to install or repair it using the exact Python interpreter detected by IDCubePro.

Python Analysis Center Controls

• Open .py File — load an existing Python script into the editor.
• Clear — clear the Python code editor.
• Return cube to IDCubePro — transfer a processed cube and its spectral axis back into IDCubePro after the script finishes.
• Close — close the Python Analysis Center.
• Help — open the built-in Python Analysis help window.
• Check Python — re-detect Python and re-test the configured package set.
• Install Packages — install or repair missing supported Python packages.
• Run Analysis — execute the current Python code using the loaded IDCubePro dataset.

Basic Workflow

1. Load a hyperspectral dataset in IDCubePro.

2. Open the Custom Python Analysis workspace.

3. Allow IDCubePro to detect Python and check the scientific environment.

4. Install or repair packages if IDCubePro reports that supported packages are missing.

5. Type Python code directly into the editor or open an existing .py file.

6. Select Return cube to IDCubePro if the script creates a processed replacement cube.

7. Click Run Analysis.

8. Inspect the returned results and, when enabled, the updated IDCubePro dataset.

Returning a Simple Result

For one simple numeric, image, or spectral result, create a variable named result.

import numpy as np

result = np.mean(cube, axis=2)

A one-dimensional result whose length matches the wavelength vector can be displayed automatically as a spectrum using the wavelength axis.

Returning Multiple Results

For more control, create an outputs list. Each item is a Python dictionary describing one result.

import numpy as np

mean_spectrum = np.mean(cube, axis=(0, 1))

outputs = [
    {
        "type": "spectrum",
        "title": "Mean Spectrum",
        "data": mean_spectrum,
        "x": wavelengths,
        "xlabel": "Wavelength",
        "ylabel": "Intensity"
    }
]

Supported result types include image, rgb, spectrum, spectra, scatter, scatter3, surface, volume, isosurface, labelvolume, bar, histogram, table, and auto.

Returning a Processed Cube to IDCubePro

Enable Return cube to IDCubePro when Python creates a processed dataset that should replace the current IDCubePro working cube.

The preferred Python variables are:

output_cube = ...
output_wavelengths = ...

The returned cube must be three-dimensional and arranged as rows × columns × bands. The number of values in output_wavelengths must equal the number of bands in output_cube.

If output_cube or output_wavelengths are not explicitly created, IDCubePro can use the current Python variables cube and wavelengths as the returned dataset.

The returned data replace the current working dataset but do not replace the original source dataset stored by IDCubePro.

Example: PCA Cube

The following example performs PCA and returns the first 20 principal component score images as a new cube.

import numpy as np
from sklearn.decomposition import PCA

rows, cols, bands = cube.shape

X = cube.reshape(-1, bands).astype(float)
valid = np.all(np.isfinite(X), axis=1)

X_valid = X[valid]

n_components = min(20, bands)

pca = PCA(n_components=n_components)
scores_valid = pca.fit_transform(X_valid)

score_cube = np.full(
    (rows * cols, n_components),
    np.nan,
    dtype=float
)

score_cube[valid, :] = scores_valid

output_cube = score_cube.reshape(
    rows,
    cols,
    n_components
)

output_wavelengths = np.arange(
    1,
    n_components + 1,
    dtype=float
)

outputs = [
    {
        "type": "image",
        "title": "PCA Component 1",
        "data": output_cube[:, :, 0]
    }
]

For a PCA cube, the returned third-axis values represent component numbers rather than physical wavelengths.

Example: scikit-image Gaussian Smoothing

import numpy as np
from skimage.filters import gaussian

mean_image = np.mean(cube, axis=2)

smoothed = gaussian(
    mean_image,
    sigma=2
)

outputs = [
    {
        "type": "image",
        "title": "Gaussian Smoothed",
        "data": smoothed
    }
]

Processing History

When a Python-generated cube is transferred back into IDCubePro, IDCubePro records the operation in the processing history.

The history entry can include the dataset dimensions and band counts before and after the Python operation, wavelength ranges, and whether the data were changed.

Matplotlib

Matplotlib can be used to create external Python figures.

Be aware that plt.show() normally pauses Python execution until the Matplotlib window is closed. IDCubePro therefore cannot finish receiving Python results until that external figure is closed.

For integrated IDCubePro results, return result or outputs instead of relying on plt.show().

Package Name Differences

Some Python import names differ from their package installation names:

• sklearn → scikit-learn
• skimage → scikit-image
• cv2 → opencv-python

Troubleshooting

ModuleNotFoundError means that a requested Python package is missing or cannot be imported by the Python interpreter used by IDCubePro.

Use Install Packages to install or repair supported packages, then use Check Python if a fresh environment scan is needed.

If a returned cube is rejected, confirm that it is a numeric 3D array and that the returned wavelength or component vector has exactly one value for each band.

Only run Python code from sources you trust.