espadon: Easy Study of Patient DICOM Data in Oncology

Description

Exploitation, processing and 2D-3D visualization of DICOM-RT files (structures, dosimetry, imagery) for medical physics and clinical research, in a patient-oriented perspective.

espadon works in a native way (user friendly):

• on images (CT, MR, PT) and fully manages changes of referential (REG)

• on dosimetry (rt-dose)

• on structures (rt-struct)

It is also able to use any DICOM format file, as long as the user knows where to look for the information. In addition to the simplified use of the above-mentioned formats, espadon contains many functions that allow the user to rework documents to produce new features that can be integrated into machine learning.

espadon integrates functionalities:

• file loading, patient-centered information fusion

• handling of 3D images

  • changes of referential

  • resampling, filtering

• Contour manipulation, allowing the creation of new contours

  • fusion, intersection, inversion, erosion, dilation, opening, closing

  • segmentation based on the image

• 2D representation

  • with application of masks

  • and transport of structures in the new reference frames

• ... and 3D

  • production of mesh for the representation

  • CT, MR or RTDose slices, RTstruct contours in 3D -space

• for measurements

  • calculation of histograms (1D, 2D), DVH (integrating Monte-Carlo to simulate organ movements)

  • measurement of surfaces, radii of curvature (on the mesh) and volumes

  • calculation of standard dosimetry indicators

  • calculation of Spatial similarity metrics

  • calculation of error metrics for comparison between 2 volumes (e.g. comparison of sCT and CT for chaue ROI)

• export of your own objects to DICOM (CT, MR, RTDose, RTStruct)

In the calculation flow, various objects are created and accessible to the developer for his own use.

Author(s)

Maintainer: Cathy Fontbonne contact.espadon@lpccaen.in2p3.fr (LPC-CAEN, France)

Authors:

• Jean-Marc Fontbonne (LPC-CAEN, France)

Other contributors:

• Nathan Azemar (LPC-CAEN, France) [contributor]

Cathy & Jean-Marc Fontbonne

See Also

Useful links:

• https://espadon.cnrs.fr

Inventory of espadon objects from Rdcm files

Description

The Rdcm.inventory function creates, from Rdcm files in a patient's directory, a dataframe describing objects.

Usage

Rdcm.inventory(dirname, upgrade.to.latest.version = FALSE)

Arguments

Value

Returns a dataframe, providing information of DICOM objects.

Examples

# First, save toy patient objects to a temporary file pat.dir for testing.
pat.dir <- file.path (tempdir(), "PM_Rdcm") 
dir.create (pat.dir, recursive = TRUE) 
patient <- toy.load.patient (modality = c("ct", "mr"), roi.name = "", 
                             dxyz = c (4, 4, 4))
save.to.Rdcm (patient$ct[[1]], dirname = pat.dir)
save.to.Rdcm (patient$mr[[1]], dirname = pat.dir)
save.T.MAT (patient$T.MAT, dirname = pat.dir)


Rdcm.inventory (pat.dir)

# Cleaning  temporary directory
unlink (pat.dir, recursive = TRUE)

Updating Rdcm files.

Description

The Rdcm.upgrade function updates Rdcm files that were created with a previous version.

Usage

Rdcm.upgrade(Rdcm.files)

Arguments

Value

Saves the updated Rdcm files. If the Rdcm files were generated from the dicom files, the data is updated from the DICOM fields.

Examples

# First, save toy patient objects to a temporary file pat.dir for testing.
pat.dir <- file.path (tempdir(), "PM_Rdcm") 
dir.create (pat.dir, recursive = TRUE) 
patient <- toy.load.patient (modality = c("ct", "mr"), roi.name = "", 
                             dxyz = c (4, 4, 4))
save.to.Rdcm (patient$ct[[1]], dirname = pat.dir)
save.to.Rdcm (patient$mr[[1]], dirname = pat.dir)
save.T.MAT (patient$T.MAT, dirname = pat.dir)
# Rdcm files in pat.dir
list.files(pat.dir)

# test of Rdcm.upgrade

Rdcm.upgrade (pat.dir)
# or
Rdcm.upgrade (list.files (pat.dir, full.names = TRUE))

# Cleaning  temporary directories
unlink (pat.dir, recursive = TRUE)

Adding or removing a margin to a volume

Description

The add.margin function adds or subtracts a margin of the rectangular parallelepiped circumscribed by a volume.

Usage

add.margin(vol, xyz.margin, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object (see espadon.class for class definitions), in which 3D volume is restricted or increased by the requested margins. If the created volume exceeds the initial volume, new voxels are set to NA.

See Also

nesting.cube, nesting.roi and nesting.bin.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "ct", roi.name = "", 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]

# Calculation of new volumes decreased by 10 mm in all directions.
new.CT <- add.margin (CT, xyz.margin = c (-10, -10, 10), alias = "new CT")
# display of the CT before and after, in the middle cutting plane
z.mid <- apply (get.extreme.pt (CT), 1, mean)[3]
display.plane (bottom = CT, view.coord = z.mid, bottom.col = pal.RVV(1000),
               bg = "#00ffff", interpolate = FALSE)
display.plane (bottom = new.CT, view.coord = z.mid, bottom.col = pal.RVV(1000),
               bg = "#00ffff", interpolate = FALSE)

Adding shape to a 3D volume.

Description

The add.shape function adds the shape defined by espadon volume object of the modality "binary" or "weight" to a 3D volume.

Usage

add.shape(obj, shape.bin, shape.mean, shape.sd)

Arguments

Value

Returns the ‘volume’ class object obj, in which the voxels identified by shape.bin have been replaced by a linear interpolation between the initial value and new values. These new values follow a normal distribution with mean shape.mean and standard deviation shape.sd. The weights of the linear interpolation are defined by the voxels values of shape.bin.

See Also

bin.cuboid, bin.cylinder, bin.ellipsoid, bin.from.roi.

Examples

# Creation of a volume
CT <- vol.create (c(80, 80,40), c(1.2, 1.2, 2), 
                  pt000 = c(-50.4,-50.4,-75), modality = "ct", 
                  default.value = as.integer(-997), value.sd = 1)
# Creation of a new shape shape                
ellipsoid <- bin.ellipsoid(CT, center = c(-20.1, 0.1, -15), 
                           radius =  c(19.3, 20.2, 15.3))  
                           
# Incorporating form into the CT
CT <- add.shape (CT, shape.bin = ellipsoid, shape.mean = 100, shape.sd = 10)

plot(CT, view.coord =  c(-20.1, 0.1, -15))      

Binary volume closing

Description

The bin.closing function performs a morphological operation of closing, using a sphere, on a "volume" class object of "binary" modality. Closing is useful for :

• filling holes that are smaller than the radius,

• merging two shapes close to each other.

Usage

bin.closing(vol, radius = 10, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object of "binary" modality (see espadon.class for class definitions), with the same grid as vol, in which $vol3D.data has been transformed by the closing operation.

See Also

bin.dilation, bin.erosion, bin.opening, add.margin, nesting.cube.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "mr", roi.name = "", 
                             dxyz = rep (step, 3))
MR <- patient$mr[[1]]

# generation of a binary volume
b <- bin.from.vol(MR, min = 15, max = 30)

b.closing <- bin.closing (b, radius = step)
display.plane (bottom = MR, top = b, main = "Before closing", 
               view.coord = -20, interpolate = FALSE)
display.plane (bottom = MR, top = b.closing, main = "After closing", 
               view.coord = -20, interpolate = FALSE)

Binary volume clustering

Description

The bin.clustering function groups and labels TRUE voxels that have a 6-connectivity (i.e. sharing a common side).

Usage

bin.clustering(vol, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object (see espadon.class for class definitions), of "cluster" modality. This object contains the $cluster.info field, detailing the label and volumes in \(cm^{3}\) of the different clusters. Note that the label "0" is used for the background.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "ct", 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]

# generation of a binary volume
b <- bin.from.vol(CT, min = -80, max = 20)

# Display of the n = 3 largest volumes
n <- 3
cluster.b <- bin.clustering (b)

col <- c ("#00000000", rainbow (n))
breaks <- seq (-0.5, n + 0.5, length.out = n+2)
display.plane (CT, top = b, main = "Before clustering",
               view.coord = 50, top.col = col, top.breaks = breaks, 
               interpolate = FALSE)
display.plane (CT, top = cluster.b, main = "After clustering", 
               view.coord = 50, top.col = col, top.breaks = breaks, 
               interpolate = FALSE)

Create a volume containing predefined shapes

Description

These functions create espadon objects of class “volume”, and of modality “binary” or “weight”, by selecting the voxels defining a rectangular cuboid, an elliptical cylinder or an ellipsoid.

Usage

bin.cuboid(
  back.vol,
  side = c(10, 10, 10),
  center = c(0, 0, 0),
  orientation = c(1, 0, 0, 0, 1, 0),
  modality = "weight",
  alias = "",
  description = NULL,
  ...
)

bin.cylinder(
  back.vol,
  center,
  radius,
  height,
  orientation = c(1, 0, 0, 0, 1, 0),
  modality = "weight",
  alias = "",
  description = NULL,
  ...
)

bin.ellipsoid(
  back.vol,
  center,
  radius,
  orientation = c(1, 0, 0, 0, 1, 0),
  modality = "weight",
  alias = "",
  description = NULL,
  ...
)

Arguments

Value

Returns a "volume" class object of "binary" or "weight" modality (see espadon.class for class definitions), with the same grid as back.vol.

• In the “binary” modality, voxels with 50 percent of their volume within the requested shape are set to TRUE.

• In the “weight” modality, the value of each voxel is its volume fraction included in the requested shape.

See Also

add.shape

Examples

# Creation of back.vol
CT <- vol.create (c(80, 80,40), c(1.2, 1.2, 2), 
                  pt000 = c(-50.4,-50.4,-39), modality = "ct", 
                  default.value = as.integer(-997), value.sd = 1)
                   
# Creation of a cuboid
cuboid <- bin.cuboid(CT, side = c(29.7, 20.0, 20.2), 
                     center = c(-10.9, -20.4, -10.6))
                       
# Creation of a cylinder 
cylinder <- bin.cylinder(CT, center =c(10.3, 15.6, 0.7), 
                         radius =  c(10, 20), height = 50, 
                         orientation = c(0.5150381, 0.7423287, 0.4285837,
                                         -0.8571673, 0.4460361, 0.2575190)) 
                      
# Creation of an ellipsoid 
ellipsoid <- bin.ellipsoid(CT, center = c(-20.1, 0.1, 5), 
                           radius =  c(3.3, 6.2, 5.3))  
                       
 # Display                         
 k.idx <- unique(which(cuboid$vol3D.data>0, arr.ind = TRUE)[,3]) - 1
 display.3D.stack(cuboid, k.idx, border = FALSE,
                  col = c("#FFFFFF00", "#EBDFDFFF", "#D8BFBFFF", "#C59F9FFF", 
                          "#B27F7FFF", "#9F5F5FFF", "#8C3F3FFF", "#791F1FFF", 
                          "#660000FF"))   
                           
 k.idx <- unique(which(cylinder$vol3D.data>0, arr.ind = TRUE)[,3]) - 1
 display.3D.stack(cylinder, k.idx, border = FALSE,
                  col = c("#FFFFFF00", "#DFEBDFFF", "#BFD8BFFF", "#9FC59FFF", 
                          "#7FB27FFF", "#5F9F5FFF", "#3F8C3FFF", "#1F791FFF", 
                          "#006600FF"))    

 k.idx <- unique(which(ellipsoid$vol3D.data>0, arr.ind = TRUE)[,3]) - 1
 display.3D.stack(ellipsoid, k.idx, border = FALSE,
                  col = c("#FFFFFF00", "#DFDFEBFF", "#BFBFD8FF", "#9F9FC5FF", 
                          "#7F7FB2FF", "#5F5F9FFF", "#3F3F8CFF", "#1F1F79FF", 
                          "#000066FF"))                           

Binary volume dilation

Description

The bin.dilation function enlarges a "volume" class object, of "binary" modality, by means of convolution with a sphere. Dilation is useful for :

• filling holes that are smaller than the radius,

• enlarging capes,

• filling narrow channels,

• merging two shapes close to each other.

Usage

bin.dilation(vol, radius = 10, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object of "binary" modality (see espadon.class for class definitions), with the same grid as vol, in which the selected volume has been enlarged by the radius.

See Also

bin.erosion, bin.opening, bin.closing, add.margin, nesting.cube.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "mr", roi.name = "", 
                             dxyz = rep (step, 3))
MR <- patient$mr[[1]]

# generation of a binary volume
b <- bin.from.vol(MR, min = 15,max = 30)

b.dilation <- bin.dilation (b, radius = step)
display.plane (bottom = MR, top = b, main = "Before dilation", 
               view.coord = -20, interpolate = FALSE)
display.plane (bottom = MR, top = b.dilation, main = "After dilation", 
               view.coord = -20,interpolate = FALSE)

Binary volume erosion

Description

The bin.erosion function decreases a "volume" class object, of "binary" modality, by means of convolution with a sphere. Erosion is useful for :

• removing volumes that are smaller than the radius,

• eliminating narrow capes,

• enlarging channels,

• turning peninsulas into islands.

Usage

bin.erosion(vol, radius = 10, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object of "binary" modality (see espadon.class for class definitions), with the same grid as vol, in which the selected volume has been reduced by the radius.

See Also

bin.dilation, bin.opening, bin.closing, add.margin, nesting.cube.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "mr", roi.name = "", 
                             dxyz = rep (step, 3))
MR <- patient$mr[[1]]

# generation of a binary volume
b <- bin.from.vol(MR, min = 15,max = 30)

b.erosion <- bin.erosion (b, radius = step)
display.plane (bottom = MR, top = b, main = "Before erosion", 
               view.coord = -20, interpolate = FALSE)
display.plane (bottom = MR, top = b.erosion, main = "After erosion", 
               view.coord = -20, interpolate = FALSE)

Creation of a binary volume according to RoI

Description

The bin.from.roi function creates a "volume" class object, of modality "binary" or "weight", by selecting the voxels defined by the RoI.

Usage

bin.from.roi(
  vol,
  struct,
  roi.name = NULL,
  roi.sname = NULL,
  roi.idx = NULL,
  T.MAT = NULL,
  within = TRUE,
  alias = "",
  description = NULL,
  modality = c("binary", "weight"),
  ...
)

Arguments

Details

roi.name, roi.sname, and roi.idx must select only one RoI.

Value

Returns a "volume" class object of "binary" or "weight" modality (see espadon.class for class definitions), with the same grid as vol.

• In the “binary” modality, voxels with 50 percent of their volume within the ROI are set to TRUE.

• In the “weight” modality, the value of each voxel is its volume fraction included in the ROI.

See Also

