API Reference

This presents API intended to be accessed within Tomviz operator modules.

Dataset

The Dataset class for managing volumetric and tilt series data. This is always passed as the first argument within an operator’s transform() function.

class tomviz.dataset.Dataset

Bases: ABC

Abstract base class for tomviz Dataset objects.

The Dataset is the standard object that is passed to operators within tomviz. It provides a unified interface for accessing and manipulating tilt image stacks and volumetric data, including scalar arrays, spacing information, tilt series metadata (such as tilt angles), and calibration data (dark/white fields).

This object will always be automatically provided as the first argument in the transform() function within operators. For example, for the Rotate operator:

def transform(dataset, rotation_angle=90.0, rotation_axis=0):
    # ...

    array = dataset.active_scalars

    # ...

Note

Concrete subclasses of this abstract base class are internal to tomviz. This documentation describes the public API that is accessible on Dataset instances passed to operators and other user-facing code. Users should interact with Dataset objects through this interface rather than instantiating subclasses directly.

abstract property active_scalars: ndarray

The currently active scalar array data as a numpy array.

The shape and dtype depend on the specific dataset.

abstract property active_name: str

The name of the currently active scalar array.

abstract property num_scalars: int

The total number of scalar arrays stored in this dataset.

abstract property scalars_names: list[str]

List containing the name of each scalar array in the dataset.

abstractmethod scalars(name=None)

Get a scalar array by name.

Parameters:

name (str | None) – The name of the scalar array to retrieve. If None, returns the active scalar array.

Returns:

The requested scalar array data.

Raises:

KeyError – If the specified name does not exist in the dataset.

Return type:

ndarray

abstractmethod set_scalars(name, array)

Add or update a scalar array in the dataset.

Parameters:

• name (str) – The name to assign to this scalar array. If a field with this name already exists, it will be overwritten.

• array (ndarray) – The scalar array data to store.

abstractmethod remove_scalars(name)

Remove a scalar array from the dataset.

Parameters:

name (str) – The name of the scalar array to remove.

Raises:

KeyError – If the specified name does not exist in the dataset.

abstract property spacing: tuple[int, int, int]

Voxel spacing in physical units for (x, y, z) dimensions.

Units depend on the dataset but are typically in nanometers or similar physical units.

abstract property tilt_angles: ndarray | None

Array of tilt angles for tomographic tilt series.

Tilt angles are typically in degrees for each projection in a tilt series. Returns None if this is not a tilt series dataset or if tilt angles have not been set.

abstract property tilt_axis: int | None

The axis index around which tilting occurs in a tomographic tilt series.

• 0 = x-axis

• 1 = y-axis

• 2 = z-axis

• None = not applicable or not set

abstract property scan_ids: ndarray | None

Array of scan IDs associated with each projection in a tilt series.

Returns None if scan IDs have not been set.

abstract property dark: ndarray | None

Dark field calibration data.

Dark field images are captured with no illumination and represent the baseline signal level of the detector (electronic noise, thermal noise, etc.). Returns None if not available.

abstract property white: ndarray | None

White field (flat field) calibration data.

White field images are captured with uniform illumination and no sample, representing the detector response and illumination variations. Used for flat-field correction. Returns None if not available.

abstract property file_name: str | None

The original filename this dataset was loaded from.

Returns None if the dataset was not loaded from a file or if the filename is not available.

abstract property metadata: dict

Dictionary containing arbitrary metadata associated with the dataset.

Can include acquisition parameters, instrument settings, timestamps, etc.

abstractmethod create_child_dataset()

Create a new child dataset derived from this dataset.

Child datasets typically share some properties with their parent but may represent derived or processed versions of the data.

This is often used, for example, in reconstruction operators, for creating reconstruction output objects.

Returns:

A new Dataset instance that is a child of this dataset.

Return type:

Dataset

Utils

Utility functions that may be used within operators.

tomviz.utils.zoom_shape(input, zoom)

Returns the shape of the output array for scipy.ndimage.interpolation.zoom

Parameters:

• input (ndarray)

• zoom (ndarray)

Return type:

tuple[int]

tomviz.utils.rotate_shape(input, angle, axes)

Returns the shape of the output array of scipy.ndimage.interpolation.rotate derived from: https://github.com/scipy/scipy/blob/v0.16.1/scipy/ndimage/ interpolation.py #L578. We are duplicating the code here so we can generate an array of the right shape and array order to pass into the rotate function.

