Generated banner for Matlab Process Images
Generated logo for Matlab Process Images

Matlab Process Images

MathWorksOfficialCreated by MathWorks

  • Skill
  • Tool integration
  • Software development
  • BSD-2-Clause
  • No issues found

From the author

Load this first for any MATLAB task involving images, photos, scans, frames, volumes, or visual data — reading, writing, filtering, enhancing, denoising, sharpening, deblurring, thresholding, segmenting, masking, detecting, counting objects, removing backgrounds, measuring, registering, stitching, aligning, cropping, resizing, or transforming. Covers image I/O (TIFF, PNG, JPEG, RAW, HDR), histograms, edge detection, color, morphology, deep learning for images, quality assessment, and 3-D volumes. Also for image problems (dark, noisy, blurry, low contrast, uneven lighting, hazy, color cast) or data exploration (folder of images). Includes medical imaging I/O (DICOM, NIfTI, NRRD, medicalVolume) and large/blocked images (blockedImage, whole-slide). Skip if the user just wants you to look at an image, with no MATLAB work. Not for Simulink video-block models, C/C++/CUDA code generation or GPU deployment of a network, or point clouds. Hyperspectral and visual inspection have sibling skills.
— the description by MathWorks

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/matlab/matlab-process-images/download
  2. Unzip 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
TypeRangeWhen to use
uint80–255Display, file I/O, memory-efficient storage
uint160–65535High dynamic range sensors, medical. Camera RAW is n-bit in a uint16 container — rescale with rawinfo BlackLevel/WhiteLevel, not 65535
single / double0.0–1.0Arithmetic, filtering, computation
logical0 or 1Binary 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, regionprops centroids)

  • 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

  • imref2d and imref3d can 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×N or M×N×1

  • RGB: M×N×3

  • With 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.md first — 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, load matlab-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; radiomicsNo 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 exportmatlab-display-image
Displaying a 3-D volume: volshow, viewer3d, isosurface rendering, slice viewer, orthogonal viewsmatlab-display-volume
Hyperspectral or multispectral cubes, spectral indices, unmixing, ENVI, band selectionmatlab-analyze-spectral-images
Calling a PyTorch or ONNX vision model from MATLABmatlab-integrate-pytorch-vision
OCR, text recognition, reading text out of an imagematlab-recognize-text (requires Computer Vision Toolbox)
Factory-floor visual inspection: anomaly detection, defect/scratch/dent detection, gauging, pass/fail countingmatlab-use-visual-inspection (requires Visual Inspection Toolbox, R2026b+)
Barcode or QR reading, camera calibrationNo 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 analysismatlab-model-optics
In scope: pick the reference
If the task or the user's words involve...Illustrative functionsLoad
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 processingimfinfo, imhist, countEachLabelreferences/image-understanding.md
read, write, load, save, import, export, open an image, convert format, batch, folder of images, TIFF, PNG, JPEG, RAW, HDR, test patternimread, imwrite, imageDatastore, hdrreadreferences/image-io.md
video, footage, frames, read video, write video, VideoReader, VideoWriter, frame rate, video codec, MP4, AVIVideoReader, VideoWriter, readFrame, hasFrame, writeVideoreferences/video-io.md
smooth, blur an image, sharpen, denoise, noise, grainy, filter, kernel, padding, edge-preserving, bilateral, non-local means, frequency filterimgaussfilt, medfilt2, imsharpen, imbilatfilt, imnlmfilt, imdiffusefilt, imfilter, ordfilt2, locallapfilt, wiener2references/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 lightingimadjust, stretchlim, adapthisteq, histeq, rescale, mat2gray, im2single, imadd, imlincomb, imblend, imflatfieldreferences/preprocessing.md
erode, dilate, open, close, structuring element, 2-D morphology, fill holes, remove small objects, skeletonize, thin, tidy up a binary resultstrel, imerode, imdilate, imopen, imclose, imfill, bwareaopen, bwskel, imtophat, imreconstructreferences/morphological-ops.md
deblur, blurry, unfocused, out of focus, motion blur, camera shake, restore a blurred image, deconvolution, PSF estimationdeconvblind, deconvlucy, deconvwnr, deconvregreferences/deblurring.md
resize, rotate, crop, warp, scale, flip, straighten, affine, projective, perspective, undistort, lens distortion, spatial referencing, world coordinates, voxel coordinates, pixel coordinates, coordinate conversionimresize, imrotate, imcrop, imwarp, imtranslate, affinetform2d, imref2dreferences/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 segmentationimbinarize, graythresh, multithresh, adaptthresh, watershed, imsegkmeans, imsegkmeans3, imsegisodata, imsegsamreferences/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 UIssegmentAnythingModel, grabcut, activecontour, lazysnapping, imsegfmm, grayconnected, superpixelsreferences/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, analysisregionprops, bwconncomp, bwareafilt, bwpropfilt, bwlabel, edge, imfindcircles, hough, bwboundariesreferences/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, esfrChartreferences/quality-assessment.md
texture, repetitive pattern, frequency domain, Fourier, FFT, DCT, Radon, Gabor, co-occurrence, GLCMgraycomatrix, graycoprops, entropyfilt, fft2, dct2, radon, gaborreferences/texture-transforms.md
color space, LAB, HSV, hue, saturation, white balance, color cast, color correction, color balance, ICC profile, grayscale conversionrgb2lab, lab2rgb, rgb2hsv, chromadapt, illumwhite, makecform, deltaE, decorrstretchreferences/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 volumeimgaussfilt3, 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, augmentedImageDatastorereferences/deep-learning-imaging.md
build your own image app or GUI: sliders, live preview, parameter tuning, ROI widgetsuifigure, uigridlayout, uislider, drawrectanglereferences/app-building.md
DICOM, NIfTI, NRRD, DICOM-RT, patient metadata, anonymizing, medicalVolume, medicalImage, reading/writing medical formats, extractSlice, volume orientation, medical spatial referencingmedicalVolume, medicalImage, dicomreadVolume, dicomCollection, extractSlice, dicomContours, dicomanonreferences/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 adaptersblockedImage, apply, getBlock, getRegion, selectBlockLocations, blockedImageDatastorereferences/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, viewer2d

  • R2026a: uidraw, uipaint, linkviewers

  • R2026b: 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

