Low-level S3 constructor and validator for 3D ([rows, cols, slices]) and
4D ([rows, cols, slices, frames]) medical imaging volumes paired with an
exact 4x4 homogeneous voxel-to-world affine matrix in DICOM "LPS" or
NIfTI "RAS" physical coordinates (millimeters).
Usage
new_dicom_volume(
voxels,
affine = diag(4L),
coord_system = c("LPS", "RAS"),
spacing = NULL,
direction = NULL,
frame_meta = NULL,
uids = list(),
modality = NA_character_,
units = NA_character_,
diagnostics = list(),
provenance = list()
)
# S3 method for class 'dicom_volume'
dim(x)
# S3 method for class 'dicom_volume'
as.array(x, ...)
# S3 method for class 'dicom_volume'
print(x, ...)Arguments
- voxels
Numeric 2D matrix
[rows, cols](automatically promoted to[rows, cols, 1L]), 3D array[rows, cols, slices], or 4D array[rows, cols, slices, frames].- affine
4x4 finite numeric homogeneous voxel-to-world affine matrix whose bottom row is
c(0, 0, 0, 1). Defaults todiag(4L).- coord_system
World coordinate convention:
"LPS"(DICOM Patient Coordinate System: Left-Posterior-Superior, default) or"RAS"(Right-Anterior-Superior).- spacing
Optional length-3 non-negative numeric vector
c(dr, dc, dz)in millimeters. Automatically derived from the Euclidean norms of columns 1..3 ofaffinewhenNULL.- direction
Optional named list with length-3 numeric direction cosine vectors
d_row,d_col, andnormal. Automatically derived fromaffinewhenNULL.- frame_meta
Optional tibble::tibble (or
data.frame, coerced to a tibble) storing per-slice or per-frame DICOM header metadata. Defaults to an empty tibble.- uids
Named
listof DICOM study/series/frame-of-reference UIDs.- modality
Single character string (e.g.
"CT","MR","PT") orNA_character_.- units
Single character string giving voxel physical units (e.g.
"HU","BQML","g/mL") orNA_character_.- diagnostics
Named
listof geometry diagnostics (e.g.irregular_spacing,gantry_tilt_deg).- provenance
listof chronological provenance entries recording transformations applied to the volume.- x
A
dicom_volumeobject.- ...
Additional arguments passed to or from methods.
Details
By convention, 0-based voxel indices (r, c, s) map to physical world
coordinates via affine %*% c(r, c, s, 1), where:
Column 1 (
rstep along rows) isd_col * drColumn 2 (
cstep along columns) isd_row * dcColumn 3 (
sstep across slices) is the inter-slice step vectorColumn 4 is the physical origin of voxel
(r = 0, c = 0, s = 0)([1, 1, 1]1-based)
Examples
vox <- array(seq_len(8 * 8 * 4), dim = c(8L, 8L, 4L))
aff <- diag(c(0.8, 0.8, 2.5, 1.0))
aff[1:3, 4] <- c(-10, -10, 0)
vol <- new_dicom_volume(vox, affine = aff, modality = "CT", units = "HU")
vol
#> <dicom_volume [CT] 8x8x4 | coord=LPS | units=HU>
#> spacing: (0.8, 0.8, 2.5) mm | origin: (-10, -10, 0) mm
#> frame_meta: 0 row(s) | provenance: 0 step(s)
is_dicom_volume(vol)
#> [1] TRUE
