Framework#

AcquisitionGeometry#

The AcquisitionGeometry class holds the system acquisition parameters.

class cil.framework.AcquisitionGeometry[source]#

This class holds the AcquisitionGeometry of the system.

Please initialise the AcquisitionGeometry using the using the static methods:

AcquisitionGeometry.create_Parallel2D()

AcquisitionGeometry.create_Cone2D()

AcquisitionGeometry.create_Parallel3D()

AcquisitionGeometry.create_Cone3D()

We create the appropriate AcquisitionGeometry for our data by using the static methods:

Parallel2D Geometry#

static AcquisitionGeometry.create_Parallel2D(ray_direction=[0, 1], detector_position=[0, 0], detector_direction_x=[1, 0], rotation_axis_position=[0, 0], units='units distance')[source]#

This creates the AcquisitionGeometry for a parallel beam 2D tomographic system

Parameters:

ray_direction (list, tuple, ndarray, optional) – A 2D vector describing the x-ray direction (x,y)
detector_position (list, tuple, ndarray, optional) – A 2D vector describing the position of the centre of the detector (x,y)
detector_direction_x (list, tuple, ndarray) – A 2D vector describing the direction of the detector_x (x,y)
rotation_axis_position (list, tuple, ndarray, optional) – A 2D vector describing the position of the axis of rotation (x,y)
units (string) – Label the units of distance used for the configuration, these should be consistent for the geometry and panel

Returns:

returns a configured AcquisitionGeometry object

Return type:

AcquisitionGeometry

Parallel3D Geometry#

static AcquisitionGeometry.create_Parallel3D(ray_direction=[0, 1, 0], detector_position=[0, 0, 0], detector_direction_x=[1, 0, 0], detector_direction_y=[0, 0, 1], rotation_axis_position=[0, 0, 0], rotation_axis_direction=[0, 0, 1], units='units distance')[source]#

This creates the AcquisitionGeometry for a parallel beam 3D tomographic system

Parameters:

ray_direction (list, tuple, ndarray, optional) – A 3D vector describing the x-ray direction (x,y,z)
detector_position (list, tuple, ndarray, optional) – A 3D vector describing the position of the centre of the detector (x,y,z)
detector_direction_x (list, tuple, ndarray) – A 3D vector describing the direction of the detector_x (x,y,z)
detector_direction_y (list, tuple, ndarray) – A 3D vector describing the direction of the detector_y (x,y,z)
rotation_axis_position (list, tuple, ndarray, optional) – A 3D vector describing the position of the axis of rotation (x,y,z)
rotation_axis_direction (list, tuple, ndarray, optional) – A 3D vector describing the direction of the axis of rotation (x,y,z)
units (string) – Label the units of distance used for the configuration, these should be consistent for the geometry and panel

Returns:

returns a configured AcquisitionGeometry object

Return type:

AcquisitionGeometry

Cone2D Geometry (Fanbeam)#

static AcquisitionGeometry.create_Cone2D(source_position, detector_position, detector_direction_x=[1, 0], rotation_axis_position=[0, 0], units='units distance')[source]#

This creates the AcquisitionGeometry for a cone beam 2D tomographic system

Parameters:

source_position (list, tuple, ndarray) – A 2D vector describing the position of the source (x,y)
detector_position (list, tuple, ndarray) – A 2D vector describing the position of the centre of the detector (x,y)
detector_direction_x (list, tuple, ndarray) – A 2D vector describing the direction of the detector_x (x,y)
rotation_axis_position (list, tuple, ndarray, optional) – A 2D vector describing the position of the axis of rotation (x,y)
units (string) – Label the units of distance used for the configuration, these should be consistent for the geometry and panel

Returns:

returns a configured AcquisitionGeometry object

Return type:

AcquisitionGeometry

Cone3D Geometry#

static AcquisitionGeometry.create_Cone3D(source_position, detector_position, detector_direction_x=[1, 0, 0], detector_direction_y=[0, 0, 1], rotation_axis_position=[0, 0, 0], rotation_axis_direction=[0, 0, 1], units='units distance')[source]#

This creates the AcquisitionGeometry for a cone beam 3D tomographic system

Parameters:

source_position (list, tuple, ndarray, optional) – A 3D vector describing the position of the source (x,y,z)
detector_position (list, tuple, ndarray, optional) – A 3D vector describing the position of the centre of the detector (x,y,z)
detector_direction_x (list, tuple, ndarray) – A 3D vector describing the direction of the detector_x (x,y,z)
detector_direction_y (list, tuple, ndarray) – A 3D vector describing the direction of the detector_y (x,y,z)
rotation_axis_position (list, tuple, ndarray, optional) – A 3D vector describing the position of the axis of rotation (x,y,z)
rotation_axis_direction (list, tuple, ndarray, optional) – A 3D vector describing the direction of the axis of rotation (x,y,z)
units (string) – Label the units of distance used for the configuration, these should be consistent for the geometry and panel

Returns:

returns a configured AcquisitionGeometry object

Return type:

AcquisitionGeometry

Configure the geometry#

This gives us an acquisition geometry object configured with the spatial geometry of the system.

It is then necessary to configure the panel, angular data and dimension labels:

AcquisitionGeometry.set_panel(num_pixels, pixel_size=(1, 1), origin='bottom-left')[source]#

