The clara.viz.core.DataDefinition class can be used to specify 3D volume data or 2D image data (also 2D multi-resolution data). It also holds information about the data, such as the physical size of data elements or the order and organization of the data. Finally it has information on how data is transformed (flipped or permuted) before used.
There are several possible ways to use the DataDefintion class.
Load from file
There are high level functions which load the data from a given filename and populate the class members with the information and data from that file. The code below will load the data from the NIFTI file “CT.nii.gz”.
from clara.viz.core import DataDefinition
data_definition = DataDefinition('CT.nii.gz')
Multiple input arrays
In some cases multiple data arrays need to be specified, such as a density volume and a mask volume. For this usage case files can be appended to a DataDefinition object.
from clara.viz.core import DataDefinition
data_definition = DataDefinition()
data_definition.append('density.nii.gz', 'DXYZ')
data_definition.append('mask.nii.gz', 'MXYZ')
Settings
The DataDefintion class also stores the settings for the renderer. The settings are organized as a dictonary and can be loaded form a JSON file.
data_definition.load_settings('settings.json')
Direct data input
There is also a ‘low level’ way to specify as numpy arrays. For this the DataDefinition class has a sublcass clara.viz.core.DataDefinition.Array.
import numpy as np
input = np.fromfile('data.raw', dtype=np.int16)
input = input.reshape((512, 512, 240))
from clara.viz.core import DataDefinition
array = DataDefinition.Array()
array.levels = [input]
array.dimension_order = "DXYZ"
array.permute_axes = [0,3,1,2]
array.flip_axes = [False, True, False, False]
array.element_sizes [[1.0, 1.16, 1.0, 1.0]]
data_definition = DataDefinition()
data_definition.arrays.append(array)
Multi resolution data
ClaraViz also supports rendering of multi-resolution 2D image data which is for example used in digital pathology. Multi-resoltution 2D images can be huge, hundrets of million of pixels, multiple GBytes of data. Therefore data for multi-resolution 2D images is loaded on demand, that means data is not loaded in a whole upfront, but if a portion of the image is visible, it’s loaded exactly at that point of time.
To support this the DataDefintion class uses cuCIM. For the user this is completely hidden, the user just specifies the file name.
from clara.viz.core import DataDefinition
data_definition = DataDefinition('large_multi_res_image.tiff')
It’s also possible for the user to provide a custum on demand data fetch callback function.