matlab-read-medical-data

name	matlab-read-medical-data
description	Read, write, and manipulate medical imaging data (DICOM, NIfTI, NRRD) in MATLAB. Covers Image Processing Toolbox functions (dicomreadVolume, niftiread, dicomContours, dicomanon) and Medical Imaging Toolbox enhanced APIs (medicalVolume, medicalImage, medicalref3d, extractSlice, updateOrientation). Use when reading medical files, listing DICOM series, extracting spatial referencing, changing orientation, working with RT structures, or anonymizing DICOM data. Some features require Medical Imaging Toolbox — see skill body and references for details.
license	https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata	{"author":"MathWorks","version":"1.0"}

Read and Write Medical Data

Read, write, and manipulate medical imaging data in MATLAB. This skill covers both Image Processing Toolbox (IPT) functions and Medical Imaging Toolbox (MIT) enhanced APIs.

When to Use

• Reading or writing DICOM, NIfTI, or NRRD files
• Listing DICOM series with dicomCollection
• Extracting spatial referencing or coordinate transforms
• Changing volume orientation or extracting oriented slices
• Working with DICOM RT structures (contours, masks, modify/write)
• Anonymizing DICOM data

When NOT to Use

• Displaying or visualizing volumes (use matlab-display-volume skill)
• Displaying 2-D medical images with annotations (use matlab-display-image skill)
• Reading non-medical image formats (PNG, TIFF, JPEG) — use imread

Toolbox Detection — CRITICAL FIRST STEP

Always check which toolboxes are available before choosing an approach. If Medical Imaging Toolbox is installed, prefer its APIs. If only Image Processing Toolbox is available, use IPT patterns.

Task → Function Quick Reference

Task	IPT only	With Medical Imaging Toolbox (preferred)
Read single DICOM file	dicomread + dicominfo	medicalImage
Read DICOM folder	dicomreadVolume	medicalVolume
Read NIfTI	niftiread + niftiinfo	medicalVolume
Read NRRD	— (requires MIT)	medicalVolume or nrrdread + nrrdinfo
List DICOM series	dicomCollection	dicomCollection
Spatial referencing	imref3d	medicalref3d
Extract oriented slice	Manual indexing	extractSlice
Change orientation	Manual permute	updateOrientation
Read DICOM RT structure	dicomContours(dicominfo(file))	Same
Anonymize DICOM	dicomanon + dicomuid	Same
Visualize volume	volumeViewer	medicalVolumeViewer or volshow(medVol)

Top 4 Patterns

1. Read DICOM folder

Call medicalVolume or dicomreadVolume directly on the DICOM folder path. Do NOT call dicomCollection first — it is unnecessary when reading a single-series folder.

% WITH Medical Imaging Toolbox (preferred):
medVol = medicalVolume("path/to/dicom/folder");
V = medVol.Voxels;               % Auto-rescaled (e.g., HU for CT)
spacing = medVol.VoxelSpacing;   % [dx dy dz] in mm
orientation = medVol.Orientation; % "transverse", "coronal", "sagittal"
modality = medVol.Modality;       % "CT", "MR"

% Access spatial referencing via VolumeGeometry (medicalref3d object)
geom = medVol.VolumeGeometry;
geom.VolumeSize;                  % [rows cols slices]
geom.PatientCoordinateSystem;     % "LPS+" or "RAS+"
geom.Position;                    % [slices×3] slice positions in patient coords
geom.VoxelDistances;              % {[slices×3] [slices×3] [slices×3]} per-axis distances
geom.PixelSpacing;                % [slices×2] in-plane pixel spacing per slice
geom.IsAffine;                    % true if uniform spacing (affine transform)
geom.IsAxesAligned;               % true if volume axes align with patient axes
geom.IsMixed;                     % true if slices have varying pixel spacing

% IPT only:
[V, spatial, dim] = dicomreadVolume("path/to/dicom/folder");
V = squeeze(V);  % Remove singleton 4th dimension

2. Read NIfTI file

% WITH Medical Imaging Toolbox (preferred):
medVol = medicalVolume("path/to/file.nii.gz");

% IPT only:
V = niftiread("path/to/file.nii.gz");
info = niftiinfo("path/to/file.nii.gz");
voxelSize = info.PixelDimensions(1:3);

3. List DICOM series and read one