This method configures the panel information of an AcquisitionGeometry object.

Parameters:

num_pixels (int, list, tuple) – num_pixels_h or (num_pixels_h, num_pixels_v) containing the number of pixels of the panel
pixel_size (int, list, tuple, optional) – pixel_size_h or (pixel_size_h, pixel_size_v) containing the size of the pixels of the panel
origin (string, default 'bottom-left') – the position of pixel 0 (the data origin) of the panel ‘top-left’, ‘top-right’, ‘bottom-left’, ‘bottom-right’

Returns:

returns a configured AcquisitionGeometry object

Return type:

AcquisitionGeometry

AcquisitionGeometry.set_angles(angles, initial_angle=0, angle_unit='degree')[source]#

This method configures the angular information of an AcquisitionGeometry object.

Parameters:

angles (list, ndarray) – The angular positions of the acquisition data
initial_angle (float, optional) – The angular offset of the object from the reference frame
angle_unit (string) – The units of the stored angles ‘degree’ or ‘radian’

Returns:

returns a configured AcquisitionGeometry object

Return type:

AcquisitionGeometry

AcquisitionGeometry.set_labels(labels=None)[source]#

This method configures the dimension labels of an AcquisitionGeometry object.

Parameters:: labels (list, optional) – The order of the dimensions describing the data.Expects a list containing at least one of the unique labels: ‘channel’ ‘angle’ ‘vertical’ ‘horizontal’ default = [‘channel’,’angle’,’vertical’,’horizontal’]
Returns:: returns a configured AcquisitionGeometry object
Return type:: AcquisitionGeometry

AcquisitionGeometry.set_channels(num_channels=1, channel_labels=None)[source]#

This method configures the channel information of an AcquisitionGeometry object.

Parameters:

num_channels (int, optional) – The number of channels of data
channel_labels (list, optional) – A list of channel labels

Returns:

returns a configured AcquisitionGeometry object

Return type:

AcquisitionGeometry

Use the geometry#

We can use this geometry to generate related objects. Including a 2D slice AcquisitionGeometry, an AcquisitionData container, and a default ImageGeometry.

AcquisitionGeometry.get_slice(channel=None, angle=None, vertical=None, horizontal=None)[source]#: Returns a new AcquisitionGeometry of a single slice of in the requested direction. Will only return reconstructable geometries.

AcquisitionGeometry.allocate(value=0, **kwargs)[source]#

allocates an AcquisitionData according to the size expressed in the instance

Parameters:

value (number or string, default None allocates empty memory block) – accepts numbers to allocate an uniform array, or a string as ‘random’ or ‘random_int’ to create a random array or None.
dtype (numpy type, default numpy.float32) – numerical type to allocate

AcquisitionGeometry.get_ImageGeometry(resolution=1.0)[source]#: returns a default configured ImageGeometry object based on the AcquisitionGeomerty

ImageGeometry#

The ImageGeometry class holds meta data describing the reconstruction volume of interest. This will be centred on the rotation axis position defined in AcquisitionGeometry, with the z-direction aligned with the rotation axis direction.

class cil.framework.ImageGeometry(voxel_num_x=0, voxel_num_y=0, voxel_num_z=0, voxel_size_x=1, voxel_size_y=1, voxel_size_z=1, center_x=0, center_y=0, center_z=0, channels=1, **kwargs)[source]#

get_slice(channel=None, vertical=None, horizontal_x=None, horizontal_y=None)[source]#: Returns a new ImageGeometry of a single slice of in the requested direction.

clone()[source]#: returns a copy of the ImageGeometry

copy()[source]#: alias of clone

allocate(value=0, **kwargs)[source]#

allocates an ImageData according to the size expressed in the instance

Parameters:

value (number or string, default None allocates empty memory block, default 0) – accepts numbers to allocate an uniform array, or a string as ‘random’ or ‘random_int’ to create a random array or None.
dtype (numpy type, default numpy.float32) – numerical type to allocate

BlockGeometry#

class cil.framework.BlockGeometry(*args, **kwargs)[source]#

get_item(index)[source]#: returns the Geometry in the BlockGeometry located at position index

allocate(value=0, **kwargs)[source]#: Allocates a BlockDataContainer according to geometries contained in the BlockGeometry

Data Containers#

AcquisitionData and ImageData inherit from the same parent DataContainer class, therefore they largely behave the same way.

There are algebraic operations defined for both AcquisitionData and ImageData. Following operations are defined:

binary operations (between two DataContainers or scalar and DataContainer)
- + addition
- - subtraction
- / division
- * multiplication
- ** power
- maximum
- minimum
in-place operations
- +=
- -=
- *=
- **=
- /=
unary operations
- abs
- sqrt
- sign
- conjugate
reductions
- sum
- norm
- dot product

DataContainer#

class cil.framework.DataContainer(array, deep_copy=True, dimension_labels=None, **kwargs)[source]#

Generic class to hold data

Data is currently held in a numpy arrays

property shape#: Returns the shape of the DataContainer

property ndim#: Returns the ndim of the DataContainer

property number_of_dimensions#: Returns the shape of the of the DataContainer

property dtype#: Returns the dtype of the data array.

property size#: Returns the number of elements of the DataContainer

get_dimension_axis(dimension_label)[source]#