bin.from.vol.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 5
patient <- toy.load.patient (modality = c("ct", "rtstruct"), 
                             roi.name =  c("eye", "optical nerve", "brain"), 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

# "optical nerve" binary, with  modality "binary" and "weight"
binl <- bin.from.roi (CT, struct = S, roi.sname = "left optical",
                      alias = "left_optical_nerve", verbose = FALSE,
                      modality = "binary")
binr <- bin.from.roi (CT, struct = S, roi.sname = "right optical",
                      alias = "right_optical_nerve", verbose = FALSE,
                      modality = "weight")

view.coord <- S$roi.info[S$roi.info$roi.pseudo == "leftopticalnerve",]$Gz
palette <- grey.colors(100, start = 0, end = 1, 
                       alpha = c(0, rep(1,99)))
plot(S, view.coord = view.coord, main ="optical nerves")
plot(binl, view.coord = view.coord, col = palette, 
    cut.interpolate = FALSE, add = TRUE)
plot(binr, view.coord = view.coord, col =palette, 
      cut.interpolate = FALSE, add = TRUE)
plot(S, view.coord = view.coord, lwd = 2, add= TRUE)

## Not run: 
# with a smaller step
step <- 1
patient <- toy.load.patient (modality = c("ct", "rtstruct"), 
                             roi.name =  c("eye", "optical nerve", "brain"), 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]
#' view.coord <- S$roi.info[S$roi.info$roi.pseudo == "leftopticalnerve",]$Gz

# "optical nerve" binary without inclusions management
bin <- bin.from.roi (CT, struct = S, roi.sname = "left optical", 
                     alias = "left_optical_nerve", within = FALSE,
                     verbose = FALSE)
display.plane (CT, top = bin, struct = S, view.coord = view.coord, 
               legend.shift = -80, interpolate = FALSE, main = "Left nerve")

# "optical nerve" binary with inclusions management
bin <- bin.from.roi (CT, struct = S, roi.sname = "left optical", 
                     alias = "left_optical_nerve", within = TRUE,
                     verbose = FALSE)
display.plane (CT, top = bin, struct = S, view.coord = view.coord, 
               legend.shift = -80, interpolate = FALSE, main = "Left nerve") 

## End(Not run)

Creation of a binary volume according to the voxel values of a volume

Description

The bin.from.vol function creates a "volume" class object, of "binary" modality, in which the voxels fulfilling a condition on their value are selected.

Usage

bin.from.vol(
  vol,
  min = -Inf,
  max = Inf,
  in.selection = TRUE,
  alias = "",
  description = NULL
)

Arguments

Value

Returns a "volume" class object of "binary" modality, with the same grid as vol, in which the selected voxels (i.e. set to TRUE) are those satisfying the following conditions :

• If in.selection = TRUE, then min <= vol$vol3D.data <= max.

• If in.selection = FALSE, then vol$vol3D.data < min or max < vol$vol3D.data

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 3
patient <- toy.load.patient (modality = "ct", roi.name = "", 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]

bin.bone <- bin.from.vol (CT, min = 300, max = 3000, alias = "bone")
display.plane (CT, top = bin.bone, interpolate = FALSE)

Intersection of two binaries

Description

The bin.intersection function creates a "volume" class object, of "binary" modality, representing the intersection (logical AND) of two binary objects.

Usage

bin.intersection(vol1, vol2, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object of "binary" modality (see espadon.class for class definitions), with the same grid as vol1 and vol2, intersection of vol1 and vol2.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 3
patient <- toy.load.patient (modality = c("mr", "rtstruct"), 
                             roi.name = c("brain", "labyrinth processing unit"), 
                             dxyz = rep (step, 3))
MR <- patient$mr[[1]]
S <- patient$rtstruct[[1]]

z.brain <- S$roi.info$Gz[S$roi.info$roi.pseudo == "brain"]

# Try to discriminate the processing unit with binary selections
bin.brain <- bin.from.roi (MR, struct = S, roi.name = "brain",
                           alias = "brain", T.MAT = patient$T.MAT,
                           verbose = FALSE)
bin.pu.density <- bin.from.vol (MR, min = 160)   
   
display.plane (MR, top = bin.pu.density, display.ref = S$ref.pseudo,
               view.coord = z.brain, T.MAT = patient$T.MAT, 
               interpolate = FALSE, main = "before brain intersection")                      
bin.pu <- bin.intersection (vol1 = bin.pu.density, vol2 = bin.brain, 
                            alias = "processing unit")
display.plane (MR, top = bin.pu, display.ref = S$ref.pseudo,
               view.coord = z.brain, T.MAT = patient$T.MAT, 
               interpolate = FALSE, main = "after brain intersection")

Inversion of a binary

Description

The bin.inversion function creates a "volume" class object, of "binary" modality, representing the inverse (logical NOT) of another binary object.

Usage

bin.inversion(vol, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object of "binary" modality (see espadon.class for class definitions), with the same grid as vol, inverse of vol.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "rtstruct"), roi.name = "", 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

bin.patient <- bin.from.roi (CT, struct = S, roi.name = c ("patient"),
                             alias = "patient", verbose = FALSE)
inverse.patient <- bin.inversion (bin.patient, alias = "inv (patient)")

display.plane(CT, top = inverse.patient, interpolate = FALSE)

Binary volume opening

Description

The bin.opening function performs a morphological operation of opening, using a sphere, on a "volume" class object of "binary" modality. Opening is useful for :

• removing volumes that are smaller than the radius,

• smoothing shapes.

Usage

bin.opening(vol, radius = 10, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object of "binary" modality (see espadon.class for class definitions), with the same grid as vol, in which $vol3D.data has been transformed by the opening operation.

Note

Opening can be time consuming, try to reduce the binary volume to the strict minimum, before any operations.

See Also

bin.dilation, bin.erosion, bin.closing, add.margin, nesting.cube.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "mr", roi.name = "", 
                             dxyz = rep (step, 3))
MR <- patient$mr[[1]]

# generation of a binary volume
b <- bin.from.vol(MR, min = 15,max = 30)

b.opening <- bin.opening (b, radius = step)
display.plane (bottom = MR, top = b, main = "Before opening", 
               view.coord = -20, interpolate = FALSE)
display.plane (bottom = MR, top = b.opening, main = "After opening", 
               view.coord = -20, interpolate = FALSE)

Subtraction of two binaries

Description

The bin.subtraction function creates a "volume" class object of "binary" modality, representing the subtraction of two binary objects.

Usage

bin.subtraction(vol1, vol2, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object of "binary" modality (see espadon.class for class definitions), with the same grid as vol1 and vol2, in which vol2 is subtracted from vol1.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = c("mr", "rtstruct"), roi.name = "", 
                             dxyz = rep (step, 3))
MR <- patient$mr[[1]]
S <- patient$rtstruct[[1]]

z.ptv <- S$roi.info$Gz[S$roi.info$roi.pseudo == "ptv"]

# binaries
bin.patient <- bin.from.roi (MR, struct = S, roi.name = "patient",
                           alias = "patient", T.MAT = patient$T.MAT,
                           verbose = FALSE)
bin.ptv <- bin.from.roi (MR, struct = S, roi.name = "ptv",
                           alias = "ptv", T.MAT = patient$T.MAT,
                           verbose = FALSE)

#' calculation of the 'patient - ptv' binary
bin <- bin.subtraction (bin.patient, bin.ptv, alias = "patient - ptv")
display.plane (MR, top = bin, view.coord = z.ptv, 
               display.ref = S$ref.pseudo, T.MAT = patient$T.MAT,
               interpolate = FALSE)

Sum of two binaries

Description

The bin.sum function creates a "volume" class object of "binary" modality, representing the sum (logical OR) of two binary objects.

Usage

bin.sum(vol1, vol2, alias = "", description = NULL)

Arguments

Value

Returns a "volume" class object of "binary" modality (see espadon.class for class definitions), with the same grid as vol1 and vol2, sum of vol1 and vol2.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "rtstruct"), roi.name = "eye",
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

z.leye<- S$roi.info$Gz[S$roi.info$roi.pseudo == "lefteye"]


# 'left eye' et 'right eye' binaries
bin.left.eye <- bin.from.roi (CT, struct = S, roi.sname = "lefteye",
                              alias = "left eye", verbose = FALSE)
bin.right.eye <- bin.from.roi (CT, struct = S, roi.name = "righteye",
                               alias = "right eye", verbose = FALSE)
bin.eyes <- bin.sum (bin.left.eye, bin.right.eye, alias = "eyes")

display.plane (CT, top = bin.eyes, struct = S, roi.sname = "eye",
               view.coord = z.leye, legend.shift = -90 ,
               interpolate = FALSE)

Cast of a character string

Description

The castlow.str function converts a word to lowercase, without accents and spaces.

Usage

castlow.str(st)

Arguments

Value

Returns the ASCII//TRANSLIT transcription of the word st, without accents, spaces and in lowercase letters.

See Also

castup.str.

Examples

castlow.str (st = c("Right eye", "Left_Lung", "Right-Lung"))

Cast of a character string

Description

The castup.str function converts a word to upper case, without accents and spaces.

Usage

castup.str(st)

Arguments

Value

Returns the ASCII//TRANSLIT transcription of the word st, without accents, spaces and in capitals.

See Also

castlow.str.

Examples

castup.str (st = c("Right eye", "Left_Lung", "Right-Lung"))

DICOM raw data browser

Description

the dicom.browser function creates a dataframe describing the tags contained in the raw data of a DICOM file, as well as the information to access them.

Usage

dicom.browser(
  dicom.raw.data,
  nbTAG = 0,
  stop.tag = "",
  stop.level = 0,
  full.info = FALSE,
  tag.dictionary = dicom.tag.dictionary()
)

Arguments

Value

Returns a dataframe if dicom.raw.data is DICOM raw data, NULL otherwise.

If full.info = FALSE, dataframe columns are

• tag : the tags contained in dicom.raw.data,

• VR : value representation of the content of the tag,

• endian : the endianness of the tag content,

• start : the start address in dicom.raw.data of the tag content.

• stop : the stop address in dicom.raw.data of the tag content.

If full.info = TRUE, the following columns are added :

• encaps.load : If the tag contains nested data, this column gives the number of bytes remaining until the end of the nesting. If there are several levels of nesting, these numbers are collapsed and separated by a space.

• load.start : the start address in dicom.raw.data of the tag load size.

• load.stop : the stop address in dicom.raw.dataof the tag load size.

• tag.start : the start address in dicom.raw.data of the tag.

See Also

dicom.raw.data.loader, dicom.tag.parser

Examples

# DICOM information dataframe of the dummy raw data toy.dicom.raw ()
df <- dicom.browser (toy.dicom.raw (), full.info = TRUE)
str (df)

Conversion of DICOM raw data into a dataframe or a list of DICOM TAG information

Description

The dicom.parser function creates a dataframe or a list from DICOM raw data. The created dataframe or list provides information about the content of the DICOM TAGs included in the raw data.

Usage

dicom.parser(
  dcm,
  as.txt = TRUE,
  nested.list = FALSE,
  try.parse = FALSE,
  txt.sep = "\\",
  txt.length = 100,
  tag.dictionary = dicom.tag.dictionary(),
  ...
)

Arguments

Value

Returns a list of elements or a dataframe, depending on as.list.

If it returns a dataframe, the columns are names TAG, VR (value representation), VM (value multiplicity), loadsize and Value. The field $Value is a string representation of the true value.

If it returns a list, each of its elements, named by a TAG, is either a vector or a string, depending of the TAG included in dicom.raw.data.

See Also

dicom.raw.data.loader, dicom.tag.parser, dicom.viewer,xlsx.from.dcm,xlsx.from.Rdcm

Examples

# content of the dummy raw data toy.dicom.raw (), as a list.
L <- dicom.parser (toy.dicom.raw (), as.txt = FALSE)
str(L[40:57])

L <- dicom.parser (toy.dicom.raw (), as.txt = FALSE, nested.list = TRUE)
str(L[40:45])

# content of the dummy raw data toy.dicom.raw (), as a dataframe.
L <- dicom.parser (toy.dicom.raw (), as.txt = TRUE)
str (L)

Anonymisation of a patient's DICOM files

Description

the dicom.patient.anonymiser function anonymises all DICOM files in a patient's directory.

Usage

dicom.patient.anonymiser(
  dcm.files,
  pat.dest.dir,
  offset = 0,
  new.PIN = "ANONYMOUS^Unknown",
  reset.private.tag = FALSE,
  new.UID = FALSE,
  UID.white.list = "UID",
  UID.black.list = c("class", "context", "mapping", "coding"),
  tag.dictionary = dicom.tag.dictionary(),
  verbose = TRUE
)

Arguments

Value

Creation of the pat.dest.dir directory, with anonymous DICOM files

Note

The files are anonymized as follows:

• Each date of the DICOM file will be shifted by offset expressed in days.

• Each patient's name, and patient'ID are remplaced by new.PIN

• All other patient data are deleted, except age, weight, height, gender and shifted birthday.

• All address, phone, physician, operator, author, reviewer, service.

• If reset.private.tag = TRUE, the values of the tags not contained in the tag.dictionary are deleted.

File names are composed of their modality and a part of the SOP UID.

Examples

# First, save toy.dicom.raw () raw data to a temporary file pat.dir for testing.
temp <- tempdir()
pat.dir <- file.path (temp, "toy_dcm") 
dir.create (pat.dir, recursive = TRUE) 
dcm.filename <- tempfile (pattern = "toyrtplan", tmpdir = pat.dir,
                          fileext = ".dcm")
zz <- file (dcm.filename, "wb")
writeBin (toy.dicom.raw (), zz, size = 1)
close (zz)

# Files anonymisation
anonymous.pat.dir <- file.path (temp, "anonymous") 
dicom.patient.anonymiser (dcm.files = pat.dir, pat.dest.dir = anonymous.pat.dir,
                          offset = 0, new.PIN = "Anonymous patient",
                          reset.private.tag = TRUE)
lf <- list.files(anonymous.pat.dir, full.names = TRUE)  
dp <- dicom.parser(lf[1])   
dp[grep("^[(]0008|^[(]0010", dp$TAG),]       

# Cleaning  temporary directory
unlink (pat.dir, recursive = TRUE)            

DICOM anonymizer

Description

the dicom.raw.data.anonymizer function anonymizes dicom.raw.data.

Usage

dicom.raw.data.anonymizer(
  dicom.raw.data,
  offset = 0,
  new.PIN = "ANONYMOUS^Unknown",
  reset.private.tag = FALSE,
  new.UID = FALSE,
  UID.white.list = "UID",
  UID.black.list = c("class", "context", "mapping", "coding"),
  tag.dictionary = dicom.tag.dictionary()
)

Arguments

Value

Returns an anonymyzed raw vector. See Note.

Note

The raw data is anonymized as follows:

• Each date of the DICOM file will be shifted by offset expressed in days.

• Each patient's name, and patient'ID are remplaced by new.PIN

• All other patient data are deleted, except age, weight, height, gender and shifted birthday.

• All address, phone, physician, operator, author, reviewer, service.

• If reset.private.tag = TRUE, the values of the tags not contained in the tag.dictionary are deleted.

Examples

# pseudomization of the dummy raw data toy.dicom.raw ()
an.raw.data <- dicom.raw.data.anonymizer (toy.dicom.raw (), offset = -2)
data <- dicom.parser (toy.dicom.raw ())
an.data <- dicom.parser (an.raw.data) 

# Checking for differences
flag.dif <- data$Value !=  an.data$Value  
df <- cbind (data[flag.dif, c ("VM","Value")], an.data[flag.dif, "Value"])      
colnames (df) <-   c ("VM","old Value","new Value")    
df                                     

# save data in a the new file
#############################
# new.file.name <- "an.dcm"
# zz <- file (new.file.name, "wb")
# writeBin (an.raw.data, zz, size = 1)
# close (zz)

DICOM file loading in raw data

Description

the dicom.raw.data.loader function loads a DICOM file as raw data.

Usage

dicom.raw.data.loader(dcm.filename)

Arguments

Value

Returns a vector of raw data from dcm.filename.

See Also

dicom.browser, dicom.tag.parser

Examples

# First, save toy.dicom.raw () raw data to a temporary file for testing.
pat.src.dir <- file.path (tempdir(), "toy_dcm")
dir.create (pat.src.dir, recursive = TRUE) 
dcm.filename <- tempfile (pattern = "toyrtplan", tmpdir = pat.src.dir,
                          fileext = ".dcm")
zz <- file (dcm.filename, "wb")
writeBin (toy.dicom.raw (), zz, size = 1)
close (zz)

# loading of file
dicom.raw.data <- dicom.raw.data.loader (dcm.filename)

# checks if it is consistent with the original raw data
all ( dicom.raw.data == toy.dicom.raw () )

# Cleaning  temporary directory
unlink (pat.src.dir, recursive = TRUE)

Change TAG value in DICOM raw data

Description

The dicom.set.tag.value function changes, in the DICOM raw data, the values of the TAG whose VR is a string of characters.

Usage

dicom.set.tag.value(
  dicom.raw.data,
  tag,
  tag.value,
  tag.dictionary = dicom.tag.dictionary(),
  ...
)

Arguments

Value

Returns a raw vector, with new tag values.

Note

1- The list of tags included in the DICOM file are given by the first columns of the dataframe provided by the functions dicom.browser and dicom.parser.

2- The dicom.set.tag.value function may take some processing time. To minimize this time, it is recommended to prepare in advance all the tags to be modified, and use the dicom.set.tag.value function only once, as shown in the example.

Examples

# change the value of tags "(0010,0010)" and "(0010,0020)" in the
# dummy raw data toy.dicom.raw ()
new.raw.data <- dicom.set.tag.value (toy.dicom.raw (), 
                                     tag =  c ("(0010,0010)", "(0010,0020)"),
                                     tag.value = c ("unknown", "000001"))
# change control 
data <- dicom.parser (new.raw.data) 
data[data$TAG %in% c ("(0010,0010)", "(0010,0020)"), ]

# save data in a the new file
#############################
# new.file.name <- "new.dcm"
# zz <- file (new.file.name, "wb")
# writeBin (new.raw.data  , zz, size = 1)
# close (zz)

DICOM TAG dictionary

Description

The dicom.tag.dictionary function gives the dictionary of tags used by default in the espadon package.

Usage

dicom.tag.dictionary(add.dict = c("raysearch.tag"))

Arguments

Value

Returns a 3-column dataframe, describing the VR (value representation) and the name of each DICOM TAG.

This dataframe is the fusion of the "nema.tag" dictionary, provided by nema [1], with the dictionaries defined in the add.dict vector:

• "raysearch.tag" dictionary is provided by RaySearch laboratories [2]

References

[1] DICOM nema (Online; accessed 2022-02-16). “Current Edition.” https://www.dicomstandard.org/current.

[2] Raysearch Laboratories (Online; accessed 2022-04-25). “RAYPLAN 11A, DICOM Conformance Statement.” https://www.raysearchlabs.com/siteassets/raystation-landing-page/dicom-conformance-statements/raystation-pdfs/rsl-d-rs-11a-dcs-en-1.0-2021-05-07-raystation-11a-dicom-conformance-statement.pdf.

Examples

str (dicom.tag.dictionary ())
str (dicom.tag.dictionary (NULL))

DICOM TAG parser

Description

the dicom.tag.parser function decodes the content between two DICOM raw data addresses.

Usage

dicom.tag.parser(start, stop, VR, endian, dicom.raw.data, try.parse = FALSE)

Arguments

Value

Returns the dicom.raw.data content between the addresses start and stop. Depending on the representation of the value (VR), it can be a character string or a numerical vector.

Examples

# creation of the toy.dicom.raw () addresses dataframe:
df <- dicom.browser (toy.dicom.raw ())

# search for modality of toy.dicom.raw ()
idx <- grep ("^[(]0008,0060[)]$", df$tag)
modality  <- dicom.tag.parser (df$start[idx], df$stop[idx], df$VR[idx], 
                               df$endian[idx], toy.dicom.raw ())
modality

Conversion of DICOM object into files that can be interpreted by the espadon package

Description

The dicom.to.Rdcm.converter function creates, for each DICOM object, a *.Rdcm file usefull for using espadon package. Each Rdcm file created is referenced by the date of acquisition of the object (if it is not available, its creation date), the patient's PIN, a reference number, an object number in this reference system, and the object modality (mr, ct, rtstruct...).

Usage

dicom.to.Rdcm.converter(
  dcm.files,
  pat.dest.dir,
  update = TRUE,
  ignore.duplicates = FALSE,
  tag.dictionary = dicom.tag.dictionary(),
  verbose = TRUE
)

Arguments

Value

Returns the list of basenames of the created files.

Returns NULL if there are no DICOM files in dcm.files

Note

For each DICOM object, dicom.to.Rdcm.converter creates a *.Rdcm file whose basename is made up of the date of the acquisition (or creation date if previous not found), the patient's PIN, the pseudonym of the frame of reference ("ref1", "ref2"...), the number of the volume object in the directory in this frame of reference ("do1", "do2"...), and the object modality ("mr", "ct", "rtdose", "rtstruct"...).

For example: BASE = "20160514_a008e9ac_ref2_do1_mr"

Examples

# First, save toy.dicom.raw () raw data to a temporary file for testing.
pat.src.dir <- file.path (tempdir(), "PM_dcm") 
dir.create (pat.src.dir, recursive = TRUE) 
dcm.filename <- tempfile (pattern = "PM_rtplan", tmpdir = pat.src.dir,
                          fileext = ".dcm")
zz <- file (dcm.filename, "wb")
writeBin (toy.dicom.raw (), zz, size = 1)
close (zz)

# Create a temporary destination directory where the *.Rdcm file will be saved
pat.dest.dir <- file.path (tempdir(), "PM_Rdcm")

dicom.to.Rdcm.converter (pat.src.dir, pat.dest.dir, update = TRUE)
# or
dicom.to.Rdcm.converter (dcm.filename, pat.dest.dir, update = TRUE)

list.files (pat.dest.dir)

# Cleaning  temporary directories
unlink (pat.src.dir, recursive = TRUE)
unlink (pat.dest.dir, recursive = TRUE)

DICOM content viewer

Description

the dicom.viewer function displays the data of a DICOM file.

Usage

dicom.viewer(
  dcm,
  txt.sep = "\\",
  txt.length = 100,
  tag.dictionary = dicom.tag.dictionary(),
  height = 600,
  width = 900,
  ...
)

Arguments

Value

Returns the DICOM file description in a browser window.

See Also

xlsx.from.dcm, xlsx.from.Rdcm, dicom.parser

Examples

if (interactive ()) dicom.viewer (toy.dicom.raw ())

Display of a 2D histogram

Description

The display.2D.histo function displays the density map of a "histo2D" class object.

Usage

display.2D.histo(
  histo.2D,
  add = TRUE,
  main = NULL,
  x.lab = NULL,
  y.lab = NULL,
  x.lim = NULL,
  y.lim = NULL,
  bg = "#000000",
  i.rng = NULL,
  display.mode = c("mono.color", "rainbow.color", "line"),
  col = "#ffffff",
  alpha = 1,
  line.pc.levels = c(1, 100),
  line.lwd = 2,
  line.lty = 1
)

Arguments

Details

The display.mode argument can be set to three values: "mono.color", "rainbow.color", or "line". The 2D histogram graph is displayed by default in "mono.color" mode.

• The "mono.color" mode displays a gradient of the color defined by the col argument, depending on the intensity of $density.map 2-dimensional array.

• The "rainbow.color" mode makes a display according to the "rainbow" palette, while managing the opacity of the colors.

• The "line" mode draws level lines defined in percent by the line.pc.levels argument.

Value

Returns a display of the density map of histo.2D. This one must be an object of class "histo2D". See espadon.class for class definitions.

See Also

histo.2D.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "mr", "rtstruct"), 
                             roi.name =  "brain", 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
MR <- patient$mr[[1]]
S <- patient$rtstruct[[1]]
T.MAT <- patient$T.MAT

# restriction of the volume around the RoI
CT.on.roi <- nesting.roi (CT, S, roi.name = "brain", vol.restrict = TRUE,
                          xyz.margin = c (1, 1, 1), alias = CT$description)
MR.on.CT <- vol.regrid (vol = MR, back.vol = CT.on.roi, interpolate = TRUE,
                        T.MAT = T.MAT, alias = CT$description,
                        description = NULL)
# selection of voxels included in the RoI.
roi.bin <- bin.from.roi (vol = CT.on.roi, struct = S, roi.sname = "brain",
                         verbose = FALSE)
MR.select <- vol.from.bin (MR.on.CT, roi.bin, alias = MR$description)
CT.select <- vol.from.bin (CT.on.roi, roi.bin, alias = CT$description)
# 2D histogram
H2D <- histo.2D (MR.select, CT.select, x.breaks = seq (50, 400, 10),
			  y.breaks = seq (50, 400, 10), alias = "H2D MR1 MR2")
display.2D.histo (H2D, display.mode = "mono.color", col = "#ffff00", 
                  main ="mono color mode")
display.2D.histo (H2D, display.mode = "rainbow.color", main ="rainbow mode")
display.2D.histo (H2D, display.mode = "line", main ="level lines mode",
                  line.pc.levels = c (0, 25, 50, 75, 100), col = "#ff0000")

Display the 3D contours of the RoI

Description

The display.3D.contour function performs a 3D display of the selected RoI in the chosen coordinate system.

Usage

display.3D.contour(
  struct,
  roi.name = NULL,
  roi.sname = NULL,
  roi.idx = NULL,
  roi.col = NULL,
  roi.print = FALSE,
  roi.lwd = 1,
  roi.cex = 1,
  display.ref = struct$ref.pseudo,
  T.MAT = NULL,
  FoR.axis = FALSE,
  FoR.col = "black"
)

Arguments

Details

If roi.name, roi.sname, and roi.idx are all NULL, then all of the RoI are selected.

Value

If the concerned regions of interest (RoI) struct exist, it displays the 3D contours of these RoI in the current RGL window if it exists, in a new window otherwise.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "rtstruct", roi.name = "eye",
                             dxyz = rep (step, 3))
rgl::open3d()
rgl::bg3d ("black")
display.3D.contour (struct = patient$rtstruct[[1]], roi.print = TRUE)

3D display of a mesh

Description

The display.3D.mesh function performs a 3D display of a mesh.

Usage

display.3D.mesh(mesh, display.ref = mesh$ref.pseudo, T.MAT = NULL, ...)

Arguments

Value

Returns a display of mesh in the current RGL window if it exists, in a new window otherwise.

See Also

mesh.from.bin.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "rtstruct"), roi.name = "",
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

# creation of the patient mesh
bin <- bin.from.roi (CT, struct = S, roi.name = "patient", verbose = FALSE)
mesh.patient <- mesh.from.bin (bin, alias = "patient", verbose = FALSE)

# display of the patient mesh, with transparency
rgl::open3d()
display.3D.mesh (mesh.patient, color = "burlywood2", specular = "#404040")

Display 3D sections of a patient

Description

The display.3D.sections function displays transverse, sagittal and frontal views at a point in 3D.

Usage

display.3D.sections(
  obj,
  cross.pt = c(0, 0, 0),
  display.ref = obj$ref.pseudo,
  T.MAT = NULL,
  col = grey.colors(10, start = 0, end = 1, alpha = c(rep(0, 1), rep(1, 9))),
  breaks = NULL,
  trans = TRUE,
  sagi = TRUE,
  front = TRUE,
  border = TRUE,
  border.col = "#379DA2",
  ...
)

Arguments

Value

Returns a display of transverse, sagittal and frontal views of obj at cross.pt in the current RGL window if it exists, in a new window otherwise. Palette colors are managed by col and breaks.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "ct", dxyz = rep (step, 3))
CT <- patient$ct[[1]]

rgl::open3d()
display.3D.sections(CT, cross.pt= c(0, 50, 80),
                    col= pal.RVV(200, alpha= c(rep(0,90), rep(1,110))))

Display in 3D the selected planes of an espadon class volume

Description

The display.3D.stack function displays in 3D the requested cutting planes of a "volume" class object.

Usage

display.3D.stack(
  vol,
  k.idx = unique(vol$k.idx[seq(1, vol$n.ijk[3], length.out = 10)]),
  display.ref = vol$ref.pseudo,
  T.MAT = NULL,
  col = grey.colors(10, start = 0, end = 1, alpha = c(rep(0, 1), rep(1, 9))),
  breaks = NULL,
  cube = TRUE,
  border = TRUE,
  ktext = TRUE,
  line.col = "#379DA2",
  line.lwd = 1,
  cex = 1
)

Arguments

Value

Returns a display of the k.idx cutting planes of vol, in the current RGL window if it exists, in a new window otherwise. The colors of the palettes are managed by col and breaks.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "ct", dxyz = rep (step, 3))

