Hyperspectral CT

Hyperspectral CT#

These are MBIRJAX functions specific to hyperspectral CT processing, exporting/importing, and generating synthetic data.

Dehydration/Rehydration#

mbirjax.hsnt.hyper_denoise(data, dataset_type='attenuation', num_materials=None, safety_factor=2, beta_loss='frobenius', max_iter=300, tolerance=1e-10, batch_size=134217728, subspace_basis=None, verbose=1)[source]#

Denoise a hyperspectral dataset using dehydration and rehydration as described in:

      1. Chowdhury, D. Yang, S. Tang, S. V. Venkatakrishnan, H. Z. Bilheux, G. T. Buzzard, and C. A. Bouman, “Fast Hyperspectral Neutron Tomography,” IEEE Transactions on Computational Imaging, vol. 11, pp. 663–677, 2025. doi:10.1109/TCI.2025.3567854

The function works for any rank array. However, the spectral axis must be the last axis.

Parameters:

  • data – Hyperspectral data array with arbitrary axes and a spectral axis in the last position.

  • dataset_type – ‘attenuation’ or ‘transmission’ where attenuation = -log(transmission). Defaults to ‘attenuation’.

  • num_materials – Number of materials in the sample. If None, the number is estimated automatically from the data. Defaults to None.

  • safety_factor – A multiplier (≥ 1) applied to the number of materials to set the subspace dimension. Defaults to 2.

  • beta_loss – Beta divergence minimized in NMF. Can be ‘frobenius’ or ‘kullback-leibler’. Defaults to ‘frobenius’.

  • max_iter – Maximum iterations for the NMF solver. Defaults to 300.

  • tolerance – Convergence tolerance for the NMF solver. Defaults to 1e-10.

  • batch_size – Size of data processed per batch. Useful for large datasets to limit memory usage. Defaults to 2^27.

  • subspace_basis – Pre-computed subspace basis spectra of shape. If None, the basis spectra are estimated directly from the data. Defaults to None.

  • verbose – Verbosity level. If 0, prints nothing; if 1, prints details; if >1, also generates plots. Defaults to 1.

Returns:

Denoised hyperspectral data with the same shape as the input data.

Example

>>> denoised_data = hyper_denoise(data, num_materials=5, safety_factor=2)
>>> data.shape, denoised_data.shape
((N_x, N_y, N_z, ..., N_k), (N_x, N_y, N_z, ..., N_k))
mbirjax.hsnt.dehydrate(data, dataset_type='attenuation', num_materials=None, safety_factor=2, beta_loss='frobenius', max_iter=300, tolerance=1e-10, batch_size=134217728, subspace_basis=None, verbose=1)[source]#

Dehydrate/compress a hyperspectral dataset onto a low-dimensional subspace as described in:

      1. Chowdhury, D. Yang, S. Tang, S. V. Venkatakrishnan, H. Z. Bilheux, G. T. Buzzard, and C. A. Bouman, “Fast Hyperspectral Neutron Tomography,” IEEE Transactions on Computational Imaging, vol. 11, pp. 663–677, 2025. doi:10.1109/TCI.2025.3567854

The function works for any rank array. However, the spectral axis must be the last axis.

Parameters:

  • data – Hyperspectral data array with arbitrary axes and a spectral axis of length \(N_k\) in the last position.

  • dataset_type – ‘attenuation’ or ‘transmission’ where attenuation = -log(transmission). Defaults to ‘attenuation’.

  • num_materials – Number of materials in the sample \(N_m\). If None, the number is estimated automatically from the data. Defaults to None.

  • safety_factor – A multiplier (≥ 1) applied to the number of materials to set the subspace dimension \(N_s\). Defaults to 2.

  • beta_loss – Beta divergence minimized in NMF. Can be ‘frobenius’ or ‘kullback-leibler’. Defaults to ‘frobenius’.

  • max_iter – Maximum iterations for the NMF solver. Defaults to 300.

  • tolerance – Convergence tolerance for the NMF solver. Defaults to 1e-10.

  • batch_size – Size of data processed per batch. Useful for large datasets to limit memory usage. Defaults to 2^27.

  • subspace_basis – Pre-computed subspace basis spectra of shape \((N_s, N_k)\). If None, the basis spectra are estimated directly from the data. Defaults to None.

  • verbose – Verbosity level. If 0, prints nothing; if 1, prints details; if >1, also generates plots. Defaults to 1.

