geometry

Contains functions to convert between world coordinates, cube coordinates, and voxel indices, as well as functions to handle gantry and couch rotations.

matRad_createRing(ct, cst, voiBase, vOuterMargin, vInnerMargin, varargin)

matRad function to create a ring VOI around a base VOI, clipped to a limiting VOI

The ring is obtained by growing the base VOI by the outer and the inner margin and subtracting the two. Growth is performed within the limiting VOI only, i.e. the ring cannot spread through structures outside of it. By default the ring is limited by all VOIs of the cst, i.e. by the patient outline. Note that the shape of the margin follows the connectivity used by matRad_addMargin and is therefore not a perfect box or sphere.

By default each CT scenario is treated separately. With ‘unionScenarios’ the ring is instead grown around the union of the base VOI over all scenarios, e.g. to obtain a ring around the full motion of a 4D target. The limiting VOI is always applied per scenario, so the resulting ring may still differ between scenarios.

All optional arguments can be given either as Name/Value pairs or as a metadata struct whose fields carry the same names, or as a combination of both (later values win). The struct thus mirrors the fifth column of the cst, so cst{i,5} of an existing VOI can be handed over directly.

call

[cst, ixRing] = matRad_createRing(ct, cst, voiBase, vOuterMargin, vInnerMargin) [cst, ixRing] = matRad_createRing(ct, cst, voiBase, vOuterMargin, vInnerMargin, metadata) [cst, ixRing] = matRad_createRing(ct, cst, voiBase, vOuterMargin, vInnerMargin, Name, Value) [cst, ixRing] = matRad_createRing(ct, cst, voiBase, vOuterMargin, vInnerMargin, metadata, Name, Value)

Input:

ct – matRad ct struct
cst – matRad cst struct
voiBase – base VOI the ring is grown around, either its name or its row index in the cst
vOuterMargin – outer margin in mm, with fields x, y and z
vInnerMargin – inner margin in mm, with fields x, y and z
Optional Name/Value properties (or fields of a metadata struct)
voiLimit – VOI the ring is clipped to, either its name or its row index in the cst. Default: all VOIs of the cst, i.e. the patient outline
name – name of the ring VOI (cst column 2) Default: [name of the base VOI ‘_RING’]
type – type of the ring VOI (cst column 3). Default: ‘OAR’
objectives – objective or cell array of objectives for the ring VOI (cst column 6). Default: {}
visibleColor – color of the ring VOI. Default: [0 1 0]
Priority, Visible, TissueClass, alphaX, betaX – cst column 5 properties of the ring VOI. Each defaults to the value of the base VOI
diagonalConnectivity – if true 26-connectivity is used for the margin, otherwise 6-connectivity. Default: false
unionScenarios – if true the ring is grown around the union of the base VOI over all CT scenarios. Default: false

Output:

cst – updated matRad cst struct
ixRing – row index of the created ring VOI

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_cubeCoords2worldCoords(cCoord, gridStruct, allowOutside)

matRad function to convert cube coordinates to world coordinates

call

coord = matRad_worldToCubeCoordinates(vCoord, gridStruct)

Input:

cCoord – cube coordinates [vx vy vz] (Nx3 in mm)
gridStruct – matRad ct struct or dij.doseGrid/ctGrid struct
allowOutside – indices not within the image bounds will be calculated optional, default is true

Output:

coord – worldCoordinates [x y z] (Nx3 in mm)

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_addMargin(mVOI, cst, vResolution, vMargin, bDiaElem)

matRad add margin function

call

mVOIEnlarged = matRad_addMargin(mVOI,cst,vResolution,vMargin,bDiaElem)

Input:

mVOI – image stack in dimensions of X x Y x Z holding ones for object and zeros otherwise
cst – matRad cst struct
vResolution ct resolution
vMargin – margin in mm
bDiaElem if true 26-connectivity is used otherwise 6-connectivity

Output:

mVOIEnlarged – enlarged VOI

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_selectVoxelsFromCst(cstOnDoseGrid, doseGrid, selectionMode)

matRad function to get mask of the voxels (on dose grid) that are included in cst structures specified by selectionMode.

call

includeMask = matRad_getVoxelsOnCstStructs(cst,doseGrid,VdoseGrid,selectionMode)

Input:

cstOnDoseGrid – cstOnDoseGrid (voxel indexes included in cst{:,4} are referred to a cube of dimensions doseGrid.dimensions)
doseGrid – doseGrid struct containing field doseGrid.dimensions
selectionMode – define which method to apply to select cst structures. Choices: all, targetOnly, oarsOnly, objectivesOnly, robustnessOnly, [indexes]