references/deep-learning-imaging.md

Deep Learning for Image Processing

Decision guidance for combining deep learning with image processing: data preparation, semantic segmentation, pretrained networks, and inference pipelines. Requires Deep Learning Toolbox; some features require Computer Vision Toolbox.

Often loaded with: image-io.md (datastores and batch loading), analysis-measurement.md (post-processing segmentation output).

Using Pretrained PyTorch Vision Models

For tasks where a pretrained PyTorch model is the best starting point (e.g., depth estimation, style transfer, foundation models not available natively in MATLAB), use the matlab-integrate-pytorch-vision skill to interface with Python model repositories from MATLAB.

Toolbox Requirements

TaskRequired toolboxes
Training/inferenceDeep Learning Toolbox
Semantic segmentation architecturesComputer Vision Toolbox
Object detection architecturesComputer Vision Toolbox
Image data augmentationDeep Learning Toolbox
Pretrained feature extractionDeep Learning Toolbox

Check availability before generating code:

hasDeepLearning = ~isempty(ver("nnet"));
hasComputerVision = ~isempty(ver("vision"));

1. Data Preprocessing

Image Datastores
Classification (folder-per-class)
imds = imageDatastore("data/images/", ...
    IncludeSubfolders=true, ...
    LabelSource="foldernames");  % Labels from folder names (e.g., cat/, dog/)
Semantic Segmentation (image + pixel label pairs)
imds = imageDatastore("data/images/");

classNames = ["background", "tumor", "healthy"];
labelIDs = [0 1 2];
pxds = pixelLabelDatastore("data/labels/", classNames, labelIDs);

ds = combine(imds, pxds);
Image Regression (image + continuous target)
imds = imageDatastore("data/images/");

% Targets from a table or file (e.g., depth maps, angles, coordinates)
targets = readtable("data/targets.csv");  % columns: filename, value1, value2, ...
targetDs = arrayDatastore(targets{:, 2:end});

ds = combine(imds, targetDs);

For image-to-image regression (e.g., denoising, super-resolution, depth estimation):

inputImds = imageDatastore("data/noisy/");
targetImds = imageDatastore("data/clean/");
ds = combine(inputImds, targetImds);
Resizing for Network Input

Networks require fixed input size. Resize images to match:

targetSize = [256 256];  % [rows cols] — NOT [width height]

