pytrip package

TODO: documentation here.

class pytrip.CtxCube(cube=None)

Bases: pytrip.cube.Cube

Class for handling CT-data. In TRiP98 these are stored in VOXELPLAN format with the .ctx suffix. This class can also handle Dicom files.

create_dicom()

Creates a Dicom object from self.

This function can be used to convert a TRiP98 CTX file to Dicom format.

Returns:A Dicom object.

data_file_extension = '.ctx'

header_file_extension = '.hed'

read_dicom(dcm)

Imports CT-images from Dicom object.

Parameters:dcm (Dicom) – a Dicom object

write(path)

Write CT-data to disk, in TRiP98/Voxelplan format.

This method will build and write both the .hed and .ctx file.

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

write_dicom(directory)

Write CT-data to disk, in Dicom format.

Parameters:directory (str) – directory to write to. If directory does not exist, it will be created.

class pytrip.VdxCube(cube=None)

VdxCube is the master class for dealing with Volume of Interests (VOIs). A VdxCube contains one or more VOIs which are structures which represent some organ (lung, eye ...) or target (GTV, PTV...) The Voi object contains Slice objects which corresponds to the CT slices, and the slice objects contains contour objects. Each contour object are a set of points which delimit a closed region. One single slice object can contain multiple contours.

VdxCube —> Voi[] —> Slice[] —> Contour[] —> Point[]

Note, since TRiP98 only supports one contour per slice for each voi. PyTRiP supports functions for connecting multiple contours to a single entity using infinte thin connects.

VdxCube can import both dicom data and TRiP data, and export in the those formats.

We strongly recommend to load a CT and/or a DOS cube first, see example below:

>>> c = CtxCube()
>>> c.read("TST000000")
>>> v = VdxCube(c)
>>> v.read("TST000000.vdx")

add_voi(voi)

Appends a new voi to this class.

Parameters:voi (Voi) – the voi to be appened to this class.

concat_contour()

Loop through all available VOIs and check whether any have mutiple contours in a slice. If so, merge them to a single contour.

This is needed since TRiP98 cannot handle multiple contours in the same slice.

create_dicom()

Generates and returns Dicom RTSTRUCT object, which holds all VOIs.

Returns:a Dicom RTSTRUCT object holding any VOIs.

get_voi_by_name(name)

Returns a Voi object by its name.

Parameters:name (str) – Name of voi to be returned. Returns:the Voi which has exactly this name, else raise an Error.

get_voi_names()

Returns:a list of available voi names.

import_vdx(path)

Reads a structure file in Voxelplan format. This method is identical to self.read() and self.read_vdx()

Parameters:path (str) – Full path including file extension.

number_of_vois()

Returns:the number of VOIs in this object.

read(path)

Reads a structure file in Voxelplan format. This method is identical to self.import_vdx() and self.read_vdx()

Parameters:path (str) – Full path including file extension.

read_dicom(data, structure_ids=None)

Reads structures from a Dicom RTSS Object.

Parameters:

• data (Dicom) – A Dicom RTSS object.
• structure_ids – (TODO: undocumented)

read_vdx(path)

Reads a structure file in Voxelplan format.

Parameters:path (str) – Full path including file extension.

write(path)

Writes all VOIs in voxelplan format, while ensuring no slice holds more than one contour. Identical to write_trip().

Parameters:path (str) – Full path, including file extension (.vdx).

write_dicom(directory)

Generates a Dicom RTSTRUCT object from self, and writes it to disk.

Parameters:directory (str) – Diretory where the rtss.dcm file will be saved.

write_to_voxel(path)

Writes all VOIs in voxelplan format.

Parameters:path (str) – Full path, including file extension (.vdx).

write_trip(path)

Writes all VOIs in voxelplan format, while ensuring no slice holds more than one contour. Identical to write().

Parameters:path (str) – Full path, including file extension (.vdx).

class pytrip.Voi(name, cube=None)

This is a class for handling volume of interests (VOIs). This class can e.g. be found inside the VdxCube object. VOIs may for instance be organs (lung, eye...) or targets (PTV, GTV...), or any other volume of interest.

add_slice(slice)

Add another slice to this VOI, and update self.slice_z table.

Parameters:slice (Slice) – the Slice object to be appended.

calculate_bad_angles(voi)

(Not implemented.)

calculate_center()

Calculates the center of gravity for the VOI.

Returns:A numpy array[x,y,z] with positions in [mm]

concat_contour()

Concat all contours in all slices found in this VOI.

concat_to_3d_polygon()