# display o 3 planes
rgl::open3d()
display.3D.stack (patient$ct[[1]],
                  col = pal.RVV (200, alpha = c(rep(0,90), rep (1, 110))))

Display of a DVH

Description

The display.DVH function displays the Dose Volume Histogram of a "dvh" class object. Y-units are \(cm^3\).

Usage

display.DVH(
  dvh,
  add = FALSE,
  xgrid = TRUE,
  ygrid = TRUE,
  MC.plot = FALSE,
  MC.col = grey.colors(4, rev = TRUE),
  ...
)

Arguments

Value

Returns a plot of the cumulative histogram included in dvh, with its median, and the quantile areas (0%-100%), (2.5%-97.5%) and (25%-75%) of the dvh$vol variations, if they exist.

See Also

display.DVH.pc

Examples

# DVH without MCMC
# loading of toy-patient objects (decrease dxyz and increase beam.nb for 
# better result)
step <- 5 
patient <- toy.load.patient (modality = c("rtdose", "rtstruct"), roi.name = "",
                             dxyz = rep (step, 3), beam.nb = 3)
H <- histo.from.roi (patient$rtdose[[1]], patient$rtstruct[[1]], roi.name = "ptv", 
                     breaks = seq (0, 60, by = 2))
DVH <- histo.DVH (H)
display.DVH (DVH)

## Not run: 
# loading of toy-patient objects
patient <- toy.load.patient (modality = c("rtdose", "rtstruct"), 
                             roi.name = "gizzard",
                             dxyz = c (2, 2, 2), beam.nb = 3)

# Calculation of the histogram
H <- histo.from.roi (patient$rtdose[[1]], patient$rtstruct[[1]], 
                     roi.name = "gizzard", 
                     breaks = seq (0, 60, by = 1), MC = 100)

# DVH
DVH <- histo.DVH (H)
display.DVH (DVH, MC.plot = TRUE, ylim = c (0, 40))

## End(Not run)

Display of a cumulative DVH in percent of total volume

Description

The display.DVH.pc function displays the Dose Volume Histogram of "dvh" class object. Y-units are percents of total volume.

Usage

display.DVH.pc(
  dvh,
  add = FALSE,
  xgrid = TRUE,
  ygrid = TRUE,
  MC.plot = FALSE,
  MC.col = grey.colors(4, rev = TRUE),
  ...
)

Arguments

Value

Returns a plot in percent of total volume of the cumulative histogram included in dvh, with its median, and the quantile areas (0%-100%), (2.5%-97.5%) and (25%-75%) of the dvh$pcv variations, if they exist.

See Also

display.DVH

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for 
# better result)
step <- 5
patient <- toy.load.patient (modality = c("rtdose", "rtstruct"), 
                             roi.name = "gizzard", dxyz = rep (step, 3), 
                             beam.nb = 3)

# Calculation of the histogram
H <- histo.from.roi (patient$rtdose[[1]], patient$rtstruct[[1]], 
                     roi.name = "gizzard", 
                     breaks = seq (0, 60, by = 1))

# DVH
DVH <- histo.DVH (H)
display.DVH.pc (DVH)

Display of the volume density of a histogram

Description

The display.dV_dx function displays the volume density of a "histo" class object. Y-units are \(cm^3.Gy^{-1}\).

Usage

display.dV_dx(
  histo,
  add = FALSE,
  xgrid = TRUE,
  ygrid = TRUE,
  MC.plot = FALSE,
  MC.col = grey.colors(4, rev = TRUE),
  ...
)

Arguments

Value

Returns a plot of the differential histogram included in histo, with its median, and the quantile areas (0%-100%), (2.5%-97.5%) and (25%-75%) of the histo$dv_dx variations, if they exist.

See Also

display.histo.

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for 
# better result)
step <- 5
patient <- toy.load.patient (modality = c("rtdose", "rtstruct"),
                             roi.name = "gizzard", dxyz = rep (step, 3), 
                             beam.nb = 3)

# Calculation of the differential histogram
H <- histo.from.roi (patient$rtdose[[1]], patient$rtstruct[[1]], 
                     roi.name = "gizzard", breaks = seq (0, 60, by = 2))
display.dV_dx (H, lwd = 2, col = '#00ff00', ylim = c (0,10))

Display of the counts of a histogram

Description

The display.histo function displays the counts of "histo" class object.

Usage

display.histo(
  histo,
  add = FALSE,
  xgrid = TRUE,
  ygrid = TRUE,
  MC.plot = FALSE,
  MC.col = grey.colors(4, rev = TRUE),
  ...
)

Arguments

Value

Returns a plot of the counts included in histo, with its median, and the quantile areas (0%-100%), (2.5%-97.5%) and (25%-75%) of the histo$counts variations, if they exist.

See Also

display.dV_dx.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 3
patient <- toy.load.patient (modality = "ct", dxyz = rep (step, 3))
CT <- patient$ct[[1]]

# histogram and display
H <- histo.vol (CT, breaks = seq (3, ceiling (CT$max.pixel), 1), 
                alias = "CT_hist")
display.histo (H, log = "y", lwd = 2)

Display of a plane of a volume

Description

The display.kplane function displays the requested plane of a "volume" class object. This function is low-level, used for example in the function display.plane with more intuitive arguments.

Usage

display.kplane(
  vol,
  k = vol$k.idx[ceiling(length(vol$k.idx)/2)],
  pt00 = c(0, 0),
  dxy = c(1, 1),
  col = grey.colors(255, start = 0, end = 1),
  breaks = NULL,
  sat.transp = FALSE,
  add = FALSE,
  main = NULL,
  abs.lab = "i",
  ord.lab = "j",
  flip = FALSE,
  flop = FALSE,
  bg = "#000000",
  abs.rng = NULL,
  ord.rng = NULL,
  interpolate = FALSE,
  ...
)

Arguments

Value

Returns a display of the \(k^{th}\) image plane of vol.

See Also

display.plane.

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for
# better result)
step <- 5
patient <- toy.load.patient (modality = c("ct","mr", "rtdose"),
                             dxyz = rep (step, 3), beam.nb = 3)
MR <- patient$mr[[1]]
CT <- patient$ct[[1]]
D <- patient$rtdose[[1]]

# display

display.kplane (CT)

display.kplane (MR, k = floor (length(MR$k.idx)*5/8), 
                col = grey.colors (256, start = 0, end = 1),
                breaks = seq (0, 500, length.out = 257), bg = "darkblue")


display.kplane (D, k = floor (length(D$k.idx)*3/8),
                col = rainbow (256, s = seq (1, 0, length.out = 256),
                               start = 0, end = 4/6,
                               alpha = seq (0.8, 0, length.out=256),
                               rev = TRUE),
                bg = "darkblue", ord.flip = TRUE, sat.transp = FALSE,
                interpolate = FALSE)

display.kplane (CT, k = floor (length(CT$k.idx)/3), col = pal.RVV (1000),
                bg = "darkblue", ord.flip = TRUE, interpolate = FALSE)

Display of the RoI legend

Description

The display.legend function displays in an image the list of requested RoI and their associated color.

Usage

display.legend(
  struct = NULL,
  roi.name = NULL,
  roi.sname = NULL,
  roi.idx = NULL,
  lwd = 1,
  cex = 1,
  displayed.roi.name = NULL,
  bg = "black",
  text.col = "white"
)

Arguments

Details

roi.name, roi.sname, and roi.idx indicates the RoI to display. If all three are set to NULL, all RoI are selected.

Value

Returns display of the RoI names and their associated color in the active graphics window.

Examples

# loading of toy-patient objects
patient <- toy.load.patient (modality = c("rtstruct"), dxyz = c (5, 5, 5))
S <- patient$rtstruct[[1]]

display.legend (struct = S, roi.idx = 2:10, lwd = 2)

Display patient objects links

Description

The display.obj.links function displays a graph of connections between objects of a patient. The name of the objects corresponds to their modality (ct, mr, rtdose...) followed by their position in their respective lists in the patient list objects. Connected objects are linked by arrows. Objects sharing the same frame of reference have the same color except for objects with warnings, errors or missing planes which are all in grey. Approved objects are circled in green. By default, objects shapes are circles, except rtdose represented as squares.

Usage

display.obj.links(
  pat,
  obj.selected = NULL,
  exclusion = NULL,
  square = "rtdose",
  group.by.connected.FoR = TRUE,
  interactive = FALSE,
  random.seed = 314
)

Arguments

Value

The function displays all patient objects, linked by an arrow when they are connected or a line when they belongs to the same DICOM object, and with a color and a shape depending on square, group.by.connected.FoR.

When interactive = TRUE, it returns a dataframe of the selected objects, or NULL if no object is selected.

Items are circled in green when the DICOM file has been approved. They are circled in red, when the DICOM series is incomplete (e.g. missing plan).

See Also

get.obj.connection

Examples

# loading of toy-patient objects
patient <- toy.load.patient (dxyz = c (5, 5, 5), beam.nb = 1)
display.obj.links (patient, group.by.connected.FoR = FALSE)
display.obj.links (patient, group.by.connected.FoR = TRUE)
display.obj.links (patient, group.by.connected.FoR = TRUE, random.seed=NULL)

Display of the color scale of a color palette

Description

The Display.palette function displays the color scale as it is used for representations in espadon functions

Usage

display.palette(
  col,
  breaks = NULL,
  factors = NULL,
  override.breaks = FALSE,
  new.window = FALSE,
  ...
)

Arguments

Value

Returns in a new device (if new.window = TRUE), or in the active graphics window (if new.window = FALSE), the palette color defined by col and breaks in priority, or by col and factors.

Note

the breaks are not necessarily evenly spaced. In this case, the colour palette can be represented as the breaks are defined (default option) or by choosing a constant spacing for each colour and displaying the associated abscissa calculated from the breaks (override.breaks = TRUE).

Examples

## Not run:                 
# simple example for breaks and factors

display.palette (c ("red", "green", "blue"), breaks = c(0, 1, 3, 7), 
                 ylab = "a simple color palette")
display.palette (c ("red", "green", "blue"), breaks = c(0, 1, 3, 7), 
                 override.breaks = TRUE)
display.palette (c ("red", "green", "blue"), 
                 factors = c("red", "green", "blue"))
display.palette (c ("grey", "green", "blue"), factors = c(NA, 1, 2))

# for RVV palette, the function computes breaks between -1000 and 1000
display.palette (pal.RVV (255), new.window = TRUE)

# a palette for dose, for instance
display.palette (rainbow (255, start = 0, end = 4/6, rev = TRUE), 
                 breaks = seq (0, 60, length.out = 256), new.window = TRUE)

# black & white palette for CTs or MRs
display.palette (grey.colors (255, start = 0, end = 1), 
                 breaks = seq (0, 60, length.out = 256), new.window = TRUE)

# transparency affects colors depending on background (black in first exemple,
# white in the second one)
display.palette (pal.rainbow(255), breaks = seq (0, 60, length.out=256))
display.palette (pal.rainbow(255), breaks = seq (0, 60, length.out=256), 
                 bg = "white", new.window = TRUE)

## End(Not run)                         
# colors contracted range using non uniform breaks in the plot window
display.palette (pal.rainbow(255),
                 breaks = seq (0, 1, length.out = 256)^0.25 * 60, bg="grey", 
                 new.window = FALSE)

# the same using breaks override
display.palette (pal.rainbow(255),
                 breaks = seq (0, 1, length.out = 256)^0.25 * 60, bg="grey", 
                 override.breaks = TRUE, new.window = FALSE)

Display the transverse frontal or sagittal view in the patient reference system

Description

The display.plane function displays an overlay of images and RoI closed planar contours on a plane defined by the equations x = constant (sagittal view), or y = constant (frontal view) or z = constant (transverse view) in a frame of reference chosen by the user.

Usage

display.plane(
  bottom = NULL,
  top = NULL,
  struct = NULL,
  roi.name = NULL,
  roi.sname = NULL,
  roi.idx = NULL,
  struct.dxyz = c(0.5, 0.5, struct$thickness),
  display.ref = NULL,
  T.MAT = NULL,
  interpolate = TRUE,
  view.type = c("trans", "front", "sagi"),
  view.coord = 0,
  bg = "#000000",
  abs.rng = NULL,
  ord.rng = NULL,
  bottom.col = grey.colors(255, start = 0, end = 1),
  top.col = pal.rainbow(255),
  bottom.breaks = NULL,
  top.breaks = NULL,
  sat.transp = FALSE,
  struct.lwd = 2,
  main = NULL,
  legend.plot = TRUE,
  legend.shift = 0,
  legend.roi.pseudo = TRUE,
  ...
)

Arguments

Details

If roi.name, roi.sname, and roi.idx are all set to NULL, all closed planar or point RoI are selected. If a RoI is not present in the requested plane, the RoI legend won't mention it.

Value

Returns a display of the transverse, sagittal or frontal plane. This plane has the coordinate z = view.coord (transverse), y = view.coord (sagittal) pr x = view.coord (frontal). The display is an overlay of:

• a background image of uniform color bg

• the bottom image if it exists

• the top image if it exists

• the contours of the regions of interest if they exist in the plane considered.

Note

1- The main title is given by bottom, the subtitle by top.

2- When top is in the "rtdose" modality, the maximum dose is written on the image.

See Also

display.kplane, plot.volume, plot.struct, plot.mesh.

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for 
# better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "mr", "rtstruct", "rtdose"), 
                             roi.name  = "",
                             dxyz = rep (step, 3), beam.nb = 3)
CT <- patient$ct[[1]]
MR <- patient$mr[[1]]
D <- patient$rtdose[[1]]
S <- patient$rtstruct[[1]]

display.plane (bottom = CT, top = D, struct = S, view.coord = -30, 
               interpolate = FALSE, legend.shift = -80)
# Display of CT in reference frame "ref1" and  MR in "ref2"               
display.plane (bottom = CT, top = MR, interpolate = FALSE)

# Display of CT and MR in reference frame "ref2"
display.plane (bottom = CT, top = MR, interpolate = FALSE, display.ref ="ref2",
               T.MAT = patient$T.MAT)

Error evaluation metrics for 2-volume comparisons

Description

The err.metrics.from.roi and err.metrics.from.bin calculate various metrics (ME, MAE, MSE, RMSE) to compare 2 “volume” class objects in the zones delimited by the requested RoI or binary selections

Usage

err.metrics.from.roi(
  obj,
  obj.ref,
  struct = NULL,
  roi.name = NULL,
  roi.sname = NULL,
  roi.idx = NULL,
  T.MAT = NULL
)

err.metrics.from.bin(obj, obj.ref, bin.list = NULL, T.MAT)

Arguments

Details

If roi.name, roi.sname, and roi.idx are all set to NULL, all RoI whose volume is greater than 0 are selected.

Value

Returns, in the zones delimited by the requested RoI, the following metrics:

• ME: Mean Error

• MAE: Mean Absolute Error

• MSE: Mean Squared Error

• RMSE: Root Mean Squared Error

• MIN: Min Error

• MAX: Max Error

Examples

# loading of toy-patient objects (decrease dxyz)
step <- 5
patient <- toy.load.patient (modality = c("ct", "sct","rtstruct"), 
                             roi.name = c("eye", "brain","gizzard"),
                             dxyz = rep (step, 3))

patient$ct[[1]]$description
patient$ct[[2]]$description
# Calculation of eye zone and ptv metrics
err.metrics.from.roi(obj = patient$ct[[2]], obj.ref = patient$ct[[1]], 
                     struct = patient$rtstruct[[1]], roi.sname = c("eye","ptv"),
                     T.MAT= patient$T.MAT)
# Calculation of metrics on delimited zones on all RoIs
err.metrics.from.roi(obj = patient$ct[[2]], obj.ref = patient$ct[[1]], 
                     struct = patient$rtstruct[[1]],
                     T.MAT= patient$T.MAT)
                     
# Calculation on all volume
err.metrics.from.roi(obj = patient$ct[[2]], obj.ref = patient$ct[[1]], 
                     T.MAT= patient$T.MAT)
 
# Calculation using err.metrics.from.bin. The binary selection must first be 
# created.  
roi.idx <- select.names(patient$rtstruct[[1]]$roi.info$roi.pseudo,
                        roi.sname = c("eye","ptv"))  
bin.ROI <- lapply (roi.idx, function(idx){
   bin.from.roi (patient$ct[[1]], struct = patient$rtstruct[[1]], 
                 roi.idx = idx, T.MAT = patient$T.MAT, 
                 alias = patient$rtstruct[[1]]$roi.info$roi.pseudo[idx], 
                 description = patient$rtstruct[[1]]$roi.info$name[idx],
                 modality = "weight")})   
 names (bin.ROI) <-patient$rtstruct[[1]]$roi.info$name[roi.idx]   
 
 err.metrics.from.bin (obj = patient$ct[[2]], obj.ref = patient$ct[[1]], 
                       bin.list = bin.ROI, T.MAT= patient$T.MAT)                             

ESPADON class

Description

ESPADON class

Usage

espadon.class()

Value

Returns a vector of espadon class names.

Note

Each object of a class has specific features that are used to display or process that object.

- the "patient" class includes :

• $patient : dataframe providing patient's information as PIN, birth date and gender.

• $pat.pseudo : patient's pseudonym, initialized to the patient's PIN of $patient dataframe.

• $description : dataframe describing the patient's DICOM objects: their modality (rtstruct, ct, mr, rtplan ...), the base name of the relevant source file in the patient's directory, the pseudonym of their frame of reference (ref1, ref2 ...), their number of sub-objects, their description if any, their numbers of slices/RoI for all sub-objects, their maximum voxels (for volume sub-objects), and finally the aliases of the sub-objects.

• $description.by.reg: list of DICOM objects descriptions that are linked by a transfer matrix.

• $T.MAT : list of class "t.mat" containing the information of the transfer matrices to move from one frame of reference to another. See load.T.MAT.

• $ct : list of CT, if any. They are named by their $object.alias See load.obj.from.Rdcm.

• $mr : list of MRI, if any. They are formatted like the $ct.

• $rtdose : list of dose matrices. They are formatted like the $ct.

• $rtstruct: list of struct objects.

• ...any DICOM objects other than the reg files, and those previously mentioned, or any modalities created by espadon.

• $dicom.dvh: if any, list of DVH computed in rt-dose DICOM files.

- the "t.mat" class includes :

• $ref.info: dataframe giving the correspondence between the frame of reference (column $ref) of the DICOM object (TAG (0020,0052) ) and its pseudonym (column $ref_pseudo).

• $reg.info: list of dataframes : the first one gives the PID, birthday, and sex of the patient, the second one gives the name of the source file of transfer matrices.

• $matrix.description: dataframe giving the transfer matrix names (column $t), its source frame of reference (column $src), the destination frame of reference (column $dest), and its type ($type). Note that only the RIGID type is supported.

• $matrix.list: list of 4X4 transfer matrices. This list contains at least as many Identity matrices as there are ref.pseudo.

A espadon object of class "dvh", "fan", "histo","histo2D","mesh", "reg", "struct", "t.mat","undef","volume" is a list containing at least:

• $patient: patient's PIN.

• $patient.name: patient's name.

• $patient.bd: patient's birthday.

• $patient.sex: patient's sex

• $file.basename: vector of .Rdcm or .dcm file basenames of the object, if it exists

• $file.dirname : directory including the .Rdcm or .dcm file, if it exists

• $object.name: name of the object.

• $object.alias: alias of the object.

• $frame.of.reference: value of TAG (0020,0052).

• $ref.pseudo: pseudonym of the $frame.of.reference

• $modality: modality of the object (e.g. ct, mr, bin, rtplan..)

• $description: description of the object.

• $acq.date : date of the content (TAG (0008,0023) for ct and mr and rtimage, TAG (300A,0006) for rtplan, TAG (3006,0008) for rtstruct)

• $creation.date : creation date of the object.

If the object was generated from a DICOM file, the list also contains:

• $object.info: Information of the object. It includes:

  -	the SOP ID (value of TAG (0008,0016)),
  -	the transfer syntax UID (value of TAG (0002,0010)),
  -	the SOP implementation ID (value of TAG (0002,0012)),
  -	the SOP type (value of TAG (0008,0008)),
  -	the study ID (value of TAG (0020,0010)),
  -	the study UID (value of TAG (0020,000D)),
  -	the serie UID (value of TAG (0020,000E)),
  -	the scanning sequence (value of TAG (0018,0020)),
  -	the list of SOP labels (values of TAG (0008,0018)),
  -	the dicom source files,
  -	the encoding of the content of text tags (values of TAG (0008,0005))
  -	the description of the study (values of TAG (0008,1030)) in which all letters whose ASCCI code is not between 32 and 125 are deleted,
  -	the description of the serie (values of TAG (0008,103E)) in which all letters whose ASCCI code is not between 32 and 125 are deleted,
  -	the number of sub-objects.

if the object is linked to another DICOM object, the list also contains:

• $ref.object.alias: Alias of the reference object.

• $ref.object.info: Information of the reference object (not available for mr and ct). It includes:

  -	the SOP ID of the reference object,
  -	the list of SOP names of the reference object.

- the "dvh" class also includes :

• $nb.MC: set to histo$nb.MC.

• $breaks: vector breakpoints.

• $mids: vector of cell centers.

• $mids.unit: Character string, representing the unit of the abcissa of the DVH. For instance, "Gy".

• $vol: cumulative volume receiving at least the doses defined by $mids.

• $pcv: percentage of the total volume receiving at least the doses defined by $mids.

• if $nb.MC is different from 0, the arrays MC.vol, MC.pcv and MC.dxyz are added. See histo.DVH.

- the "fan" class also includes :

• $origin: the xyz-coordinates of the source point.

• $direction: the xyz-coordinates of the main direction of the fan.

• $orientation: the xyz-coordinates of the two unit vectors of the plane orthogonal to the $direction.