% For datastores — use transform
dsResized = transform(ds, @(data) resizeForNetwork(data, targetSize));

function out = resizeForNetwork(data, targetSize)
    out{1} = imresize(data{1}, targetSize);
    out{2} = imresize(data{2}, targetSize, "nearest");  % Labels: nearest!
end

Gotcha: Always use "nearest" interpolation when resizing label maps or masks. Default bicubic creates invalid fractional labels.

Aspect-Ratio-Preserving Resize

When aspect ratio distortion hurts accuracy (e.g., object detection), pad to the target size instead of stretching:

function out = letterboxResize(img, targetSize)
    [h, w, ~] = size(img);
    scale = min(targetSize(1)/h, targetSize(2)/w);
    newSize = round([h w] * scale);
    resized = imresize(img, newSize);

    padValue = 114;  % common gray fill for detection networks
    out = ones(targetSize(1), targetSize(2), size(img,3), class(img)) * padValue;
    offset = floor((targetSize - newSize) / 2) + 1;
    out(offset(1):offset(1)+newSize(1)-1, offset(2):offset(2)+newSize(2)-1, :) = resized;
end

For semantic segmentation, wrap as a paired transform that also pads labels with an ignore value (e.g., 255) so padded pixels do not contribute to loss.

Input Normalization — Critical

Networks expect specific input ranges. Common patterns:

Network typeExpected inputPrepare with
Pretrained (ImageNet)Per-channel zero-mean, unit-varianceSubtract ImageNet channel means, divide by stds
Pretrained (COCO)Per-channel zero-mean, unit-varianceSubtract COCO channel means, divide by stds
Custom (trained on [0,1])[0, 1] singleim2single(img) or rescale(img, 0, 1) for arbitrary-range data
Custom (trained on [-1,1])[-1, 1]rescale(img, -1, 1)
Arbitrary range (medical HU, float sensors)Dataset-specific z-scoreCompute dataset mean/std, normalize

Gotcha: If training data was uint8 [0,255] but inference images are double [0,1], the network can produce incorrect predictions. Always match inference preprocessing to training preprocessing.

Pretrained Networks (ImageNet / COCO)

Most pretrained backbones use fixed per-channel statistics:

% ImageNet (ResNet, VGG, EfficientNet, etc.)
channelMeans = single([0.485, 0.456, 0.406]);
channelStds  = single([0.229, 0.224, 0.225]);

% COCO (detection/segmentation models pretrained on COCO)
channelMeans = single([0.471, 0.448, 0.408]);
channelStds  = single([0.234, 0.239, 0.242]);

% Apply: input must be single [0,1] first
img = im2single(img);  % uint8 [0,255] → single [0,1]
img = (img - reshape(channelMeans, 1, 1, 3)) ./ reshape(channelStds, 1, 1, 3);
Custom Networks (Compute-Then-Apply)

Compute mean/std from your training set, save, then apply via transform:

% Step 1: Compute channel-wise statistics
imds = imageDatastore("train/", IncludeSubfolders=true);
pixelSum = single([0 0 0]);
pixelSqSum = single([0 0 0]);
nPixels = 0;

while hasdata(imds)
    img = single(read(imds));
    nPx = size(img, 1) * size(img, 2);
    pixelSum = pixelSum + sum(img, [1 2]);
    pixelSqSum = pixelSqSum + sum(img.^2, [1 2]);
    nPixels = nPixels + nPx;
end
reset(imds);

channelMeans = pixelSum / nPixels;
channelStds = sqrt(pixelSqSum / nPixels - channelMeans.^2);
save("normalization_params.mat", "channelMeans", "channelStds");

% Step 2: Apply in training pipeline
params = load("normalization_params.mat");
dsTrain = transform(dsTrain, @(data) normalizeForTraining(data, params));

function out = normalizeForTraining(data, params)
    img = single(data{1});
    img = (img - reshape(params.channelMeans, 1, 1, [])) ./ ...
          reshape(params.channelStds, 1, 1, []);
    out = {img, data{2}};  % {normalized image, label}
end
Data Augmentation
augmenter = imageDataAugmenter( ...
    RandXReflection=true, ...
    RandRotation=[-10 10], ...
    RandScale=[0.9 1.1]);

augDs = augmentedImageDatastore(targetSize, imds, ...
    DataAugmentation=augmenter);

