Matlab Read Medical Data Agent Skill

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.

----