• $xyz: the xyz-coordinates of the unit vectors of the fan rays

• $local: depending on the generation of the fan rays, it can be the spherical coordinates, the deflection angles, the voxel coordinates...

- the "histo" class also includes :

• $nb.MC: number of Monte-Carlo simulations

• $breaks: vector breakpoints

• $mids: vector of cell centers.

• $mids.unit: Character string, representing the unit of the abcissa of the histogram. For instance, "Gy".

• counts: count of voxels whose value is included in the limits defined by $breaks.

• dV_dx: differential histogram, expressed in \(cm^3\) by voxel units, at each $mids.

• if $nb.MC is different from 0, the arrays MC.counts, MC.dV_dx and MC.dxyz are added. See histo.from.roi.

- the "histo2D" class also includes :

• $nb.pixels: number of elements in the density.map.

• $x.file.src: x label. See histo.2D.

• $y.file.src: y label. See histo.2D.

• x.breaks: vector of x-axis breakpoints.

• y.breaks: vector of y-axis breakpoints.

• x.mids: vector of x-axis cell centers.

• y.mids: vector of y-axis cell centers.

• density.map: array of densities.

• total.counts: number of counted voxels.

- the "mesh" class also includes :

• $nb.faces: set to the number of faces of the mesh.

• $mesh: list of 3 elements defining the mesh :$vb, $it and $normals. See mesh.from.bin.

- the "reg" class also includes :

• $nb.of.ref: number of transfer matrices.

• $ref.data: list including the lists of information on transfer matrices, namely: the source frame of reference ($src), the matrix type ($type, for example 'RIGID') and the transfer matrix ($matrix).

- the "rtplan" class also includes :

• $approval.status: value of TAG (300E,0002).

• $number: sub-object number.

• $plan.info: dataframe containing, if they exist,

  	- $label the label for the treatment plan,
  	- $plan.name the name for the treatment plan,
  	- $plan.description description of treatment plan,
  	- $tt.protocol the treatment protocol,
  	- $plan.intent the intent of this plan,
  	- $tt.site describing the anatomical treatment site,
  	- $geometry describing whether RT Plan is based on patient or treatment device geometry.

• $presc.dose: dataframe containing, if they exist,

  	- $ref.roi.nb value of TAG (3006,0084),
  	- $dose.ref.nb value of TAG (300A,0012),
  	- $dose.ref.id value of TAG (300A,0013),
  	- $struct.type value of TAG (300A,0014),
  	- $description value of TAG (300A,0016),
  	- $pt.coord value of TAG (300A,0018),
  	- $nominal.prior.dose value of TAG (300A,001A),
  	- $dose.type value of TAG (300A,0020),
  	- $constraint.weight value of TAG (300A,0021),
  	- $deliv.warn.dose value of TAG (300A,0022),
  	- $deliv.max.dose value of TAG (300A,0023),
  	- $targ.min.dose value of TAG (300A,0025),
  	- $targ.presc.dose value of TAG (300A,0026),
  	- $targ.max.dose value of TAG (300A,0027),
  	- $targ.underdose.vol.frac value of TAG (300A,0028),
  	- $org.risk.full.vol.dose value of TAG (300A,002A),
  	- $org.risk.lim.dose value of TAG (300A,002B),
  	- $org.risk.max.dose value of TAG (300A,002C),
  	- $org.risk.overdose.vol.frac value of TAG (300A,002D)

• $fraction.info: dataframe containing, if they exist,

  	- $fraction.id the id of the fraction group,
  	- $description its description,
  	- $planned.frac.nb the total number of treatments (Fractions) prescribed for current fraction group,
  	- $frac.pattern.digit.per.day.nb the number of digits in $frac.pattern used to represent one day,
  	- $repeat.frac.cycle.le the number of weeks needed to describe treatment pattern,
  	- $frac.pattern the value of TAG (300A,007B) describing treatment pattern every day,
  	- $nb.of.beam the number of beams in current fraction group,
  	- $beam.dose.meaning the value of TAG (300A,008B) indicating the meaning of Beam Dose,
  	- $nb.of.brachy.app the number of brachy application setups in current fraction group.

• $fraction.beam (in case of beam treatment): dataframe containing, if they exist,

  	- $fraction.id,
  	- $nb.of.frac.planned,
  	- $beam.dose the value of TAG (00A,0084),
  	- $beam.specif.pt the value of TAG (300A,0082),
  	- $beam.meterset the value of TAG (300A,0086),
  	- $beam.type the value of TAG (300A,0090,
  	- $alt.dose the value of TAG (300A,0091),
  	- $alt.type the value of TAG (300A,0092,
  	- $duration.lim the value of TAG (300A,00C5),
  	- $beam.nb the value of TAG (300C,0006) or (300A,00C0),

• $beam.info (in case of beam treatment): dataframe containing, if they exist,

  	- $beam.nb the value of TAG (300C,0006) or (300A,00C0),
  	- $beam.name the value of TAG (300A,00C2),
  	- $beam.description the value of TAG (300A,00C3),
  	- $beam.type the value of TAG (300A,00C4),
  	- $radiation.type the value of TAG (300A,00C6),
  	- $high.dose.technique.type the value of TAG (300A,00C7),
  	- $treatment.machine.name the value of TAG (300A,00B2),
  	- $device.serial.nb the value of TAG (0018,1000),
  	- $primary.dosimeter.unit the value of TAG (300A,00B3),
  	- $referenced.tolerance.table.nb the value of TAG (300C,00A0),
  	- $src.axis.dist the value of TAG (300A,00B4),
  	- $referenced.patient.setup.nb the value of TAG (300C,006A),
  	- $treatment.delivery.type the value of TAG (300A,00CE),
  	- $wedges.nb the value of TAG (300A,00D0),
  	- $compensators.nb the value of TAG (300A,00E0),
  	- $total.compensator.tray.factor the value of TAG (300A,00E2),
  	- $boli.nb the value of TAG (300A,00ED),
  	- $blocks.nb the value of TAG (300A,00F0),
  	- $total.block.tray.factor the value of TAG (300A,00F2),
  	- $final.cumul.meterset.weight the value of TAG (300A,010E),
  	- $ctl.pts.nb the value of TAG (300A,0110),
  	- $radiation.mass.nb the value of TAG (300A,0302),
  	- $radiation.atomic.nb the value of TAG (300A,0304),
  	- $radiation.charge.state the value of TAG (300A,0306),
  	- $scan.mode the value of TAG (300A,0308),
  	- $modulated.scan.mode.type the value of TAG (300A,0309),
  	- $virtual.src.axis.dist the value of TAG (300A,030A),
  	- $total.wedge.tray.water.equ.thickness the value of TAG (300A,00D7),
  	- $total.compensator.tray.water.equ.thickness the value of TAG (300A,02E3),
  	- $total.block.tray.water.equ.thickness the value of TAG (300A,00F3),
  	- $range.shifters.nb the value of TAG (300A,0312),
  	- $lateral.spreading.devices.nb the value of TAG (300A,0330),
  	- $range.modulators.nb the value of TAG (300A,0340),
  	- $fixation.light.azimuthal.angle the value of TAG (300A,0356),
  	- $fixation.light.polar.angle the value of TAG (300A,0358).

• $beam.ctl.pt (in case of beam treatment): list containing, for each beam,

  	- $info a data.frame of control points information from DICOM
  	- $beam.source the coordinates of the source in the patient frame of reference
  	- $beam.direction the coordinates of the beam direction in the patient frame of reference
  	- $beam.direction the coordinates of the beam orientation in the patient frame of reference
  	- $beam.isocenter the coordinates of the isocenter in the patient frame of reference
  	- $spot.map, if they exist,the coordinates of the spots in the patient frame of reference

  For the moment, only the rotations of the gantry and the patient support, and the position of the isocenter are taken into account in the calculation of these coordinates.

• $brachy.info (in case of brachy treatment): dataframe containing, if they exist,

  	- $fraction.id
  	- $nb.of.frac.planned,
  	- $brachy.dose the value of TAG (300A,00A4),
  	- $brachy.nb the value of TAG (300C,000C),
  	- $brachy.specif.pt the value of TAG (300A,00A).

- the "struct" class also includes :

• $nb.of.roi: number of regions of interest (RoI).

• $thickness: thickness between two consecutive planes of a contour.

• $ref.from.contour: reference frame change matrix, from the contour reference frame to the ref.pseudo reference frame

• $roi.info: dataframe. Information on RoI contours. It includes the followings columns:

  	-$number: value of TAG (3006,0084) for the concerned RoI.
  	-$name: value of TAG (3006,0026) for the concerned RoI.
  	-$description: value of TAG (3006,0028) for the concerned RoI.
  	-$generation.algorithm: value of TAG (3006,0036) for the concerned RoI.
  	-$color: value of TAG (3006,002A) for the concerned RoI.
  	-$dz: z step between planes for the concerned RoI.
  	-$roi.pseudo: pseudonym of the RoI $name. It can be changed by the user.
  	-$min.x: minimum value x in mm of the RoI. Absent when data = FALSE.
  	-$max.x: maximum value x in mm of the RoI. Absent when data = FALSE.
  	-$min.y: minimum value y in mm of the RoI. Absent when data = FALSE.
  	-$max.y: maximum value y in mm of the RoI. Absent when data = FALSE.
  	-$min.z: minimum value z in mm of the RoI. Absent when data = FALSE.
  	-$max.z: maximum value z in mm of the RoI. Absent when data = FALSE.
  	-$vol: volume in mm^3 of the RoI. Absent when data = FALSE.
  	-$Gx: position x in mm of the RoI center of gravity. Absent when data = FALSE.
  -	-$Gy: position y in mm of the RoI center of gravity. Absent when data = FALSE.
  -	-$Gz: position z in mm of the RoI center of gravity. Absent when data = FALSE.
  -	-$continue: boolean, indicating whether the contours are on adjacent planes.

• $roi.obs: dataframe. RT RoI observations (sequence TAG (3006,0080)). It includes the followings columns :

  	-$nb: value of TAG (3006,0082) for the concerned RoI.
  	-$roi.nb: value of TAG (3006,0084) for the concerned RoI.
  	-$label: value of TAG (3006,0085) for the concerned RoI.
  	-$code.value: value of TAG (0008,0100) in the Identification code sequence.
  	-$code.scheme: value of TAG (0008,0102) in the Identification code sequence.
  	-$code.scheme.v: value of TAG (0008,0103) in the Identification code sequence.
  	-$code.meaning: value of TAG (0008,0104) in the Identification code sequence.
  	-$type: value of TAG (3006,00A4) for the concerned RoI.
  	-$interpreter:value of TAG (3006,00A6) for the concerned RoI.

• $roi.data: exists only if the data is loaded. Contains the list of contour coordinates. The RoI of list number i is that of line i of roi.info. Each element of the list is a list giving the contour information for each plane, namely:

  	- $type: value of TAG (3006,0042).
  	- $pt: dataframe of the coordinates of the contour points.
  	If the contour is closed (i.e.$type = "CLOSED_PLANAR"),
  	then the first point is repeated at the end.
  	- $level: contour inclusion level. If this number is even,
  	the inside of the closed contour belongs to the RoI.
  	Otherwise, if odd, the inside of the closed contour is excluded from the RoI.

- the "undef" class : is used for DICOM objects that will not be processed further by espadon functions. It can also include what the user wants.

- the "volume" class also includes :

• $number: sub-object number.

• $unit: unit of the voxel

• $rtdose.info: for rtdose only, dataframe with the type, the dose summation type and referenced beam number.

• $n.ijk: vector defining the number of indices i, j, k. The product prod(...$n.ijk) represents the number of voxels in the 3D volume.

• $slice.thickness: thickness in mm of a plane.

• $min.pixel: minimum value of voxels in the volume.

• $max pixel: maximum value of voxels in the volume.

• $dxyz: x, y, z steps in mm.

• $orientation: value of TAG (0020,0037). Vector, comprising the vectors i and j defining the orientation of the patient with respect to the volume planes.

• $xyz0: in the patient frame of reference, position of the first voxel of each plane.

• $xyz.from.ijk: transfer matrix of the voxels i, j, k indices to the position x, y, z in mm in the patient's frame of reference.

• $k.idx: index of planes in the 3D volume.

• $missing.k.idx: Boolean, indicating if k is a continuous sequence of integers.

• $cube.idx: 3D volume vertices indices.

• $vol3D.data: exists only if the data is loaded. 3D array of the voxel values of the 3D volume.

See Also

toy.load.patient, load.patient.from.dicom, load.patient.from.Rdcm, load.T.MAT histo.DVH, histo.vol, histo.from.roi, histo.from.bin, histo.2D, mesh.from.bin, load.obj.from.Rdcm

Examples

cat ("espadon class names are:", paste (espadon.class(), collapse = ", "))

Export espadon objects in DICOM format

Description

The export function exports struct class objects and volume class objects with CT or RTDOSE modality in DICOM format.

Usage

export(
  obj,
  format = "dcm",
  ref.obj.list = NULL,
  use.original.UIs = FALSE,
  use.original.ref.UIs = TRUE,
  file.prefix = "",
  file.dirname = ".",
  file.name = NULL,
  tag.dictionary = dicom.tag.dictionary(),
  ...
)

Arguments

Details

The object you want to export may be known in a TPS thanks to these Unique Identifiers (UIs). If you want to create a DICOM object that is different and recognised by your TPS, it is important that the DICOM files you want to create have new UIs: in this case, set the use.original.UIs argument to FALSE. Otherwise, UIs in $object.info item of your object will be used.

Your object may have been created from another DICOM object (i.e. a reference object). You can, for example, see these links with the function display.obj.links.

If you want to keep this links, you must indicate which objects are references in the ref.obj.list argument, in the form of a list of espadon objects. If these reference objects have their own identifier and you wish to keep them, you must set the use.original.ref.UIs argument to TRUE.

Otherwise (use.original.ref.UIs=FALSE), the UIs of the reference objects will be regenerated. It is therefore important that the reference objects contain all their data such as vol3D.data or roi.data.

It may be useful to impose a study number (tag '(0020,000D)'), serial number (tag '(0020,000E)'), or your Image Type Attribute (tag '(0008,0008)'). In this case, you need to add the arguments#'

• '(0020,000D)' = your_study_UID,

• '(0020,000E)' = your_serial_UID,

• '(0008,0008)' = your_image_type_attribute.

For MRI, add the argument

• '(0018,0020)' = your_scanning_sequence. It will be set to 'SE' otherwise

• '(0018,0021)' = your_sequence_variant. It will be set to 'NONE' otherwise

You can change patient position by adding the argument :

• '(0018,5100)' = your_patient_position. It will be set to 'HFS' otherwise

Value

Returns nothing, but generate DICOM files if conditions are required, and indicates the name or number of files created

Examples

# First, save toy patient objects to a temporary file pat.dir for testing.
pat.dir <- file.path (tempdir(), "PM_Rdcm") 
dir.create (pat.dir, recursive = TRUE) 
patient <- toy.load.patient (modality = c("ct", "rtstruct"), roi.name = "", 
                             dxyz = c (6, 6, 6))
dicom.dir <- file.path (tempdir(), "PM_dcm") 
export(patient$rtstruct[[1]], ref.obj.list = list (patient$ct[[1]]),
       file.dirname = dicom.dir,file.name="RS")
export(patient$ct[[1]], file.dirname = dicom.dir,file.name="CT")
list.files(dicom.dir)

# check that the links have been preserved.
pat <- load.patient.from.dicom (dicom.dir, verbose = FALSE)
display.obj.links (pat)

# Cleaning  temporary directories
unlink (dicom.dir, recursive = TRUE)

Creation of pyramid fan object with constant angle step.

Description

The fan.beam function creates a "fan" class object containing, among others, the coordinates of the unit director vectors of the rays of rectangular pyramid fan. Rays are uniformly distributed by angle.

Usage

fan.beam(
  alpha,
  dalpha,
  orientation = c(0, 0, 1, 1, 0, 0),
  origin = c(0, 0, 0),
  ref.pseudo = "ref1",
  frame.of.reference = "",
  alias = "",
  description = "beam fan"
)

Arguments

Value

Returns a "fan" class object (see espadon.class for class definitions) containing, among others,

• $xyz : a matrix of 3 columns giving the xyz coordinates of the fan rays.

• $local : a matrix of 2 columns indicating the deflection angle (in rad) in the main directions defined by orientation.

See Also

fan.planar, fan.sphere, fan.to.voxel.

Examples

fan <- fan.beam (alpha = 30, dalpha = 1)
head (fan$xyz)
if (interactive()) {
  rgl::open3d ()
  rgl::points3d (fan$xyz)
}

Creation of pyramid fan object passing through pixels of a plane.

Description

The fan.planar function creates a "fan" class object containing, among others, the coordinates of the unit director vectors of the rays of rectangular pyramid fan. Rays are passing through all pixels of a plane, which represent the pyramid basis. It is for instance useful to compute rt-image.

Usage

fan.planar(
  vol,
  k = vol$k.idx[ceiling(length(vol$k.idx)/2)],
  origin = c(0, 0, 0),
  alias = "",
  description = "planar fan"
)

Arguments

Value

Returns a "fan" class object (see espadon.class for class definitions) containing, among others,

• $xyz : a matrix of 3 columns giving the xyz coordinates of the fan rays.

• $local.coords : a list of the ijkt DICOM coordinates of the crossed plane, and the transfer matrix to xyz.from.ijk to compute xyz coordinates in $ref.pseudo.

See Also

fan.sphere, fan.beam, fan.to.voxel

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for
# better result)
step <- 5
patient <- toy.load.patient (modality = c("ct"), dxyz = rep (step, 3))
fan <- fan.planar (patient$ct[[1]], origin = patient$ct[[1]]$xyz0[1,])
head (fan$xyz)
if (interactive()) {
  rgl::open3d ()
  points3d (fan$xyz)
}

Creation of spherical fan object.

Description

The fan.sphere function creates a "fan" class object containing, among others, the coordinates of the unit director vectors of the rays of a spherical fan.

Usage

fan.sphere(
  angle = 1,
  method = c("regular", "random"),
  origin = c(0, 0, 0),
  ref.pseudo = "ref1",
  frame.of.reference = "",
  alias = "",
  description = "spherical fan"
)

Arguments

Details

The "regular" and "random" method are explained by Deserno [1].

• If method = "regular", the returned vectors composing $xyz matrix are regularly equidistributed at the specified angle.

• If method = "random", the returned vectors composing $xyz matrix are randomly equidistributed at the specified angle.

Value

Returns a "fan" class object (see espadon.class for class definitions) containing, among others,

• $xyz : a matrix of 3 columns giving the xyz coordinates of the fan rays.

• $local : a matrix of 2 columns indicating the polar angle theta (rad) and the azimuthal angle phi (rad) of each ray are added.

References

[1] Deserno, Markus (Online; accessed 2022-08-24). “How to generate equidistributed points on the surface of a sphere.” https://www.cmu.edu/biolphys/deserno/pdf/sphere_equi.pdf.

See Also

fan.beam, fan.planar, fan.to.voxel

Examples

regular.fan <- fan.sphere (angle = 30)
head (regular.fan$xyz)
random.fan <- fan.sphere (angle = 30, method = "random")
head (random.fan$xyz)
if (interactive()){
  rgl::open3d ()
  rgl::points3d (regular.fan$xyz)
  rgl::open3d ()
  rgl::points3d (random.fan$xyz)
}

Indices of voxels crossed by a fan

Description

The fan.to.voxel function computes the indices of voxels crossed by a fan. It is useful for retrieving voxel values and voxel indices of a volume (dose or ct) along the fan rays.

Usage

fan.to.voxel(vol, fan, restrict = FALSE, vol.value = 1)

Arguments

Value

Returns a dataframe of 4 columns. Each line gives:

• column "ray.index": the index (i.e. the row number) of the ray concerned in fan$dxyz,

• column "vol.index": the index of the voxel crossed in vol$vol.3Ddata,

• column "l.in": the distance between fan source (i.e. fan$origin) and the first face of the voxel crossed by the ray,

• column "dl": the distance crossed by the ray in the voxel.

If the rays do not cross any voxel, the dataframe has no row.

See Also

fan.beam, fan.planar, fan.sphere.

Examples

vol <- vol.create (pt000 = c(1,10,10), dxyz = c (1 , 1, 1),
                   n.ijk = c(100, 100, 100)) 
fan.origin <- c (50,50,50)                         
fan <- fan.sphere (angle = 10, origin = fan.origin)
fan.voxel <- fan.to.voxel (vol = vol, fan = fan)
head (fan.voxel)

# Use of the 2nd column of fan.voxel to select voxels 
bin <- vol.copy (vol, modality = "binary")
bin$vol3D.data[] <- FALSE
bin$vol3D.data[fan.voxel[,2]] <- TRUE
bin$max.pixel <- TRUE
bin$min.pixel <- FALSE
display.kplane(bin, k=10)

Coordinates of the extreme points

Description

The get.extreme.pt function returns the x, y, z coordinates of the 2 extreme voxels of the rectangular parallelepiped, containing the objet obj of class volume, struct or mesh. These coordinates are given in the ref.pseudo frame of reference.

Usage

get.extreme.pt(obj, ref.pseudo = obj$ref.pseudo, T.MAT = NULL, ...)

Arguments

Value

Returns a dataframe of min and max columns, and x, y and z rows.

• If obj is a member of the class volume: the returned dataframe represents the coordinates of the 2 extreme points of the rectangle parallelepiped including all the voxels such as min <= obj$vol3D.data <= max, if the arguments min or max exist, or including all the voxels otherwise.

• If obj is a member of the class struct: the returned dataframe represents the coordinates of the 2 extreme points of the rectangular parallelepiped including all the selected RoI.

• if obj is a member of the class mesh: the returned dataframe represents the coordinates of the 2 extreme points of the rectangular parallelepiped including all the mesh.

Examples

# loading of toy-patient objects
patient <- toy.load.patient (modality = "ct", roi.name = "", dxyz = c (5, 5, 5))
CT <- patient$ct[[1]]

# xyz extreme coordinate
get.extreme.pt (CT)
get.extreme.pt (CT, min = 0)

Conversion of the indices of a point into ijk vector

Description

The get.ijk.from.index function converts the voxel indices of vol$vol3D.data (for example, obtained with the function which) into a vector or matrix of DICOM indices i, j, k.

Usage

get.ijk.from.index(idx, vol)

Arguments

Value

Returns an i, j, k column matrix of the DICOM indices of the points of vol$vol3D.data.

See Also

get.value.from.ijk, display.kplane

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for 
# better result)
step <- 4
patient <- toy.load.patient (modality = "rtdose", roi.name = "", 
                             dxyz = rep (step, 3), beam.nb = 3)
D <- patient$rtdose[[1]]

# voxels location where the dose is greater than 99.9% Dmax
Dmax <- max (D$vol3D.data, na.rm = TRUE) # D$max.pixel
get.ijk.from.index (which (D$vol3D.data >= 0.999 * Dmax), D)
# or
get.ijk.from.index (which (D$vol3D.data >= 0.999 * Dmax, arr.ind = TRUE), D)

ijk <- as.numeric (get.ijk.from.index (which.max (D$vol3D.data), D))
display.kplane (D, k = ijk[3]) 

Indices relating to the coordinates of the points

Description

The get.ijk.from.xyz function calculates the i, j, k DICOM indices of the points given in the patient's reference frame.

Usage

get.ijk.from.xyz(xyz = matrix(c(0, 0, 0), ncol = 3), vol, verbose = FALSE)

Arguments

Value

Returns a vector or a matrix of the i, j, k DICOM indices of the x, y, z coordinate points in the patient's frame of reference.

Note

The vector or matrix is made up of real numbers. It is up to the user to make the indices as integer.

The indices of the first voxel vol are 0, 0, 0. WARNING: As i,j,k are DICOM indices, they are not directly related to array indices. To get the value of the vol$vol3D.data, use the function get.value.from.ijk.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "ct", roi.name = "", 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]

get.ijk.from.xyz (xyz = CT$xyz0[1,], vol = CT, verbose = TRUE)
get.ijk.from.xyz (xyz = c (1,1,1), vol = CT, verbose = TRUE)

index <- get.ijk.from.xyz (xyz = c (1,1,1), vol = CT)
floor (index)

index <- get.ijk.from.xyz (xyz = matrix (c (0,0,0,1,1,1), ncol = 3, byrow = TRUE), 
                           vol = CT)
floor (index)

Image value along an axis

Description

The get.line function calculates the value of the points of a volume vol along an axis in any direction.

Usage

get.line(
  vol,
  origin = c(0, 0, 0),
  orientation = c(1, 0, 0),
  grid = seq(-100, 100, 1),
  interpolate = TRUE
)

Arguments

Value

Returns a dataframe, composed of the columns $x, $y, $z, representing the coordinates of the points where the values are taken in vol volume, the column $s representing the curvilinear abcissa, and the column $value representing values along $s.

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for 
# better result)
step <- 4
patient <- toy.load.patient (modality = "rtdose", roi.name = "", 
                             dxyz = rep (step, 3), beam.nb = 3)
D <- patient$rtdose[[1]]

# Dose at maximum dose
origin <- get.xyz.from.index (which.max (D$vol3D.data), D)
display.plane (bottom = D, view.coord =  origin[3], 
               bg = "#0000ff")

# Dose profile at x = origin[1] and z = origin[3].
l <- get.line (vol = D, origin = origin,
               orientation = c (0, 1, 0), interpolate = FALSE)
plot (l$y, l$value, type = "l")
grid ()

# Dose profile at y = origin[2] and z = origin[3].
l <- get.line (D, origin = origin,
               orientation = c (1, 0, 0), interpolate = FALSE)
plot (l$s, l$value, type = "l")
grid ()

List of connections between objects

Description

The get.obj.connection function describes with 4 matrices the different connections between the DICOM objects of the patient.

Usage

get.obj.connection(pat)

Arguments

Value

Returns a list of 4 named matrices:

• the $adjacency matrix matrix specifies the source objects that generated the destination objects: the column names correspond to the destinations, and the row names to the sources.

• the $same.object matrix specifies the elements belonging to the same DICOM object.

• the $components matrix specifies the objects belonging to the same study.

• the $same.ref matrix specifies the objects that share the same frame of reference, or with frames of reference linked in T.MAT (by a DICOM reg file for instance)

See Also

display.obj.links

Examples

# loading of toy-patient objects
patient <- toy.load.patient (dxyz = c (5, 5, 5), beam.nb = 1)
get.obj.connection (patient)
display.obj.links (patient)

Extracting a plane from a volume

Description

The get.plane function extracts a plane from a "volume" class object.

Usage

get.plane(
  vol,
  origin = c(0, 0, 0),
  plane.orientation = c(1, 0, 0, 0, 1, 0),
  alias = "plane.n",
  xgrid = NULL,
  ygrid = NULL,
  interpolate = TRUE,
  method = c("NN", "Av")
)

Arguments

Details

The interpolation method is chosen from:

• 'NN': the value of a voxel is calculated from its nearest adajcent neighbors.

• 'Av': the value of a voxel is the weighted average of the voxels contained in a box, whose sides are automatically calculated from the back.bol$dxyz steps.

Value

Returns a "volume" class object, containing only a single plane, at k = 0, in the same frame of reference as vol. This returned object has 2 new fields local.xgrid, and local.ygrid, representing the local grids of the abscissa (columns) and ordinate (rows) of the plane.

Returns NULL if plane doesn't exist.

Note

Determination of axes :

• the x-axis has plane.orientation[1:3] as unit vector.

• the y-axis has plane.orientation[4:6] as unit vector.

• If xgrid is not NULL, origin + x.grid * plane.orientation[1:3] are the coordinates of the points on the x axis.

• If ygrid is not NULL, origin + y.grid * plane.orientation[4:6] are the coordinates of the points on the y axis.

• If xgrid or ygrid are NULL, they are determined to represent as closely as possible the initial volume in the required cut.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = "mr", dxyz = rep (step, 3))
MR <- patient$mr[[1]] 
    