Returns the axis index of the DataContainer array if the specified dimension_label(s) match any dimension_labels of the DataContainer or their indices

Parameters:: dimension_label (string or int or tuple of strings or ints) – Specify dimension_label(s) or index of the DataContainer from which to check and return the axis index
Returns:: The axis index of the DataContainer matching the specified dimension_label
Return type:: int or tuple of ints

as_array()[source]#: Returns the pointer to the array.

get_slice(**kw)[source]#: Returns a new DataContainer containing a single slice in the requested direction. Pass keyword arguments <dimension label>=index

reorder(order)[source]#

reorders the data in memory as requested.

Parameters:: order (list, sting) – ordered list of labels from self.dimension_labels

fill(array, **dimension)[source]#

fills the internal data array with the DataContainer, numpy array or number provided

Parameters:

array (DataContainer or subclasses, numpy array or number) – number, numpy array or DataContainer to copy into the DataContainer
dimension – dictionary, optional

if the passed numpy array points to the same array that is contained in the DataContainer, it just returns

In case a DataContainer or subclass is passed, there will be a check of the geometry, if present, and the array will be resorted if the data is not in the appropriate order.

User may pass a named parameter to specify in which axis the fill should happen:

dc.fill(some_data, vertical=1, horizontal_x=32) will copy the data in some_data into the data container.

get_data_axes_order(new_order=None)[source]#

returns the axes label of self as a list

If new_order is None returns the labels of the axes as a sorted-by-key list. If new_order is a list of length number_of_dimensions, returns a list with the indices of the axes in new_order with respect to those in self.dimension_labels: i.e.

>>> self.dimension_labels = {0:'horizontal',1:'vertical'}
>>> new_order = ['vertical','horizontal']
returns [1,0]

clone()[source]#: returns a copy of DataContainer

copy()[source]#: alias of clone

sapyb(a, y, b, out=None, num_threads=2)[source]#

performs a*self + b * y. Can be done in-place

Parameters:

a (multiplier for self, can be a number or a numpy array or a DataContainer)
y (DataContainer)
b (multiplier for y, can be a number or a numpy array or a DataContainer)
out (return DataContainer, if None a new DataContainer is returned, default None.) – out can be self or y.
num_threads (number of threads to use during the calculation, using the CIL C library) – It will try to use the CIL C library and default to numpy operations, in case the C library does not handle the types.

Example

>>> a = 2
>>> b = 3
>>> ig = ImageGeometry(10,11)
>>> x = ig.allocate(1)
>>> y = ig.allocate(2)
>>> out = x.sapyb(a,y,b)

exp(*args, **kwargs)[source]#: Applies exp pixel-wise to the DataContainer

log(*args, **kwargs)[source]#: Applies log pixel-wise to the DataContainer

squared_norm(**kwargs)[source]#: return the squared euclidean norm of the DataContainer viewed as a vector

norm(**kwargs)[source]#: return the euclidean norm of the DataContainer viewed as a vector

dot(other, *args, **kwargs)[source]#: returns the inner product of 2 DataContainers viewed as vectors. Suitable for real and complex data. For complex data, the dot method returns a.dot(b.conjugate())

sum(axis=None, out=None, *args, **kwargs)[source]#

Returns the sum of values in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘sum’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) – Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The sum as a scalar or inside a DataContainer with reduced dimension_labels Default is to accumulate and return data as float64 or complex128

Return type:

scalar or DataContainer

min(axis=None, out=None, *args, **kwargs)[source]#

Returns the minimum pixel value in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘min’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The min as a scalar or inside a DataContainer with reduced dimension_labels

Return type:

scalar or DataContainer

max(axis=None, out=None, *args, **kwargs)[source]#

Returns the maximum pixel value in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘max’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The max as a scalar or inside a DataContainer with reduced dimension_labels

Return type:

scalar or DataContainer

mean(axis=None, out=None, *args, **kwargs)[source]#

Returns the mean pixel value of the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘mean’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The mean as a scalar or inside a DataContainer with reduced dimension_labels Default is to accumulate and return data as float64 or complex128

Return type:

scalar or DataContainer

AcquisitionData#

class cil.framework.AcquisitionData(array=None, deep_copy=True, geometry=None, **kwargs)[source]#

DataContainer for holding 2D or 3D sinogram

as_array()#: Returns the pointer to the array.

clone()#: returns a copy of DataContainer

copy()#: alias of clone

dot(other, *args, **kwargs)#: returns the inner product of 2 DataContainers viewed as vectors. Suitable for real and complex data. For complex data, the dot method returns a.dot(b.conjugate())

property dtype#: Returns the dtype of the data array.

exp(*args, **kwargs)#: Applies exp pixel-wise to the DataContainer

fill(array, **dimension)#

fills the internal data array with the DataContainer, numpy array or number provided

Parameters:

array (DataContainer or subclasses, numpy array or number) – number, numpy array or DataContainer to copy into the DataContainer
dimension – dictionary, optional

if the passed numpy array points to the same array that is contained in the DataContainer, it just returns

In case a DataContainer or subclass is passed, there will be a check of the geometry, if present, and the array will be resorted if the data is not in the appropriate order.

User may pass a named parameter to specify in which axis the fill should happen:

dc.fill(some_data, vertical=1, horizontal_x=32) will copy the data in some_data into the data container.