For segmentation (paired image + label augmentation), use transform with custom function:

ds = combine(imds, pxds);
dsAug = transform(ds, @augmentPair);

function out = augmentPair(data)
    img = data{1};
    lbl = data{2};
    % Apply same geometric transform to both
    if rand > 0.5
        img = fliplr(img);
        lbl = fliplr(lbl);
    end
    tform = randomAffine2d(Rotation=[-15 15], Scale=[0.8 1.2]);
    rout = affineOutputView(size(img), tform);
    img = imwarp(img, tform, OutputView=rout);
    lbl = imwarp(lbl, tform, OutputView=rout, Interpolation="nearest");
    out = {img, lbl};
end
Channel Count Mismatches
ScenarioSolution
Grayscale image → network expects RGB (3-ch)repmat(grayImg, 1, 1, 3)
RGB image → network expects grayscale (1-ch)im2gray(rgbImg)
Volumetric data with a 2-D networkProcess slices independently only when a 2-D workflow is appropriate; otherwise, consider a 3-D architecture such as unet3d
Multi-channel (>3) → standard networkCustom input layer or channel reduction

2. Modeling

Building from Scratch (Layer-by-Layer)

Define custom architectures using Deep Learning Toolbox layers:

layers = [
    imageInputLayer([256 256 3], Normalization="none")
    convolution2dLayer(3, 32, Padding="same")
    batchNormalizationLayer
    reluLayer
    maxPooling2dLayer(2, Stride=2)
    convolution2dLayer(3, 64, Padding="same")
    batchNormalizationLayer
    reluLayer
    globalAveragePooling2dLayer
    fullyConnectedLayer(numClasses)
    softmaxLayer
];
net = dlnetwork(layers);

Use addLayers and connectLayers for branching or multi-input architectures. Each layer must have a unique Name, and all inputs of multi-input layers (e.g., concatenationLayer) must be connected:

net = dlnetwork;

% Main path
net = addLayers(net, [
    imageInputLayer([256 256 3], Name="input")
    convolution2dLayer(3, 32, Padding="same", Name="conv1")
    reluLayer(Name="relu1")
    ]);

% Branch path
net = addLayers(net, [
    convolution2dLayer(1, 32, Padding="same", Name="conv_branch")
    reluLayer(Name="relu_branch")
    ]);

% Merge
net = addLayers(net, concatenationLayer(3, 2, Name="concat"));

% Connect: branch takes same input, concat merges both paths
net = connectLayers(net, "input", "conv_branch");
net = connectLayers(net, "relu1", "concat/in1");
net = connectLayers(net, "relu_branch", "concat/in2");

Use Deep Network Designer app (deepNetworkDesigner) to visually inspect, edit, and validate network architectures.

Classification with Pretrained Encoders

Use pretrainedEncoderNetwork to create a feature extractor from a pretrained backbone, then add classification layers:

[encoder, outputNames] = pretrainedEncoderNetwork("resnet18", 4);
Semantic Segmentation Architectures
ArchitectureFunctionBest for
U-NetunetLimited training data and segmentation of small or intricate structures
3-D U-Netunet3dVolumetric image data, such as CT and MRI
DeepLab v3+deeplabv3plusPrecise boundary delineation and objects at multiple scales
BiSeNet v2bisenetv2Real-time segmentation and applications with limited computational resources
inputSize = [256 256 1];  % [H W C]
numClasses = 3;

% U-Net
net = unet(inputSize, numClasses, EncoderDepth=4);

% 3-D U-Net (volumetric)
net = unet3d([64 64 64 1], numClasses, EncoderDepth=3);

% DeepLab v3+ with pretrained backbone
net = deeplabv3plus([256 256 3], numClasses, "resnet18");

% BiSeNet v2 — pretrained transfer learning (keeps pretrained weights)
net = bisenetv2(inputSize, numClasses);

% BiSeNet v2 — custom uninitialized network (no pretrained weights)
net = bisenetv2(inputSize, numClasses, NetworkType="custom");

To adapt segmentation architectures for image-to-image regression (e.g., depth estimation, denoising), replace the final classification layer with a regression output (1 or N channels, no softmax):