# mid-volume point 
mid.point <- apply (get.extreme.pt (MR),1,mean)

plane <- get.plane (MR, origin = mid.point, interpolate = TRUE)
display.kplane (plane, interpolate = FALSE)

plane <- get.plane (MR, origin = mid.point, xgrid = seq (-50, 50, 1), 
                    ygrid = seq (-50, 50, 1), interpolate = TRUE)
display.kplane (plane, interpolate = FALSE)

# 3 points on the inclined plane
pts <- t ((MR$xyz.from.ijk %*% MR$cube.idx) [1:3 , c (1, 2, 7)])
orientation <- orientation.create (A = pts[1,], B = pts[2,], C = pts[3,])
origin <- apply (pts, 2, mean)
plane <- get.plane (MR, origin = origin, 
                    plane.orientation = orientation, interpolate = TRUE)
display.kplane (plane, interpolate = FALSE)

orientation <- orientation.create (A = c (0, 0, 0) , B = c (1, 1, 0), 
                                   C = c (-1, 1, 0))
plane <- get.plane (MR, origin = origin, 
                    plane.orientation = orientation, interpolate = TRUE) 
display.kplane (plane, interpolate = FALSE)

Transfer matrix between two frames of reference

Description

The function get.rigid.M provides, from the T.MAT list created by the functions load.patient.from.Rdcm, load.patient.from.dicom or load.T.MAT, the 4x4 transfer matrix from the FoR (frame o reference) pseudonym src.ref to the FoR pseudonym dest.ref.

Usage

get.rigid.M(T.MAT, src.ref, dest.ref)

Arguments

Value

Returns the 4x4 transfer matrix dest.ref from src.ref.

Examples

# loading of toy-patient objects
patient <- toy.load.patient (modality = c ("ct", "mr"), roi.name = "",
                             dxyz = c(5, 5, 5))
get.rigid.M (patient$T.MAT, "ref1", "ref2")

List of inter-connections between RoI

Description

The get.roi.connection function describes the interconnections between Regions of Interest (RoI), from an imaging volume of "cluster" modality, created by struct.clustering.

Usage

get.roi.connection(vol)

Arguments

Value

Returns the list of regions of interest (RoI), where each item in the list gives the inter-connections with other RoI.

See Also

struct.clustering

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 5
patient <- toy.load.patient (modality = c ("mr", "rtstruct"),  
                             dxyz = rep (step, 3))
MR <- patient$mr[[1]]
S <- patient$rtstruct[[1]]
cluster.vol <- struct.clustering (MR, S, T.MAT = patient$T.MAT, verbose = FALSE)

get.roi.connection (cluster.vol)

Value of the volume at a selection of DICOM indices

Description

The get.value.from.ijk function calculates the value of a "volume" class object at DICOM indices i, j, k, whether they are integers or not.

Usage

get.value.from.ijk(ijk, vol, interpolate = TRUE, s.ijk = c(1, 1, 1))

Arguments

Value

Returns a vector of the values of the volume at the requested DICOM indices.

See Also

get.ijk.from.index.

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for 
# better result)
step <- 4
patient <- toy.load.patient (modality = "rtdose", roi.name = "", 
                             dxyz = rep (step, 3), beam.nb = 3)
D <- patient$rtdose[[1]]
# isodose
Dmax <- max (D$vol3D.data, na.rm = TRUE)
Dmax
idx <- which (D$vol3D.data >= (Dmax -1) & D$vol3D.data <= (Dmax - 0.2))
ijk <- get.ijk.from.index (idx, D)
get.value.from.ijk (ijk, vol = D, interpolate = FALSE)

Voxel value at a given depth of a mesh

Description

The get.value.from.mesh function is used to retrieve the values of an object of class "volume" at the desired depth of a surface described by a mesh. If the mesh corresponds to the "patient" contour, the zero depth is the skin, positive depths enter the patient and negative depths exit to the outside.

Usage

get.value.from.mesh(
  mesh,
  vol,
  method = c("point", "disk", "sphere"),
  depth = 0,
  radius = 5,
  spacing = 1,
  T.MAT = NULL,
  FUN = median,
  ...
)

Arguments

Details

The get.value.from.mesh function works at each vertex of the mesh. It moves along the normal at that point to the desired depth.

• When the method is "point", it simply retrieves the value of the volume vol specified at that point.

• When the method is "disk", the values are retrieved on the disk orthogonal to the normal,with radius radius.

• When the method is "sphere", the values are retrieved inside the sphere of radius radius.

For "disk" or "sphere", the measurement points are spaced by spacing. For radius=5 and spacing=1, "disk" and "sphere" perform 78 and 523 measurements respectively. In both cases, the measured values must be reduced to a single result using the FUN function. By default, espadon uses the median, but it can be provided with more complex functions to filter the data efficiently (see example below).

Value

Returns a vector of values measured at the requested depth, with the desired method, filtered by FUN, at each vertex of the mesh.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 5
patient <- toy.load.patient (modality = c("ct", "rtstruct"), roi.name = "",
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

# creation of the patient mesh
bin <- bin.from.roi (CT, struct = S, roi.name = "patient", 
                     verbose = FALSE)
mesh.patient <- mesh.from.bin (bin, alias = "patient", verbose = FALSE)

# density value on the skin contour, extracted from CT
density <- get.value.from.mesh (mesh.patient, CT ,depth = 0) 

if (interactive()){
  # Display of mesh, with RVV pal
  density[density < -1000] <- -1000
  density[density > 1000] <- 1000
  col <- pal.RVV(255)[cut (density, seq (-1000, 1000, length.out = 256), 
                           include.lowest=TRUE)]
  rgl::open3d ()
  display.3D.mesh (mesh.patient, col = col)
}

Voxel values on a selection of points

Description

The get.value.from.xyz function calculates the voxel values at the x, y, z coordinate points in the chosen frame of reference.

Usage

get.value.from.xyz(
  xyz,
  vol,
  xyz.ref.pseudo = NULL,
  T.MAT = NULL,
  interpolate = TRUE,
  verbose = FALSE
)

Arguments

Value

Returns a vector of the voxel values at the requested coordinates.

See Also

get.xyz.from.index

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for 
# better result)
step <- 4
patient <- toy.load.patient (modality = "rtdose", roi.name = "", 
                             dxyz = rep (step, 3), beam.nb = 3)
D <- patient$rtdose[[1]]
get.value.from.xyz (xyz = matrix (c (0, 0, 0, 10, 10, 10), 
                    ncol = 3, byrow = TRUE), vol = D)

# isodose
Dmax <- max (D$vol3D.data, na.rm = TRUE)
idx <- which (D$vol3D.data >= (Dmax -1) & D$vol3D.data <= (Dmax - 0.3))
pt <- get.xyz.from.index (idx, D)
get.value.from.xyz (pt, vol = D, interpolate = FALSE, verbose = TRUE)

Volume selected by binary volume

Description

The get.volume.from.bin function calculates the volume in \(cm^3\) of the selection specified by a "volume" class object of "binary" modality.

Usage

get.volume.from.bin(bin)

Arguments

Value

Returns the volume of the binary selection, in \(cm^3\).

See Also

get.volume.from.roi

Examples

# loading of toy-patient objects
step <- 4
patient <- toy.load.patient (modality = c ("ct", "rtstruct"), roi.name = "brain",
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]] 

# creation of  weight and binary objects
bin.brain.w <- bin.from.roi (vol = CT, struct = S, roi.sname = "bra", 
                           modality = "weight", verbose = FALSE)
bin.brain.b <- bin.from.roi (vol = CT, struct = S, roi.sname = "bra", 
                           verbose = FALSE)
# Volume calculation
get.volume.from.roi (struct = S, roi.sname = "bra")
get.volume.from.bin (bin.brain.w)
get.volume.from.bin (bin.brain.b)

Volume of a region of interest (RoI)

Description

The get.volume.from.roi function extracts the volume in\(cm^3\) of one or more RoI, from the $roi.info of the "struct" class object.

Usage

get.volume.from.roi(struct, roi.name = NULL, roi.sname = NULL, roi.idx = NULL)

Arguments

Details

If roi.name, roi.sname, and roi.idx are all set to NULL, all RoI are selected.

Value

Returns a vector of the volumes in \(cm^3\) of the requested RoI.

See Also

get.volume.from.bin, select.names

Examples

# loading of toy-patient objects
step <- 4
patient <- toy.load.patient (modality = c ("rtstruct"), 
                             dxyz = rep (step, 3))
S <- patient$rtstruct[[1]] 

# Volume extraction
vol <- get.volume.from.roi (S, roi.sname = "bra", roi.idx = c (1, 3))
names (vol)
vol

Conversion of the indices of a point, into xyz coordinate vector in the patient's frame of reference

Description

The get.xyz.from.index function converts the indices of a voxel of vol$vol3D.data (for example, obtained with the function which) into a vector or matrix of x, y, z coordinates in the patient's frame of reference.

Usage

get.xyz.from.index(idx, vol)

Arguments

Value

Returns a column-matrix of coordinates in the patient's reference frame, corresponding to the indices idx.

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for better
# result)
step <- 4
patient <- toy.load.patient (modality = "rtdose", roi.name = "", 
                             dxyz = rep (step, 3), beam.nb = 3)
D <- patient$rtdose[[1]]

# voxels location where the dose is greater than 99.9% Dmax
Dmax <- max (D$vol3D.data, na.rm = TRUE) # D$max.pixel
get.xyz.from.index (which (D$vol3D.data >= 0.99 * Dmax), D)
# or
get.xyz.from.index (which (D$vol3D.data >= 0.99 * Dmax, arr.ind = TRUE), D)

Comparison of the grids of two volume objects

Description

The grid.equal function checks that two volumes share the same grid, i.e. the same frame of reference, the same origin point, and the same dx, dy, dz steps.

Usage

grid.equal(vol1, vol2)

Arguments

Value

Returns TRUE if the 2 volumes share the same grid.

Examples

# loading of toy-patient objects
patient <- toy.load.patient (modality = c ("ct","mr","rtdose"), roi.name = "", 
                             dxyz = c (4, 4, 4), beam.nb = 1)

# Comparison of the grids
grid.equal (patient$rtdose[[1]], patient$ct[[1]])
grid.equal (patient$mr[[1]], patient$ct[[1]])

2D histograms of 2 volumes

Description

The histo.2D function creates a "histo2D" class object, containing the two-dimensional array of histograms of two "volume" class objects that have the same grid.

Usage

histo.2D(
  x.vol,
  y.vol,
  x.breaks = NULL,
  y.breaks = NULL,
  include.outer = TRUE,
  alias = "",
  description = ""
)

Arguments

Details

The arguments x.breaks and y.breaks represent the scales of the x and y axes of 2D-histogram graph. If they are NULL, the histo.2D function defaults to 256 cells between the values vol$min.pixel and vol$max.pixel.

Value

Returns a "histo2D" class object. This is a list including:

• $patient: set to x.vol$patient.

• $patient.name: set to x.vol$patient.name.

• $patient.bd: set to x.vol$patient.bd.

• $patient.sex: set to x.vol$patient.sex.

• $file.basename: set to "".

• $file.dirname: set to "".

• $object.name: set to "".

• $object.alias: alias of the histo2D object.

• $frame.of.reference: set to x.vol$frame.of.reference.

• $ref.pseudo : set to x.vol$ref.pseudo.

• $modality : set to "histo2D".

• $description: description of the histo2D object.

• $creation.date: set to Sys.Date.

• $nb.pixels: number of elements in the density.map.

• $x.file.src: set to x.vol$object.alias

• $y.file.src: set to y.vol$object.alias

• x.breaks: vector of x-axis breakpoints.

• y.breaks: vector of y-axis breakpoints.

• x.mids: vector of x-axis cell centers.

• y.mids: vector of y-axis cell centers.

• density.map: array of densities.

• total.counts: number of counted voxels.

See Also

display.2D.histo.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "mr", "rtstruct"), 
                             roi.name =  "brain", 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
MR <- patient$mr[[1]]
S <- patient$rtstruct[[1]]
T.MAT <- patient$T.MAT

# restriction of the volume around the RoI
CT.on.roi <- nesting.roi (CT, S, roi.name = "brain", vol.restrict = TRUE,
                          xyz.margin = c (1, 1, 1), alias = CT$description)
MR.on.CT <- vol.regrid (vol = MR, back.vol = CT.on.roi, interpolate = TRUE,
                        T.MAT = T.MAT, alias = CT$description,
                        description = NULL)
# selection of voxels included in the RoI.
roi.bin <- bin.from.roi (vol = CT.on.roi, struct = S, roi.sname = "brain", 
                         verbose = FALSE)
MR.select <- vol.from.bin (MR.on.CT, roi.bin, alias = MR$description)
CT.select <- vol.from.bin (CT.on.roi, roi.bin, alias = CT$description)
# 2D histogram
H2D <- histo.2D (MR.select, CT.select, x.breaks = seq (50, 400, 10),
			  y.breaks = seq (50, 400, 10), alias = "H2D MR CT")
str (H2D)

Cumulative Dose Volume Histogram

Description

The histo.DVH function calculates, for each dose, the volume receiving at least this dose.

Usage

histo.DVH(histo, alias = "", description = histo$description)

Arguments

Value

Returns a "dvh" class object. This is a list including:

• $patient: set to histo$patient.

• $patient.name: set to histo$patient.name.

• $patient.bd: set to histo$patient.bd.

• $patient.sex: set to histo$patient.sex.

• $file.basename: set to "".

• $file.dirname: set to "".

• $object.name: set to "".

• $object.alias: alias of the dvh object..

• $frame.of.reference: set to histo$frame.of.reference.

• $ref.pseudo : set to histo$ref.pseudo.

• $modality : set to "dvh".

• $description: description of the dvh object. By default, set to histo$description.

• $creation.date: set to Sys.Date.

• $nb.MC: set to histo$nb.MC.

• $breaks: vector breakpoints.

• $mids: vector of cell centers.

• $mids.unit: Character string, representing the unit of the abcissa of the DVH. For instance, "Gy", when vol is a rtdose.

• $vol: cumulative volume receiving at least the doses defined by $mids.

• $pcv: percentage of the total volume receiving at least the doses defined by $mids.

• $MC.vol: cumulative volume associated with histo$MC.dV_dx, if it exists.

• $MC.pcv: percentage of the total volume associated with histo$MC.dV_dx, if it exists.

• $MC.dxyz: set to histo$MC.dxyz, if it exists.

See Also

histo.from.roi, histo.from.bin, histo.vol, display.DVH, display.DVH.pc

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for 
# better result)
step <- 5
patient <- toy.load.patient (modality = c("rtdose", "rtstruct"), 
                             roi.name = "gizzard", dxyz = rep (step, 3), 
                             beam.nb = 3)

# Calculation of the histogram
H <- histo.from.roi (patient$rtdose[[1]], patient$rtstruct[[1]], 
                     roi.name = "gizzard", 
                     breaks = seq (0, 60, by = 1))

# DVH
DVH <- histo.DVH (H)
str (DVH)

Histogram according to a binary

Description

The histo.from.bin function computes the voxels histogram of the selection defined by the binary object sel.bin of a "volume" class object.

Usage

histo.from.bin(vol, sel.bin, breaks = NULL, alias = "", description = NULL)

Arguments

Value

Returns a "histo" class object. See histo.vol.

See Also

histo.from.roi, histo.vol, display.histo, display.dV_dx

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 5
patient <- toy.load.patient (modality = c("ct","rtstruct"), roi.name = "", 
                             dxyz = rep (step, 3))