get_data_axes_order(new_order=None)#

returns the axes label of self as a list

>>> self.dimension_labels = {0:'horizontal',1:'vertical'}
>>> new_order = ['vertical','horizontal']
returns [1,0]

get_dimension_axis(dimension_label)#

Returns the axis index of the DataContainer array if the specified dimension_label(s) match any dimension_labels of the DataContainer or their indices

Parameters:: dimension_label (string or int or tuple of strings or ints) – Specify dimension_label(s) or index of the DataContainer from which to check and return the axis index
Returns:: The axis index of the DataContainer matching the specified dimension_label
Return type:: int or tuple of ints

get_slice(channel=None, angle=None, vertical=None, horizontal=None, force=False)[source]#: Returns a new dataset of a single slice in the requested direction.

log(*args, **kwargs)#: Applies log pixel-wise to the DataContainer

max(axis=None, out=None, *args, **kwargs)#

Returns the maximum pixel value in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘max’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The max as a scalar or inside a DataContainer with reduced dimension_labels

Return type:

scalar or DataContainer

mean(axis=None, out=None, *args, **kwargs)#

Returns the mean pixel value of the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘mean’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The mean as a scalar or inside a DataContainer with reduced dimension_labels Default is to accumulate and return data as float64 or complex128

Return type:

scalar or DataContainer

min(axis=None, out=None, *args, **kwargs)#

Returns the minimum pixel value in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘min’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The min as a scalar or inside a DataContainer with reduced dimension_labels

Return type:

scalar or DataContainer

property ndim#: Returns the ndim of the DataContainer

norm(**kwargs)#: return the euclidean norm of the DataContainer viewed as a vector

property number_of_dimensions#: Returns the shape of the of the DataContainer

partition(num_batches, mode, seed=None)#

Partition the data into num_batches batches using the specified mode.

The modes are

sequential - The data will be partitioned into num_batches batches of sequential indices.
staggered - The data will be partitioned into num_batches batches of sequential indices, with stride equal to num_batches.
random_permutation - The data will be partitioned into num_batches batches of random indices.

Parameters:

num_batches (int) – The number of batches to partition the data into.
mode (str) – The mode to use for partitioning. Must be one of sequential, staggered or random_permutation.
seed (int, optional) – The seed to use for the random permutation. If not specified, the random number generator will not be seeded.

Returns:

Block of AcquisitionData objects containing the data requested in each batch

Return type:

BlockDataContainer

Example

Partitioning a list of ints [0, 1, 2, 3, 4, 5, 6, 7, 8] into 4 batches will return:

[[0, 1, 2], [3, 4], [5, 6], [7, 8]] with sequential
[[0, 4, 8], [1, 5], [2, 6], [3, 7]] with staggered
[[8, 2, 6], [7, 1], [0, 4], [3, 5]] with random_permutation and seed 1

sapyb(a, y, b, out=None, num_threads=2)#

performs a*self + b * y. Can be done in-place

Parameters:

a (multiplier for self, can be a number or a numpy array or a DataContainer)
y (DataContainer)
b (multiplier for y, can be a number or a numpy array or a DataContainer)
out (return DataContainer, if None a new DataContainer is returned, default None.) – out can be self or y.
num_threads (number of threads to use during the calculation, using the CIL C library) – It will try to use the CIL C library and default to numpy operations, in case the C library does not handle the types.

Example

>>> a = 2
>>> b = 3
>>> ig = ImageGeometry(10,11)
>>> x = ig.allocate(1)
>>> y = ig.allocate(2)
>>> out = x.sapyb(a,y,b)

property shape#: Returns the shape of the DataContainer

property size#: Returns the number of elements of the DataContainer

squared_norm(**kwargs)#: return the squared euclidean norm of the DataContainer viewed as a vector

sum(axis=None, out=None, *args, **kwargs)#

Returns the sum of values in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘sum’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The sum as a scalar or inside a DataContainer with reduced dimension_labels Default is to accumulate and return data as float64 or complex128

Return type:

scalar or DataContainer

reorder(order)[source]#

Reorders the data in memory as requested. This is an in-place operation.

Parameters:: order (list or str) – Ordered list of labels from self.dimension_labels, or string ‘astra’ or ‘tigre’.

ImageData#

class cil.framework.ImageData(array=None, deep_copy=False, geometry=None, **kwargs)[source]#

DataContainer for holding 2D or 3D DataContainer

get_slice(channel=None, vertical=None, horizontal_x=None, horizontal_y=None, force=False)[source]#: Returns a new ImageData of a single slice of in the requested direction.

apply_circular_mask(radius=0.99, in_place=True)[source]#

Apply a circular mask to the horizontal_x and horizontal_y slices. Values outside this mask will be set to zero.

This will most commonly be used to mask edge artefacts from standard CT reconstructions with FBP.

Parameters:

radius (float, default 0.99) – radius of mask by percentage of size of horizontal_x or horizontal_y, whichever is greater
in_place (boolean, default True) – If True masks the current data, if False returns a new ImageData object.

Returns:

If in_place = False returns a new ImageData object with the masked data

Return type:

ImageData

as_array()#: Returns the pointer to the array.

clone()#: returns a copy of DataContainer

copy()#: alias of clone