Returns:

A list containing the dehydrated hyperspectral dataset in the form [subspace_data, subspace_basis, dataset_type].

  • subspace_data: ndarray with same shape as input data except the last axis length is \(N_s\).

  • subspace_basis: ndarray of shape \((N_s, N_k)\), where rows are subspace basis spectra.

  • dataset_type: Can be ‘attenuation’ or ‘transmission’ where attenuation = -log(transmission).

Example

>>> [subspace_data, subspace_basis, dataset_type] = dehydrate(data, num_materials=5, safety_factor=2)
>>> data.shape, subspace_data.shape, subspace_basis.shape
((N_x, N_y, N_z, ..., N_k), (N_x, N_y, N_z, ..., 10), (10, N_k))
mbirjax.hsnt.rehydrate(dehydrated_data, hyperspectral_idx=None)[source]#

Rehydrate/decompress selected spectral bins from dehydrated hyperspectral data as described in:

      1. Chowdhury, D. Yang, S. Tang, S. V. Venkatakrishnan, H. Z. Bilheux, G. T. Buzzard, and C. A. Bouman, “Fast Hyperspectral Neutron Tomography,” IEEE Transactions on Computational Imaging, vol. 11, pp. 663–677, 2025. doi:10.1109/TCI.2025.3567854

Parameters:

  • dehydrated_data – Dehydrated hyperspectral data in the form [subspace_data, subspace_basis, dataset_type]:

    • subspace_data: ndarray with arbitrary axes and a subspace axis of length \(N_s\) in the last position.

    • subspace_basis: ndarray of shape \((N_s, N_k)\), where rows are subspace basis spectra.

    • dataset_type: ‘attenuation’ or ‘transmission’ where attenuation = -log(transmission).

  • hyperspectral_idx – A list of \(N_h\) indices along the original spectral axis to rehydrate. If None, all \(N_k\) spectral bins are rehydrated. Defaults to None.

Returns:

Rehydrated/decompressed hyperspectral data with the same shape as the input subspace_data except the last axis length is \(N_h (N_h <= N_k)\).

Example

>>> hyper_data = rehydrate([subspace_data, subspace_basis, dataset_type], hyperspectral_idx=[5, 10, 15])
>>> subspace_data.shape, subspace_basis.shape, hyper_data.shape
((N_x, N_y, N_z, ..., N_s), (N_s, N_k), (N_x, N_y, N_z, ..., 3))

Import/Export#

mbirjax.hsnt.import_hsnt_list_hdf5(filename)[source]#

Returns a list of all datasets in the HDF5 file.

Parameters:

filename – Path to the HDF5 file containing the datasets.

Returns:

A list of dataset names available in the HDF5 file.

mbirjax.hsnt.import_hsnt_data_hdf5(filename, dataset_name)[source]#

Import a hyperspectral dataset and metadata from an HDF5 file.

Parameters:

  • filename – Path to the HDF5 file.

  • dataset_name – Character string with the name of the dataset.

Returns:

A list containing hyperspectral data and parameters in the form [data, metadata].

  • data: ndarray with spectral last axis (hyperspectral form) or a list (dehydrated form).

  • metadata: A dictionary with the keys shown below.

Keys:

  • dataset_name: Character string with the name of the dataset.

  • dataset_type: ‘attenuation’ or ‘transmission’.

  • dataset_modality: ‘hyperspectral neutron’.

  • wavelengths: Array of wavelength values in Angstroms.

  • alu_unit: Character string defining geometry unit (e.g., ‘mm’ or ‘cm’).

  • alu_value: Float that represents the value of 1 ALU in the defined unit.

  • delta_det_channel: Detector channel spacing in ALU.

  • delta_det_row: Detector row spacing in ALU.

  • dataset_geometry: ‘parallel’ or ‘cone’.

  • angles: Array of view angles in degrees.

  • det_channel_offset: Assumed offset between center of rotation and center of detector in ALU.

  • source_detector_dist: Distance from source to detector in ALU.

  • source_iso_dist: Distance from source to iso in ALU.

Note

Multiple datasets can coexist in the same HDF5 file, each stored under a unique dataset name.

mbirjax.hsnt.create_hsnt_metadata(**kwargs)[source]#

Create a dictionary of parameters (metadata) associated with a hyperspectral neutron dataset.