Output:

includeMask – logical array #voxels in dose grid

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_getIsoCenter(cst, ct, visBool)

computes the isocenter [mm] as the joint center of gravity of all volumes of interest that are labeled as target within the cst struct

call

isoCenter = matRad_getIsoCenter(cst,ct,visBool)

Input:

cst – matRad cst struct
ct – ct cube
visBool – toggle on/off visualization (optional)

Output:

isoCenter – isocenter in [mm]

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_world2cubeCoords(wCoord, gridStruct, allowOutside)

matRad function to convert world coordinates to cube coordinates

call

coord = world2cubeCoords(wCoord, ct)

Input:

wCoord – world coordinates array Nx3 (x,y,z) [mm]
gridStruct – can be matRad ct, dij.doseGrid, or the ctGrid required fields x,y,x,dimensions,resolution
allowOutside – indices not within the image bounds will be calculated optional, default is true

Output:

coord – cube coordinates (x,y,z) - Nx3 in mm

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_cubeIndex2worldCoords(cubeIx, gridStruct)

matRad function to convert cube indices to world coordinates

call

coord = matRad_cubeIndex2worldCoords(vCoord, gridStruct)

Input:

cCoord – cube indices [i j k] (Nx3) or [linIx] (Nx1)
gridStruct – matRad ct struct or dij.doseGrid/ctGrid struct
allowOutside – indices not within the image bounds will be calculated optional, default is true

Output:

coord – worldCoordinates [x y z] (Nx3 in mm)

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_resizeCstToGrid(cst, vXgridOld, vYgridOld, vZgridOld, vXgridNew, vYgridNew, vZgridNew)

matRad function to resize the cst to a given resolution

call

cst = matRad_resizeCstToGrid(cst,vXgridOld,vYgridOld,vZgridOld,vXgridNew,vYgridNew,vZgridNew)

Input:

cst – matRad cst struct
vXgridOld – vector containing old spatial grid points in x [mm]
vYgridOld – vector containing old spatial grid points in y [mm]
vZgridOld – vector containing old spatial grid points in z [mm]
vXgridNew – vector containing new spatial grid points in x [mm]
vYgridNew – vector containing new spatial grid points in y [mm]
vZgridNew – vector containing new spatial grid points in z [mm]

Output:

cst – updated matRad cst struct containing new linear voxel indices

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_getWorldAxes(gridStruct)

matRad function to compute and store world coordinates into ct.x

call

gridStruct = matRad_getWorldAxes(gridStruct)

gridStruct: can be ct, dij.doseGrid,dij.ctGrid

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_world2cubeIndex(wCoord, gridStruct, allowOutside)

matRad function to convert world coordinates to cube indices

call

coord = world2cubeCoords(wCoord, ct)

Input:

wCoord – world coordinates array Nx3 (x,y,z) [mm]
gridStruct – can be matRad ct, dij.doseGrid, or the ctGrid required fields x,y,x,dimensions,resolution
allowOutside – If coordinates outside are allowed. False default.

Output:

index – cube index (i,j,k) honoring Matlab permuatation of i,j

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_setOverlapPriorities(cst, ctDim)

function to handle overlap priorities during fluence optimization and dose calculation. If you have overlapping volumes of interest you need to inform matRad to which volume(s) the intersection voxels belong.

call

cst = matRad_considerOverlap(cst) [cst, overlapPriorityCube] = matRad_setOverlapPriorities(cst,ctDim)

Input:

cst – cst file
ctDim – (optional) dimension of the ct for overlap cube claculation

Output:

cst – updated cst file considering overlap priorities
overlapPriorityCube – (optional) cube visualizing the overlap priority

References

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_getRotationMatrix(gantryAngle, couchAngle, system)

matRad function to return the rotation / transformation matrix for gantry and/or couch rotation. The Rotation matrix stands for a (1) counter-clockwise, (2) active rotation in the patient coordinate system that is performed on a (4) column vector (by premultiplying the matrix). Per change of one of these directions a matrix transpose of the returned matrix is required.

call

rotMat = matRad_getRotationMatrix(gantryAngle,couchAngle,type,system)

Input:

gantryAngle – beam/gantry angle
couchAngle – couch angle
system – optional coordinate system the transformation matrix is requested for. So far, only the default option ‘LPS’ is supported (right handed system).

Output:

rotMat – 3x3 matrix that performs an active rotation around the patient system origin via rotMat * x

References: https://en.wikipedia.org/wiki/Rotation_matrix (2017, Mar 1)

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.