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 ndim#

Returns the ndim of the DataContainer

property shape#

Returns the shape 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=None)[source]#

reorders the data in memory as requested.

Parameters

order (list, sting) – ordered list of labels from self.dimension_labels, or order for engine ‘astra’ or ‘tigre’

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

get_slice(channel=None, angle=None, vertical=None, horizontal=None, force=False)[source]#

Returns a new dataset of a single slice of in the requested direction.

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

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]
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

partition(num_batches, mode, seed=None)#

Partition the data into num_batches batches using the specified mode.

The modes are

  1. sequential - The data will be partitioned into num_batches batches of sequential indices.

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

  3. 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:

  1. [[0, 1, 2], [3, 4], [5, 6], [7, 8]] with sequential

  2. [[0, 4, 8], [1, 5], [2, 6], [3, 7]] with staggered

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

reorder(order=None)#

reorders the data in memory as requested.

Parameters

order (list, sting) – ordered list of labels from self.dimension_labels, or order for engine ‘astra’ or ‘tigre’

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

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

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]
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

reorder(order=None)#

reorders the data in memory as requested.

Parameters

order (list, sting) – ordered list of labels from self.dimension_labels, or order for engine ‘astra’ or ‘tigre’

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

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

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]
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=None)#

reorders the data in memory as requested.

Parameters

order (list, sting) – ordered list of labels from self.dimension_labels, or order for engine ‘astra’ or ‘tigre’

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

  1. algebra between `BlockDataContainer`s will be element-wise, only if the shape of the 2 `BlockDataContainer`s is the same, otherwise it will fail

  2. 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

  3. 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.

  4. 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

>>> 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

DataOrder#

class cil.framework.DataOrder[source]#

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 and suppresses the return

Returns

The processed data. Suppressed if out is passed

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 and suppresses the return

Returns

The processed data. Suppressed if out is passed

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