Concats all contours into a single contour, and writes all data points to sefl.polygon3d.

coronal = 1

create_copy(margin=0)

Returns an independent copy of the Voi object

Parameters:margin – (unused) Returns:a deep copy of the Voi object

create_dicom_contour_data(i)

Based on self.slices, DICOM contours are generated for the DICOM ROI.

Returns:Dicom ROI_CONTOURS

create_dicom_label()

Based on self.name and self.type, a Dicom ROI_LABEL is generated.

Returns:a Dicom ROI_LABEL

create_dicom_structure_roi()

Based on self.name, an empty Dicom ROI is generated.

Returns:a Dicom ROI.

create_point_tree()

Concats all contours. Writes a list of points into self.points describing this VOI.

define_colors()

Creates a list of default colours [R,G,B] in self.colours.

get_2d_projection_on_basis(basis, offset=None)

(TODO: Documentation)

get_2d_slice(plane, depth)

Gets a 2d Slice object from the contour in either sagittal or coronal plane. Contours will be concated.

Parameters:

• plane (int) – either self.sagittal or self.coronal
• depth (float) – position of plane

Returns:

a Slice object.

get_3d_polygon()

Returns a list of points rendering a 3D polygon of this VOI, which is stored in sefl.polygon3d. If this attibute does not exist, create it.

get_color(i=None)

Parameters:i (int) – selects a colour, default if None. Returns:a [R,G,B] list.

get_min_max()

Set self.temp_min and self.temp_max if they dont exist.

Returns:minimum and maximum x y coordinates in Voi.

get_name()

Returns:The name of this VOI.

get_roi_type_name(type_id)

Returns:The type name of the ROI.

get_roi_type_number(type_name)

Returns:1 if GTV or CTV, 10 for EXTERNAL, else 0.

get_row_intersections(pos)

(TODO: Documentation needed)

get_slice_at_pos(z)

Finds and returns a slice object found at position z [mm] (float).

Parameters:z (float) – slice position in absolute coordiantes (i.e. including any offsets) Returns:VOI slice at position z, z position may be approxiamte

get_voi_cube()

This method returns a DosCube object with value 1000 in each voxel within the Voi and zeros elsewhere. It can be used as a mask, for selecting certain voxels. The function may take some time to execute the first invocation, but is faster for subsequent calls, due to caching.

Returns:a DosCube object which holds the value 1000 in those voxels which are inside the Voi.

number_of_slices()

Returns:number of slices covered by this VOI.

read_dicom(info, data)

Reads a single ROI (= VOI) from a Dicom data set.

Parameters:

• info – (not used)
• data (Dicom) – Dicom ROI object which contains the contours.

read_vdx(content, i)

Reads a single VOI from Voxelplan .vdx data from ‘content’. Format 2.0 :params [str] content: list of lines with the .vdx content :params int i: line number to the list. :returns: current line number, after parsing the VOI.

read_vdx_old(content, i)

Reads a single VOI from Voxelplan .vdx data from ‘content’, assuming a legacy .vdx format. VDX format 1.2. :params [str] content: list of lines with the .vdx content :params int i: line number to the list. :returns: current line number, after parsing the VOI.

sagital = 2

sagittal = 2

set_color(color)

Parameters:[3*int] – set a color [R,G,B].

to_voxel_string()

Creates the Voxelplan formatted text, which can be written into a .vdx file (format 2.0).

Returns:a str holding the all lines needed for a Voxelplan formatted file.

class pytrip.DosCube(cube=None)

Bases: pytrip.cube.Cube

Class for handling Dose data. In TRiP98 these are stored in VOXELPLAN format with the .dos suffix. This class can also handle Dicom files.

calculate_dvh(voi)

Calculate DHV for given VOI. Dose is given in relative units (target dose = 1.0). In case VOI lies outside the cube, then None is returned.

Parameters:voi – VOI for which DHV should be calculated Returns:(dvh, min_dose, max_dose, mean, area) tuple. dvh - 2D array holding DHV histogram,

min_dose and max_dose, mean_dose - obvious, mean_volume - effective volume dose.

create_dicom()

Creates a Dicom RT-Dose object from self.

This function can be used to convert a TRiP98 Dose file to Dicom format.

Returns:a Dicom RT-Dose object.

create_dicom_plan()

Create a dummy Dicom RT-plan object.

The only data which is forwarded to this object, is self.patient_name. :returns: a Dicom RT-plan object.

data_file_extension = '.dos'

header_file_extension = '.hed'

read_dicom(dcm)

