R/load_obj_from_Rdcm.R

In espadon: Easy Study of Patient DICOM Data in Oncology

#' Loading an \pkg{espadon} object from *.Rdcm file
#' @description The \code{load.obj.from.Rdcm} function loads a DICOM object into 
#' memory, creating a list containing the information necessary for its subsequent 
#' use with the \pkg{espadon} package.
#' @param Rdcm.filename Character string, representing the full name of a *.Rdcm 
#' file created by \link[espadon]{dicom.to.Rdcm.converter}.
#' @param data Boolean. Only works for objects usable by the \pkg{espadon} package, namely
#' ct, mr, rtdose, rtstruct, pt... If \code{data = TRUE}, either the values of the 
#' voxels when modality is (ct, mr, rtdose), or the coordinates of the RoI when modality 
#' is rtstruct, are loaded into memory.
#' @param nb Vector of integers, active only if \code{data = TRUE}, and only
#' operating on rtstruct. If \code{nb = NULL}, all the RoI of rtstruct are
#' loaded into memory. Otherwise only data of the RoI indices defined by the vector 
#' \code{nb} are loaded.
#' @param upgrade.to.latest.version Boolean. If \code{TRUE}, the function attempts 
#' to upgrade to the latest version, parsing the DICOM data. It may take longer 
#' to load the data. Consider using the \link[espadon]{Rdcm.upgrade} function.
#' @return Returns an \pkg{espadon} object of class "dvh","histo","histo2D","mesh", 
#' "rtplan","struct", "undef" or "volume" depending on the object modality. See 
#' \link[espadon]{espadon.class} for class definitions.

#' @seealso \link[espadon]{load.obj.data} and \link[espadon]{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)  
                  
#' @export
load.obj.from.Rdcm <- function (Rdcm.filename, data = TRUE, nb = NULL,
                                upgrade.to.latest.version = FALSE){
  if (length(Rdcm.filename)>1){
    message  ("only first file is used.")
    Rdcm.filename <- Rdcm.filename[1]
  }
  if ((length(Rdcm.filename)==0) | !file.exists(Rdcm.filename)){
    warning ("no file to load.")
    return (NULL)
  }
  
  if (grepl ("[.]Rdcm$", Rdcm.filename)){
    Lobj <- load.Rdcm.raw.data (Rdcm.filename,  data=data, 
                                upgrade.to.latest.version = upgrade.to.latest.version)
    if (Lobj$update.needed){

      if (upgrade.to.latest.version) {
        warning(paste(Lobj$header$file.basename, "version has been upgraded, consider using Rdcm.upgrade() for faster loading."))
      } else {
        warning(paste(Lobj$header$file.basename, "version is not up to date, consider using Rdcm.upgrade()."))  
      }
    }
    return (.load.object (Lobj, data=data, nb=nb))
  }
  return (NULL)
}