net = unet([256 256 3], 2, EncoderDepth=4);  % Start with 2-class U-Net
% Replace final conv + softmax for single-channel regression output
net = replaceLayer(net, "encoderDecoderFinalConvLayer", ...
    convolution2dLayer(1, 1, Name="encoderDecoderFinalConvLayer"));
net = removeLayers(net, "FinalNetworkSoftmax-Layer");
Custom Encoder-Decoder

For more control over skip connections and decoder structure, use encoderDecoderNetwork with a pretrained encoder:

[encoder, outputNames] = pretrainedEncoderNetwork("resnet18", 4);
net = encoderDecoderNetwork([256 256 3], encoder, outputNames, ...
    NumClasses=numClasses);

3. Training

options = trainingOptions("adam", ...
    InitialLearnRate=1e-3, ...
    MaxEpochs=50, ...
    MiniBatchSize=8, ...
    Shuffle="every-epoch", ...
    ValidationData=valDs, ...
    ValidationFrequency=50, ...
    Plots="training-progress");

net = trainnet(dsTrain, net, "crossentropy", options);

Modern API: Use trainnet, not the legacy trainNetwork. trainnet returns a dlnetwork directly.

4. Evaluation

Inference
% Single image
result = semanticseg(testImage, net);  % Returns categorical label map

% Batch via datastore
pxdsResults = semanticseg(testImds, net, WriteLocation="results/");
Inference — Reuse Training Normalization

Always load and apply the same normalization at inference:

params = load("normalization_params.mat");
testImg = im2single(imread("test.png"));
testImg = (testImg - reshape(params.channelMeans, 1, 1, [])) ./ ...
          reshape(params.channelStds, 1, 1, []);
result = semanticseg(testImg, net);
Tiled or Patch-Based Inference (Large Images/Volumes)

For images larger than GPU memory, use blockedImage with apply to process tiles:

bim = blockedImage(largeImage);

patchSize = [256 256];
overlap = [32 32];
result = apply(bim, @(block) semanticseg(block.Data, net), ...
    BlockSize=patchSize, ...
    BorderSize=overlap, ...
    PadPartialBlocks=true);

For tiled training workflows that use blockedImage or blockedImageDatastore to prepare image tiles, see references/large-image-processing.md.

Classification Metrics
scores = minibatchpredict(net, dsTest);
YPred = scores2label(scores, classNames);

% ROC curve and AUC
rocObj = rocmetrics(YTest, scores, classNames);
plot(rocObj);

% Confusion matrix
confusionchart(YTest, YPred);
Segmentation Quality Metrics
% Confusion matrix metrics
metrics = evaluateSemanticSegmentation(pxdsResults, pxdsGT);
disp(metrics.ClassMetrics);    % Per-class IoU, accuracy
disp(metrics.DataSetMetrics);  % Mean IoU, mean accuracy, weighted IoU
Post-Processing Segmentation Output

Raw network output often needs cleanup:

% Convert categorical to numeric labels
labelMap = uint8(result);

% Remove small regions (per-class)
for c = 1:numClasses
    classMask = labelMap == c;
    classMask = bwareaopen(classMask, minPixels);
    labelMap(labelMap == c & ~classMask) = 0;
end

% Fill holes in segmentation
for c = 1:numClasses
    classMask = labelMap == c;
    classMask = imfill(classMask, "holes");
    labelMap(classMask) = c;
end

Common Mistakes

MistakeWhy it's wrongCorrect approach
trainNetwork (legacy)Deprecated, returns SeriesNetwork/DAGNetworkUse trainnet, returns dlnetwork
Resizing labels with default interpolationBicubic creates invalid fractional labelsAlways imresize(lbl, sz, "nearest")
Mismatched input range at inferenceNetwork trained on [0,255] but given [0,1]Match preprocessing exactly to training
Grayscale into 3-channel networkDimension mismatch errorrepmat(gray, 1, 1, 3)
Training segmentation without class weightingRare classes never learnedUse class weights or "focal" loss
Processing a large image at full resolutionCan exceed available memoryUse tiled or patch-based processing when the full-resolution image exceeds available memory (blockedImage or randomPatchExtractionDatastore)
augmentedImageDatastore for segmentationOnly augments images, not labelsUse transform with paired augmentation function
Forgetting "nearest" for warping labelsimwarp default is linear → fractional labelsimwarp(lbl, tform, Interpolation="nearest")

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.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download matlab-process-images.zip