bin.patient <- bin.from.roi (patient$ct[[1]], struct = patient$rtstruct[[1]],
                             roi.name = "patient", verbose = FALSE)
# ct histogram in patient  volume
H <- histo.from.bin (patient$ct[[1]], sel.bin = bin.patient, breaks = NULL, 
                     alias = "patient_hist")
str(H)

## Not run:     
# Skin dose histogram 
patient <- toy.load.patient (modality = c("rtdose", "rtstruct"), roi.name = "", 
                             dxyz = c (2, 2, 2), beam.nb = 3)
D <- patient$rtdose[[1]]
S <- patient$rtstruct[[1]]

# Creation of the skin contour of 3 mm
bin.patient <- bin.from.roi (D, struct = S, roi.name = "patient", 
                             alias = "patient", verbose = FALSE)
inverse.patient <- bin.inversion (bin.patient, alias = "inv (patient)")
expansion <- bin.dilation (inverse.patient, radius = 3, 
                           alias = "inv (patient) + 3")
contour.3mm <- bin.intersection (bin.patient, expansion, 
                                 alias = "contour 3 mm")

# Dose histogram in this volume
H <- histo.from.bin (D, sel.bin = contour.3mm, breaks = NULL, 
                     alias = "Skin dose")
str(H)

## End(Not run)

Histogram according to a RoI

Description

The histo.from.roi function calculates the histogram of the volume voxels belonging to a RoI.

Usage

histo.from.roi(
  vol,
  struct,
  roi.name = NULL,
  roi.sname = NULL,
  roi.idx = NULL,
  T.MAT = NULL,
  breaks = NULL,
  MC = NULL,
  sd = c(1, 1, 1),
  offset = c(0, 0, 0),
  over.sampling.factor = 1,
  alias = "",
  description = NULL
)

Arguments

Details

roi.name, roi.sname, and roi.idx must select only one RoI.

Value

Returns "histo" class object. This is a list including:

• $alias: alias of the histo object.

• $description: description of the histo object.

• $breaks: vector breakpoints

• $mids: vector of cell centers.

• $mids.unit: Character string, representing the unit of the abcissa of the histogram. For instance, "Gy", when vol is a rtdose.

• counts: count of voxels whose value is included in the limits defined by $breaks.

• dV_dx: differential histogram, expressed in cm3 by voxel units, at each $mids.

• MC.counts: array of MC rows. Each row i represents the histogram of the voxels contained in the RoI, whose points have been shifted by $MC.dxyz[i,].

• MC.dV_dx: array of MC rows. Each row i represents the differential histogram of the voxels contained in the RoI, the points of which have been shifted by $MC.dxyz[i,].

• MC.dxyz: array of MC rows, representing the offset applied to the RoI.

Note

Using Monte-Carlo can be time consuming for large RoI.

If you only want the result just for a translation, use the arguments MC = 1, sd = 0 and offset = desired translation vector.

See Also

histo.vol, histo.from.bin, display.histo, display.dV_dx

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for better
# result)
step <- 5
patient <- toy.load.patient (modality = c("rtdose", "rtstruct"), 
                             roi.name = "gizzard", dxyz = rep (step, 3), 
                             beam.nb = 3)

# Calculation of the histogram
H <- histo.from.roi (patient$rtdose[[1]], patient$rtstruct[[1]], 
                     roi.name = "gizzard", 
                     breaks = seq (0, 60, by = 1))
str (H)

Histogram of a volume

Description

The histo.vol function calculates the voxel values histogram of "volume" class object.

Usage

histo.vol(vol, breaks = NULL, alias = "", description = NULL, weight = NULL)

Arguments

Value

Returns a "histo" class object. This is a list including:

• $patient: set to vol$patient.

• $patient.name: set to vol$patient.name.

• $patient.bd: set to vol$patient.bd.

• $patient.sex: set to vol$patient.sex.

• $file.basename: set to "".

• $file.dirname: set to "".

• $object.name: set to "".

• $object.alias: alias of the histo object.

• $frame.of.reference: set to vol$frame.of.reference.

• $ref.pseudo : set to vol$ref.pseudo.

• $modality : set to "histo".

• $description: description of the histo object.

• $creation.date: set to Sys.Date.

• $nb.MC: set to 0.

• $breaks: vector breakpoints

• $mids: vector of cell centers.

• $mids.unit: Character string, representing the unit of the abcissa of the histogram. For instance, "Gy", when vol is a rtdose.

• counts: count of voxels whose value is included in the limits defined by $breaks.

• dV_dx: differential histogram, expressed in \(cm^3\) by voxel units, at each $mids.

See Also

histo.from.roi, histo.from.bin, display.histo, display.dV_dx

Examples

# loading of toy-patient objects
step <- 3
patient <- toy.load.patient (modality = "ct", dxyz = rep (step, 3))
CT <- patient$ct[[1]]

# histogram and display
H <- histo.vol (CT, breaks = seq (3, ceiling (CT$max.pixel), 1), 
                alias = "CT_hist")
str (H)

Loading a *.Rdcm file

Description

the load.Rdcm.raw.data function loads the content of a *.Rdcm file.

Usage

load.Rdcm.raw.data(
  Rdcm.filename,
  address = TRUE,
  data = TRUE,
  upgrade.to.latest.version = FALSE
)

Arguments

Value

Returns a list containing the information, converted by espadon, of a DICOM object..

See Also

dicom.to.Rdcm.converter, load.obj.from.Rdcm.

Examples

# For testing, save first toy.dicom.raw () raw data to a temporary file, and
# convert it in Rdcm fie
pat.src.dir <- file.path (tempdir(), "PM_dcm") 
dir.create (pat.src.dir, recursive = TRUE) 
dcm.filename <- tempfile (pattern = "PM_rtplan", tmpdir = pat.src.dir,
                          fileext = ".dcm")
zz <- file (dcm.filename, "wb")
writeBin (toy.dicom.raw (), zz, size = 1)
close (zz)
pat.dir <- file.path (tempdir(), "PM_Rdcm")
dicom.to.Rdcm.converter (pat.src.dir, pat.dir, update = TRUE)
lf <- list.files (pat.dir, pattern = "[.]Rdcm$", full.names = TRUE)
lf

# Inspect Rdcm raw data
L <- load.Rdcm.raw.data (lf[1])
str (L, max.level =3)

# Cleaning  temporary directory
unlink (pat.src.dir, recursive = TRUE)  

Loading of information about transfer matrices between frames of reference of patient Rdcm objects.

Description

The load.T.MAT function lists all the frames of reference of the objects included in the patient directory. It concatenates all the information of the reg matrices of a directory, creating, among other things, a list of 4x4 transfer matrices between frames of reference.

Usage

load.T.MAT(dirname, upgrade.to.latest.version = FALSE)

Arguments

Value

Returns a "t.mat" class object. It is a list that includes :

• $ref.info: dataframe giving the correspondence between the frame of reference (column $ref) of the DICOM object (TAG (0020,0052) ) and its pseudonym (column $ref_pseudo).

• $reg.info:list of dataframes : the first one gives the PID, birthday, and sex of the patient, the second one gives the name of the source file of transfer matrices.

• $matrix.description: dataframe giving the transfer matrix names (column $t), its source frame of reference (column $src), the destination frame of reference (column $dest), and its type ($type). Note: only the RIGID type is supported.

• $matrix.list: list of 4X4 transfer matrices. This list contains at least as many Identity matrices as there are ref.pseudo.

Examples

# First, save toy patient objects to a temporary file pat.dir for testing.
pat.dir <- file.path (tempdir(), "PM_Rdcm") 
dir.create (pat.dir, recursive = TRUE) 
patient <- toy.load.patient (modality = c("ct", "mr"), roi.name = "", 
                             dxyz = c (4, 4, 4))
save.to.Rdcm (patient$ct[[1]], dirname = pat.dir)
save.to.Rdcm (patient$mr[[1]], dirname = pat.dir)
save.T.MAT (patient$T.MAT, dirname = pat.dir)
# Rdcm files in pat.dir
list.files(pat.dir)

T.MAT <- load.T.MAT (pat.dir)
T.MAT

# Cleaning  temporary directory
unlink (pat.dir, recursive = TRUE)

Load data of an espadon class object

Description

The load.obj.data function loads all the data of an espadon object of class 'struct' or 'volume'.

Usage

load.obj.data(obj, tag.dictionary = dicom.tag.dictionary())

Arguments

Value

Returns the espadon object with data $vol3D.data or $roi.data

See Also

load.obj.from.dicom and load.obj.from.Rdcm

Examples

# First, save toy patient objects to a temporary file pat.dir for testing.
pat.dir <- file.path (tempdir(), "PM_Rdcm") 
dir.create (pat.dir, recursive = TRUE) 
patient <- toy.load.patient (modality = c("ct", "mr"), roi.name = "", 
                             dxyz = c (4, 4, 4))
save.to.Rdcm (patient$ct[[1]], dirname = pat.dir)
rm( patient)


patient <- load.patient.from.Rdcm (pat.dir, data = FALSE)
CT <- load.obj.data (patient$ct[[1]])
str (CT, max.level = 2)
# Cleaning  temporary directory
unlink (pat.dir, recursive = TRUE)

Loading an espadon object from *.Rdcm file

Description

The load.obj.from.Rdcm function loads a DICOM object into memory, creating a list containing the information necessary for its subsequent use with the espadon package.

Usage

load.obj.from.Rdcm(
  Rdcm.filename,
  data = TRUE,
  nb = NULL,
  upgrade.to.latest.version = FALSE
)

Arguments

Value

Returns an espadon object of class "dvh","histo","histo2D","mesh", "rtplan","struct", "undef" or "volume" depending on the object modality. See espadon.class for class definitions.

See Also

load.obj.data and load.obj.from.dicom

Examples

# First, save toy patient objects to a temporary file pat.dir for testing.
pat.dir <- file.path (tempdir(), "PM_Rdcm") 
dir.create (pat.dir, recursive = TRUE) 
patient <- toy.load.patient (modality = c("ct", "mr"), roi.name = "", 
                             dxyz = c (4, 4, 4))
save.to.Rdcm (patient$ct[[1]], dirname = pat.dir)
save.to.Rdcm (patient$mr[[1]], dirname = pat.dir)
save.T.MAT (patient$T.MAT, dirname = pat.dir)
# Rdcm files in pat.dir
list.files(pat.dir)

CT <- load.obj.from.Rdcm (file.path (pat.dir, 
                                     list.files(pat.dir, pattern="ct1[.]Rdcm")[1]),
                          data=TRUE)
MR <- load.obj.from.Rdcm (file.path (pat.dir, 
                                     list.files(pat.dir, pattern="mr1[.]Rdcm")[1]),
                          data=TRUE)
Reg <-load.obj.from.Rdcm (file.path (pat.dir,"ref1_from_ref2.Rdcm"), data=TRUE)     
str(Reg)

# Cleaning  temporary directory
unlink (pat.dir, recursive = TRUE)  

Loading an espadon object from DICOM files or folder

Description

Loading an espadon object from DICOM files or folder.

Usage

load.obj.from.dicom(
  dcm.files,
  data = TRUE,
  ref.pseudo = "ref1",
  tag.dictionary = dicom.tag.dictionary(),
  verbose = TRUE
)

Arguments

Value

Returns an espadon object of class "dvh","histo","histo2D","mesh", "rtplan","struct", "undef" or "volume" depending on the object modality. See espadon.class for class definitions.

See Also

load.obj.data and load.obj.from.Rdcm

Examples

# First, save toy.dicom.raw () raw data to a temporary file pat.dir for testing.
pat.dir <- file.path (tempdir(), "PM_dcm") 
dir.create (pat.dir, recursive = TRUE) 
dcm.filename <- tempfile (pattern = "toyrtplan", tmpdir = pat.dir,
                          fileext = ".dcm")
zz <- file (dcm.filename, "wb")
writeBin (toy.dicom.raw (), zz, size = 1)
close (zz)

# loading of rt-plan object
RTplan <- load.obj.from.dicom (dcm.filename)
str (RTplan)
# Cleaning  temporary directory
unlink (pat.dir, recursive = TRUE)

Loading patient data from *.Rdcm files

Description

The load.patient.from.Rdcm function is used to load or pre-load in memory all patient objects converted in *.Rdcm files.

Usage

load.patient.from.Rdcm(
  dirname,
  data = FALSE,
  dvh = FALSE,
  upgrade.to.latest.version = FALSE,
  ignore.duplicates = FALSE
)

Arguments

Value

Returns an espadon object of class "patient", describing the information contained in dirname. See espadon.class for a description of the "patient" class.

See Also

dicom.to.Rdcm.converter, load.patient.from.dicom, load.obj.data, load.obj.from.dicom, load.obj.from.Rdcm and load.T.MAT.

Examples

# First, save toy patient objects to a temporary file pat.dir for testing.
pat.dir <- file.path (tempdir(), "PM_Rdcm") 
dir.create (pat.dir, recursive = TRUE) 
patient <- toy.load.patient (modality = c("ct", "mr"), roi.name = "", 
                             dxyz = c (4, 4, 4))
save.to.Rdcm (patient$ct[[1]], dirname = pat.dir)
save.to.Rdcm (patient$mr[[1]], dirname = pat.dir)
save.T.MAT (patient$T.MAT, dirname = pat.dir)
# Rdcm files in pat.dir
list.files(pat.dir)

# loading patient from Rdcm files with data: 
new.patient <- load.patient.from.Rdcm (pat.dir, data = TRUE)
str (new.patient, max.level = 2 )

# Cleaning  temporary directory
unlink (pat.dir, recursive = TRUE)

Loading patient data from DICOM files

Description

The load.patient.from.dicom function is used to load or pre-load in memory all patient objects from DICOM files.

Usage

load.patient.from.dicom(
  dcm.files,
  data = FALSE,
  dvh = FALSE,
  ignore.duplicates = FALSE,
  tag.dictionary = dicom.tag.dictionary(),
  verbose = TRUE
)

Arguments

Value

Returns an espadon object of class "patient", describing the information from dcm.files. See espadon.class for a description of the "patient" class.

See Also

dicom.to.Rdcm.converter, load.patient.from.Rdcm, load.obj.data, load.obj.from.dicom, load.obj.from.Rdcm and load.T.MAT.

Examples

# First, save toy.dicom.raw () raw data to a temporary file pat.dir for testing.
pat.dir <- file.path (tempdir(), "toy_dcm") 
dir.create (pat.dir, recursive = TRUE) 
dcm.filename <- tempfile (pattern = "toyrtplan", tmpdir = pat.dir,
                          fileext = ".dcm")
zz <- file (dcm.filename, "wb")
writeBin (toy.dicom.raw (), zz, size = 1)
close (zz)

# loading patient. Here the toy patient ha only a unique rt-plan object
patient <- load.patient.from.dicom (pat.dir, data = FALSE)
str (patient, max = 2)
# description of object
patient$description
# transfer matrices :
patient$T.MAT
# rt-plan object
str (patient$rtplan[[1]])
# Cleaning  temporary directory
unlink (pat.dir, recursive = TRUE)

Creation of a mesh according to a binary volume

Description

The mesh.from.bin function creates a mesh class object from a volume object of "binary" modality.

Usage

mesh.from.bin(
  bin,
  alias = "",
  tol = min(abs(bin$dxyz))/2,
  smooth.iteration = 10,
  smooth.type = c("taubin", "laplace", "HClaplace", "fujiLaplace", "angWeight",
    "surfPreserveLaplace"),
  smooth.lambda = 0.5,
  smooth.mu = -0.53,
  smooth.delta = 0.1,
  verbose = FALSE
)

Arguments

Value

Returns a "mesh" class object. This is a list including the following 6 elements:

• $patient: set to bin$patient.

• $patient.bd: set to bin$patient.bd.

• $patient.name: set to bin$patient.name.

• $patient.sex: set to bin$patient.sex.

• $file.basename: set to "".

• $file.dirname: set to "".

• $object.name: set to "".

• $object.alias: set to the alias argument of the function.

• $frame.of.reference: set to bin$frame.of.reference.

• $ref.pseudo : set to bin$ref.pseudo.

• $modality : set to "mesh".

• $description: By default, set to paste (bin$object.alias, "mesh").

• $creation.date: set to Sys.Date.

• $nb.faces: set to the number of faces of the mesh.

• $mesh: list of 3 elements defining the mesh:

  	- $vb: array made up of the generalized coordinates (x, y, z, 1) of the vertices of the triangles.
  	There are as many columns as there are vertices.
  	- $it: array of the 3 indices of the vertices forming a triangle, arranged by column.
  	There are as many columns as there are triangles in the mesh.
  	- $normals: array made up of the generalized coordinates (x, y, z, 1) of the normal vectors of each triangle.
  	There are as many columns as there are vertices.

Note

To compute the mesh, all NA voxels of the binary volume bin are set to FALSE. If all voxels are equal to FALSE, the function returns the code NULL.

See Also

vcgSmooth

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "rtstruct"), roi.name = "",
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

# creation of the patient mesh
bin <- bin.from.roi (CT, struct = S, roi.name = "patient", verbose = FALSE)
mesh.patient <- mesh.from.bin (bin, alias = "patient", verbose = FALSE)
str (mesh.patient)

Change of frame of reference of a mesh

Description

The mesh.in.new.ref function allows you to change the frame of reference of a mesh.

Usage

mesh.in.new.ref(
  mesh,
  new.ref.pseudo,
  T.MAT = NULL,
  alias = "",
  description = NULL
)

Arguments

Value

Returns "mesh" class object in the new frame of reference new.ref.pseudo.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "rtstruct", "mr"), 
                             roi.name = "", dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

#creation of the patient mesh
bin <- bin.from.roi (CT, struct = S, roi.name = "patient", verbose = FALSE)
mesh.patient <- mesh.from.bin (bin, alias = "patient", verbose = FALSE)

# mesh in the MR frame of reference
new.mesh <- mesh.in.new.ref (mesh.patient, patient$mr[[1]]$ref.pseudo, 
                             T.MAT = patient$T.MAT)

str (new.mesh, max.level = 2)                             

Repair of a mesh

Description

The mesh.repair function repairs holes in a mesh class object.

Usage

mesh.repair(mesh, verbose = TRUE)

Arguments

Value

Returns a mesh, repaired by removing degenerated triangles and filling holes.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "rtstruct"), 
                             roi.name = "gizzard", dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

# creation of the gizzard mesh
bin <- bin.from.roi (CT, struct = S, roi.name = "gizzard", verbose = FALSE)
mesh.gizzard <- mesh.from.bin (bin, alias = "gizzard", verbose = FALSE)

repair.mesh.gizzard <- mesh.repair (mesh.gizzard, verbose = FALSE)
str (mesh.gizzard)
str (repair.mesh.gizzard)

Adding spherical coordinates to a mesh

Description

The mesh.spheric.proj function adds latitude and longitude coordinates to a mesh. These features map the mesh surface to a sphere. Latitude and longitude are computed using the heat diffusion approach explained by Brechbühler and al [1].

Usage

mesh.spheric.proj(mesh, verbose = TRUE)

Arguments

Value

returns a "mesh" class object in which $mesh contains Lat and lon evaluated at vertices. The function allows to have a parameterized surface for later computations as curvature or shape index, hence, nor the surface, nor the angles are preserved. In the DICOM frame of reference, latitude goes along Z axis (from feet = -1 to head = +1) and longitude turns counter clockwise (from -1 to +1).

Note

This funtion is time consuming.

References

[1] Brechbuhler C, Gerig G, Kubler O (1995). “Parametrization of Closed Surfaces for 3-D Shape Description.” Computer Vision and Image Understanding, 61(2), 154-170. ISSN 1077-3142, doi:10.1006/cviu.1995.1013.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 6
patient <- toy.load.patient (modality = c("ct", "rtstruct"), roi.name = "", 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

# creation of the patient mesh
bin <- bin.from.roi (CT, struct = S, roi.name = "patient", verbose = FALSE)
m.skin <- mesh.from.bin (bin)

m.proj <- mesh.spheric.proj (m.skin, verbose = FALSE)

if (interactive()) {
  col <- hcl.colors (12, "Blue-Red 3")
  rgl::open3d()
  rgl::shade3d (m.proj$mesh, meshColors = "vertices",
                color = col[round ((m.proj$mesh$Lat/2 + 0.5) * 11) + 1],
                specular = "#404040")
  rgl::open3d()         
  rgl::shade3d (m.proj$mesh, meshColors = "vertices",
                color = col[round ((m.proj$mesh$Lon/2 + 0.5) * 11) + 1],
                specular = "#404040")
                
}

Restrict volume to a binary selection

Description

The nesting.bin function restricts a "volume" class object to the rectangular parallelepiped circumscribed to the selected voxels.

Usage

nesting.bin(
  obj,
  sel.bin,
  alias = "",
  description = NULL,
  xyz.margin = c(0, 0, 0),
  obj.restrict = FALSE,
  ...
)

Arguments

Details

If obj is of class "volume", xyz.margin represents the distances in mm to be added to the x, y and z directions of the rectangular parallelepiped circumscribed to the voxels selected in sel.bin, in the obj frame of reference.

If obj is of class “mesh”, sel.bin will undergo a margin expansion xyz.margin before the mesh points are selected..

Value

Returns a "volume" class object, in which 3D volume is limited to the rectangular parallelepiped circumscribed to the voxels selected by sel.bin, increased by the requested margins.

See Also

add.margin, nesting.cube and nesting.roi.

Examples

# loading of toy-patient objects (decrease dxyz for  better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "rtstruct"), 
                             roi.name = "brain", dxyz = rep (step, 3))
CT <- patient$ct[[1]]
b <- bin.from.vol (CT, min = 0, max =200)