Parameters:

• input (ndarray)

• angle (float)

• axes (tuple[int, int])

Return type:

tuple[int]

tomviz.utils.apply_to_each_array(func)

This decorator causes an operator transform() function to automatically run one time for every array.

For example, for the rotation operator:

@apply_to_each_array
def transform(dataset, rotation_angle=90.0, rotation_axis=0):
    # ...

The transform() function will be executed one time for every array. When executing the transform() function, the dataset object will only contain a single array on dataset.active_scalars each time.

This allows an operator transform() function to be written in a way that appears to only operate on one array, but then automatically be ran multiple times to apply to each array.

The final dataset object will automatically contain each of the transformed arrays on it.

tomviz.utils.pad_array(array, padding, tilt_axis)

Add padding to an array. Ignore the tilt axis.

The resulting padded array can eventually be depadded by calling the depad_array() function.

Parameters:

• array (ndarray)

• padding (int)

• tilt_axis (int)

Return type:

ndarray

tomviz.utils.depad_array(array, padding, tilt_axis)

Remove padding from an array. Ignore the tilt axis.

Parameters:

• array (ndarray)

• padding (int)

• tilt_axis (int)

Return type:

ndarray

tomviz.utils.make_spreadsheet(column_names, table, axes_labels=None, axes_log_scale=None)

Make a spreadsheet object to use within Tomviz

If returned from an operator, this will ultimately appear within the pipeline, and will be save-able to a JSON file.

The output of this function ought to be included in the returned dictionary. For example:

spreadsheet = utils.make_spreadsheet(column_names, table)

return {
    'table_data': spreadsheet,
}

Parameters:

• column_names (list[str])

• table (ndarray)

• axes_labels (tuple[str, str])

• axes_log_scale (tuple[bool, bool])

Return type:

vtkTable

Operators

Operators for data transformation and processing.

class tomviz.operators.Progress(operator)

Bases: object

Class used to update operator progress.

This often exists as self.progress on an Operator class.

An example of how it can be utilized within a transform() function is provided below:

class MyOperator(Operator):
    def transform(self, dataset, ...):
        self.progress.maximum = 100

        for i in range(100):
            self.progress.value = i
            self.progress.message = f'Running: {i}'

property maximum: int

Property defining the maximum progress value

property value: int

Property defining the current progress value

property message: str

Property defining the current progress message

class tomviz.operators.Operator(*args, **kwargs)

Bases: object

The base operator class from which all operators should be derived.

Progress can be utilized and modified via the self.progress object. Details about the self.progress object interface can be see in the tomviz.operators.Progress class.

class tomviz.operators.CancelableOperator(*args, **kwargs)

Bases: Operator

A cancelable operator allows the user to interrupt the execution of the operator. The canceled property can be using in the transform(…) method to break out when the operator is canceled.

To utilize this class, the transform() function must be defined as a method within a class that inherits from Progress within the operator module. For example:

import tomviz.operators

class MyCancelableOperator(tomviz.operators.CancelableOperator):
    def transform(self, dataset, ...):
        while not self.canceled:
            # Do work

Note how self.canceled is checked in order to determine whether the operator was canceled or not. If it was canceled, the transform() function should abort.

This operator may also report progress as well in self.progress. See the generic Operator class for details.

property canceled: bool

returns True if the operator has been canceled, False otherwise.

class tomviz.operators.CompletableOperator(*args, **kwargs)

Bases: CancelableOperator

A completable operator allows a user to interrupt the execution of the operator using either “cancel” or “complete”. The completable property can be used in the transform(…) method to break out when an operator is finished early, like if an iterative algorithm is a reasonable quality before the designated iterations are reached. Use similar to “cancel”, but be sure to return data.

To utilize this class, the transform() function must be defined as a method within a class that inherits from CompletableOperator within the operator module. For example:

import tomviz.operators

class MyCompletableOperator(tomviz.operators.CompletableOperator):
    def transform(self, dataset, ...):
        while True:
            if self.completed:
                # Break out of the iterative loop and return the current
                # results.

Note how self.completed is checked in order to determine whether the operator was completed or not. If completed, the transform function should skip to the end and return the current dataset.

self.canceled may also be used in this operator, since it inherits from CancelableOperator as well.

This operator may also report progress as well in self.progress. See the generic Operator class for details.

property completed: bool

returns True if the operator is early completed (from Button), False otherwise

Note

This API documentation is automatically generated from the source code docstrings.