Imports the dose distribution from Dicom object.

Parameters:dcm (Dicom) – a Dicom object

write(path)

Write Dose data to disk, in TRiP98/Voxelplan format.

This method will build and write both the .hed and .dos file.

Parameters:path (str) – Path, any file extentions will be ignored.

write_dicom(directory)

Write Dose-data to disk, in Dicom format.

This file will save the dose cube and a plan associated with that dose. Function call create_dicom() and create_dicom_plan() and then save these.

Parameters:directory (str) – Directory where ‘rtdose.dcm’ and ‘trplan.dcm’ will be stored.

write_dvh(voi, filename)

Save DHV for given VOI to the file.

class pytrip.DensityCube(ctxcube, hlut_path='/data/hlut_den.dat')

Bases: pytrip.cube.Cube

Class for working with denisity cubes [g/cm3]

calculate_cube()

Calculate the density values from HU table and interpolating the loaded hlut_data.

import_hlut()

Imports the Hounsfield lookup table and stores it into self.hlut_data object self.hlut_data is trained linear interpolator, it can be later called to get interpolated values

class pytrip.LETCube(cube=None)

Bases: pytrip.cube.Cube

This class handles LETCubes.

It is similar to DosCubes and CtxCubes, but is intended to hold LET data. The object has build-in methods to read and write the LET data cubes, calculate the LET-volume historgrams, and write these to disk. It is inherited from Cube, which contains many additional methods and attributes.

calculate_lvh(voi)

Calculate a LET-volume historgram.

Parameters:voi (Voi) – The volume of interest, in the form of a Voi object. Returns:A tuple containing - lvh: the LET-volume histogram - min_lvh: array of LET values below 2% - max_lvh: array of LET values above 98% - area: TODO - what is this?

data_file_extension = '.dosemlet.dos'

get_max()

Returns the largest value in the LETCube.

Returns:the largets value found in the in the LETCube.

header_file_extension = '.dosemlet.hed'

write(path)

Write the LETCube and its header to a file with the filename ‘path’.

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

write_lvh_to_file(voi, path)

Write the LET-volume historgram to a file.

Parameters:

• voi (Voi) – The volume of interest, n the form of a Voi object.
• path (str) – Full path of file to be written.

class pytrip.Rst

This class handles raster scan data, which are accelerator control files in GSI format. Raster scan data are stored in .rst file, and describe the amount of particles going into each spot in each energy layer. Each energy layer is called a ‘submachine’.

gaussian_blur(sigma)

For a loaded .rst file, apply a normal distributed setup error to each energy layer of sigma magnitude. :params float sigma” 1-sigma error to be applied to all positions.

get_min_max()

Retrieve the largest and smallest x,y position found in all energy layers.

Returns:A list of four values in [x_min,x_max,y_min,y_max] in [mm].

get_stepsize()

Returns the distance between each spot in the first energy plane.

Most likely the distance will be the same in all planes.

Returns:Distancce between spots in [mm]. If no submachines are found, None is returned.

get_submachines()

Returns:A list of submachines.

read(path)

Load and parse a raster scan (.rst) file.

Parameters:path (str) – Full path to the file to be loaded, including file extension.

read_from_dicom(path)

Load a Dicom file from ‘path’

Currently, this function merely stores the dicom data into self.data. No interpretation is done.

Parameters:path (str) – Full path to Dicom file.

save_random_error_rst(path, sigma)

Subpackages

• pytrip.res package
  • Submodules
    • pytrip.res.interpolate module
    • pytrip.res.point module
    • pytrip.res.utils module
• pytrip.tripexecuter package
  • Submodules
    • pytrip.tripexecuter.execute module
    • pytrip.tripexecuter.field module
    • pytrip.tripexecuter.plan module
• pytrip.utils package
  • Submodules
    • pytrip.utils.bevlet2oer module
    • pytrip.utils.cubeslice module
    • pytrip.utils.dicom2trip module
    • pytrip.utils.dvhplot module
    • pytrip.utils.gd2agr module
    • pytrip.utils.gd2dat module
    • pytrip.utils.rst2sobp module
    • pytrip.utils.rst_plot module
    • pytrip.utils.trip2dicom module

Submodules

• pytrip.ctx module
• pytrip.cube module
• pytrip.ddd module
• pytrip.dicomhelper module
• pytrip.dos module
• pytrip.error module
• pytrip.field module
• pytrip.file_parser module
• pytrip.let module
• pytrip.paths module
• pytrip.raster module
• pytrip.util module
• pytrip.vdx module