dot(other, *args, **kwargs)#: returns the inner product of 2 DataContainers viewed as vectors. Suitable for real and complex data. For complex data, the dot method returns a.dot(b.conjugate())

property dtype#: Returns the dtype of the data array.

exp(*args, **kwargs)#: Applies exp pixel-wise to the DataContainer

fill(array, **dimension)#

fills the internal data array with the DataContainer, numpy array or number provided

Parameters:

array (DataContainer or subclasses, numpy array or number) – number, numpy array or DataContainer to copy into the DataContainer
dimension – dictionary, optional

if the passed numpy array points to the same array that is contained in the DataContainer, it just returns

In case a DataContainer or subclass is passed, there will be a check of the geometry, if present, and the array will be resorted if the data is not in the appropriate order.

User may pass a named parameter to specify in which axis the fill should happen:

dc.fill(some_data, vertical=1, horizontal_x=32) will copy the data in some_data into the data container.

get_data_axes_order(new_order=None)#

returns the axes label of self as a list

>>> self.dimension_labels = {0:'horizontal',1:'vertical'}
>>> new_order = ['vertical','horizontal']
returns [1,0]

get_dimension_axis(dimension_label)#

Returns the axis index of the DataContainer array if the specified dimension_label(s) match any dimension_labels of the DataContainer or their indices

Parameters:: dimension_label (string or int or tuple of strings or ints) – Specify dimension_label(s) or index of the DataContainer from which to check and return the axis index
Returns:: The axis index of the DataContainer matching the specified dimension_label
Return type:: int or tuple of ints

log(*args, **kwargs)#: Applies log pixel-wise to the DataContainer

max(axis=None, out=None, *args, **kwargs)#

Returns the maximum pixel value in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘max’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The max as a scalar or inside a DataContainer with reduced dimension_labels

Return type:

scalar or DataContainer

mean(axis=None, out=None, *args, **kwargs)#

Returns the mean pixel value of the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘mean’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The mean as a scalar or inside a DataContainer with reduced dimension_labels Default is to accumulate and return data as float64 or complex128

Return type:

scalar or DataContainer

min(axis=None, out=None, *args, **kwargs)#

Returns the minimum pixel value in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘min’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The min as a scalar or inside a DataContainer with reduced dimension_labels

Return type:

scalar or DataContainer

property ndim#: Returns the ndim of the DataContainer

norm(**kwargs)#: return the euclidean norm of the DataContainer viewed as a vector

property number_of_dimensions#: Returns the shape of the of the DataContainer

sapyb(a, y, b, out=None, num_threads=2)#

performs a*self + b * y. Can be done in-place

Parameters:

a (multiplier for self, can be a number or a numpy array or a DataContainer)
y (DataContainer)
b (multiplier for y, can be a number or a numpy array or a DataContainer)
out (return DataContainer, if None a new DataContainer is returned, default None.) – out can be self or y.
num_threads (number of threads to use during the calculation, using the CIL C library) – It will try to use the CIL C library and default to numpy operations, in case the C library does not handle the types.

Example

>>> a = 2
>>> b = 3
>>> ig = ImageGeometry(10,11)
>>> x = ig.allocate(1)
>>> y = ig.allocate(2)
>>> out = x.sapyb(a,y,b)

property shape#: Returns the shape of the DataContainer

property size#: Returns the number of elements of the DataContainer

squared_norm(**kwargs)#: return the squared euclidean norm of the DataContainer viewed as a vector

sum(axis=None, out=None, *args, **kwargs)#

Returns the sum of values in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘sum’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The sum as a scalar or inside a DataContainer with reduced dimension_labels Default is to accumulate and return data as float64 or complex128

Return type:

scalar or DataContainer

reorder(order)[source]#

Reorders the data in memory as requested. This is an in-place operation.

Parameters:: order (list or str) – Ordered list of labels from self.dimension_labels, or string ‘astra’ or ‘tigre’.

VectorData#

class cil.framework.VectorData(array=None, **kwargs)[source]#

DataContainer to contain 1D array

as_array()#: Returns the pointer to the array.

clone()#: returns a copy of DataContainer

copy()#: alias of clone

dot(other, *args, **kwargs)#: returns the inner product of 2 DataContainers viewed as vectors. Suitable for real and complex data. For complex data, the dot method returns a.dot(b.conjugate())

property dtype#: Returns the dtype of the data array.

exp(*args, **kwargs)#: Applies exp pixel-wise to the DataContainer

fill(array, **dimension)#

fills the internal data array with the DataContainer, numpy array or number provided

Parameters:

array (DataContainer or subclasses, numpy array or number) – number, numpy array or DataContainer to copy into the DataContainer
dimension – dictionary, optional

if the passed numpy array points to the same array that is contained in the DataContainer, it just returns

In case a DataContainer or subclass is passed, there will be a check of the geometry, if present, and the array will be resorted if the data is not in the appropriate order.

User may pass a named parameter to specify in which axis the fill should happen:

dc.fill(some_data, vertical=1, horizontal_x=32) will copy the data in some_data into the data container.

get_data_axes_order(new_order=None)#

returns the axes label of self as a list

>>> self.dimension_labels = {0:'horizontal',1:'vertical'}
>>> new_order = ['vertical','horizontal']
returns [1,0]

get_dimension_axis(dimension_label)#

