voxtox.structures module

VoxTox extenstions to Scikit-rt for ROIs and StructureSets

class voxtox.structures.ROI(source=None, name=None, color=None, load=True, image=None, shape=None, affine=None, voxel_size=None, origin=None, mask_threshold=0.25, default_geom_method='auto', overlap_level=None, point_cloud=False, key_precision=0.1, **kwargs)

Bases: ROI

VoxTox-specific extensions to Scikit-rt ROI class.

__init__(source=None, name=None, color=None, load=True, image=None, shape=None, affine=None, voxel_size=None, origin=None, mask_threshold=0.25, default_geom_method='auto', overlap_level=None, point_cloud=False, key_precision=0.1, **kwargs)

Constructor for ROI object.

Parameters :

point_cloudbool, default=False

If True, write ROI data in VoxTox point-cloud format. Each file contains contour data for a single ROI. Each line gives (column, row, slice) coordinates for a single point. Points are ordered sequentially around a slice. Slice numbers are inverted with respect to the usual DICOM numbering.

key_precisionfloat, default=0.1

Precision with which z-coordinate should match z-plane when loading point-cloud data.

For details of other parameters, see documentation for skrt.structures.ROI.

apply_couch_shifts(reverse=False, force_contours=True)

Apply couch shifts to ROI.

Couch shifts - applied in the order translation, rotation - represent the transformation for mapping from guidance scan to planning scan.

Reverse shifts - applied in the order rotation, translation - represent the transformation for mapping from planning scan to guidance scan.

Parameters:

reverse: bool, default=False

If True, reverse couch shifts are applied.

force_contoursbool, default=True

If True, and the transform corresponds to a translation and/or rotation about the z-axis, apply transform to contour points independently of the original data source. Otherwise apply transform to mask.

load(force=False)

Load ROI from file or source.

Parameter:

forcebool, default=False

If True, force loading, even if ROI data already loaded.

write(outname=None, outdir='.', ext=None, point_cloud=False, **kwargs)

Write ROI data.

Parameters:

outdirstr, default=’.’

Directory where point-cloud file is to be written.

outnamestr, default=None

Name to be used for the point-cloud file. If not already present, the extension defined by ext, or ‘.txt’ if ext is None, is appended.

extstr, default=None

Extension to be added to the name of the output file.

point_cloudbool, default=False

If True, write ROI data in VoxTox point-cloud format. Each file contains contour data for a single ROI. Each line gives (column, row, slice) coordinates for a single point. Points are ordered sequentially around a slice. Slice numbers are inverted with respect to the usual DICOM numbering.

kwargsdict, default={}

Dictionary containing keyword arguments to pass to the constructor of the associated skrt.image.Image object. See skrt.image.Image documentation for details of available parameters.

class voxtox.structures.StructureSet(sources=None, name=None, image=None, load=True, names=None, to_keep=None, to_remove=None, multi_label=False, point_cloud=False, key_precision=0.1, **kwargs)

Bases: StructureSet

VoxTox-specific extensions to Scikit-rt StructureSet class.

__init__(sources=None, name=None, image=None, load=True, names=None, to_keep=None, to_remove=None, multi_label=False, point_cloud=False, key_precision=0.1, **kwargs)

Constructor for StructureSet object.

Parameters:

point_cloudbool, default=False

If True, write StructureSet data in VoxTox point-cloud format. Each file contains contour data for a single ROI. Each line gives (column, row, slice) coordinates for a single point. Points are ordered sequentially around a slice. Slice numbers are inverted with respect to the usual DICOM numbering.

key_precisionfloat, default=0.1

Precision with which z-coordinate should match z-plane when loading point-cloud data.

For details of parameters, see documentation for skrt.structures.StructureSet.

apply_couch_shifts(reverse=False, names=None)

Apply couch shifts to structure-set ROIs.

Couch shifts - applied in the order translation, rotation - represent the transformation for mapping from guidance scan to planning scan.

Reverse shifts - applied in the order rotation, translation - represent the transformation for mapping from planning scan to guidance scan.

Parameters:

reverse: bool, default=False

If True, reverse couch shifts are applied.

nameslist/None, default=False

List of ROIs to which transform is to be applied. If None, transform is applied to all ROIs.

load(sources=None, force=False)

Load structure set form sources. If None, load from self.sources.

When loading a structure set from point clouds, the default precision with which z-coordinates are matched to z-planes is key_value=0.1. If a different value is wanted, this should be specified when creating the StructureSet instance.

For details of loading from sources other than point-cloud files, see documnetation for skrt.structures.StructureSet.load().

Parameters:

sourcesVarious, default=None

Sources from which to load structure set. If the sources are files with the extension ‘.txt’, they are treated as being in VoxTox point-cloud format. The default precision with which z-coordinates are matched to z-planes is key_value=0.1. If a different value is wanted, this should be specified when creating the StructureSet instance.

forcebool, default=False

If True, force loading, even if StructureSet data already loaded.

write(outname=None, outdir='.', ext=None, overwrite=False, point_cloud=False, names={}, **kwargs)

Write StructureSet data.

Parameters:

outnamestr, default=None

Filename when a single output file is produced. Disregarded when set to None, or when multiple output files are produced, in which case filenames match the corresponding ROI names.

outdirstr, default=’.’

Directory where output files are be written.

extstr, default=None

The filename extension. For point-cloud files this is disregarded, and the extension is ‘.txt’.

overwrite: bool, default=True

If True, overwrite any pre-existing point files.

point_cloudbool, default=False

If True, write ROI data in VoxTox point-cloud format. Each file contains contour data for a single ROI. Each line gives (column, row, slice) coordinates for a single point. Points are ordered sequentially around a slice. Slice numbers are inverted with respect to the usual DICOM numbering.

namesdict, default={}

Dictionary mapping between possible ROI names within a structure set (dictionary values) and names to be used for point-cloud files (dictionary keys). The possible names names can contain wildcards with the ‘*’ symbol.

kwargsdict, default={}

Dictionary containing arbitrary parameter-value pairs passed in the function call. For point-cloud files this dictionary is disregarded. Otherwise it’s passed in a call to skrt.structures.StructureSet.write().

voxtox.structures.contours_mean_z(contours_3d={})

Recalculate point cloud, averaging over z-coordinates in a plane

Parameter:

contours_3ddict, default={}

Dictionary of point-cloud data, where the keys are plane z-coordinates, as strings, and the value for a given key is a list of (x, y, z) point coordinates.

voxtox.structures.get_key(z_point=0, contours_3d={}, key_precision=0.1)

Determine z-plane key corresponding to given z-coordinate.

Parameters:

z_pointfloat, default=0

Z-coordinate of a contour point.

contours_3ddict, default={}

Dictionary of contour-point coordinates, stored by z-plane.

key_precisionfloat, default=0.1

Precision with which z-coordinate should match z-plane. As a result of rounding errors, and/or small translations when applying registration transforms, z-coordinates for points in the same plane may not be identical.