Clara Viz Core API Reference

clara-viz-core: Core functionality for Clara Viz.

class clara.viz.core.Array
__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: clara.viz.core._viz.Array, array: numpy.ndarray, dimension_order: str = ‘’, permute_axes: List[int] = [], flip_axes: List[bool] = [], element_size: List[float] = []) -> None

Construct an array.

Parameters
  • array – numpy array

  • dimension_order – a string defining the data organization and format. Each character defines a dimension starting with the fastest varying axis and ending with the slowest varying axis. For example a 2D color image is defined as ‘CXY’, a time sequence of density volumes is defined as ‘DXYZT’. Each character can occur only once. Either one of the data element definition characters ‘C’, ‘D’ or ‘M’ and the ‘X’ axis definition has to be present. - ‘X’: width - ‘Y’: height - ‘Z’: depth - ‘T’: time - ‘I’: sequence - ‘C’: RGB(A) color - ‘D’: density - ‘M’: mask

  • permute_axes – Permutes the given data axes, e.g. to swap x and y of a 3-dimensional density array specify (0, 2, 1, 3)

  • flip_axes – flips the given axes

  • element_size – Physical size of each element, the order is defined by the ‘dimension_order’ field. For elements which have no physical size like ‘M’ or ‘T’ the corresponding value is 1.0.

  1. __init__(self: clara.viz.core._viz.Array, levels: List[numpy.ndarray], dimension_order: str = ‘’, permute_axes: List[int] = [], flip_axes: List[bool] = [], element_sizes: List[List[float]] = []) -> None

Construct an array holding multi-dimensional data.

Parameters
  • levels – array of numpy arrays with the data for each level for multi-dimensional data, an array with a single numpy array for other (e.g. volume) data

  • dimension_order – a string defining the data organization and format. Each character defines a dimension starting with the fastest varying axis and ending with the slowest varying axis. For example a 2D color image is defined as ‘CXY’, a time sequence of density volumes is defined as ‘DXYZT’. Each character can occur only once. Either one of the data element definition characters ‘C’, ‘D’ or ‘M’ and the ‘X’ axis definition has to be present. - ‘X’: width - ‘Y’: height - ‘Z’: depth - ‘T’: time - ‘I’: sequence - ‘C’: RGB(A) color - ‘D’: density - ‘M’: mask

  • permute_axes – Permutes the given data axes, e.g. to swap x and y of a 3-dimensional density array specify (0, 2, 1, 3)

  • flip_axes – flips the given axes

  • element_sizes – Physical size of an element for each level. The order is defined by the ‘dimension_order’ field. For elements which have no physical size like ‘M’ or ‘T’ the corresponding value is 1.0. For multi-dimensional data this is an array of element sizes, else an array with a single element.

property dimension_order

data organization

property element_sizes

physical size of each element for each level

property flip_axes

flips the given axes

property levels

numpy array for each level

property permute_axes

permutes the given axes

class clara.viz.core.DataDefinition(path: Optional[pathlib.Path] = None, dimension_order='')[source]

Defines the data used by the renderer.

arrays

A list of ‘Array’ elements holding the volume data

settings

The render settings

fetch_func

A function to be called on demand data fetches

class Array(array=None, dimension_order='', order='')[source]

Defines one array.

levels

array of numpy arrays with the data for each level for multi-dimensional data, an array with a single numpy array for other (e.g. volume) data

element_sizes

Physical size of an element for each level. The order is defined by the ‘dimension_order’ field. For elements which have no physical size like ‘M’ or ‘T’ the corresponding value is 1.0. For multi-dimensional data this is an array of element sizes, else an array with a single element. Default: [1.0, 1.0, …]

dimension_order

A string defining the data organization and format. Each character defines a dimension starting with the fastest varying axis and ending with the slowest varying axis. For example a 2D color image is defined as ‘CXY’, a time sequence of density volumes is defined as ‘DXYZT’. Each character can occur only once. Either one of the data element definition characters ‘C’, ‘D’ or ‘M’ and the ‘X’ axis definition has to be present. - X: width - Y: height - Z: depth - T: time - I: sequence - C: RGB(A) color - D: density - M: mask

permute_axes

Permutes the given data axes, e.g. to swap x and y of a 3-dimensional density array specify [0, 2, 1, 3]

flip_axes

Flips the given axes, e.g. to flip the x axis of a 3-dimensional density array specify [False, True, False, False]

__init__(array=None, dimension_order='', order='')[source]

Construct an array

Parameters
  • array – numpy array with the data (optional)

  • dimension_order – a string defining the data organization and format (optional)

  • order – deprecated since 0.2, use the ‘dimension_order’ argument instead

property array

Deprecated since version 0.2: use the ‘levels’ array instead

Get the numpy array

Returns

numpy array

property element_size

Deprecated since version 0.2: use the ‘element_sizes’ array instead

Get the physical size of each element

Returns

physical size of each element

property order

Deprecated since version 0.2: use the ‘dimension_order’ attribute instead

Get the dimension order

Returns

A string defining the data organization and format

__init__(path: Optional[pathlib.Path] = None, dimension_order='')[source]

Construct a DataDefinition object