Returns the axis index of the DataContainer array if the specified dimension_label(s) match any dimension_labels of the DataContainer or their indices

Parameters:: dimension_label (string or int or tuple of strings or ints) – Specify dimension_label(s) or index of the DataContainer from which to check and return the axis index
Returns:: The axis index of the DataContainer matching the specified dimension_label
Return type:: int or tuple of ints

get_slice(**kw)#: Returns a new DataContainer containing a single slice in the requested direction. Pass keyword arguments <dimension label>=index

log(*args, **kwargs)#: Applies log pixel-wise to the DataContainer

max(axis=None, out=None, *args, **kwargs)#

Returns the maximum pixel value in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘max’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The max as a scalar or inside a DataContainer with reduced dimension_labels

Return type:

scalar or DataContainer

mean(axis=None, out=None, *args, **kwargs)#

Returns the mean pixel value of the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘mean’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The mean as a scalar or inside a DataContainer with reduced dimension_labels Default is to accumulate and return data as float64 or complex128

Return type:

scalar or DataContainer

min(axis=None, out=None, *args, **kwargs)#

Returns the minimum pixel value in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘min’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The min as a scalar or inside a DataContainer with reduced dimension_labels

Return type:

scalar or DataContainer

property ndim#: Returns the ndim of the DataContainer

norm(**kwargs)#: return the euclidean norm of the DataContainer viewed as a vector

property number_of_dimensions#: Returns the shape of the of the DataContainer

reorder(order)#

reorders the data in memory as requested.

Parameters:: order (list, sting) – ordered list of labels from self.dimension_labels

sapyb(a, y, b, out=None, num_threads=2)#

performs a*self + b * y. Can be done in-place

Parameters:

a (multiplier for self, can be a number or a numpy array or a DataContainer)
y (DataContainer)
b (multiplier for y, can be a number or a numpy array or a DataContainer)
out (return DataContainer, if None a new DataContainer is returned, default None.) – out can be self or y.
num_threads (number of threads to use during the calculation, using the CIL C library) – It will try to use the CIL C library and default to numpy operations, in case the C library does not handle the types.

Example

>>> a = 2
>>> b = 3
>>> ig = ImageGeometry(10,11)
>>> x = ig.allocate(1)
>>> y = ig.allocate(2)
>>> out = x.sapyb(a,y,b)

property shape#: Returns the shape of the DataContainer

property size#: Returns the number of elements of the DataContainer

squared_norm(**kwargs)#: return the squared euclidean norm of the DataContainer viewed as a vector

sum(axis=None, out=None, *args, **kwargs)#

Returns the sum of values in the DataContainer

Parameters:

axis (string or tuple of strings or int or tuple of ints, optional) – Specify the axis or axes to calculate ‘sum’ along. Can be specified as string(s) of dimension_labels or int(s) of indices Default None calculates the function over the whole array
out (ndarray or DataContainer, optional) –
Provide an object in which to place the result. The object must have the correct dimensions and (for DataContainers) the correct dimension_labels, but the type will be cast if necessary. See Output type determination for more details. Default is None

Returns:

The sum as a scalar or inside a DataContainer with reduced dimension_labels Default is to accumulate and return data as float64 or complex128

Return type:

scalar or DataContainer

BlockDataContainer#

A BlockDataContainer can be instantiated from a number of DataContainer and subclasses represents a column vector of DataContainer s.

bdc = BlockDataContainer(DataContainer0, DataContainer1)

This provide a base class that will behave as normal DataContainer.

class cil.framework.BlockDataContainer(*args, **kwargs)[source]#

Class to hold DataContainers as column vector

Provides basic algebra between BlockDataContainer’s, DataContainer’s and subclasses and Numbers

algebra between `BlockDataContainer`s will be element-wise, only if the shape of the 2 `BlockDataContainer`s is the same, otherwise it will fail
algebra between BlockDataContainer`s and `list or numpy array will work as long as the number of rows and element of the arrays match, independently on the fact that the BlockDataContainer could be nested
algebra between BlockDataContainer and one DataContainer is possible. It will require all the DataContainers in the block to be compatible with the DataContainer we want to operate with.
algebra between BlockDataContainer and a Number is possible and it will be done with each element of the BlockDataContainer even if nested

A = [ [B,C] , D] A * 3 = [ 3 * [B,C] , 3* D] = [ [ 3*B, 3*C] , 3*D ]

next()[source]#: python2 backwards compatibility

is_compatible(other)[source]#: basic check if the size of the 2 objects fit

add(other, *args, **kwargs)[source]#

Algebra: add method of BlockDataContainer with number/DataContainer or BlockDataContainer

