Tasks#

Note

Use these tasks to build your own tomography workflows. For a walkthrough of the packaged graphs, see the workflow example.

ESRF HDF5 Files Conversion#

H5ToNx#

Identifier:
ewokstomo.tasks.nxtomomill.H5ToNx
Task type:
class
Inputs:
bliss_hdf5_path* : str

Path to the Bliss-produced raw scan (.h5).

nx_path* : str

Target path for the generated .nx file (parent dir created).

Outputs:
nx_path : str

Path to the created .nx file.

FluoToNx#

Identifier:
ewokstomo.tasks.nxtomomill.FluoToNx
Task type:
class
Inputs:
bliss_hdf5_path* : str

Path to the Bliss-produced raw XRFCT scan (.h5).

nx_path* : str

Target path for the generated .nx file (parent dir created).

Outputs:
nx_path : str

Path to the created .nx file.

Preprocessing#

ReduceDarkFlat#

Identifier:
ewokstomo.tasks.reducedarkflat.ReduceDarkFlat
Task type:
class
Inputs:
nx_path* : str

Path to the input NX file.

dark_reduction_method : str= mean

Method to reduce dark frames (‘mean’ or ‘median’).

flat_reduction_method : str= median

Method to reduce flat frames (‘mean’ or ‘median’).

overwrite : bool= True

Whether to overwrite existing reduced files.

output_dtype : type= <class 'numpy.float32'>

Data type for the output reduced frames.

return_info : bool= False

Whether to return additional info from reduction.

reference_dir_to_soft_link : str | None= None

Directory from which the reduced darks and flats will be linked. If provided, reduction is skipped.

Outputs:
reduced_darks_path : str

Path to the reduced dark frames file.

reduced_flats_path : str

Path to the reduced flat frames file.

OnlineReduceDarkFlat#

Identifier:
ewokstomo.tasks.online.reducedarkflat.OnlineReduceDarkFlat
Task type:
class
Inputs:
index*
output_file_path*
reduction_method*
output_dtype
overwrite
scan_file_path
scan_key
scan_number
Outputs:
reduced_url

Reconstruction#

ReconstructSlice#

Identifier:
ewokstomo.tasks.reconstruct_slice.ReconstructSlice
Task type:
class
Inputs:
nx_path* : str

Path to the input NX file.

config_dict* : dict[str, Any]

