
Read a 3D or 4D DICOM Volume with Exact Patient-Space Geometry
Source:R/volume-read.R
read_dicom_volume.RdReconstructs a 3D ([rows, cols, slices]) or 4D
([rows, cols, slices, frames]) dicom_volume object
from classical multi-file DICOM series, single-file Enhanced Multi-Frame IODs
(SharedFunctionalGroupsSequence / PerFrameFunctionalGroupsSequence),
stationary cine loops (XA, US), or dynamic multi-timepoint stacks.
Usage
read_dicom_volume(
path,
series_uid = NULL,
subseries = NULL,
rescale = TRUE,
split = FALSE,
recursive = TRUE,
warn = TRUE
)Arguments
- path
Directory path or character vector of DICOM file/directory paths.
- series_uid
Optional
SeriesInstanceUIDstring to select a specific DICOM series whenpathcontains multiple series.- subseries
Optional 1-based integer index selecting which homogeneous sub-series from
dicom_split_series()to read whensplit = FALSE. WhenNULL(default), reads primary sub-series1Land emits a warning if multiple sub-series (e.g. a localizer scout or multiple echoes) were detected.- rescale
Logical. Apply per-frame or top-level
RescaleSlopeandRescaleInterceptto convert stored integers to physical modality units (e.g."HU"for CT,"BQML"for PET). Default isTRUE.- split
Logical. If
TRUE, returns alistofdicom_volumeobjects, one for every homogeneous sub-series discovered bydicom_split_series(). Default isFALSE.- recursive
Logical. When
pathcontains directories, search subdirectories recursively. Default isTRUE.- warn
Logical. Emit informative
cli::cli_warn()diagnostics when multiple sub-series, irregular slice spacing, gantry tilt shear, or duplicate slice positions are encountered. Default isTRUE.
Value
A dicom_volume object when split = FALSE, or
a list of dicom_volume objects when split = TRUE.
Details
Slices are ordered strictly by projecting ImagePositionPatient (0020,0032)
onto the right-handed slice normal cross(d_row, d_col) derived from
ImageOrientationPatient (0020,0037) (never trusting InstanceNumber when
spatial positions are present). Computes the exact 4x4 DICOM LPS
voxel-to-world affine matrix (including gantry/detector tilt shear when
present) and records geometry diagnostics for irregular spacing, slice
gaps/overlaps, gantry tilt, and duplicate positions.
Examples
out_dir <- tempfile("vol_read_demo_")
dicom_synthesize(
out_dir = out_dir,
modality = "CT",
dims = c(16L, 16L, 4L),
orientation = "oblique",
reverse_order = TRUE
)
vol <- read_dicom_volume(out_dir)
vol
#> <dicom_volume [CT] 16x16x4 | coord=LPS | units=HU>
#> spacing: (1, 1, 2.5) mm | origin: (-16, -16, 0) mm
#> frame_meta: 4 row(s) | provenance: 1 step(s)
unlink(out_dir, recursive = TRUE)