pytrip.cube module

This module provides the Cube class, which is used by the CTX, DOS, LET and VDX modules. A cube is a 3D object holding data, such as CT Hounsfield units, Dose- or LET values.

class pytrip.cube.Cube(cube=None)

Bases: object

Top level class for 3-dimensional data cubes used by e.g. DosCube, CtxCube and LETCube. Otherwise, this cube class may be used for storing different kinds of data, such as number of cells, oxygenation level, surviving fraction, etc.

static check_compatibility(a, b)

Simple comparison of cubes. if X,Y,Z dims are the same, and voxel sizes as well, then they are compatible. (Duck typed)

See also the function is_compatible().

Params Cube a:the first cube to be compared with the second (b). Params Cube b:the second cube to be compared with the first (a).

create_cube_from_equation(equation, center, limits, radial=True)

Create Cube from a given equation.

This function is currently out of order.

create_dicom_base()

create_empty_cube(value, dimx, dimy, dimz, pixel_size, slice_distance, slice_offset=0.0)

Creates an empty Cube object.

Values are stored as 2-byte integers.

Parameters:

• value (int16) – integer value which will be assigned to all voxels.
• dimx (int) – number of voxels along x
• dimy (int) – number of voxels along y
• dimz (int) – number of voxels along z
• pixel_size (float) – size of each pixel (x == y) in [mm]
• slice_distance (float) – the distance between two slices (z) in [mm]
• slice_offset (float) – start position of the first slice in [mm] (default 0.0 mm)

static discover_file(file_name)

Checks if file_name exists in the filesystem. If yes, gives back its path. If not, checks if gzipped file with same name exists. If gzipped file exists, gives back it path, otherwise returns None.

Parameters:file_name – File name or path Returns:file_name, file_name + ”.gz” or None

indices_to_pos(indices)

Translate index number of a voxel to real position in [mm], including any offsets.

The z position is always following the slice positions.

Params [int] indices:  tuple or list of integer indices (i,j,k) or [i,j,k] Returns:list of positions, including offsets, as a list of floats [x,y,z]

is_compatible(other)

Check if this Cube object is compatible in size and dimensions with ‘other’ cube.

A cube object can be a CtxCube, DosCube, LETCube or similar object. Unlike check_compatibility(), this function compares itself to the other cube.

Parameters:other (Cube) – The other Cube object which will be checked compability with. Returns:True if compatibe.

mask_by_voi(voi, value)

Overwrites the Cube voxels within the given Voi with ‘value’.

Voxels within the structure are filled it with ‘value’. Voxels outside the contour are not touched.

Parameters:

• voi (Voi) – the volume of interest
• value=0 – value to be assigned to the voxels within the contour.

mask_by_voi_add(voi, value=0)

Add ‘value’ to all voxels within the given Voi

‘value’ is added to each voxel value within the given volume of interest. Voxels outside the volume of interest are not touched.

Parameters:

• voi (Voi) – the volume of interest
• value=0 – value to be added to the voxel values within the contour.

mask_by_voi_all(voi, preset=0, data_type=<type 'numpy.int16'>)

Attaches/overwrites Cube.data based on a given Voi.

Voxels within the structure are filled it with ‘preset’ value. Voxels outside the contour will be filled with Zeros.

Parameters:

• voi (Voi) – the volume of interest
• preset (int) – value to be assigned to the voxels within the contour.
• data_type – numpy data type, default is np.int16

merge(cube)

merge_zero(cube)

classmethod parse_path(path_name)

Parse path_name which can have form of: bare name (i.e. TST001), plain file (TST001.hed or TST001.ctx), gzipped file (TST001.hed.gz or TST001.ctx.gz) or some other name. Calculates plain file names of header and data file. Extension of data file is extracted from the class from which this method was called (.ctx for CtxCube, .dos for DosCube, .dosemlet.dos for LetCube). In case of non-parseable data None is returned.

>>> from pytrip import CtxCube
>>> CtxCube.parse_path("frodo.hed")
('frodo.hed', 'frodo.ctx')
>>> CtxCube.parse_path("baggins.ctx")
('baggins.hed', 'baggins.ctx')
>>> CtxCube.parse_path("mordor")
('mordor.hed', 'mordor.ctx')
>>> CtxCube.parse_path("legolas.hed.gz")
('legolas.hed', 'legolas.ctx')
>>> CtxCube.parse_path("gimli.son.of.gloin.ctx.gz")
('gimli.son.of.gloin.hed', 'gimli.son.of.gloin.ctx')
>>> CtxCube.parse_path("bilbo.dos")
(None, None)
>>> pt.CtxCube.parse_path("/home/pytrip/patient.ctx")
('/home/pytrip/patient.hed', '/home/pytrip/patient.ctx')
>>> from pytrip import DosCube
>>> DosCube.parse_path("bilbo.dos")
('bilbo.hed', 'bilbo.dos')
>>> DosCube.parse_path("baggins.ctx")
(None, None)
>>> from pytrip import LETCube
>>> LETCube.parse_path("aragorn.dosemlet.dos")
('aragorn.dosemlet.hed', 'aragorn.dosemlet.dos')
>>> LETCube.parse_path("aragorn.dosemlet")
(None, None)
>>> LETCube.parse_path("aragorn")
('aragorn.dosemlet.hed', 'aragorn.dosemlet.dos')
>>> LETCube.parse_path("aragorn.ctx")
(None, None)

Parameters:path_name – path to header file, data file or basename path (path to file without extension).

Path can be absolute or relative. It can also lead to gzipped files. :return: pair of filenames for header and data

read(path)

Reads both TRiP98 data and its associated header into the Cube object.

Parameters:path (str) – Path to filename to be read, file extention may be given but is not neccesary.

set_byteorder(endian=None)

Set/change the byte order of the data to be written to disk.

Available options are: - ‘little’ vms, Intel style little-endian byte order. - ‘big’ aix, Motorola style big-endian byte order. - if unspecified, the native system dependent endianess is used.

Parameters:endian (str) – optional string containing the endianess.

set_data_type(type)

Sets the data type for the TRiP98 header files.

Parameters:type (numpy.type) – numpy type, e.g. np.uint16

slice_to_z(slice_number)

Return z-position in [mm] of slice number (starting at 1).

Params int slice_number:  slice number, starting at 1 and no bound check done here. Returns:position of slice in [mm] including offset