CT.restricted <- nesting.bin (CT, b, xyz.margin =  rep (step, 3))
display.plane (bottom = CT.restricted, top = b, view.type = "sagi",
             bottom.col = pal.RVV (1000),
             bottom.breaks = seq (-1000, 1000, length.out = 1001),
             bg = "#00ff00",  interpolate  = FALSE)

Restriction of a volume to a rectangular parallelepiped

Description

The nesting.cube function restricts or increases a volume to the rectangular parallelepiped defined by its 2 extreme vertices.

Usage

nesting.cube(obj, pt.min, pt.max, alias = "", description = NULL, ...)

Arguments

Value

Returns a "volume" class object, in which 3D volume is restricted or increased to be circumscribed to the requested rectangular parallelepiped. If the created volume exceeds the initial volume, new voxels are set to NA.

See Also

add.margin, nesting.roi and nesting.bin.

Examples

# loading of toy-patient objects (decrease dxyz for better result)
step <- 5
patient <- toy.load.patient (modality = "ct", roi.name = "", 
                             dxyz = rep (step, 3))
CT <- patient$ct[[1]]
# Calculation of the new CT restricted to the parallelepiped reduced by 10 mm.
pt.CT <- get.extreme.pt (CT) # extreme points of CT
new.pt.CT <- pt.CT + matrix (rep (c (+ 12, -12), 3), ncol = 2, byrow = TRUE)
new.CT <- nesting.cube (CT, new.pt.CT$min, new.pt.CT$max, alias = "new CT")
## Not run:   
# check for change
display.3D.stack (CT)
display.3D.stack (new.CT, line.col="red")

## End(Not run)

Restrict volume to RoI

Description

The nesting.roi function restricts a "volume" class object to the rectangular parallelepiped circumscribed to the chosen RoI.

Usage

nesting.roi(
  obj,
  struct,
  roi.name = NULL,
  roi.sname = NULL,
  roi.idx = NULL,
  xyz.margin = c(0, 0, 0),
  obj.restrict = FALSE,
  T.MAT = NULL,
  alias = "",
  description = NULL,
  ...
)

Arguments

Details

If roi.name, roi.sname, and roi.idx are all set to NULL, all RoI are selected.

Value

Returns a "volume" class object, in which 3D volume is limited to the rectangular parallelepiped circumscribed to the chosen RoI, increased by the requested margins.

See Also

add.margin, nesting.cube and nesting.bin.

Examples

# loading of toy-patient objects (decrease dxyz for  better result)
step <- 4
patient <- toy.load.patient (modality = c("ct", "rtstruct"), 
                             roi.name = "brain", dxyz = rep (step, 3))
CT <- patient$ct[[1]]
S <- patient$rtstruct[[1]]

CT.brain <- nesting.roi (CT, S, roi.sname = "brain")
CT.brain.with.margin <- nesting.roi (CT, S, roi.sname = "brain",
                                         xyz.margin = c (10,10,10))

# display at the center of gravity of the cerebellum Gz
Gz <- S$roi.info [grep("^brain",S$roi.info$roi.pseudo),]$Gz
display.plane (bottom = CT.brain, view.coord = Gz,
               struct = S, bottom.col = pal.RVV (1000),
               bottom.breaks = seq (-1000, 1000, length.out = 1001),
               bg = "#00ff00",  interpolate  = FALSE, legend.shift = -20)
display.plane (bottom = CT.brain.with.margin,view.coord = Gz,
               struct = S,  bottom.col = pal.RVV (1000),
               bottom.breaks = seq(-1000, 1000, length.out = 1001),
               bg = "#00ff00", interpolate  = FALSE, legend.shift = -20)

Espadon object creating

Description

The obj.create function creates an espadon object with the essential properties it must have.

Usage

obj.create(class = c("", "volume", "struct", "mesh"), alias = "")

Arguments

Value

Returns a espadon class object (see espadon.class for class definitions).

See Also

vol.create, struct.create.

Examples

# Creation of an espadon mesh of a cube
M <- obj.create (class = "mesh")
M$mesh <- Rvcg::vcgIsotropicRemeshing (Rvcg::vcgBox(),0.5) 
M$nb.faces <- ncol (M$mesh$it)
rgl::wire3d (M$mesh)

Creation of orientation

Description

The orientation.create function creates the orientation vectors of a plane:

• from 3 points A, B and C (see details),

• or from 2 vectors B and C, resp. defining x and y-axis (see details),

• or from 2 points A, B defining x-axis, and the normal vector to the plane (see details),

• or from a vector B defining x-axis, and the normal vector to the plane (see details).

Usage

orientation.create(A = c(0, 0, 0), B = NULL, C = NULL, normal = NULL)

Arguments

Details

When using B and C, B-A define the x-axis unit vector. The unit vector of the y-axis is orthonormal to the x-axis, coplanar with A, B and C, and in the direction of A to C.

When using B and normal, the unit vector of the x-axis is orthonormal to the normal vector, in the direction of A to B. The unit vector of the y-axis is defined so as to constitute a direct orthonormal basis with the unit vector of the x-axis and the normal vector of the plane.

Value

Returns the orientation of the plane. That means the concatenation of 2 vectors, defining an orthonormal basis of the plane.

Examples

A <- c (-29.93, 18.85, 4.34)
B <- c (28.73, 15.36, 4.46)
C <- c (1.53, 75.21, 13.51)
orientation.create (A, B, C)

Conversion of Hounsfied Units to Realistic Volume Vizualization colors

Description

The RVV.pal function produces a color palette where Hounsfield Units in the range -1000 HU to 1000 HU are converted into realistically colorized virtual anatomy (for use with CT), developped by J.C. Silverstein and al [1]

Usage

pal.RVV(n, alpha = NULL, min.col = "#000000", max.col = "#FFFFFF")

Arguments

Value

Returns a color-labeled vector of size n.

References

[1] Silverstein JC, Parsad NM, Tsirline V (2008). “Automatic perceptual color map generation for realistic volume visualization.” Journal of Biomedical Informatics, 41(6), 927-935. ISSN 1532-0464, doi:10.1016/j.jbi.2008.02.008.

Examples

pal <- pal.RVV (256)

image (x = seq (-1000, 1000, length.out = 1024), y = 1,
       z = matrix (seq (-1100, 1100, length.out = 1024), ncol = 1),
       col = pal,
       main = "Realistic Volume Vizualization colors")

Rainbow palette

Description

The pal.rainbow function produces a color palette adapted to dose repesentation.

Usage

pal.rainbow(n, alpha = seq(0.8, 0, length.out = n))

Arguments

Value

Returns a color-labeled vector of size n.

Examples

pal <- pal.rainbow (255)

image (x = seq (0, 70, length.out = 255), y = 1,
       z = matrix (seq (0, 70, length.out = 255), ncol = 1),
       col = pal,
       main = "Rainbow colors")

plot a 2D cut of a 3D object

Description

The plot function displays the requested map of espadon objects of class "volume", "struct", "mesh".

Usage

## S3 method for class 'volume'
plot(
  x,
  ...,
  view.type = "trans",
  view.coord = NULL,
  flip = FALSE,
  flop = FALSE,
  cut.interpolate = TRUE,
  display.interpolate = FALSE,
  col = grey.colors(255, start = 0, end = 1),
  breaks = NULL,
  sat.transp = FALSE
)

## S3 method for class 'struct'
plot(
  x,
  ...,
  view.type = "trans",
  view.coord = NULL,
  flip = FALSE,
  flop = FALSE,
  roi.name = NULL,
  roi.sname = NULL,
  roi.idx = NULL,
  back.dxyz = c(0.5, 0.5, x$thickness)
)

## S3 method for class 'mesh'
plot(
  x,
  ...,
  view.type = "trans",
  view.coord = NULL,
  flip = FALSE,
  flop = FALSE,
  col = "#ff0000"
)

Arguments

Details

... can be xlim, ylim, add, bg etc. If view.type is egal to 'trans' or 'front' or 'sagi', the direction of xlim and ylim is ignored.

If roi.name, roi.sname, and roi.idx are all set to NULL, all closed planar or point RoI, present at view.coord are selected.

Value

Returns a display of the \(k^{th}\) image plane of x.

See Also

display.plane, display.kplane, display.palette, pal.RVV, pal.rainbow.

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for
# better result)
step <- 5
patient <- toy.load.patient (modality = c("ct","mr", "rtdose", "rtstruct"),
                             dxyz = rep (step, 3), beam.nb = 3)
MR <- patient$mr[[1]]
CT <- patient$ct[[1]]
D <- patient$rtdose[[1]]
S <- patient$rtstruct[[1]]

# display 1
layout (matrix(c(1,1,2,3), ncol=2), widths=c(1,0.2))
plot (CT, view.coord = 0, col = pal.RVV(255))
S_plot <- plot (S, view.coord = 0, add = TRUE, lwd = 2)
display.palette (col = pal.RVV(255), main="HU")
display.legend (S_plot, bg="white", text.col="black", lwd = 2, cex = 1.1)
# display 2
layout (matrix(c (1, 1, 2, 3), ncol = 2), widths = c (1, 0.2))
# Coordinates of the PTV barycenter in CT frame of reference
G <- as.numeric (S$roi.info[S$roi.info$roi.pseudo == "ptv", 
                            c ("Gx", "Gy", "Gz")])
# Coordinates of the PTV baricenter in MR frame of reference
G_MR <- as.numeric (c(G, 1) %*% 
                   t(get.rigid.M(CT$ref.pseudo, MR$ref.pseudo, 
                               T.MAT = patient$T.MAT)))[1:3]
plot (MR, view.type = "sagi", view.coord =  G_MR,
      col = grey.colors (255, start = 0, end = 1),
      breaks = seq (0, 500, length.out = 256) , bg = "darkblue")
plot (vol.in.new.ref(D, MR$ref.pseudo, T.MAT = patient$T.MAT),
      view.type = "sagi", view.coord = G_MR,
      col = pal.rainbow(255), add = TRUE)
display.palette (col = grey.colors (255, start = 0, end = 1),
                 breaks = seq (0, 500, length.out = 256), main="MR")
display.palette (col =  pal.rainbow(255),
                 breaks = seq (D$min.pixel, D$max.pixel, length.out = 256),
                 main="Gy")
layout(1)

Adding a frame of reference in T.MAT

Description

The ref.add function adds the transfer matrices from or to a new frame of reference defined from 2 unit vectors and an origin point.

Usage

ref.add(
  src.ref,
  orientation = c(1, 0, 0, 0, 1, 0),
  origin = c(0, 0, 0),
  new.ref.pseudo = "newref",
  T.MAT = NULL
)

Arguments

Value

Returns a "t.mat" class object, which contains the transfer matrices from or to new.ref.pseudo pseudonym of the new frame of reference. If the T.MAT is NULL, then the returned object will contain only 4 matrices: "src.ref<-src.ref", "src.ref<-new.ref.pseudo", "new.ref.pseudo<- new.ref.pseudo", "new.ref.pseudo<-src.ref".

Returns a NULL if orientation is not well defined.

See Also

ref.cutplane.add, ref.remove, ref.srctodest.add.

Examples

# Adding of the reference frame "ref1_60", which is a 60 degree rotation of 
# reference frame "ref1".
orientation <- c (cos (pi / 3), sin (pi / 3), 0, 
                  -sin (pi / 3), cos (pi / 3), 0)

local.Tmat <- ref.add (src.ref = "ref1", orientation = orientation,
                  new.ref.pseudo = "ref1_60")

str(local.Tmat)

Adding volume's cutting planes frame of reference in T.MAT

Description

The ref.cutplane.add function adds in T.MAT the transfer matrices from or to volume's cutting planes frame of reference.

Usage

ref.cutplane.add(
  vol,
  origin = c(0, 0, 0),
  ref.cutplane = paste0(vol$ref.pseudo, "m"),
  T.MAT = NULL
)

Arguments

Value

Returns a "t.mat" class object, which contains the transfer matrices from or to volume's cutting planes frame of reference. If the T.MAT is NULL, then the returned object will contain only 4 matrices: "src.ref<-src.ref", "src.ref<-ref.cutplane", "ref.cutplane<-ref.cutplane", "ref.cutplane<-src.ref".

See Also

ref.add, ref.srctodest.add, ref.remove.

Examples

# loading of toy-patient objects
patient <- toy.load.patient (modality = "mr", roi.name = "", dxyz = c (4, 4, 4))
MR <- patient$mr[[1]]
MR$xyz.from.ijk

# creation of t.mat, containing the transfer matrix to the frame of reference 
# of the MR cutting planes
t.mat <- ref.cutplane.add (MR)

# Change of frame of reference
MR.m <- vol.in.new.ref (MR, paste0 (MR$ref.pseudo, "m"), t.mat)

MR.m$xyz.from.ijk

Deletion of a frame of reference in T.MAT

Description

The ref.remove function removes the management of a frame of reference in T.MAT.

Usage

ref.remove(ref.name, T.MAT)

Arguments

Value

Returns a "t.mat" class object, which no longer contains transfer matrices from or to the ref.pseudo ref.name. ref.cutplane.add.

Examples

# Adding of the reference frame "ref1_60", which is a 60 degree rotation of 
# reference frame "ref1".
orientation <- c (cos (pi / 3), sin (pi / 3), 0, 
                  -sin (pi / 3), cos (pi / 3), 0)

local.Tmat <- ref.add (src.ref = "ref1", orientation = orientation,
                  new.ref.pseudo = "ref1_60")
str(local.Tmat)

# Removal of  "ref1_60"
local.Tmat <- ref.remove (ref.name =  "ref1_60", T.MAT = local.Tmat)
str(local.Tmat)

Linking two existing frames of reference in T.MAT

Description

The ref.srctodest.add function links the source frame of reference with the destination frame of reference.

Usage

ref.srctodest.add(src.ref, dest.ref, TM = diag(4), T.MAT = NULL)

Arguments

Value

Returns a "t.mat" class object, which contains the transfer matrices from or to dest.ref pseudonym of the new frame of reference. If the T.MAT is NULL, then the returned object will contain only 4 matrices: "src.ref<-src.ref", "src.ref<-dest.ref", "dest.ref<- dest.ref", "dest.ref<-src.ref".

See Also

ref.add, ref.cutplane.add, ref.remove.

Examples

local.Tmat <-  ref.srctodest.add ("ref1","ref2", 
                                  TM = matrix(c (0.5, -sin (pi / 3), 0, 0,
                                                 sin (pi / 3), 0.5, 0, 0,
                                                 0, 0, 1, 0, 0, 0, 0, 1),
                                              ncol = 4))
str (local.Tmat)   

Chi index 2D - 3D

Description

The rt.chi.index function computes the local or global Chi index from a measurement and a reference. These latter are "volume" class objects containing one (2D) or several planes (3D).

Usage

rt.chi.index(
  vol,
  vol.ref,
  abs = TRUE,
  vol.max = vol.ref$max.pixel,
  dose.th = 0.02,
  delta.r = 3,
  analysis.th = 0.05,
  local = FALSE,
  local.th = 0.3,
  project.to.isocenter = TRUE,
  alias = "",
  description = NULL
)

Arguments

Details

The Chi index of a voxel \(n\) was defined by Bakai and al [1]. It is computed from the formulae: \[\chi_n = \frac{D_i-Dref_n}{\sqrt{{\Delta D}^2 + {\Delta r}^2~\cdot~\Vert \nabla Dref_n \Vert^2}}\] If abs = TRUE, the used formulae is : \[\chi_n = \frac{\vert D_i-Dref_n\vert}{\sqrt{{\Delta D}^2 + {\Delta r}^2~\cdot~\Vert \nabla Dref_n \Vert^2}}\] with \(D_i\) the measured dose at voxel \(i\), \(Dref_n\) the reference dose at voxel \(n\), \(\nabla Dref_n\) the gradient of reference dose at voxel \(n\), \(\Delta r\) the distance difference criterion equal to delta.r, and \(\Delta D\) the distance difference criterion at voxel \(n\) defined as follows:

• If local = FALSE a global Chi index is computed and \(\Delta D~=~dose.th~\cdot~vol.max\).

• If local = TRUE, then \(\Delta D~=~dose.th~\cdot~Dref_n\) when \(Dref_n~\ge~local.th~\cdot~vol.max\), and \(\Delta D~=~dose.th~\cdot~local.th~\cdot~vol.max\) otherwise.

Value

Returns a "volume" class object (see espadon.class for class definitions). The $vol3D.data field represents the Chi index. Two fields are added: the $setup field recalls the calculation setup, and the $chi.info field details the number of dose points, the number of evaluated dose points,the rate of evaluated dose points, the rate of absolute values of the Chi index below 1, above 1.2 and 1.5,the max and the mean Chi index.

References

[1] Bakai A, Alber A, Nüsslin F (2003). “A revision of the Gamma-evaluation concept for the comparison of dose distributions.” Physics in Medicine and Biologys, 48(21), 3543–3553.

See Also

rt.gamma.index

Examples

# Creation of a reference volume  and measured volume
# loading of toy-patient objects (decrease dxyz for  better result)
patient <- toy.load.patient (modality = c ("rtdose", "rtstruct"), 
                             roi.name = "ptv", dxyz = c (5, 5, 5))
D.ref <- patient$rtdose[[1]]  
# We will assume that the measured dose is equal to the reference dose shifted
# by 3 pixels on the x axis
D.meas <- vol.copy (D.ref, alias = "measured_dose")
D.meas$vol3D.data[1:(D.meas$n.ijk[1] - 3) ,,] <- D.ref$vol3D.data[4:D.ref$n.ijk[1],,] 
D.max <- as.numeric(quantile(as.numeric(D.ref$vol3D.data), 
                             probs = 99.99/100, na.rm = TRUE))
abs_chi <- rt.chi.index (D.meas, D.ref, vol.max = D.max, delta.r = 6)  
abs_chi$chi.info  

# Display chi index at isocenter
G.iso <- patient$rtstruct[[1]]$roi.info$Gz[
  patient$rtstruct[[1]]$roi.info$name == "ptv"]
display.plane(abs_chi, view.coord = G.iso, 
              bottom.col = c ("#00FF00", "#007F00", "#FF8000", "#FF0000", 
                              "#AF0000"),
              bottom.breaks = c (0, 0.8, 1, 1.2, 1.5, abs_chi$max.pixel),
              interpolate = FALSE, bg = "blue")

Gamma index 2D - 3D

Description

The rt.gamma.index function computes the local or global Gamma index from a measurement and a reference. These latter are "volume" class objects containing one (2D) or several planes (3D).

Usage

rt.gamma.index(
  vol,
  vol.ref,
  over.sampling.factor = 1,
  vol.max = vol.ref$max.pixel,
  dose.th = 0.02,
  delta.r = 3,
  analysis.th = 0.05,
  local = FALSE,
  local.th = 0.3,
  project.to.isocenter = TRUE,
  alias = "",
  description = NULL
)

Arguments

Details

The Gamma index of a voxel \(n\) was defined by Low and al [1]. It is computed from the formulae: \[\gamma_n = min \left( \sqrt{\frac{(D_i-Dref_n)^2}{{\Delta D}^2} + \frac{{r_i}^2}{{\Delta r}^2}}\right)\] whith \(D_i\) the measured dose at voxel \(i\), \(Dref_n\) the reference dose at voxel \(n\), \(r_i\) the distance between voxels \(i\) and \(n\), \(\Delta r\) the distance difference criterion equal to delta.r, \(\Delta D\) the distance difference criterion at voxel \(n\) defined as follows:

• If local = FALSE a global Gamma index is computed and \(\Delta D~=~dose.th~\cdot~vol.max\).

• If local = TRUE, then \(\Delta D~=~dose.th~\cdot~Dref_n\) when \(Dref_n~\ge~local.th~\cdot~vol.max\), and \(\Delta D~=~dose.th~\cdot~local.th~\cdot~vol.max\) otherwise.

Value

Returns a "volume" class object (see espadon.class for class definitions). The $vol3D.data field represents the Gamma index. Two fields are added: the $setup field recalls the calculation setup, and the $gamma.info field details the number of dose points, the number of evaluated dose points,the rate of evaluated dose points, the rate of Gamma indices below 1, above 1.2 and 1.5, the max and the mean Gamma index.

References

[1] Low DA, Harms WB, Mutic S, Purdy JA (1998). “A technique for the quantitative evaluation of dose distributions.” Medical Physics, 25(5), 656–661.

See Also

rt.chi.index

Examples

# Creation of a reference volume  and measured volume
# loading of toy-patient objects (decrease dxyz for  better result)
patient <- toy.load.patient (modality = c ("rtdose", "rtstruct"), 
                             roi.name = "ptv", dxyz = c (5, 5, 5))
D.ref <- patient$rtdose[[1]]  
# We will assume that the measured dose is equal to the reference dose shifted
# by 3 pixels on the x axis
D.meas <- vol.copy (D.ref, alias = "measured_dose")
D.meas$vol3D.data[1:(D.meas$n.ijk[1] - 3) ,,] <- D.ref$vol3D.data[4:D.ref$n.ijk[1],,] 
D.max <- as.numeric(quantile(as.numeric(D.ref$vol3D.data), 
                             probs = 99.99/100, na.rm = TRUE))
gamma <- rt.gamma.index (D.meas, D.ref, delta.r = 6, vol.max = D.max)  
gamma$gamma.info  

# Display gamma index at isocenter
G.iso <- patient$rtstruct[[1]]$roi.info$Gz[
  patient$rtstruct[[1]]$roi.info$name == "ptv"]
display.plane(gamma, view.coord = G.iso, 
              bottom.col = c ("#00FF00", "#007F00", "#FF8000", "#FF0000", 
                              "#AF0000"),
              bottom.breaks = c (0, 0.8, 1, 1.2, 1.5, gamma$max.pixel), 
              bg = "blue", interpolate = FALSE)

Dosimetry, volume, conformity, homogeneity indices from binary selection

Description