Parameters:

  • dataset_name – Character string with the name of the dataset.

  • dataset_type – ‘attenuation’ or ‘transmission’.

  • dataset_modality – ‘hyperspectral neutron’.

  • wavelengths – Array of wavelength values in Angstroms.

  • alu_unit – Character string defining geometry unit (e.g., ‘mm’ or ‘cm’).

  • alu_value – Float that represents the value of 1 ALU in the defined unit.

  • delta_det_channel – Detector channel spacing in ALU.

  • delta_det_row – Detector row spacing in ALU.

  • dataset_geometry – ‘parallel’ or ‘cone’.

  • angles – Array of view angles in degrees.

  • det_channel_offset – Assumed offset between center of rotation and center of detector in ALU.

  • source_detector_dist – Distance from source to detector in ALU.

  • source_iso_dist – Distance from source to iso in ALU.

Returns:

dict – Dictionary containing hyperspectral neutron dataset parameters (metadata).

Example

>>> metadata = create_hsnt_metadata(
...     dataset_name="sample1",
...     dataset_type="attenuation",
...     dataset_modality="hyperspectral neutron",
...     wavelengths=np.linspace(1.0, 5.0, 50),
...     alu_unit="mm",
...     alu_value=1.0,
...     dataset_geometry="parallel",
...     angles=np.linspace(0, 180, 10)
... )
>>> print(metadata["dataset_name"])
sample1
mbirjax.hsnt.export_hsnt_data_hdf5(filename, data, metadata)[source]#

Export a hyperspectral dataset and metadata to an HDF5 file.

Parameters:

  • filename – Path to the HDF5 file.

  • data – ndarray with spectral last axis (hyperspectral form) or a list (dehydrated form).

  • metadata – A dictionary with the keys shown below. Use create_hsnt_metadata to create a metadata dictionary.

Keys:

  • dataset_name: Character string with the name of the dataset.

  • dataset_type: ‘attenuation’ or ‘transmission’.

  • dataset_modality: ‘hyperspectral neutron’.

  • wavelengths: Array of wavelength values in Angstroms.

  • alu_unit: Character string defining geometry unit (e.g., ‘mm’ or ‘cm’).

  • alu_value: Float that represents the value of 1 ALU in the defined unit.

  • delta_det_channel: Detector channel spacing in ALU.

  • delta_det_row: Detector row spacing in ALU.

  • dataset_geometry: ‘parallel’ or ‘cone’.

  • angles: Array of view angles in degrees.

  • det_channel_offset: Assumed offset between center of rotation and center of detector in ALU.

  • source_detector_dist: Distance from source to detector in ALU.

  • source_iso_dist: Distance from source to iso in ALU.

Returns:

None. Creates or appends to an HDF5 file with the corresponding structure.

Note

  • Multiple datasets can coexist in the same HDF5 file, each is stored under a unique dataset name.

  • If a dataset with the same name already exists in the file, it will be overwritten with a warning.

Generate Synthetic Data#

mbirjax.hsnt.generate_hyper_data(material_basis, num_angles=1, detector_rows=64, detector_columns=64, dosage_rate=300, material_density=None, verbose=1)[source]#

Simulate noisy hyperspectral neutron attenuation data for \(N_m=3\) materials (Ni, Cu, Al) and \(N_k\) wavelength bins.

Parameters:

  • material_basis – ndarray of shape \((N_m, N_k)\), where rows are material linear attenuation coefficient spectra.

  • num_angles – Number of view angles \((N_v)\). Defaults to 1.

  • detector_rows – Number of rows in the detector \((N_r)\). Defaults to 64.

  • detector_columns – Number of columns in the detector \((N_c)\). Defaults to 64.

  • dosage_rate – Neutron dosage rate during hyperspectral data collection. Defaults to 300.

  • material_density – Material density (vol. fraction) for Ni, Cu, and Al. Defaults to {“Ni”: 0.2, “Cu”: 0.2, “Al”: 1.0}.

  • verbose – Verbosity level. If 0, prints nothing; if 1, prints details; if >1, also generates plots. Defaults to 1.

Returns:

A list in the form [hsnt_data, gt_hyper_projection].

  • hsnt_data: Simulated noisy hyperspectral data of shape \((N_v, N_r, N_c, N_k)\).

  • angles: ndarray of view angles in radian

  • gt_hyper_projection: Ground truth noiseless hyperspectral data of same shape.