Param:: other (number, DataContainer or subclasses or BlockDataContainer
Param:: out (optional): provides a placehold for the resul.

subtract(other, *args, **kwargs)[source]#

Algebra: subtract method of BlockDataContainer with number/DataContainer or BlockDataContainer

Param:: other (number, DataContainer or subclasses or BlockDataContainer
Param:: out (optional): provides a placeholder for the result.

multiply(other, *args, **kwargs)[source]#

Algebra: multiply method of BlockDataContainer with number/DataContainer or BlockDataContainer

Param:: other (number, DataContainer or subclasses or BlockDataContainer)
Param:: out (optional): provides a placeholder for the result.

divide(other, *args, **kwargs)[source]#

Algebra: divide method of BlockDataContainer with number/DataContainer or BlockDataContainer

Param:: other (number, DataContainer or subclasses or BlockDataContainer)
Param:: out (optional): provides a placeholder for the result.

power(other, *args, **kwargs)[source]#

Algebra: power method of BlockDataContainer with number/DataContainer or BlockDataContainer

Param:: other (number, DataContainer or subclasses or BlockDataContainer
Param:: out (optional): provides a placeholder for the result.

maximum(other, *args, **kwargs)[source]#

Algebra: power method of BlockDataContainer with number/DataContainer or BlockDataContainer

Param:: other (number, DataContainer or subclasses or BlockDataContainer)
Param:: out (optional): provides a placeholder for the result.

minimum(other, *args, **kwargs)[source]#

Algebra: power method of BlockDataContainer with number/DataContainer or BlockDataContainer

Param:: other (number, DataContainer or subclasses or BlockDataContainer)
Param:: out (optional): provides a placeholder for the result.

sapyb(a, y, b, out, num_threads=2)[source]#

performs axpby element-wise on the BlockDataContainer containers

Does the operation .. math:: a*x+b*y and stores the result in out, where x is self

Parameters:

a – scalar
b – scalar
y – compatible (Block)DataContainer
out – (Block)DataContainer to store the result

Example:#

>>> a = 2
>>> b = 3
>>> ig = ImageGeometry(10,11)
>>> x = ig.allocate(1)
>>> y = ig.allocate(2)
>>> bdc1 = BlockDataContainer(2*x, y)
>>> bdc2 = BlockDataContainer(x, 2*y)
>>> out = bdc1.sapyb(a,bdc2,b)

axpby(a, b, y, out, dtype=<class 'numpy.float32'>, num_threads=2)[source]#: Deprecated method. Alias of sapyb

binary_operations(operation, other, *args, **kwargs)[source]#

Algebra: generic method of algebric operation with BlockDataContainer with number/DataContainer or BlockDataContainer

Provides commutativity with DataContainer and subclasses, i.e. this class’s reverse algebraic methods take precedence w.r.t. direct algebraic methods of DataContainer and subclasses.

This method is not to be used directly

unary_operations(operation, *args, **kwargs)[source]#

Unary operation on BlockDataContainer:

generic method of unary operation with BlockDataContainer: abs, sign, sqrt and conjugate

This method is not to be used directly

copy()[source]#: alias of clone

Partitioner#

This method partitions an instance of tomography AcquisitionData into a number of batches. For example, to use with a stochastic optimisation method.

The partitioning is done by taking batches of angles and the corresponding data collected by taking projections along these angles. The partitioner method chooses what angles go in which batch depending on the mode and takes in an AquisitionData object and outputs a BlockDataContainer where each element in the block is AquisitionData object with the batch of data and corresponding geometry. We consider a batch to be a subset of the AcquisitionData and the verb, to partition, to be the act of splitting into batches.

For example:

from cil.utilities import dataexample
from cil.plugins.astra.operators import ProjectionOperator

# get the data
data = dataexample.SIMULATED_PARALLEL_BEAM_DATA.get()
data.reorder('astra')
data = data.get_slice(vertical='centre')

# create the geometries
ag = data.geometry
ig = ag.get_ImageGeometry()

# partition the data into batches contained in the elements of a BlockDataContainer
data_partitioned = data.partition(num_batches=10, mode='staggered') # Choose mode from `sequential`, `staggered` or `random_permutation`
# From the partitioned data build a BlockOperator container the projectors for each batch
A_partitioned = ProjectionOperator(ig, data_partitioned.geometry, device = "cpu")

print('The total number of angles is ', len(data.geometry.angles))
print('The first 30 angles are ', data.geometry.angles[:30])

print('In batch zero the number of angles is ', len(data_partitioned[0].geometry.angles))
print('The angles in batch zero are ', data_partitioned[0].geometry.angles)
print('The angles in batch one are ', data_partitioned[1].geometry.angles)

The total number of angles is  300
The first 30 angles are  [ 0.   1.2  2.4  3.6  4.8  6.   7.2  8.4  9.6 10.8 12.  13.2 14.4 15.6
16.8 18.  19.2 20.4 21.6 22.8 24.  25.2 26.4 27.6 28.8 30.  31.2 32.4
33.6 34.8]
In batch zero the number of angles is  30
The angles in batch zero are  [  0.  12.  24.  36.  48.  60.  72.  84.  96. 108. 120. 132. 144. 156.
168. 180. 192. 204. 216. 228. 240. 252. 264. 276. 288. 300. 312. 324.
336. 348.]
The angles in batch one are  [  1.2  13.2  25.2  37.2  49.2  61.2  73.2  85.2  97.2 109.2 121.2 133.2
145.2 157.2 169.2 181.2 193.2 205.2 217.2 229.2 241.2 253.2 265.2 277.2
289.2 301.2 313.2 325.2 337.2 349.2]

The partition method is defined as part of:

class cil.framework.Partitioner[source]#

Interface for AcquisitionData to be able to partition itself in a number of batches.

This class, by multiple inheritance with AcquisitionData, allows the user to partition the data, by using the method partition. The partitioning will generate a BlockDataContainer with appropriate AcquisitionData.

partition(num_batches, mode, seed=None)[source]#

Partition the data into num_batches batches using the specified mode.

The modes are

sequential - The data will be partitioned into num_batches batches of sequential indices.
staggered - The data will be partitioned into num_batches batches of sequential indices, with stride equal to num_batches.
random_permutation - The data will be partitioned into num_batches batches of random indices.

Parameters:

num_batches (int) – The number of batches to partition the data into.
mode (str) – The mode to use for partitioning. Must be one of sequential, staggered or random_permutation.
seed (int, optional) – The seed to use for the random permutation. If not specified, the random number generator will not be seeded.

Returns:

Block of AcquisitionData objects containing the data requested in each batch

Return type:

BlockDataContainer

Example

Partitioning a list of ints [0, 1, 2, 3, 4, 5, 6, 7, 8] into 4 batches will return:

[[0, 1, 2], [3, 4], [5, 6], [7, 8]] with sequential
[[0, 4, 8], [1, 5], [2, 6], [3, 7]] with staggered
[[8, 2, 6], [7, 1], [0, 4], [3, 5]] with random_permutation and seed 1

Labels#

Classes which define the accepted labels

class cil.framework.labels.ImageDimension(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Available dimension labels for image data.

Examples

>>> data.reorder([ImageDimension.HORIZONTAL_X, ImageDimension.VERTICAL])
>>> data.reorder(["horizontal_x", "vertical"])

CHANNEL = 'channel'#

VERTICAL = 'vertical'#

HORIZONTAL_X = 'horizontal_x'#

HORIZONTAL_Y = 'horizontal_y'#

class cil.framework.labels.AcquisitionDimension(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Available dimension labels for acquisition data.

Examples

>>> data.reorder([AcquisitionDimension.CHANNEL,
              AcquisitionDimension.ANGLE,
              AcquisitionDimension.HORIZONTAL])
>>> data.reorder(["channel", "angle", "horizontal"])

CHANNEL = 'channel'#

ANGLE = 'angle'#

VERTICAL = 'vertical'#

HORIZONTAL = 'horizontal'#

class cil.framework.labels.FillType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Available fill types for image data.

RANDOM#: Fill with random values.

RANDOM_INT#: Fill with random integers.

Examples

>>> data.fill(FillType.RANDOM)
>>> data.fill("random")

class cil.framework.labels.AngleUnit(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Available units for angles.

Examples

>>> data.geometry.set_angles(angle_data, angle_units=AngleUnit.DEGREE)
>>> data.geometry.set_angles(angle_data, angle_units="degree")

DEGREE = 'degree'#

RADIAN = 'radian'#

class cil.framework.labels.AcquisitionType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Available acquisition types & dimensions.

WARNING: It’s best to use strings rather than integers to initialise. >>> AcquisitionType(3) == AcquisitionType(2 | 1) == AcquisitionType.CONE|PARALLEL != AcquisitionType(‘3D’)

PARALLEL#: Parallel beam.

CONE#: Cone beam.

DIM2#: 2D acquisition.

DIM3#: 3D acquisition.

validate()[source]#: Check if the geometry and dimension types are allowed

property dimension#: Returns the label for the dimension type

property geometry#: Returns the label for the geometry type

DataProcessor#

class cil.framework.DataProcessor(**attributes)[source]#

Basically an alias of Processor Class

check_input(dataset)#

Checks parameters of the input DataContainer

Should raise an Error if the DataContainer does not match expectation, e.g. if the expected input DataContainer is 3D and the Processor expects 2D.

get_input()#

returns the input DataContainer

It is useful in the case the user has provided a DataProcessor as input

get_output(out=None)#

Runs the configured processor and returns the processed data

Parameters:: out (DataContainer, optional) – Fills the referenced DataContainer with the processed data
Returns:: The processed data
Return type:: DataContainer

set_input(dataset)#

Set the input data to the processor

Parameters:: input (DataContainer) – The input DataContainer

class cil.framework.Processor(**attributes)[source]#

Defines a generic DataContainer processor

accepts a DataContainer as input returns a DataContainer __setattr__ allows additional attributes to be defined

store_output boolian defining whether a copy of the output is stored. Default is False. If no attributes are modified get_output will return this stored copy bypassing process

set_input(dataset)[source]#

Set the input data to the processor

Parameters:: input (DataContainer) – The input DataContainer

check_input(dataset)[source]#

Checks parameters of the input DataContainer

Should raise an Error if the DataContainer does not match expectation, e.g. if the expected input DataContainer is 3D and the Processor expects 2D.

get_output(out=None)[source]#

Runs the configured processor and returns the processed data

Parameters:: out (DataContainer, optional) – Fills the referenced DataContainer with the processed data
Returns:: The processed data
Return type:: DataContainer

get_input()[source]#

returns the input DataContainer

It is useful in the case the user has provided a DataProcessor as input

Return Home

Table of Contents

Framework#

AcquisitionGeometry#

Parallel2D Geometry#

Parallel3D Geometry#

Cone2D Geometry (Fanbeam)#

Cone3D Geometry#

Configure the geometry#

Use the geometry#

ImageGeometry#

BlockGeometry#

Data Containers#

DataContainer#

AcquisitionData#

ImageData#

VectorData#

BlockDataContainer#

Example:#

Partitioner#

Labels#

DataProcessor#