pytrip.vdx module

This module holds all the user needs to deal with Volume of interests. It provides the top-level VdxCube class, Voi, Slice and Contour classes. The Voi class represents a volume of interest ‘VOI’, also called region of interest ‘ROI’ in Dicom lingo. Each Voi holds several Slice, which are noramlly synced with an associated CT-cube. Each Slice holds one or more Contours.

class pytrip.vdx.Contour(contour, cube=None)

Class for handling single Contours.

add_child(contour)

(TODO: Document me)

calculate_center()

Calculate the center for a single contour, and the area of a contour in 3 dimensions.

Returns:Center of the contour [x,y,z] in [mm], area [mm**2] (TODO: to be confirmed)

concat()

In case of multiple contours in the same slice, this method will concat them to a single conour. This is important for TRiP98 compability, as TRiP98 cannot handle multiple contours in the same slice of of the same VOI.

contains_contour(contour)

Returns:True if contour in argument is contained inside self.

get_min_max()

Returns:The lowest x,y,z values and the highest x,y,z values found in this Contour object.

has_childs()

Returns:True or False, whether this Contour object has children.

number_of_points()

Returns:Number of points in this Contour object.

print_child(level)

Print child to stdout.

Parameters:level (int) – (TODO: needs documentation)

push(contour)

Push a contour on the contour stack.

Parameters:contour (Contour) – a Contour object.

read_vdx(content, i)

Reads a single Contour from Voxelplan .vdx data from ‘content’.

VDX format 2.0.

Note

• in VDX files the last contour point is repeated if the contour is closed.
• If we have a point of interest, the length is 1.
• Length 2 and 3 should thus never occur in VDX files (assuming all contours are closed)

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(slice_number, xy_line)

Reads a single Contour from Voxelplan .vdx data from ‘content’ and appends it to self.contour data VDX format 1.2.

See also notes in read_vdx(), regarding the length of a contour.

Params slice_number:  list of numbers (as characters) with slice number Params xy_line:list of numbers (as characters) representing X and Y coordinates of a contour

remove_inner_contours()

(TODO: needs documentation)

to_voxel_string()

Creates the Voxelplan formatted text, which can be written into a .vdx file.

Returns:a str holding the contour points needed for a Voxelplan formatted file.

class pytrip.vdx.Slice(cube=None)

The Slice class is specific for structures, and should not be confused with Slices extracted from CTX or DOS objects.

add_contour(contour)

Adds a new ‘contour’ to the existing contours.

Parameters:contour (Contour) – the contour to be added.

add_dicom_contour(dcm)

Adds a Dicom CONTOUR to the existing list of contours in this Slice class.

Parameters:dcm (Dicom) – a Dicom CONTOUR object.

calculate_center()

Calculate the center position of all contours in this slice.

Returns:a list of center positions [x,y,z] in [mm] for each contour found.

concat_contour()

Concat all contours in this Slice object to a single contour.

create_dicom_contours(dcmcube)

Creates and returns a list of Dicom CONTOUR objects from self.

get_intersections(pos)

(TODO: needs documentation)

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_position()

Returns:the position of this slice in [mm] including zoffset

number_of_contours()

Returns:number of contours found in this Slice object.

read_vdx(content, i)

Reads a single Slice from Voxelplan .vdx data from ‘content’. VDX 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 Slice from Voxelplan .vdx data from ‘content’. 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.

remove_inner_contours()

Removes any “holes” in the contours of this slice, thereby changing the topology of the contour.

to_voxel_string()

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

Returns:a str holding the slice information with the countour lines for a Voxelplan formatted file.

class pytrip.vdx.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.vdx.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

id for coronal view

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

deprecated, backwards compability to pytripgui, do not use.

sagittal = 2

id for sagittal view

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.

pytrip.vdx.create_cube(cube, name, center, width, height, depth)

Creates a new VOI which holds the contours rendering a square box

Parameters:

• cube (Cube) – A CTX or DOS cube to work on.
• name (str) – Name of the VOI
• center ([float*3]) – Center position [x,y,z] in [mm]
• width (float) – Width of box, along x in [mm]
• height (float) – Height of box, along y in [mm]
• depth (float) – Depth of box, along z in [mm]

Returns:

A new Voi object.

pytrip.vdx.create_cylinder(cube, name, center, radius, depth)

Creates a new VOI which holds the contours rendering a cylinder along z

Parameters:

• cube (Cube) – A CTX or DOS cube to work on.
• name (str) – Name of the VOI
• center ([float*3]) – Center position of cylinder [x,y,z] in [mm]
• radius (float) – Radius of cylinder in [mm]
• depth (float) – Depth of cylinder, along z in [mm]

Returns:

A new Voi object.

pytrip.vdx.create_sphere(cube, name, center, radius)

Creates a new VOI which holds the contours rendering a sphere along z

Parameters:

• cube (Cube) – A CTX or DOS cube to work on.
• name (str) – Name of the VOI
• center ([float*3]) – Center position of sphere [x,y,z] in [mm]
• radius (float) – Radius of sphere in [mm]

Returns:

A new Voi object.

pytrip.vdx.create_voi_from_cube(cube, name, value=100)

Creates a new VOI which holds the contours following an isodose lines.

Parameters:

• cube (Cube) – A CTX or DOS cube to work on.
• name (str) – Name of the VOI
• value (int) – The isodose value from which the countour will be generated from.

Returns:

A new Voi object.