Use dicomCollection only when:

• The user says the folder contains multiple series or volumes
• medicalVolume or dicomreadVolume fails with an error (e.g., "not a DICOM file" or "multiple volumes detected")
• You need to identify what series exist before deciding which one to read

dicomCollection scans the directory, excludes non-DICOM files, and returns a table where each row is one series. It does not read pixel data.

collection = dicomCollection("path/to/directory");
disp(collection);  % Table with Modality, SeriesDescription, Rows, Columns, Frames

% WITH Medical Imaging Toolbox:
medVol = medicalVolume(collection, "s1");

% IPT only:
[V, spatial] = dicomreadVolume(collection, "s1");

4. Extract slice / change orientation (Requires Medical Imaging Toolbox)

medVol = medicalVolume("path/to/file.nii");

% Extract slices — works for any orientation
[axialSlice, position, spacings] = extractSlice(medVol, 50, "transverse");
[coronalSlice, ~, ~] = extractSlice(medVol, 30, "coronal");
[sagittalSlice, ~, ~] = extractSlice(medVol, 45, "sagittal");

% If medVol.Orientation is not empty, use it as the third input
[sliceData, position, spacings] = extractSlice(medVol, 50, medVol.Orientation);

% Change orientation — do NOT use permute
medVolCoronal = updateOrientation(medVol, "coronal");  % Returns NEW object

updateOrientation was introduced in R2025a.

Detailed Reference Files

IMPORTANT: Before generating code for any task below, read the matching reference file first.

Task trigger	Reference	Read BEFORE
Reading/writing DICOM or NIfTI with IPT	references/ipt-reading-writing.md	Writing dicomreadVolume, niftiread, imref3d, or rescale logic
Using medicalVolume, medicalImage, slices, or orientation	references/mit-medical-volume.md	Writing medicalImage, medicalVolume, extractSlice, or updateOrientation calls
Spatial referencing or coordinate transforms	references/mit-spatial-referencing.md	Writing medicalref3d, intrinsicToWorld, or worldToIntrinsic calls
RT structures (contours, labelmaps, RTSTRUCT)	references/dicom-rt-workflows.md	Reading, editing, displaying, or plotting contours/RTSTRUCT files, or writing any dicomContours, plotContour, createMask, addContour, deleteContour call
Anonymizing DICOM files	references/dicom-anonymization.md	Writing any dicomanon or dicomuid call

Legacy Patterns to Avoid

Do NOT use	Use instead	Why
dicomread + dicominfo for single file	medicalImage (MIT)	Unified access, auto-rescale
dicomreadVolume for DICOM folder	medicalVolume (MIT)	Preserves spatial referencing
niftiread + niftiinfo	medicalVolume (MIT)	Unified container
V.Voxels(:,:,n) or V(:,:,n) for slice extraction	extractSlice(medVol, n, medVol.Orientation) (MIT)	Handles orientation, spatial metadata, works regardless of storage order
Manual permute for orientation	updateOrientation(medVol, orient) (MIT)	Updates spatial metadata
Manual struct parsing for RT	dicomContours(info)	Clean tabular output
volumeViewer	medicalVolumeViewer (MIT, R2026a)	Medical-specific features
imshow for medical images	imageshow	Better defaults for medical data

Conventions

• Always detect available toolboxes before choosing functions
• Prefer Medical Imaging Toolbox APIs (medicalVolume, medicalImage) when available
• Always capture output from immutable methods (deleteContour, updateOrientation)
• Always use CreateMode="Copy" when writing RT Structure DICOM files
• Do NOT call dicomCollection before medicalVolume/dicomreadVolume by default — call the reader directly on the folder path
• Use dicomCollection only when: the folder contains multiple series, medicalVolume fails with an error, or you need to identify what series exist without reading pixel data
• Always squeeze the output of dicomreadVolume for grayscale data
• Always use extractSlice to get slices from a medicalVolume — never use V.Voxels(:,:,n) manual indexing. extractSlice handles orientation, spatial metadata, and works correctly regardless of how the volume is stored on disk
• Never manually parse nested DICOM structs — use dicomContours
• extractSlice argument order: (vol, sliceIndex, direction) — numeric before string
• intrinsicToWorld returns 3 separate outputs: [x, y, z] — not a single vector

---

Copyright 2026 The MathWorks, Inc.

---