Matlab Process Images
MathWorksOfficialCreated by MathWorks
- Skill
- Tool integration
- Software development
- BSD-2-Clause
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill serves as the primary entry point for MATLAB tasks involving images, scans, frames, and 3-D volumes. It provides core conventions for image data types, coordinate systems, and display practices, while routing users to specific references for tasks such as I/O, filtering, segmentation, and measurement. It ensures consistent use of Image Processing Toolbox functions and helps users navigate common pitfalls in image analysis workflows.
What it does
- Provides standardized conventions for image data types and coordinate systems.
- Routes users to specialized references for image I/O, filtering, and transformation tasks.
- Defines best practices for displaying images using the imageshow function.
- Offers guidance on handling 3-D volumetric data and large-scale images.
- Assists with selecting appropriate functions for segmentation and object measurement.
- Provides troubleshooting patterns for common image processing errors.
When to use it
- When performing image processing tasks in MATLAB, such as filtering, enhancing, or segmenting.
- When working with image formats like TIFF, PNG, JPEG, DICOM, or NIfTI.
- When needing to understand MATLAB-specific coordinate conventions for image data.
- When determining the correct toolbox function for a specific image analysis goal.
- When troubleshooting syntax or type-related errors in image processing scripts.
Advantages
- Ensures consistent coding patterns across different image processing tasks.
- Reduces errors by providing clear guidance on coordinate and data type conventions.
- Simplifies the selection of appropriate tools for complex workflows like 3-D volume processing.
- Promotes the use of modern display functions like imageshow over legacy alternatives.
- Provides a structured approach to identifying the correct documentation for specific functions.
Usage examples
- “How do I read a DICOM file and display it in MATLAB?”
- The agent will guide you to use the medical-data-io reference for reading the file and the imageshow function for display, following the core conventions.
- “I need to count the number of objects in a binary image.”
- The agent will provide the standard analysis pipeline using bwconncomp and regionprops, ensuring the input is correctly formatted as logical.
- “How do I perform 3-D filtering on a volume?”
- The agent will direct you to the 3-D volume processing reference to select the appropriate 3-D specific function, such as imgaussfilt3.
- “Why is my regionprops measurement returning only one object?”
- The agent will explain that the input must be a logical array and provide the code to convert your numeric array to logical.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/matlab/matlab-process-images/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip matlab-process-images.zip -d .agents/skills
Documentation by MathWorks
Image Processing
Process, analyze, and transform images using MATLAB Image Processing Toolbox (IPT). This skill routes you to the correct reference for your task and provides core conventions that apply across all IPT work.
When to Use
Loaded for general-purpose IPT work: file and batch I/O, filtering, restoration, morphology, segmentation, measurement, geometric transforms, color, texture, quality metrics, deep learning on images, and image apps. Non-medical microscopy — cell and particle counting on plain IPT — is in scope.
Hand off (and co-load) instead of answering alone: see the handoff table under ## Routing.
When NOT to Use
Training a network with no image-specific preprocessing — use Deep Learning Toolbox directly
Simulink or Stateflow video blocks — use Simulink directly
C/C++ code generation, MEX, GPU acceleration and deployment — use MATLAB Coder / GPU Coder directly
Point clouds, 3-D reconstruction, and video stabilization — use Computer Vision Toolbox directly
General MATLAB questions unrelated to images
Looking at an image yourself (e.g., "look at this screenshot") when no MATLAB work is requested — use your own vision instead
Core Conventions
Image Data Types
| Type | Range | When to use |
|---|---|---|
uint8 | 0–255 | Display, file I/O, memory-efficient storage |
uint16 | 0–65535 | High dynamic range sensors, medical. Camera RAW is n-bit in a uint16 container — rescale with rawinfo BlackLevel/WhiteLevel, not 65535 |
single / double | 0.0–1.0 | Arithmetic, filtering, computation |
logical | 0 or 1 | Binary masks, segmentation results |
Most IPT functions accept integer types directly — do not convert to floating-point unless required.
Default Coordinate Conventions
MATLAB images are (row, col) — row is Y (down), column is X (right)
size(img)returns[height, width, channels]Spatial functions use (x, y) order for coordinates (e.g.,
imref2d,regionpropscentroids)Pixel centers are at integer intrinsic coordinates; in default world referencing, pixel (1,1) center is at world (1.0, 1.0) and the image edge starts at 0.5
imref2dandimref3dcan specify non-default spatial referencing to place images into world coordinate systems. By default they use the unit-spaced, integer-pixel-centered coordinate system described here, e.g.Rout = imref2d(imageSize). Functions that do not accept spatial referencing objects assume this intrinsic coordinate system for any operation requiring spatial referencing.
Multichannel Images
Grayscale:
M×NorM×N×1RGB:
M×N×3With alpha: read using
[img, ~, alpha] = imread(...)(alpha is the third output)Convert:
rgb2gray,im2gray(preferred, handles more input types)
Display Functions — use imageshow, not imshow
Always use imageshow instead of imshow in all generated code — scripts, apps, examples, and quick previews. The signatures are compatible for common cases: replace imshow(...) with imageshow(...). imageshow (R2024b+) handles sub-bit-depth containers (e.g., 12-bit in uint16) via DisplayRangeMode, supports OverlayData for label/mask overlays, and works with viewer2d. imshow lacks all of these capabilities and should not appear in new code.
Title convention: imageshow creates a viewer2d, not an axes — gca does not return it. To add a title, get the viewer from the Image object's parent:
obj = imageshow(im);
viewer = obj.Parent;
title(viewer, "Title Text");Do not use title("text") or title(gca, "text") after imageshow — these silently fail or create a stray axes title.
Code Execution
Execute code blocks via evaluate_matlab_code before presenting them to the user. If it errors, fix and re-run. This catches type mismatches, wrong argument orders, and nonexistent functions before the user sees them. If execution requires user data or toolboxes not available in the current session, present the code with a note that it should be run with the user's own data — do not loop trying to synthesize stand-in data.
Error Recovery
If code throws an error after execution, load the matlab-read-documentation skill and look up the function's doc page to verify syntax, required arguments, and supported input types before retrying.
When to Ask the User
Ask for clarification before proceeding when:
The image type/format is ambiguous and affects the processing approach
Multiple valid approaches exist with different tradeoffs (speed vs quality, lossy vs lossless)
The task requires choosing parameters that depend on domain knowledge (e.g., object size thresholds, noise characteristics)
The user's MATLAB release is unknown and the recommended function may not be available
Routing
Match your task in the tables below. Check the handoff table first. If the task belongs to another skill, load that skill in addition to this one — the Core Conventions above (data types, coordinate order, code execution) apply to all image data. Do not re-derive them from the sibling. If a row in both tables fits, the handoff table wins on workflow; this skill still owns conventions.
Unfamiliar data? Load
references/image-understanding.mdfirst — but only when class, range, or content is unknown.Starting from a function name, not a task? The function column is illustrative, not exhaustive. To locate any function:
grep -rln '<functionName>' references/. To look up syntax details, loadmatlab-read-documentation.Pipeline tasks: load several references; cap at three unless the task genuinely spans more.
Follow the patterns in loaded references. References contain specific code patterns and workflows — use them instead of improvising equivalent code from general knowledge.
No row matches? Name the owning product, state the closest IPT fallback, and say so — do not guess a reference.
Check first: is this another skill's job?
| If the task involves... | Also load |
|---|---|
| Segmenting anatomy — tumor, lesion, organ, vessel — in CT, MRI, PET, ultrasound; MedSAM; radiomics | No skill covers this — Medical Imaging Toolbox (segmentMedicalImage, groundTruthMedical); look up the doc page |
Displaying or viewing a 2-D image: imshow, imageshow, viewer2d, montage, mask overlay, annotation, colorbar, colormap, figure export | matlab-display-image |
Displaying a 3-D volume: volshow, viewer3d, isosurface rendering, slice viewer, orthogonal views | matlab-display-volume |
| Hyperspectral or multispectral cubes, spectral indices, unmixing, ENVI, band selection | matlab-analyze-spectral-images |
| Calling a PyTorch or ONNX vision model from MATLAB | matlab-integrate-pytorch-vision |
| OCR, text recognition, reading text out of an image | matlab-recognize-text (requires Computer Vision Toolbox) |
| Factory-floor visual inspection: anomaly detection, defect/scratch/dent detection, gauging, pass/fail counting | matlab-use-visual-inspection (requires Visual Inspection Toolbox, R2026b+) |
| Barcode or QR reading, camera calibration | No skill covers this — Computer Vision Toolbox (readBarcode, estimateCameraParameters); look up the doc page |
| Optical system design: lens import, prescription-side MTF, spot diagrams, ray tracing, tolerance analysis | matlab-model-optics |
In scope: pick the reference
| If the task or the user's words involve... | Illustrative functions | Load |
|---|---|---|
| inspect, understand, characterize, explore data, look at my images, what kind of image, what am I working with, what's in this folder, describe the data, summarize the dataset, what format, bit depth, class and range, indexed image, alpha channel, metadata, file info, dataset characterization, before I start processing | imfinfo, imhist, countEachLabel | references/image-understanding.md |
| read, write, load, save, import, export, open an image, convert format, batch, folder of images, TIFF, PNG, JPEG, RAW, HDR, test pattern | imread, imwrite, imageDatastore, hdrread | references/image-io.md |
| video, footage, frames, read video, write video, VideoReader, VideoWriter, frame rate, video codec, MP4, AVI | VideoReader, VideoWriter, readFrame, hasFrame, writeVideo | references/video-io.md |
| smooth, blur an image, sharpen, denoise, noise, grainy, filter, kernel, padding, edge-preserving, bilateral, non-local means, frequency filter | imgaussfilt, medfilt2, imsharpen, imbilatfilt, imnlmfilt, imdiffusefilt, imfilter, ordfilt2, locallapfilt, wiener2 | references/filtering.md |
| contrast, brighten, darken, too dark, washed out, enhance, improve, histogram, equalize, CLAHE, normalize, rescale, blend, arithmetic, type convert, flat-field, illumination correction, vignetting, uneven lighting | imadjust, stretchlim, adapthisteq, histeq, rescale, mat2gray, im2single, imadd, imlincomb, imblend, imflatfield | references/preprocessing.md |
| erode, dilate, open, close, structuring element, 2-D morphology, fill holes, remove small objects, skeletonize, thin, tidy up a binary result | strel, imerode, imdilate, imopen, imclose, imfill, bwareaopen, bwskel, imtophat, imreconstruct | references/morphological-ops.md |
| deblur, blurry, unfocused, out of focus, motion blur, camera shake, restore a blurred image, deconvolution, PSF estimation | deconvblind, deconvlucy, deconvwnr, deconvreg | references/deblurring.md |
| resize, rotate, crop, warp, scale, flip, straighten, affine, projective, perspective, undistort, lens distortion, spatial referencing, world coordinates, voxel coordinates, pixel coordinates, coordinate conversion | imresize, imrotate, imcrop, imwarp, imtranslate, affinetform2d, imref2d | references/geometric-transforms.md |
| align two images, stitch, mosaic, panorama, overlapping shots, seam, motion correction, multi-modal alignment, control points, non-rigid, deformable, homography (feature-based requires Computer Vision Toolbox) | imregister, imregtform, imregdemons, imregcorr, detectSIFTFeatures, matchFeatures, estgeotform2d (last three: Computer Vision Toolbox), imregdeform (Medical Imaging Toolbox) | references/registration.md |
segment or threshold with no user input: binarize, Otsu, watershed, k-means or colour clustering, imsegsam automatic mode, deep-learning segmentation | imbinarize, graythresh, multithresh, adaptthresh, watershed, imsegkmeans, imsegkmeans3, imsegisodata, imsegsam | references/segmentation-automated.md |
| segment with user input: clicks, points, boxes, scribbles, seeds, prompted SAM, grabcut, active contours, region growing, lazy snapping, superpixels, App Designer segmentation UIs | segmentAnythingModel, grabcut, activecontour, lazysnapping, imsegfmm, grayconnected, superpixels | references/segmentation-interactive.md |
| measure, count objects, how many, area, perimeter, centroid, size, shape, width, thickness, gap, diameter, Feret, orientation, detect edges, circles, lines, boundary tracing, ROI, world units, metrology, region, region properties, analysis | regionprops, bwconncomp, bwareafilt, bwpropfilt, bwlabel, edge, imfindcircles, hough, bwboundaries | references/analysis-measurement.md |
| quality, PSNR, SSIM, sharpness, noise level, is it blurry, compare two images, difference, before/after, MTF (camera/chart SFR), test chart, artifact (register first — full-reference metrics need pixel correspondence) | psnr, ssim, multissim, immse, brisque, niqe, piqe, measureSharpness, esfrChart | references/quality-assessment.md |
| texture, repetitive pattern, frequency domain, Fourier, FFT, DCT, Radon, Gabor, co-occurrence, GLCM | graycomatrix, graycoprops, entropyfilt, fft2, dct2, radon, gabor | references/texture-transforms.md |
| color space, LAB, HSV, hue, saturation, white balance, color cast, color correction, color balance, ICC profile, grayscale conversion | rgb2lab, lab2rgb, rgb2hsv, chromadapt, illumwhite, makecform, deltaE, decorrstretch | references/color-processing.md |
| 3-D array, volume, volumetric, voxel, slice stack, z-stack — filtering, 3-D morphology, 3-D transforms, or measurement applied to a volume | imgaussfilt3, medfilt3, imresize3, regionprops3, bwvolumefilt (R2026b), bwpropfilt3 (R2026b) | references/3d-volume-processing.md |
| deep learning, neural network, train, U-Net, semantic segmentation networks, classify images, pretrained model, transfer learning, fine-tune, inference, augment, training dataset (requires DLT, often CVT) | unet, deeplabv3plus, trainnet, semanticseg, imageDataAugmenter, augmentedImageDatastore | references/deep-learning-imaging.md |
| build your own image app or GUI: sliders, live preview, parameter tuning, ROI widgets | uifigure, uigridlayout, uislider, drawrectangle | references/app-building.md |
DICOM, NIfTI, NRRD, DICOM-RT, patient metadata, anonymizing, medicalVolume, medicalImage, reading/writing medical formats, extractSlice, volume orientation, medical spatial referencing | medicalVolume, medicalImage, dicomreadVolume, dicomCollection, extractSlice, dicomContours, dicomanon | references/medical-data-io.md |
gigapixel, whole-slide, out-of-memory images, blockedImage, tiled workflows, image pyramids, .svs, .ndpi, .czi, TIFF > 10,000 px, parallel image processing, custom adapters | blockedImage, apply, getBlock, getRegion, selectBlockLocations, blockedImageDatastore | references/large-image-processing.md |
Toolbox Detection
When unsure what's available, check installed toolboxes:
hasIPT = ~isempty(ver('images'));
hasCVT = ~isempty(ver('vision'));
hasDLT = ~isempty(ver('nnet'));
hasMIT = ~isempty(ver('medical'));
hasWavelet = ~isempty(ver('wavelet'));Most functions in this skill require Image Processing Toolbox. The deep-learning-imaging reference also requires Deep Learning Toolbox. Feature-based registration (detectSIFTFeatures, matchFeatures, estgeotform2d) requires Computer Vision Toolbox.
Release-Gated Features
This skill targets R2024b+ but some features require newer releases. References annotate these with the required release. Key ones:
R2024b:
imageshow,imblend,viewer2dR2026a:
uidraw,uipaint,linkviewersR2026b:
bwvolumefilt,bwpropfilt3,uiannotate
If targeting an older release, check with isMATLABReleaseOlderThan("R2026a") and use the fallback patterns documented in the references. To check release notes for a specific function, load matlab-read-documentation.
Copyright 2026 The MathWorks, Inc.
Files
- ATTRIBUTION.mdAdded by AutoGineer1.1 KiB
- LICENSELicence file added by AutoGineer1.4 KiB
- SKILL.md15.8 KiB
- manifest.yaml811 B
- references/3d-volume-processing.md20.2 KiB
- references/analysis-measurement.md18.5 KiB
- references/app-building.md16.9 KiB
- references/blocked-3d-volumes.md9.9 KiB
- references/blocked-data-discovery.md22.1 KiB
- references/blocked-geospatial.md3.2 KiB
- references/blocked-specialized-workflows.md4.3 KiB
- references/blocked-training-and-labeling.md7.0 KiB
- references/blocked-visualization.md5.1 KiB
- references/blocked-whole-slide-images.md3.1 KiB
- references/color-processing.md9.0 KiB
- references/deblurring.md8.1 KiB
- references/deep-learning-imaging.md14.8 KiB
- references/dicom-anonymization.md3.3 KiB
- references/dicom-rt-workflows.md7.4 KiB
- references/filtering.md21.8 KiB
- references/geometric-transforms.md14.3 KiB
- references/image-io.md15.5 KiB
- references/image-understanding.md20.0 KiB
- references/ipt-reading-writing.md4.8 KiB
- references/large-image-processing.md12.3 KiB
- references/medical-data-io.md8.3 KiB
- references/mit-medical-volume.md8.2 KiB
- references/mit-spatial-referencing.md5.9 KiB
- references/morphological-ops.md18.0 KiB
- references/preprocessing.md14.4 KiB
- references/quality-assessment.md13.5 KiB
- references/registration.md24.7 KiB
- references/segmentation-automated.md9.7 KiB
- references/segmentation-interactive.md15.3 KiB
- references/texture-transforms.md10.4 KiB
- references/video-io.md3.4 KiB
references/registration.md
Image Registration
Register and align 2-D images and 3-D volumes using intensity-based, deformable, groupwise, and surface-based methods.
Often loaded with:
geometric-transforms.md(applying transforms viaimwarp),image-io.md(loading image pairs),quality-assessment.md(scoring a pair only after it is aligned).
When NOT to Use This Reference
Point cloud registration for non-medical data → use Computer Vision Toolbox (
pcregistericp)
Strategy Selection
| Scenario | Function | Toolbox | Speed |
|---|---|---|---|
| Feature-based (panorama, mosaic, large viewpoint change) | detectSIFTFeatures + estgeotform2d | CVT | Fast |
| Rigid/affine, same modality | imregister or imregtform + imwarp | IPT | Moderate |
| Rigid/affine, different modalities | imregtform with "multimodal" config | IPT | Moderate |
| Control-point (landmarks, fiducials) | cpselect + fitgeotform2d / fitgeotform3d (R2024a+) | IPT | Fast |
| Quick translation/rotation estimate | imregcorr | IPT | Fast |
| Fast similarity alignment (moment-based) | imregmoment | MIT | Very fast |
| Deformable (demons algorithm) | imregdemons | IPT | Slow |
| Deformable (total variation) | imregdeform | MIT | Moderate |
| Groupwise slice-to-slice | imreggroupwise | MIT | Moderate |
| Surface-based (ICP) | extractIsosurface + imregicp | MIT | Moderate |
IPT = Image Processing Toolbox, CVT = Computer Vision Toolbox, MIT = Medical Imaging Toolbox.
When Medical Imaging Toolbox is available, prefer the MIT functions — they are faster (imregmoment), more robust (imregdeform), or handle workflows that IPT doesn't cover (imreggroupwise, surface-based).
Feature-Based Registration (Computer Vision Toolbox)
Requires: Computer Vision Toolbox
Workflow: Detect → Extract → Match → Estimate Transform
% 1. Detect features in both images
pointsFixed = detectSIFTFeatures(im2gray(fixed));
pointsMoving = detectSIFTFeatures(im2gray(moving));
% 2. Extract descriptors
[featuresFixed, validPtsFixed] = extractFeatures(im2gray(fixed), pointsFixed);
[featuresMoving, validPtsMoving] = extractFeatures(im2gray(moving), pointsMoving);
% 3. Match descriptors
indexPairs = matchFeatures(featuresFixed, featuresMoving);
matchedFixed = validPtsFixed(indexPairs(:,1));
matchedMoving = validPtsMoving(indexPairs(:,2));
% 4. Estimate geometric transform with RANSAC
tform = estgeotform2d(matchedMoving, matchedFixed, "projective");
% 5. Apply transform
registered = imwarp(moving, tform, OutputView=imref2d(size(fixed)));Detector Selection
| Function | Type | Scale-Invariant | Rotation-Invariant | Best for |
|---|---|---|---|---|
detectSIFTFeatures | Blob | Yes | Yes | General purpose, most robust |
detectSURFFeatures | Blob | Yes | Yes | Faster than SIFT, good default |
detectKAZEFeatures | Blob | Yes | Yes | Non-linear scale space, sharper boundaries |
detectBRISKFeatures | Corner | Yes | Yes | Fast binary descriptor |
detectORBFeatures | Corner | Yes | Yes | Fastest, binary descriptor |
detectMSERFeatures | Region | Yes | Yes | Uniform-intensity regions, text |
detectHarrisFeatures | Corner | No | No | Simple corners, known scale |
detectMinEigenFeatures | Corner | No | No | Shi-Tomasi corners |
detectFASTFeatures | Corner | No | No | Real-time corner detection |
Decision guide:
Default choice →
detectSIFTFeatures(most reliable across conditions)Need speed →
detectSURFFeaturesordetectORBFeaturesKnown scale (no zoom change) →
detectHarrisFeaturesordetectFASTFeaturesText / uniform regions →
detectMSERFeatures
Descriptor Extraction
extractFeatures selects the descriptor method automatically based on the point type, or you can specify explicitly:
| Method | Binary | Descriptor Size | Best paired with |
|---|---|---|---|
"SIFT" | No | 128 floats | detectSIFTFeatures |
"SURF" | No | 64 floats | detectSURFFeatures |
"KAZE" | No | 64 floats | detectKAZEFeatures |
"FREAK" | Yes | 64 bytes | Any point type |
"BRISK" | Yes | 64 bytes | detectBRISKFeatures |
"ORB" | Yes | 32 bytes | detectORBFeatures |
"Block" | No | Variable | Simple patch comparison |
Binary descriptors use Hamming distance in matchFeatures (selected automatically).
Transform Estimation
| Function | Use case |
|---|---|
estgeotform2d | 2-D: similarity, affine, or projective (with RANSAC) |
estgeotform3d | 3-D point correspondences |
estimateFundamentalMatrix | Epipolar geometry between views |
% Similarity (4 DOF): translation + rotation + uniform scale
tform = estgeotform2d(matchedMoving, matchedFixed, "similarity");
% Affine (6 DOF): adds shear and non-uniform scale
tform = estgeotform2d(matchedMoving, matchedFixed, "affine");
% Projective (8 DOF): full perspective (homography)
tform = estgeotform2d(matchedMoving, matchedFixed, "projective");Panorama Stitching Pattern
% Stitch multiple images into a panorama
I1 = imread("scene1.jpg");
I2 = imread("scene2.jpg");
% Detect and match (SURF is fast enough for panoramas)
pts1 = detectSURFFeatures(im2gray(I1));
pts2 = detectSURFFeatures(im2gray(I2));
[f1, vp1] = extractFeatures(im2gray(I1), pts1);
[f2, vp2] = extractFeatures(im2gray(I2), pts2);
pairs = matchFeatures(f1, f2);
% Estimate projective transform
tform = estgeotform2d(vp2(pairs(:,2)), vp1(pairs(:,1)), "projective");
% Compute output limits by transforming image corners
[xlimOut, ylimOut] = outputLimits(tform, [1 size(I2,2)], [1 size(I2,1)]);
xMin = min(1, xlimOut(1));
xMax = max(size(I1,2), xlimOut(2));
yMin = min(1, ylimOut(1));
yMax = max(size(I1,1), ylimOut(2));
% Create output canvas and warp
outputRef = imref2d([ceil(yMax-yMin) ceil(xMax-xMin)], [xMin xMax], [yMin yMax]);
warped = imwarp(I2, tform, OutputView=outputRef);When to Use Feature-Based vs Intensity-Based
| Criterion | Feature-based | Intensity-based (imregtform) |
|---|---|---|
| Large displacement / viewpoint change | Preferred | May not converge |
| Moving is subimage/crop of fixed | Preferred | Fails (metric dominated by non-overlap) |
| No texture (uniform regions) | Fails | Preferred |
| Different modalities (CT vs MRI) | Fails | Use multimodal metric |
| Speed for many image pairs | Fast | Slow (iterative) |
| Sub-pixel accuracy | Moderate | High |
| 3-D volumes | Limited | Full support |
| Panorama / mosaic | Preferred | Not suitable |
Subimage matching: When the moving image is a crop of the fixed image, MeanSquares fails because non-overlapping pixels dominate the metric. Use feature-based registration (SURF or MSER work well for this). If you must use intensity-based, switch to MattesMutualInformation + OnePlusOneEvolutionary — these are more robust to partial overlap than the default monomodal config.
Critical: Spatial Referencing
Always provide spatial referencing when data is anisotropic or volumes have different voxel spacings. Without imref2d/imref3d, registration assumes unit spacing (1×1×1). This is fine for isotropic same-resolution pairs (e.g., 2-D camera images, volumes with identical spacing), but silently produces wrong results when voxels are non-cubic or images differ in resolution.
Building imref3d — Dimension Order Gotcha
Get voxel spacing from relevant file metadata when available. imref3d expects (imageSize, xSpacing, ySpacing, zSpacing) where x = columns, y = rows, z = slices — this differs from the row-major order most metadata provides:
% NIfTI: PixelDimensions is [rowSpacing colSpacing sliceSpacing]
info = niftiinfo(niftiFile);
ref = imref3d(info.ImageSize, ...
info.PixelDimensions(2), ... % x = col spacing
info.PixelDimensions(1), ... % y = row spacing
info.PixelDimensions(3)); % z = slice spacing
% DICOM: PixelSpacing is [rowSpacing colSpacing], SliceThickness is scalar
info = dicominfo(dicomFile);
ref = imref3d(imageSize, ...
info.PixelSpacing(2), ... % x = col spacing
info.PixelSpacing(1), ... % y = row spacing
info.SliceThickness); % z = slice spacingGetting the order wrong silently produces misaligned registrations.
Intensity-Based Registration (IPT)
Configuration
% Same modality (MRI-to-MRI, CT-to-CT)
[optimizer, metric] = imregconfig("monomodal");
% optimizer: RegularStepGradientDescent, metric: MeanSquares
% Different modalities (CT-to-MRI, PET-to-CT)
[optimizer, metric] = imregconfig("multimodal");
% optimizer: OnePlusOneEvolutionary, metric: MattesMutualInformationTransform Type Selection
| Transform | DOF (2-D / 3-D) | Use when |
|---|---|---|
"translation" | 2 / 3 | Only shift, no rotation |
"rigid" | 3 / 6 | Same-patient, no deformation (most common) |
"similarity" | 4 / 7 | Need uniform scale change |
"affine" | 6 / 12 | Need shear and non-uniform scale |
Grayscale requirement: imregtform and imregister accept only single-channel (grayscale) images. For RGB input, convert first with im2gray(img). For multi-channel volumes, extract the channel of interest before registering.
Full Workflow
% 1. Read data
fixedData = niftiread(fixedFile);
fixedInfo = niftiinfo(fixedFile);
movingData = niftiread(movingFile);
movingInfo = niftiinfo(movingFile);
% 2. Build spatial referencing
fixedRef = imref3d(size(fixedData), ...
fixedInfo.PixelDimensions(2), ... % x = col spacing
fixedInfo.PixelDimensions(1), ... % y = row spacing
fixedInfo.PixelDimensions(3)); % z = slice spacing
movingRef = imref3d(size(movingData), ...
movingInfo.PixelDimensions(2), ...
movingInfo.PixelDimensions(1), ...
movingInfo.PixelDimensions(3));
% 3. Configure optimizer
[optimizer, metric] = imregconfig("monomodal");
% 4. Compute transform
tform = imregtform(movingData, movingRef, fixedData, fixedRef, "rigid", optimizer, metric);
% 5. Apply transform
registered = imwarp(movingData, movingRef, tform, OutputView=fixedRef);Gotcha: imregister returns the resampled image directly but does NOT give you the transform. Use imregtform + imwarp when you need the transform (e.g., to apply to other volumes or to chain transforms).
Optimizer Tuning
Multimodal registration often needs tuning:
[optimizer, metric] = imregconfig("multimodal");
optimizer.InitialRadius = 0.001; % Decrease for more precise search
optimizer.MaximumIterations = 200; % Increase for convergenceRegularStepGradientDescent (monomodal):
| Parameter | Default | Effect | Adjust when |
|---|---|---|---|
MaximumIterations | 100 | More iterations for convergence | Increase to 200–300 for large deformations |
MaximumStepLength | 0.0625 | Step size per iteration | Decrease for fine alignment |
MinimumStepLength | 1e-5 | Convergence threshold | Default usually fine |
OnePlusOneEvolutionary (multimodal):
| Parameter | Default | Effect | Adjust when |
|---|---|---|---|
MaximumIterations | 100 | More iterations for convergence | Increase to 200–300 for large deformations |
InitialRadius | 0.00625 | Initial search radius | Decrease to 0.001 for finer search |
GrowthFactor | 1.05 | Search radius growth rate | Default usually fine |
imregtform Name-Value Arguments
| Parameter | Default | Purpose |
|---|---|---|
PyramidLevels | 3 | Number of multi-resolution levels — increase for large misalignments |
InitialTransformation | identity | Seed transform for refinement (hierarchical registration) |
DisplayOptimization | false | Print iteration info — useful for debugging convergence |
Hierarchical Registration (Coarse-to-Fine)
When imregtform fails to converge, use a simpler transform as a starting point for a more complex one:
[optimizer, metric] = imregconfig("multimodal");
optimizer.InitialRadius = 0.001;
optimizer.MaximumIterations = 300;
% Step 1: Estimate similarity (4 DOF — more likely to converge)
tformSimilarity = imregtform(moving, movingRef, fixed, fixedRef, ...
"similarity", optimizer, metric);
% Step 2: Refine with affine using similarity result as seed
tformAffine = imregtform(moving, movingRef, fixed, fixedRef, ...
"affine", optimizer, metric, ...
InitialTransformation=tformSimilarity);
registered = imwarp(moving, movingRef, tformAffine, OutputView=fixedRef);This pattern resolves most convergence failures — the simpler model captures gross alignment, then the complex model refines local distortions.
Correlation-Based — imregcorr
Fastest method for 2-D translation/rotation estimation. No optimizer tuning needed:
tform = imregcorr(moving, fixed, "rigid");
registered = imwarp(moving, tform, OutputView=imref2d(size(fixed)));R2024b: gradient correlation is the default — more accurate, more robust to noise, and more consistent than phase correlation. Do NOT specify Method="phasecorr" unless reproducing legacy results. Always use the default "gradcorr".
Limitations: 2-D only. No affine. Unreliable on images with repetitive patterns (correlation peak is ambiguous). Best as a fast initial estimate for refinement with imregtform.
Control-Point Registration
Use when you have known corresponding landmarks — manually selected points, fiducial markers, or matched keypoints without RANSAC.
Interactive Selection with cpselect
% Launch interactive tool for manual point selection
cpselect(moving, fixed);
% After selecting points and exporting, variables movingPoints and fixedPoints
% are created in the workspace (File > Export Points to Workspace)Compute Transform from Point Pairs
% fitgeotform2d — modern API (R2022b+)
tform = fitgeotform2d(movingPoints, fixedPoints, "affine");
registered = imwarp(moving, tform, OutputView=imref2d(size(fixed)));
% Transform types: "similarity", "affine", "projective"
% Minimum points: similarity=2, affine=3, projective=4fitgeotform2d vs estgeotform2d: fitgeotform2d fits all points (least-squares, no outlier rejection). estgeotform2d uses RANSAC to reject outliers — use it when matches may contain incorrect pairs (e.g., from matchFeatures). Use fitgeotform2d when all correspondences are known-good (manual selection, fiducials).
Non-Rigid: Local Weighted Mean
For local deformations that a single global transform cannot capture:
tform = fitgeotform2d(movingPoints, fixedPoints, "lwm", 12);
% 12 = number of points per local neighborhood
registered = imwarp(moving, tform, OutputView=imref2d(size(fixed)));Deformable Registration — imregdemons (IPT)
For non-rigid deformations (breathing motion, tissue deformation):
% Convert to double and match histogram for better convergence
fixedD = double(fixedData);
movingD = double(movingData);
% Multi-resolution pyramid: [coarsest ... finest] iterations
[D, registered] = imregdemons(movingD, fixedD, [500 400 200], ...
AccumulatedFieldSmoothing=1.3);
% D is M×N×P×ndim displacement field (2 for 2-D, 3 for 3-D)| Parameter | Effect | Typical value |
|---|---|---|
Iteration vector [500 400 200] | Multi-resolution levels, coarse to fine | 3 levels, more iterations at coarse |
AccumulatedFieldSmoothing | Regularization (higher = smoother) | 1.0–2.0 (default 1.0) |
Gotcha — iteration vector length: The length of the iteration vector must equal the number of pyramid levels (default 3). Using [500 400] (2 elements) with default 3 levels will error.
Medical Imaging Toolbox Functions
imregmoment — Fast Moment-Based Similarity Alignment
Computes a similarity transform (rotation + uniform scale + translation) using image moments. 20–30× faster than iterative imregtform.
When to use: First-pass alignment, fast similarity registration, or when imregtform is too slow.
% Preferred: with spatial referencing (handles different voxel spacings correctly)
fixedRef = imref3d(size(fixedData), fixedSpacing(2), fixedSpacing(1), fixedSpacing(3));
movingRef = imref3d(size(movingData), movingSpacing(2), movingSpacing(1), movingSpacing(3));
[tform, registered] = imregmoment(movingData, movingRef, fixedData, fixedRef);
% Without spatial referencing (only when volumes share identical voxel spacing)
[tform, registered] = imregmoment(movingData, fixedData);Output: affinetform3d (3-D) or affinetform2d (2-D) + registered result.
Name-value pairs:
MedianThresholdBitmap(logical, defaultfalse) — set totruefor multimodal registration or when images have different intensity levels (different sensors). Uses median-based thresholding for moment computation.
Limitations: Works best for roughly aligned volumes. For large misalignments, use as initialization then refine with imregtform. Always pass spatial referencing when volumes have different voxel spacings — without it, imregmoment assumes uniform unit spacing.
imregdeform — Total Variation Deformable
% Basic usage (defaults)
[D, registered] = imregdeform(movingData, fixedData);
% With tuning parameters
[D, registered] = imregdeform(movingData, fixedData, ...
GridSpacing=[4 4 4], ...
PixelResolution=voxelSpacing, ...
NumPyramidLevels=3, ...
GridRegularization=0.11, ...
DisplayProgress=false);Output: Displacement field D (MxNxPx3 for 3-D, MxNx2 for 2-D) + registered image/volume.
| Parameter | Default | Purpose |
|---|---|---|
GridSpacing | [4 4] (2-D), [4 4 4] (3-D) | Control point spacing — smaller = more flexible |
PixelResolution | [1 1] or [1 1 1] | Physical voxel spacing in mm — order is [row col slice], not [x y z] |
NumPyramidLevels | 3 | Multi-resolution levels — more = better large-motion handling |
GridRegularization | 0.11 | Smoothness constraint — higher = smoother deformation |
DisplayProgress | true | Show iteration progress |
vs imregdemons: Uses total variation regularization (better edge preservation), while imregdemons uses Gaussian smoothing. Prefer imregdeform when available.
imreggroupwise — Groupwise Slice Registration
Registers all slices in a series simultaneously to reduce inter-slice motion. Single function call replaces manual iterative loops.
When to use: Correcting breathing motion between slices, inter-slice misalignment in a volume acquired slice-by-slice.
% Basic usage (defaults)
[D, registered] = imreggroupwise(sliceStack);
% With tuning parameters
[D, registered] = imreggroupwise(sliceStack, ...
GridSpacing=[4 4], ...
PixelResolution=[rowRes colRes], ...
NumPyramidLevels=3, ...
DisplayProgress=false);Output: 4-D displacement field + registered 3-D slice series.
Why not per-slice imregdemons: Groupwise registration finds a consensus alignment across all slices simultaneously, avoiding bias toward any single reference. Manual per-slice loops produce inferior results and destroy anatomy.
Performance: 512×512×20 stack completes in under 60 seconds; 512×512×167 may take 20+ minutes. For large stacks, reduce NumPyramidLevels to 2 or increase GridSpacing to [8 8].
Surface-Based Registration — extractIsosurface + imregicp
% 1. Extract isosurfaces from volumes
[~, fixedVerts] = extractIsosurface(fixedData, isovalue);
[~, movingVerts] = extractIsosurface(movingData, isovalue);
% 2. Scale vertices to physical coordinates
fixedVerts = fixedVerts .* voxelSpacing;
movingVerts = movingVerts .* voxelSpacing;
% 3. Align using ICP
[regSurface, tform, rmse] = imregicp(movingVerts, fixedVerts, ...
Metric="pointToPlane", DistanceThreshold=50, MaxIterations=50);DistanceThreshold scaling — critical: The default (0.1) assumes small-scale coordinates. For medical volumes in mm (typically spanning 100–500 mm), set DistanceThreshold to 10–50 to ensure enough inlier correspondences. Too small a threshold produces near-zero fitness and an identity transform.
Do NOT confuse with pcregistericp from Computer Vision Toolbox — use imregicp for medical image surface registration.
Complete Example: Rigid + Deformable Pipeline
% Read volumes
fixedVol = medicalVolume("/path/to/fixed/dicom");
movingVol = medicalVolume("/path/to/moving/dicom");
% Build spatial referencing
fixedRef = imref3d(size(fixedVol.Voxels), ...
fixedVol.VoxelSpacing(2), fixedVol.VoxelSpacing(1), fixedVol.VoxelSpacing(3));
movingRef = imref3d(size(movingVol.Voxels), ...
movingVol.VoxelSpacing(2), movingVol.VoxelSpacing(1), movingVol.VoxelSpacing(3));
% Fast rigid alignment first
[tformRigid, rigidResult] = imregmoment( ...
double(movingVol.Voxels), movingRef, ...
double(fixedVol.Voxels), fixedRef);
% Deformable refinement if needed
[D, deformResult] = imregdeform(double(rigidResult), double(fixedVol.Voxels), ...
PixelResolution=fixedVol.VoxelSpacing, ...
DisplayProgress=false);
% Evaluate
midSlice = round(size(fixedVol.Voxels, 3) / 2);
imshowpair(fixedVol.Voxels(:,:,midSlice), deformResult(:,:,midSlice), "falsecolor");
title("Registration Result");Evaluating Registration Quality
Programmatic Composite — imfuse
imfuse creates a composite image for saving or further processing (unlike imshowpair which only displays):
C = imfuse(fixed, registered, "falsecolor"); % Default: overlay in different color bands
C = imfuse(fixed, registered, "blend"); % Alpha blending
C = imfuse(fixed, registered, "diff"); % Difference image
C = imfuse(fixed, registered, "checkerboard"); % Alternating rectangular regions
% With spatial referencing (for images of different sizes/resolutions)
[C, RC] = imfuse(fixed, fixedRef, moving, movingRef, "falsecolor");Methods: "falsecolor" (default), "blend", "checkerboard", "diff", "montage".
Visual and Quantitative Checks
% Visual: falsecolor overlay
midSlice = round(size(fixedData, 3) / 2);
imshowpair(fixedData(:,:,midSlice), registered(:,:,midSlice), "falsecolor");
% Quantitative: SSIM (structural similarity)
% IMPORTANT: use im2double (not double) — see quality-assessment.md for details
ssimBefore = ssim(im2double(movingData(:,:,midSlice)), im2double(fixedData(:,:,midSlice)));
ssimAfter = ssim(im2double(registered(:,:,midSlice)), im2double(fixedData(:,:,midSlice)));
fprintf("SSIM: %.4f (before) -> %.4f (after)\n", ssimBefore, ssimAfter);Interpreting the Recovered Transform
Use the transform object's properties — do not read .A columns directly:
angle = tform.RotationAngle; % Degrees (2-D rigid/similarity)
t = tform.Translation; % [tx ty] translation in world unitsOrigin vs. centre:
.Translationis the translation about the origin(0,0), not the image centre. For a rotation about a pointc, the effective translation atcist_c = t + R*c - c. If you need the displacement at the image centre, compute it explicitly.
Common Mistakes
| Mistake | Why it's wrong | Correct approach |
|---|---|---|
Hallucinating registerVolumes | Does not exist | Use imregtform/imregister (IPT) or imregmoment (MIT) |
| Registering anisotropic data without spatial referencing | Assumes unit spacing, wrong when voxels are non-cubic or resolutions differ | Build imref3d/imref2d from voxel dimensions |
imref3d(size, rowSpacing, colSpacing, sliceSpacing) | Constructor takes (size, xSpacing, ySpacing, zSpacing) — x=cols, y=rows | Swap: imref3d(sz, colSpacing, rowSpacing, sliceSpacing) |
Using "monomodal" for CT-to-MRI | Mean squares metric fails across modalities | Use "multimodal" (mutual information) |
imregister when transform is needed | Returns only the resampled image, not the transform | Use imregtform + imwarp |
Per-slice imregdemons loop for motion correction | Over-registers, destroys anatomy | Use imreggroupwise (MIT) |
Using pcregistericp for medical surfaces | Wrong toolbox, different interface | Use extractIsosurface + imregicp from MIT |
No OutputView in imwarp | Output may be cropped or wrong size | Always: imwarp(..., OutputView=fixedRef) |
Default DistanceThreshold for ICP on medical data | 0.1 is too small for mm-scale coordinates | Set to 10–50 for medical volumes |
| Rigid-then-deformable for small deformations | Unnecessary, wastes time | Use imregdemons or imregdeform directly |
Using estimateGeometricTransform2D | Not recommended (deprecated) | Use estgeotform2d |
| Feature-based on textureless/multimodal images | No features to match | Use intensity-based imregtform instead |
Copyright 2026 The MathWorks, Inc.
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- MathWorks
- Publisher
- MathWorks (Official)
- Source
- matlab/matlab-agentic-toolkit · skills-catalog/image-processing-and-computer-vision/matlab-process-images · commit 2a7f215
- Licence
- BSD 2-Clause License (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE.md)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by MathWorks or MathWorks.
Related skills
Implement
Matt Pocock· Community
A structured workflow for implementing software tasks from specifications or tickets.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository317.5k
Source Driven Development
Addy Osmani· Community
A rigorous process for grounding code implementation in official, version-specific documentation to ensure accuracy and avoid outdated patterns.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository113.9k
Write Swift
Emil Kowalski· Community
A comprehensive guide to writing modern, safe, and performant Swift code following the language's latest idioms and concurrency models.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Cardputer Buddy
AnthropicOfficial
Iterate on the Cardputer-Adv MicroPython app bundle (Claude Buddy, Snake, Hello) after the device is already provisioned via m5-onboard. Use when the user wants to add a new app, push a single changed .py without re-flashing, watch device serial logs, or run a one-shot REPL command. Trigger on "add an app", "push to the cardputer", "tail the device", "run on the device", or follow-up work after /maker-setup.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreApache-2.0GitHub stars of the source repository46.3k
Typescript Pro
Seth Hobson· Community
An expert TypeScript persona focused on advanced typing, enterprise architecture, and strict type safety.
Software developmentClaude CodeMITGitHub stars of the source repository42.3k
Scala Pro
Seth Hobson· Community
An expert Scala engineer persona specializing in functional programming, distributed systems, and enterprise-grade architecture.
Software developmentClaude CodeMITGitHub stars of the source repository42.3k
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download matlab-process-images.zip