Parameters
  • path – data file to load (optional)

  • dimension_order – a string defining the data organization and format, if not provided it’s set to ‘DXYZ’ for three dimensional volume data and to ‘CXY’ for two dimensional image data (optional)

append(path: pathlib.Path, dimension_order='')[source]

Append a file to the DataDefinition.

Parameters
  • path – path to file

  • dimension_order – a string defining the data organization and format, if not provided it’s set to ‘DXYZ’ for three dimensional volume data and to ‘CXY’ for two dimensional image data

load_settings(path: pathlib.Path)[source]

Read settings from a JSON file

Parameters

path – path to the JSON file to read

class clara.viz.core.ImageCapsule
__init__(*args, **kwargs)
class clara.viz.core.ImageType
class ImageType

Members:

RAW_RGB_U8_DEPTH_U8 : RAW uncompressed RGB unsigned int 8-bit with depth uinsigned int 8-bit

JPEG : JPEG

JPEG = <ImageType.JPEG: 2>
RAW_RGB_U8_DEPTH_U8 = <ImageType.RAW_RGB_U8_DEPTH_U8: 1>
__init__(self: clara.viz.core._viz.ImageType.ImageType, value: int) None
property name
property value
JPEG = <ImageType.JPEG: 2>
RAW_RGB_U8_DEPTH_U8 = <ImageType.RAW_RGB_U8_DEPTH_U8: 1>
__init__(*args, **kwargs)
class clara.viz.core.InterfaceSelector
ALL = <InterfaceSelector.ALL: 0>
BACKGROUND_LIGHT = <InterfaceSelector.BACKGROUND_LIGHT: 8>
CAMERA = <InterfaceSelector.CAMERA: 1>
CAMERA_APERTURE = <InterfaceSelector.CAMERA_APERTURE: 2>
DATA = <InterfaceSelector.DATA: 3>
DATA_CONFIG = <InterfaceSelector.DATA_CONFIG: 4>
DATA_CROP = <InterfaceSelector.DATA_CROP: 5>
DATA_VIEW = <InterfaceSelector.DATA_VIEW: 6>
class InterfaceSelector

Members:

ALL

CAMERA

CAMERA_APERTURE

DATA

DATA_CONFIG

DATA_CROP

DATA_VIEW

LIGHT

BACKGROUND_LIGHT

POST_PROCESS_DENOISE

POST_PROCESS_TONEMAP

RENDER_SETTINGS

TRANSFER_FUNCTION

VIEW

ALL = <InterfaceSelector.ALL: 0>
BACKGROUND_LIGHT = <InterfaceSelector.BACKGROUND_LIGHT: 8>
CAMERA = <InterfaceSelector.CAMERA: 1>
CAMERA_APERTURE = <InterfaceSelector.CAMERA_APERTURE: 2>
DATA = <InterfaceSelector.DATA: 3>
DATA_CONFIG = <InterfaceSelector.DATA_CONFIG: 4>
DATA_CROP = <InterfaceSelector.DATA_CROP: 5>
DATA_VIEW = <InterfaceSelector.DATA_VIEW: 6>
LIGHT = <InterfaceSelector.LIGHT: 7>
POST_PROCESS_DENOISE = <InterfaceSelector.POST_PROCESS_DENOISE: 9>
POST_PROCESS_TONEMAP = <InterfaceSelector.POST_PROCESS_TONEMAP: 10>
RENDER_SETTINGS = <InterfaceSelector.RENDER_SETTINGS: 11>
TRANSFER_FUNCTION = <InterfaceSelector.TRANSFER_FUNCTION: 12>
VIEW = <InterfaceSelector.VIEW: 13>
__init__(self: clara.viz.core._viz.InterfaceSelector.InterfaceSelector, value: int) None
property name
property value
LIGHT = <InterfaceSelector.LIGHT: 7>
POST_PROCESS_DENOISE = <InterfaceSelector.POST_PROCESS_DENOISE: 9>
POST_PROCESS_TONEMAP = <InterfaceSelector.POST_PROCESS_TONEMAP: 10>
RENDER_SETTINGS = <InterfaceSelector.RENDER_SETTINGS: 11>
TRANSFER_FUNCTION = <InterfaceSelector.TRANSFER_FUNCTION: 12>
VIEW = <InterfaceSelector.VIEW: 13>
__init__(*args, **kwargs)
class clara.viz.core.Renderer
__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: clara.viz.core._viz.Renderer) -> None

Constructor of the Clara Viz renderer

  1. __init__(self: clara.viz.core._viz.Renderer, density: numpy.ndarray, mask: Optional[numpy.ndarray] = None, view_mode: clara.viz.core._viz.ViewMode.ViewMode = <ViewMode.CINEMATIC: 0>, settings: json = None) -> None

Constructor of the Clara Viz renderer to render a density volume with an optional segmentation mask volume

Parameters
  • density – numpy array with density values

  • mask – numpy array with mask values

  • view_mode – initial view mode

  • settings – initial settings in JSON format

  1. __init__(self: clara.viz.core._viz.Renderer, data_definition: object, view_mode: clara.viz.core._viz.ViewMode.ViewMode = <ViewMode.CINEMATIC: 0>) -> None