Configuration dictionary for Nabu. Must include at least “dataset” -> “location”, pointing to the input NX file.(see https://www.silx.org/pub/nabu/doc/nabu_config_items.html)

slice_index : int | Literal['first', 'middle', 'last']= middle

Index of the slice to reconstruct. Accepts an integer or one of the fixed strings: “first”, “middle”, “last”.

Outputs:
reconstructed_slice_path : str

Path to the saved reconstructed slice.

slice_index : int

Index of the reconstructed slice.

nabu_dict : dict

Nabu configuration dictionary used for reconstruction.

processing_options : dict

Resolved Nabu processing options used by ProcessConfig.

ReconstructVolume#

Identifier:
ewokstomo.tasks.reconstruct_volume.ReconstructVolume
Task type:
class
Inputs:
nx_path* : pathlib.Path

Path to the input NX file containing the tomography data.

config_dict* : dict

A dictionary containing parameters used to override Nabu’s default configuration. Must include at least ‘dataset’ -> ‘location’, pointing to the input NX file. (see https://www.silx.org/pub/nabu/doc/nabu_config_items.html)

slice_index_range : tuple[int, int] | None= None

Optional tuple specifying the (start, end) indices of slices to reconstruct. If not provided, the entire volume will be reconstructed.

Outputs:
reconstructed_volume_path : str

The file path to the saved reconstructed volume.

nabu_dict : dict

The Nabu configuration dictionary used for reconstruction.

processing_options : dict

The resolved Nabu processing options used by ProcessConfig.

OnlineReconstructSlice#

(ESRF-only) Perform real-time tomography reconstruction on streaming data.

This task connects to a live scan stream and performs incremental reconstruction by processing projections in batches. It includes flat field correction, phase retrieval, and FBP reconstruction.

The reconstruction is performed on a single slice (middle by default) to minimize computational cost while providing real-time feedback.

Required Inputs

scan_key : str Blissdata scan key for accessing the live stream output_path : str Directory path where reconstructed slice files will be saved. Individual batch results are saved as reconstructed_slice_{start}_{end}.h5 rotation_motor : str Name of the rotation axis motor in the scan total_nb_projection : int Total expected number of projections in the scan center_of_rotation : float Center of rotation position batch_size : int Number of projections to process in each batch, default is 100 reduced_dark_path : str Path to HDF5 file containing reduced dark frames reduced_flat_path : str Path to HDF5 file containing reduced flat frames distance_m: Effective propagation distance (m) energy_keV: Energy (keV) pixel_size_m: detector pixel size (m)

Optional Inputs

delta_beta : float Delta/beta ratio for Paganin phase retrieval. Default is 100. halftomo : bool Whether the scan is a half-tomography (180°). Default is False. padding_mode : str Sinogram padding mode. Default is ‘edges’. extra_options : dict Additional backprojector options. Default is {‘centered_axis’: True}. slice_index : int or str Slice index to reconstruct. Can be an integer index or ‘middle’, ‘first’, ‘last’. Default is ‘middle’.

Outputs

reconstructed_slices_directory : str Path to the saved reconstructed slice files

Identifier:
ewokstomo.tasks.online.reconstruct_slice.OnlineReconstructSlice
Task type:
class
Inputs:
batch_size*
center_of_rotation*
distance_m*
energy_keV*
output_path*
pixel_size_m*
reduced_dark_path*
reduced_flat_path*
rotation_motor*
scan_key*
total_nb_projection*
delta_beta
extra_options
halftomo
padding_mode
slice_index
Outputs:
reconstructed_slices_directory

Postprocessing#

ConvertVolumeTo16Bit#

Task to convert volume to 16-bit format and save it to disk. The output file format is determined by the Nabu configuration dictionary provided as input. The task also removes the original 32-bit volume after conversion to save disk space.

Identifier:
ewokstomo.tasks.convert_volume.ConvertVolumeTo16Bit
Task type:
class
Inputs:
reconstructed_volume_path* : str

The file path to the reconstructed volume.

nabu_dict* : dict

The Nabu configuration dictionary used for reconstruction. Used to determine the output file format for the converted volume.

output_format : Literal['hdf5', 'tiff', 'edf', 'jp2']= tiff

The desired output file format for the converted volume. Supported formats include ‘hdf5’, ‘tiff’, ‘edf’, ‘jp2’.

Outputs:
converted_volume_path : str

The file path of the converted 16-bit volume.

Galleries#

BuildProjectionsGallery#

Identifier:
ewokstomo.tasks.buildgallery.BuildProjectionsGallery
Task type:
class
Inputs:
nx_path* : str

Path to the input NX file.

reduced_darks_path* : str

Path to the reduced dark frames HDF5 file.

reduced_flats_path* : str

Path to the reduced flat frames HDF5 file.

bounds : tuple[float, float] | None= None

Intensity bounds (min, max) for image normalization. If not provided, robust defaults are computed automatically.

angle_step : float= 90.0

Angular step in degrees for selecting projections to include in the gallery.

output_format : Literal['jpg', 'png', 'jpeg', 'webp']= jpg

Image format for gallery images (e.g., ‘jpg’, ‘png’).

overwrite : bool= True

Whether to overwrite existing gallery images.

image_size : int= 1000

Maximum size (in pixels) for the largest dimension of gallery images. Images larger than this will be downsampled.

Outputs:
processed_data_dir : str

Directory containing the processed data.

gallery_path : str

Path to the created gallery directory.

BuildSlicesGallery#

Create two gallery images from a reconstructed slice (full-size suffixed _large, and a 200x200 resized version). The large image is downsampled if needed so neither dimension exceeds the configured image_size (default 1000 px).

Identifier:
ewokstomo.tasks.buildgallery.BuildSlicesGallery
Task type:
class
Inputs:
reconstructed_slice_path* : str

Path to the reconstructed slice file.

bounds : tuple[float, float] | None= None

Intensity bounds (min, max) for image normalization. If not provided, robust defaults are computed automatically.

output_format : Literal['jpg', 'png', 'jpeg', 'webp']= jpg

Image format for gallery images (e.g., ‘jpg’, ‘png’).

overwrite : bool= True

Whether to overwrite existing gallery images.

image_size : int= 1000

Maximum size (in pixels) for the largest dimension of gallery images. Images larger than this will be downsampled.

Outputs:
processed_data_dir : str

Directory containing the processed data.

gallery_path : str

Path to the created gallery directory.

gallery_image_path : str

Path to the created gallery image.

BuildVolumeGallery#

Create gallery images from a reconstructed 3D volume.

For each axis (X, Y, Z), extract slices at 1/4, 2/4 and 3/4 of the volume extent and save them to the gallery directory.

Identifier:
ewokstomo.tasks.buildgallery.BuildVolumeGallery
Task type:
class
Inputs:
reconstructed_volume_path* : str

Path to the reconstructed 3D TIFF volume file.

bounds : tuple[float, float] | None= None

Intensity bounds (min, max) for image normalization. If not provided, robust defaults are computed automatically.

output_format : Literal['jpg', 'png', 'jpeg', 'webp']= jpg

Image format for gallery images (e.g., ‘jpg’, ‘png’).

overwrite : bool= True

Whether to overwrite existing gallery images.

image_size : int= 1000

Maximum size (in pixels) for the largest dimension of gallery images. Images larger than this will be downsampled.

Outputs:
processed_data_dir : str

Directory containing the processed data.

gallery_path : str

Path to the created gallery directory.

gallery_image_paths : list[str]

Paths to the created gallery images.

ESRF Data Portal integration#

BuildDataPortalMetadata#

(ESRF-only) Convert Nabu processing options into Data Portal metadata.

Identifier:
ewokstomo.tasks.dataportalupload.BuildDataPortalMetadata
Task type:
class
Inputs:
processing_options : dict[str, Any] | None= None

Nabu processing options dictionary to convert into Data Portal metadata.

Outputs:
dataportal_metadata : dict[str, Any]

Generated Data Portal metadata dictionary.

DataPortalUpload#

(ESRF-only) Upload a processed dataset folder to the Data Portal using pyicat_plus.

Identifier:
ewokstomo.tasks.dataportalupload.DataPortalUpload
Task type:
class
Inputs:
process_folder_path* : str

Path to the processed dataset folder to upload.

metadata : dict[str, Any] | None= None

Optional metadata dictionary to include in the upload.

dry_run : bool= False

If True, simulate the upload without performing it.

dataset : str | None= None

Optional dataset name to use for the upload.

Energy and beamline calculations#

ComputeBMSpectrum#

Compute a bending-magnet (BM) spectrum using XOPPY’s xoppy_calc_bm.

Inputs (units):

  • TYPE_CALC (int): must be 0.

  • VER_DIV (int): vertical divergence model, {0, 2}.

  • MACHINE_NAME (str), RB_CHOICE (int), MACHINE_R_M (m).

  • BFIELD_T (T), BEAM_ENERGY_GEV (GeV), CURRENT_A (A), HOR_DIV_MRAD (mrad).

  • PHOT_ENERGY_MIN / PHOT_ENERGY_MAX (eV), NPOINTS (int), LOG_CHOICE (0/1).

  • PSI_* (mrad) and PSI_NPOINTS (int), FILE_DUMP (bool).

Outputs:

  • energy_eV (eV), sorted ascending.

  • flux (phot/s/0.1%bw) as returned by XOPPY.

  • spectral_power (W/eV).

  • cumulated_power (W).

Identifier:
ewokstomo.tasks.energycalculation.ComputeBMSpectrum
Task type:
class
Inputs:
BEAM_ENERGY_GEV*
BFIELD_T*
CURRENT_A*
FILE_DUMP*
HOR_DIV_MRAD*
LOG_CHOICE*
MACHINE_NAME*
MACHINE_R_M*
NPOINTS*
PHOT_ENERGY_MAX*
PHOT_ENERGY_MIN*
PSI_MAX*
PSI_MIN*
PSI_MRAD_PLOT*
PSI_NPOINTS*
RB_CHOICE*
TYPE_CALC*
VER_DIV*
Outputs:
cumulated_power
energy_eV
flux
spectral_power

ComputeWigglerSpectrum#

Compute a wiggler spectrum on an aperture using xoppy_calc_wiggler_on_aperture.

Inputs (units):

  • PHOT_ENERGY_MIN / PHOT_ENERGY_MAX (eV), NPOINTS (int).

  • ENERGY (GeV), CURRENT (mA).

  • FIELD, NPERIODS (int), ULAMBDA (m), K (–), NTRAJPOINTS (int), FILE (str).

  • SLIT_*: distances in m/mm per name; flags as ints.

  • SHIFT_X_VALUE (m), SHIFT_BETAX_VALUE (rad).

  • TRAJ_RESAMPLING_FACTOR, SLIT_POINTS_FACTOR (floats), LOG_CHOICE (0/1).

Outputs:

  • energy_eV (eV), sorted ascending.

  • flux (phot/s/0.1%bw) as returned by XOPPY.

  • spectral_power (W/eV).

  • cumulated_power (W).

Identifier:
ewokstomo.tasks.energycalculation.ComputeWigglerSpectrum
Task type:
class
Inputs:
CURRENT*
ENERGY*
FIELD*
FILE*
K*
LOG_CHOICE*
NPERIODS*
NPOINTS*
NTRAJPOINTS*
PHOT_ENERGY_MAX*
PHOT_ENERGY_MIN*
SHIFT_BETAX_FLAG*
SHIFT_BETAX_VALUE*
SHIFT_X_FLAG*
SHIFT_X_VALUE*
SLIT_CENTER_H_MM*
SLIT_CENTER_V_MM*
SLIT_D*
SLIT_FLAG*
SLIT_HEIGHT_V_MM*
SLIT_NY*
SLIT_POINTS_FACTOR*
SLIT_WIDTH_H_MM*
TRAJ_RESAMPLING_FACTOR*
ULAMBDA*
Outputs:
cumulated_power
energy_eV
flux
spectral_power

ApplyAttenuators#

Apply a stack of attenuators to the source spectrum (and optionally flux).

Inputs

energy_eV : numpy.ndarray Photon energy grid in electron-volts. spectral_power : numpy.ndarray Power spectrum (W/eV). attenuators : dict[str, dict] Mapping where each value contains material, thickness_mm and optional density_g_cm3. material accepts element symbols (e.g. "Al"), NIST aliases (e.g. "kapton") or chemical formulae parsable by :mod:xraylib. order : list[str], optional Explicit stacking order of the attenuator keys. Defaults to the dictionary insertion order. flux : numpy.ndarray, optional Source flux array (phot/s/0.1%bw) matching energy_eV.

Outputs

energy_eV : numpy.ndarray Same energy grid passed through. transmission : numpy.ndarray Cumulative transmission of the attenuator stack. attenuated_spectral_power : numpy.ndarray spectral_power multiplied by transmission. attenuated_flux : numpy.ndarray | None flux multiplied by transmission when provided, otherwise None.

Identifier:
ewokstomo.tasks.energycalculation.ApplyAttenuators
Task type:
class
Inputs:
attenuators*
energy_eV*
spectral_power*
flux
order
Outputs:
attenuated_flux
attenuated_spectral_power
energy_eV
transmission

SpectrumStats#

Stats on an attenuated spectrum.

Inputs

  • energy_eV: array-like (eV)

  • attenuated_flux : array-like (ph/s/0.1%bw)

Outputs

  • mean_energy_eV: Flux-weighted mean using bin weights: weights = flux * ΔE / (0.001 * E).

  • mean_idx (int): Index of energy_eV closest to mean_energy_eV (−1 if N/A).

  • pic_energy_eV: energy at which flux * ΔE / (0.001 * E) is maximal (NaN if N/A).

  • pic_idx (int): Index of that maximum (−1 if N/A).

Identifier:
ewokstomo.tasks.energycalculation.SpectrumStats
Task type:
class
Inputs:
attenuated_flux*
energy_eV*
Outputs:
mean_energy_eV
mean_idx
pic_energy_eV
pic_idx