Package 'espadon'

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)

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

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)

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)

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"))

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)

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)

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 <- 3
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)

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)

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")

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)

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)

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)

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)

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"))

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"))

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)

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)

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 patient",
  reset.private.tag = FALSE,
  new.UID = FALSE,
  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)

Description

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

Usage

dicom.raw.data.anonymizer(
  dicom.raw.data,
  offset = 0,
  new.PIN = "Anonymous ",
  reset.private.tag = FALSE,
  new.UID = FALSE,
  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)

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)

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)

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

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

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)

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

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")

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))
library (rgl)
open3d()
bg3d ("black")
display.3D.contour (struct = patient$rtstruct[[1]], roi.print = TRUE)

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
library (rgl)
open3d()
display.3D.mesh (mesh.patient, color = "burlywood2", specular = "#404040")

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]]

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

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
library (rgl)
open3d()
display.3D.stack (patient$ct[[1]],
                  col = pal.RVV (200, alpha = c(rep(0,90), rep (1, 110))))

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

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)

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)

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)

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)

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)

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)

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)

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)

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).