The rt.indices.from.bin function calculates, from a "volume" class object of modality "rtdose", all the standard indicators of radiotherapy, as long as their options are transmitted, for the target and healthy "volume" object of modality "binary".

Usage

rt.indices.from.bin(
  vol,
  target.bin.list = NULL,
  healthy.bin.list = NULL,
  T.MAT = NULL,
  presc.dose = NA,
  healthy.tol.dose = NA,
  healthy.weight = 1,
  dosimetry = c("D.min", "D.max", "D.mean", "STD"),
  volume.indices = c("V.tot", "area", "V.prescdose"),
  conformity.indices = c("PITV", "CI.lomax2003", "CN", "NCI", "DSC", "CI.distance",
    "CI.abs_distance", "CDI", "CS3", "ULF", "OHTF", "gCI", "COIN", "G_COSI", "COSI"),
  homogeneity.indices = c("HI.RTOG.max_ref", "HI.RTOG.5_95", "HI.ICRU.max_min",
    "HI.ICRU.2.98_ref", "HI.ICRU.2.98_50", "HI.ICRU.5.95_ref", "HI.mayo2010",
    "HI.heufelder"),
  gradient.indices = c("GI.ratio.50"),
  D.xpc = NULL,
  D.xcc = NULL,
  V.xpc = NULL,
  V.xGy = NULL,
  DVH = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Value

Return a list of indices dataframe. For details, see rt.indices.from.roi.

See Also

rt.indices.from.roi.

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb for better
# result)
step <- 5
patient <- toy.load.patient (modality = c("rtdose", "rtstruct"), roi.name = "eye",
                             dxyz = rep (step, 3), beam.nb = 3)
D <- patient$rtdose[[1]]
struct <- patient$rtstruct[[1]]
T.MAT <- patient$T.MAT

# creation of the list of target binary volumes
target.roi.idx <- select.names (struct$roi.info$roi.pseudo, roi.sname = "ptv")
healthy.roi.idx <- select.names (struct$roi.info$roi.pseudo, roi.sname = "eye")
target.bin.list <- lapply (target.roi.idx , function (idx) {
  vr <- nesting.roi (D, struct, roi.idx = idx, xyz.margin = c (5, 5, 5),
                     T.MAT = T.MAT, alias = struct$roi.info$name[idx])
  b <- bin.from.roi(vr, struct, roi.idx = idx, T.MAT = T.MAT,
                    alias = struct$roi.info$name[idx], verbose = FALSE)
  })
names (target.bin.list) <- struct$roi.info$name[target.roi.idx]

healthy.bin.list <- lapply (healthy.roi.idx , function (idx) {
  vr <- nesting.roi (D, struct, roi.idx = idx, xyz.margin = c (5, 5, 5),
                     T.MAT = T.MAT, alias = struct$roi.info$name[idx])
  b <- bin.from.roi(vr, struct, roi.idx = idx, T.MAT = T.MAT,
                    alias = struct$roi.info$name[idx], verbose = FALSE)
})
names (healthy.bin.list) <- struct$roi.info$name[healthy.roi.idx]

indices <- rt.indices.from.bin (D, target.bin.list, healthy.bin.list,
                                presc.dose = 50,
                                conformity.indices = c("PITV", "PDS", "CI.lomax2003", 
                                                       "CN", "NCI", "DSC","COIN"),
                                verbose = FALSE)
indices[c("dosimetry","volume", "conformity","homogeneity","gradient")]
head(indices$DVH)

Dosimetry, volume, conformity, homogeneity indices from RoI

Description

The rt.indices.from.roi function calculates, from a "volume" class object of modality "rtdose", standard indicators of radiotherapy in relation to the target and healthy RoI, as long as their options are transmitted.

Usage

rt.indices.from.roi(
  vol,
  struct = NULL,
  T.MAT = NULL,
  target.roi.name = NULL,
  target.roi.sname = NULL,
  target.roi.idx = NULL,
  healthy.roi.name = NULL,
  healthy.roi.sname = NULL,
  healthy.roi.idx = NULL,
  presc.dose = NA,
  healthy.tol.dose = NA,
  healthy.weight = 1,
  dosimetry = c("D.min", "D.max", "D.mean", "STD"),
  volume.indices = c("V.tot", "area", "V.prescdose"),
  conformity.indices = c("PITV", "PDS", "CI.lomax2003", "CN", "NCI", "DSC",
    "CI.distance", "CI.abs_distance", "CDI", "CS3", "ULF", "OHTF", "gCI", "COIN",
    "G_COSI", "COSI"),
  homogeneity.indices = c("HI.RTOG.max_ref", "HI.RTOG.5_95", "HI.ICRU.max_min",
    "HI.ICRU.2.98_ref", "HI.ICRU.2.98_50", "HI.ICRU.5.95_ref", "HI.mayo2010",
    "HI.heufelder"),
  gradient.indices = c("GI.ratio.50", "mGI"),
  D.xpc = NULL,
  D.xcc = NULL,
  V.xpc = NULL,
  V.xGy = NULL,
  DVH = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Details

If target.roi.name, target.roi.sname, and target.roi.idx are all set to NULL, all RoI containing 'ptv' (if they exist) are selected.

If target.roi.name, target.roi.sname, and target.roi.idx are all set to NULL,no target RoI are selected.

If healthy.roi.name, healthy.roi.sname, and healthy.roi.idx are all set to NULL, no healthy RoI are selected.

Value

Returns a list containing (if requested)

\(-~dosimetry\) : dataframe containing, for all target and healthy structures:

• the requested dosimetry : D.min (Gy), D.max (Gy), D.mean (Gy) and STD (Gy), respectively the minimum, maximum, mean and standard deviation of the dose in the regions of interest.

• the requested $D.x% : (Gy) Dose covering x percent of structure volume.

• the requested $D.xcc : (Gy) Dose covering x (\(cm^3\)) of structure volume.

All numbers are displayed with a resolution depending on the DVH quantization step. The default resolution is 1e-3.

\(-~volume\) : dataframe containing, for all target and healthy structures, and isodoses:

• the requested volume.indices : V_tot (\(cm^3\)) (except for isodose) the total volume of the regions of interest, area (\(cm^2\)) (except for isodose) their surface areas, V.prescdose (\(cm^3\)) the volumes receiving at least presc.dose Gy,

• the requested V.xGy (\(cm^3\)): volumes receiving at least x Gy.

• the requested V.xpc (\(cm^3\)) Volume receiving at least x% of the reference dose.

\(-~conformity\) : dataframe containing, if requested,

• PITV : (1) Prescription Isodose Target Volume, or conformity index defined by E.Shaw [1] \[PITV = \frac{V_{presc.dose}}{V_{target}}\]

• PDS : (1) Prescription Dose Spillage defined by SABR UK Consortium 2019 [2] \[PDS = \frac{V_{presc.dose}}{V_{target ~\ge~ presc.dose}} = \frac{V_{presc.dose}}{V_{target} ~\cap~ V_{presc.dose}}\]

• CI.lomax2003 : (1) Conformity Index defined by Lomax and al [3] \[CI_{lomax2003} = \frac{V_{target ~\ge~ presc.dose}}{V_{presc.dose}} = \frac{V_{target} ~\cap~ V_{presc.dose}}{V_{presc.dose}}\]

• CN : (1) Conformation Number defined by Van't Riet and al [4]. It corresponds to conformity index defined by Paddick [5] \[CN = CI_{paddick2000} =\frac{V_{target ~\ge~ presc.dose}^2}{V_{target}~\cdot~V_{presc.dose}} = \frac{(V_{target} ~\cap~ V_{presc.dose})^2}{V_{target}~\cdot~V_{presc.dose}}\]

• NCI : (1) New conformity index, inverse of CN, defined by Nakamura and al [6] \[NCI =\frac{1}{CN}\]

• DSC : (1) Dice Similarity Coefficient [7] \[DSC = 2 ~\cdot~\frac{V_{target ~\ge~ presc.dose}}{V_{target} + V_{presc.dose}} = 2 ~\cdot~\frac{V_{target} ~\cap~ V_{presc.dose}}{V_{target} + V_{presc.dose}}\]

• CI.distance : (1) Conformity Index based on distance defined by Park and al [8] \[CI.distance = \frac{100}{N} \sum^N \frac{dist_{S_{presc.dose}~\to~G_{target}} - dist_{S_{target}~\to~G_{target}}}{dist_{S_{target}~\to~G_{target}}}\] where \(dist_{S_{presc.dose}~\to~G_{target}}\) is the distance between the surface of the prescription dose volume and the centroid of the target, and \(dist_{S_{target}~\to~G_{target}}\) the surface of the target volume and the centroid of the target. \(N\) is the number of directions where the distances are calculated. These directions are computed every 1°. If the centroid is not within the target volume, then CI.distance = NA.

• CI.abs_distance : (1) Conformity Index based on distance defined by Park and al [8] \[CI.abs_distance = \frac{100}{N} \sum^N \frac{|dist_{S_{presc.dose}~\to~G_{target}} - dist_{S_{target}~\to~G_{target}}|}{dist_{S_{target}~\to~G_{target}}}\]

• CDI : (1) Conformity Distance Index defined by Wu and al [9] \[CDI = 2 \frac{V_{presc.dose} + V_{target} - 2~V_{target ~\ge~ presc.dose}} {S_{target} + S_{presc.dose}} = \frac{V_{presc.dose} + V_{target} - 2~\cdot~V_{target} ~\cap~ V_{presc.dose}} {S_{target} + S_{presc.dose}}\] where \(S_{target}\) is the surface of the target volume and \(S_{presc.dose}\) is the surface of the prescription dose volume.

• CS3 : (1) Triple Point Conformity Scale defined by Ansari and al [10] \[CS3 = \frac{V_{0.95~\cdot~presc.dose} + V_{presc.dose} + V_{1.05~\cdot~presc.dose}}{3~\cdot~V_{target}}\]

• ULF : (1) Underdosed lesion factor defined by Lefkopoulos and al [11] \[ULF = \frac{V_{target ~<~ presc.dose}}{V_{target}}= \frac{V_{target} ~\cap~ \overline{V_{presc.dose}}}{V_{target}}\]

• OHTF :(1) Overdosed healthy tissues factor defined by Lefkopoulos and al [11] \[OHTF = \frac{\sum V_{healthy ~\ge~ presc.dose}}{V_{target}} = \frac{\sum V_{healthy} ~\cap~ V_{presc.dose}}{V_{target}} \]

• gCI : (1) Geometric Conformity Index defined by Lefkopoulos and al [11] \[gCI = ULF + OHTF\]

• COIN : Conformity Index defined by Baltas and al [12] \[COIN =\frac{V_{target ~\ge~ presc.dose}^2}{V_{target}~\cdot~V_{presc.dose}}~\cdot~ \prod^{N_{healthy}} \left( 1 -\frac{V_{healthy ~\ge~ presc.dose}}{V_{healthy}}\right)\]

• gCOSI : generalized COSI, defined by Menhel and al [13]. \[gCOSI = 1- \sum^{N_{healthy}} healthy.weight~\cdot~ \frac{\frac{V_{healthy ~\ge~ healthy.tol.dose}}{V_{healthy}}}{\frac{V_{target ~\ge~ presc.dose}}{V_{target}}}\]

\(-~COSI\) : if "COSI" is requested in conformity.indices, it returns a dataframe of Critical Organ Scoring Index for each healthy organ, at each presc.dose, and for each target. COSI is defined by Menhel and al [13] \[COSI = 1- \frac{\frac{V_{healthy ~\ge~ healthy.tol.dose}}{V_{healthy}}}{\frac{V_{target ~\ge~ presc.dose}}{V_{target}}}\]

\(-~homogeneity\) : dataframe containing

• HI.RTOG.max_ref : (1) Homogeneity Index from RTOG defined by E.Shaw [1] \[HI.RTOG.max_-ref = \frac{D_{~max}}{presc.dose}\] where \(D_{max}\) is the maximum dose in the target volume.

• HI.RTOG.5_95 : (1) Homogeneity Index from RTOG [1] \[HI.RTOG.5_-95 = \frac{D.5pc}{D.95pc}\] where \(D.5pc\) and \(D.95pc\) are respectively the doses at 5% and 95% of the target volume in cumulative dose-volume histogram.

• HI.ICRU.max_min : (1) Homogeneity Index from ICRU report 62 [14] \[HI.ICRU.max_-min = \frac{D_{~max}}{D_{~min}}\] where \(D_{max}\) and \(D_{min}\) are respectively the maximum and the minimum dose in the target volume.

• HI.ICRU.2.98_ref : (1) Homogeneity Index from ICRU report 83 [15] \[HI.ICRU.2.98_-ref = 100 \frac{D.2pc - D.98pc}{presc.dose}\] where \(D.2pc\) and \(D.98pc\) are respectively the doses at 2% and 98% of the target volume in cumulative dose-volume histogram.

• HI.ICRU.2.98_50 : (1) Homogeneity Index from ICRU report 83 [15] \[HI.ICRU.2.98_-50 = 100 \frac{D.2pc - D.98pc}{D.50pc}\] where \(D.2pc\), \(D.98pc\) and \(D.50pc\) are respectively the doses at 2%, 98% and 50% of the target volume in cumulative dose-volume histogram.

• HI.ICRU.5.95_ref : (1) Homogeneity Index from ICRU report 83 [15] \[HI.ICRU.5.95_-ref = 100 \frac{D.5pc - D.95pc}{presc.dose}\] where \(D.5pc\) and \(D.95pc\) are respectively the doses at 5% and 95% of the target volume in cumulative dose-volume histogram.

• HI.mayo2010 : (1) Homogeneity Index defined by Mayo and al [16] \[HI.mayo2010 =\sqrt{\frac{D_{~max}}{presc.dose}~\cdot~(1 + \frac{\sigma_D}{presc.dose})}\] where \(D_{max}\) is the maximum dose in the target volume, and \(\sigma_D\) the standard deviation of the dose in the target volume.

• HI.heufelder : (1) Homogeneity Index defined by Heufelder and al [17] \[HI.heufelder = e^{-0.01~\cdot~ (1-\frac{\mu_D}{presc.dose})^2}~\cdot~ e^{-0.01~\cdot~ (\frac{\sigma_D}{presc.dose})^2}\] where \(\mu_D\) and \(\sigma_D\) are respectively the mean and the standard deviation of the dose in the target volume.

\(-~gradient\) : dataframe containing

• GI.ratio.50: Gradient Index based on volumes ratio defined by Paddick and Lippitz [18] \[GI.ratio.50 = \frac {V_{0.5~\cdot~presc.dose}}{V_{presc.dose}}\]

• mGI: Modified Gradient Index defined by SABR UK Consortium 2019 [2] \[mGI = \frac{V_{0.5~\cdot~presc.dose}}{V_{target ~\ge~ presc.dose}} = \frac{V_{0.5~\cdot~presc.dose}}{V_{target} ~\cap~ V_{presc.dose}}\]

\(-~DVH\) : dataframe containing the Dose-Volume histograms of target and healthy ROIs, in percent.

References

[1] Shaw E, Kline R, Gillin M, Souhami L, Hirschfeld A, Dinapoli R, Martin L (1993). “Radiation therapy oncology group: Radiosurgery quality assurance guidelines.” International journal of radiation oncology, biology, physics, 27(5), 1231-1239. ISSN 0360-3016, doi:10.1016/0360-3016(93)90548-A.

[2] UK SABR Consortium (Online; accessed 2022-04-01). “Stereotactic Ablative Radiation Therapy (SABR): a resource. v6.1, January 2019.” https://www.sabr.org.uk/wp-content/uploads/2019/04/SABRconsortium-guidelines-2019-v6.1.0.pdf.

[3] Lomax NJ, Scheib SG (2003). “Quantifying the degree of conformity in radiosurgery treatment planning.” International journal of radiation oncology, biology, physics, 55(5), 1409-1419. ISSN 0360-3016, doi:10.1016/S0360-3016(02)04599-6.

[4] Riet AV, Mak AC, Moerland MA, Elders LH, Van der Zee W (1997). “A conformation number to quantify the degree of conformality in brachytherapy and external beam irradiation: Application to the prostate.” International journal of radiation oncology, biology, physics, 37(3), 731-736. ISSN 0360-3016, doi:10.1016/S0360-3016(96)00601-3.

[5] Paddick I (2000). “A simple scoring ratio to index the conformity of radiosurgical treatment plans. Technical note.” Journal of neurosurgery, 93 Suppl 3, 219-222.

[6] Nakamura J, Verhey L, Smith V, Petti P, Lamborn K, Larson D, Wara W, Mcdermott M, Sneed P (2002). “Dose conformity of Gamma Knife radiosurgery and risk factors for complications.” International journal of radiation oncology, biology, physics, 51, 1313-9. doi:10.1016/S0360-3016(01)01757-6.

[7] Dice LR (1945). “Measures of the Amount of Ecologic Association Between Species.” Ecology, 26(3), 297–302. ISSN 00129658, 19399170.

[8] Park JM, Park S, Ye S, Kim J, Carlson J, Wu H (2014). “New conformity indices based on the calculation of distances between the target volume and the volume of reference isodose.” The British journal of radiology, 87, 20140342. doi:10.1259/bjr.20140342.

[9] Wu Q, Wessels BW, Einstein DB, Maciunas RJ, Kim EY, Kinsella TJ (2003). “Quality of coverage: Conformity measures for stereotactic radiosurgery.” Journal of Applied Clinical Medical Physics, 4, 374-381.

[10] Ansari S, Satpathy S, Singh P, Lad S, Thappa N, Singh B (2018). “A new index: Triple Point Conformity Scale (CS3) and its implication in qualitative evaluation of radiotherapy plan.” Journal of Radiotherapy in Practice, 17, 1-4. doi:10.1017/S1460396917000772.

[11] Lefkopoulos D, Dejean C, balaa ZE, Platoni K, Grandjean P, Foulquier J, Schlienger M (2000). “Determination of dose-volumes parameters to characterise the conformity of stereotactic treatment plans.” In chapter XIII, 356-358. Springer Berlin Heidelberg. ISBN 978-3-540-67176-3, doi:10.1007/978-3-642-59758-9_135.

[12] Baltas D, Kolotas C, Geramani KN, Mould RF, Ioannidis G, Kekchidi M, Zamboglou N (1998). “A conformal index (COIN) to evaluate implant quality and dose specification in brachytherapy.” International journal of radiation oncology, biology, physics, 40 2, 515-24. doi:10.1016/s0360-3016(97)00732-3.

[13] Menhel J, Levin D, Alezra D, Symon Z, Pfeffer R (2006). “Assessing the quality of conformal treatment planning: a new tool for quantitative comparison.” Physics in Medicine and Biology, 51(20), 5363–5375.

[14] Landberg T, Chavaudra J, Dobbs J, Gerard J, Hanks G, Horiot J, Johansson K, Möller T, Purdy J, Suntharalingam N, Svensson H (1999). “ICRU Report 62: Prescribing, Recording and Reporting Photon Beam Therapy (Supplement to ICRU Report 50),3. Absorbed Doses.” Reports of the International Commission on Radiation Units and Measurements, os-32(1), 21-25.

[15] ICRU (2010). “Report 83 : Prescribing, Recording, and Reporting Photon-Beam Intensity-Modulated Radiation Therapy (IMRT).” Reports of the International Commission on Radiation Units and Measurements, 10(1), 1-3.

[16] Mayo CS, Ding L, Addesa A, Kadish S, Fitzgerald TJ, Moser R (2010). “Initial Experience With Volumetric IMRT (RapidArc) for Intracranial Stereotactic Radiosurgery.” International Journal of Radiation Oncology*Biology*Physics, 78(5), 1457-1466. ISSN 0360-3016, doi:10.1016/j.ijrobp.2009.10.005.

[17] Heufelder J, Zink K, Scholz M, Kramer K, Welker K (2003). “Eine Methode zur automatisierten Bewertung von CT-basierten Bestrahlungsplanen in der perkutanen Strahlentherapie.” Zeitschrift fur Medizinische Physik, 13(4), 231-239. ISSN 0939-3889, doi:10.1078/0939-3889-00175.

[18] Paddick I, Lippitz BE (2006). “A simple dose gradient measurement tool to complement the conformity index.” Journal of neurosurgery, 105 Suppl, 194-201.

All this references are compiled by

• Kaplan LP, Korreman SS (2021). “A systematically compiled set of quantitative metrics to describe spatial characteristics of radiotherapy dose distributions and aid in treatment planning.” Physica Medica, 90, 164-175. ISSN 1120-1797, doi:10.1016/j.ejmp.2021.09.014. and

• Patel G, Mandal A, Choudhary S, Mishra R, Shende R (2020). “Plan evaluation indices: A journey of evolution.” Reports of Practical Oncology & Radiotherapy, 25. doi:10.1016/j.rpor.2020.03.002..

See Also

rt.indices.from.bin.

Examples

# loading of toy-patient objects (decrease dxyz and increase beam.nb 
#  for better result)
step <- 5
patient <- toy.load.patient (modality = c("rtdose", "rtstruct"), roi.name = "eye",
                             dxyz = rep (step, 3), beam.nb = 3)
indices <- rt.indices.from.roi (patient$rtdose[[1]],  patient$rtstruct[[1]],
                                target.roi.sname = "ptv",
                                healthy.roi.sname = "eye", presc.dose = 50,
                                conformity.indices = c("PITV", "PDS", "CI.lomax2003", 
                                                       "CN", "NCI", "DSC","COIN"),
                                verbose = FALSE)
indices[c("dosimetry","volume", "conformity","homogeneity","gradient")]
head(indices$DVH)

Save a T.MAT class object

Description

The save.T.MAT function saves the data required by load.T.MAT, load.patient.from.dicom or load.patient.from.Rdcm to generate T.MAT, as pre-formatted Rdcm files.

Usage

save.T.MAT(T.MAT, dirname)

Arguments