Constructor of the Clara Viz renderer with a DataDefinition object

Parameters
  • data_definition – a DataDefinition object

  • view_mode – initial view mode

create_video_stream(self: clara.viz.core._viz.Renderer, callback: Callable[[object, bool], None]) clara.viz.core._viz.VideoStream

Create a video stream.

Parameters

callback – video data callback function. The function receives the video stream data and a boolean flag. If this is true then this is the first data segment of a new stream. This can be triggered when e.g. the resolution changed. When writing to a file this can be used to close the current file and start writing to a new file. When streaming to a browser then a new MediaSource SourceBuffer object needs to be created.

Returns

Video stream object

deduce_settings(self: clara.viz.core._viz.Renderer, view_mode: clara.viz.core._viz.ViewMode.ViewMode = <ViewMode.CINEMATIC: 0>) None

Deduce settings from configured data (data needs to be configered by SetArray()). Make the whole dataset visible. Set a light in correct distance. Set a transfer function using the histogram of the data.

Parameters

view_mode – view mode

get_arrays(self: clara.viz.core._viz.Renderer) List[clara.viz.core._viz.Array]

Get data arrays

Returns

list of clara.viz.Array objects

get_settings(self: clara.viz.core._viz.Renderer) json

Get settings

Returns

json with settings

merge_settings(self: clara.viz.core._viz.Renderer, new_settings: json) None

Merge settings

Parameters

new_settings – json with settings to merge in

render_image(self: clara.viz.core._viz.Renderer, width: int, height: int, image_type: clara.viz.core._viz.ImageType.ImageType = <ImageType.JPEG: 2>) clara.viz.core._viz.ImageCapsule

Render an image.

Parameters
  • width – width of the image to render

  • height – width of the image to render

  • image_type – type of the image to render

Returns

Image data

reset(self: clara.viz.core._viz.Renderer, selector: List[clara.viz.core._viz.InterfaceSelector.InterfaceSelector] = [<InterfaceSelector.ALL: 0>]) None

Reset selected interfaces to default.

Parameters

selectors – list of interfaces to reset to defaults

set_arrays(self: clara.viz.core._viz.Renderer, arrays: List[clara.viz.core._viz.Array], fetch_func: Callable[[int, str, int, List[int], List[int], Callable[[int, int, List[int], List[int], numpy.ndarray], bool]], bool] = None) None

Set data arrays

Parameters
  • array – list of clara.viz.Array objects

  • fetch_func – function to be called on demand data fetches

set_settings(self: clara.viz.core._viz.Renderer, new_settings: json) None

Set settings

Parameters

new_settings – json with new settings

class clara.viz.core.VideoStream
__init__(*args, **kwargs)
configure(self: clara.viz.core._viz.VideoStream, width: int, height: int, frame_rate: float, bit_rate: int) None

Configure the video stream.

Parameters
  • width – Width of the video, value needs to evenly divisible by 2

  • height – Height of the video, value needs to evenly divisible by 2

  • frame_rate – Target framerate of the video. If set to 0.0 the frames will delivered when rendering is done. Converging renderers will deliver the final frame only.

  • bit_rate – Target bitrate of the video

pause(self: clara.viz.core._viz.VideoStream) None

Pause video.

play(self: clara.viz.core._viz.VideoStream) None

Play video.

stop(self: clara.viz.core._viz.VideoStream) None

Stop video. Video stream is closed if it had been open.

class clara.viz.core.ViewMode
CINEMATIC = <ViewMode.CINEMATIC: 0>
SLICE = <ViewMode.SLICE: 1>
SLICE_SEGMENTATION = <ViewMode.SLICE_SEGMENTATION: 2>
TWOD = <ViewMode.TWOD: 3>
class ViewMode

Members:

CINEMATIC :

3D Cinematic render view

The view is using a perspective projection. Data is displayed using realistic lighting and shadows. Transfer functions are used to map from input data to material properties.

SLICE :

3D Slice view

The view is using an orthographic projection. The vector between the camera ‘look_at’ and ‘eye’ points define the view direction. The ‘eye’ point of the camera defines the slice to display within the volumetric data. The size of the data is defined by the data array level configuration ‘size’ and ‘element_size’ parameters, the data is also limited to the data crop settings. The ‘fov’ camera parameter defines the width of the viewing frustum.

SLICE_SEGMENTATION :

3D Slice with segmenation view

Same as the ‘SLICE’ mode above but when a segmentation mask is specified the segments are colored with the transfer function emissive and diffuse color blended with the density of the data.

TWOD :

2D n-dimensional data view

The view is displaying generic n-dimensional data. The section of the data to display is defined by ‘data_view_name’.

CINEMATIC = <ViewMode.CINEMATIC: 0>
SLICE = <ViewMode.SLICE: 1>
SLICE_SEGMENTATION = <ViewMode.SLICE_SEGMENTATION: 2>
TWOD = <ViewMode.TWOD: 3>
__init__(self: clara.viz.core._viz.ViewMode.ViewMode, value: int) None
property name
property value
__init__(*args, **kwargs)