matlab/matlab-agentic-toolkit / skills-catalog/image-processing-and-computer-vision/matlab-process-images
matlab-process-images
VerifiedLoad 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.
references/analysis-measurement.md
View on GitHub# Analysis & Measurement
Decision guidance and gotchas for measuring region properties, detecting objects (edges, circles, lines), boundary tracing, and ROI-based processing.
> **Often loaded with:** `segmentation-automated.md` (creating masks to measure), `morphological-ops.md` (cleaning masks before measurement).
## The Standard Analysis Pipeline
```matlab
bw = imbinarize(img); % 1. Threshold
bw = imfill(bw, "holes"); % 2. Clean up
bw = imclearborder(bw); % 3. Remove border objects
cc = bwconncomp(bw); % 4. Find connected components
numObjects = cc.NumObjects; % 5. Object count
props = regionprops(cc, "Area", "Centroid", "Eccentricity"); % 6. Measure
```
## `bwconncomp` vs `bwlabel`
| | `bwconncomp` | `bwlabel` |
|-|-------------|-----------|
| Dimensionality | 2-D, 3-D, N-D | 2-D only |
| Output | Struct with `PixelIdxList` | Double label matrix |
| Memory | Stores only pixel indices | Full image-sized label matrix |
| Connectivity control | Explicit via second argument | Limited |
Use `bwconncomp` when you need N-D support, explicit connectivity control, or want to avoid allocating a full label matrix. `bwlabel` is a concise 2-D labeling API that returns a label matrix directly — legitimate when that is the representation you need.
```matlab
cc = bwconncomp(bw); % Component structure — N-D, explicit connectivity
L = labelmatrix(cc); % Create label matrix only when needed (uses smallest uint type)
bw2 = cc2bw(cc); % Convert back to binary (R2024a) — cleaner than labelmatrix(cc)>0
L = bwlabel(bw); % Direct label matrix — 2-D only
```
## `regionprops` — Measurement
### Critical: Input Must Be `logical` for Binary Images
```matlab
% WRONG — numeric [0,1] treated as label matrix (finds 1 region!)
BW = double(imbinarize(gray));
props = regionprops(BW, "Area"); % Returns 1 object
% CORRECT — logical input triggers connected component analysis
props = regionprops(logical(BW), "Area"); % Finds all objects
% BEST — use bwconncomp for explicit control over connectivity
cc = bwconncomp(logical(BW), 4); % 4-connected (default is 8)
props = regionprops(cc, "Area");
```
If `regionprops` returns fewer objects than expected, check that the input is `logical` — numeric arrays (even with only 0/1 values) are interpreted as pre-formed label matrices.
### Output Format: Struct (Default) vs Table
```matlab
% Struct output (default)
props = regionprops(cc, "Area", "Centroid", "Eccentricity");
areas = [props.Area]; % Extract as numeric array
keep = areas > 500;
% Table output — convenient for display and complex filtering
props = regionprops("table", cc, "Area", "Centroid", "Eccentricity");
large = props(props.Area > 500, :);
```
**Performance tip:** Compute all desired properties in a single `regionprops` call rather than calling it multiple times for different properties.
### Coordinate Convention — Critical Gotcha
**`Centroid` and `BoundingBox` use [x, y] coordinates, NOT [row, col]:**
```matlab
% Object at rows 20-40, cols 50-80:
% Centroid = [65.0, 30.0] → [x=col, y=row]
% BoundingBox = [49.5 19.5 31.0 21.0] → [x y width height]
```
To plot centroids from **struct** output (default): `centroids = cat(1, props.Centroid); plot(centroids(:,1), centroids(:,2), 'r+')` — struct-array dot indexing returns a comma-separated list, so concatenate first. From **table** output: `plot(props.Centroid(:,1), props.Centroid(:,2), 'r+')` works directly.
To index into image: `img(round(centroid(2)), round(centroid(1)))` — swap order!
### Intensity Measurements Require a Grayscale Image
```matlab
% Shape-only properties:
props = regionprops("table", bw, "Area", "Perimeter", "Circularity");
% Intensity properties need the grayscale image as second arg:
props = regionprops("table", bw, gray, "MeanIntensity", "MaxIntensity", "PixelValues");
```
### Key Properties Reference
**Shape (no intensity image needed):**
| Property | What it measures |
|----------|-----------------|
| `Area` | Pixel count |
| `Centroid` | Center of mass [x, y] |
| `BoundingBox` | [x y width height] enclosing rectangle |
| `Perimeter` | Boundary length in pixels |
| `Circularity` | Measure of circularity (max is 1.0, a perfect circle) |
| `Eccentricity` | 0 (circle) to 1 (line) |
| `Solidity` | Area / ConvexArea (1.0 = convex) |
| `Orientation` | Angle of major axis (-90° to 90°) |
| `EquivDiameter` | Diameter of circle with same area |
| `MajorAxisLength`, `MinorAxisLength` | Equivalent ellipse axes (same 2nd moments) — **not** physical length |
| `MaxFeretProperties`, `MinFeretProperties` | Structs with `.MaxFeretDiameter`/`.MinFeretDiameter` (caliper length/width), angle, and endpoint coordinates |
| `Extent` | Area / BoundingBox area |
| `FilledArea` | Area with holes filled |
| `ConvexArea` | Area of convex hull |
| `EulerNumber` | Objects minus holes |
| `BoundaryCoordinates` | Exterior boundary pixels as N×2 [x, y] matrix (R2026a) |
**`BoundaryCoordinates` (R2026a):** Returns boundary pixel coordinates directly from `regionprops`, eliminating the need for a separate `bwboundaries` call. Coordinates are [x, y] (same as Centroid). Requires a `bwconncomp` struct or logical input — not supported with label matrix input. Use when you need both measurements and boundaries from the same `regionprops` call.
**Measuring length:** `MajorAxisLength` is the axis of an equivalent ellipse, not the actual object length. For non-elliptical shapes it can exceed the true extent. Use `MaxFeretDiameter` for actual length (longest caliper distance) and `MinFeretDiameter` for width.
**Intensity (requires grayscale image):**
| Property | What it measures |
|----------|-----------------|
| `MeanIntensity` | Mean pixel value in region |
| `MaxIntensity` | Maximum pixel value |
| `MinIntensity` | Minimum pixel value |
| `PixelValues` | Vector of all pixel values (can be large) |
| `WeightedCentroid` | Intensity-weighted center [x, y] |
### Filtering Objects by Properties
Three approaches, from simplest to most flexible:
```matlab
% 1. One-liner with bwpropfilt (best for simple filters)
bw_large = bwpropfilt(bw, "Area", [500 Inf]);
bw_round = bwpropfilt(bw, "Eccentricity", [0 0.5]);
% 2. Struct filtering + cc2bw (for compound conditions, R2024a)
props = regionprops(cc, "Area", "Eccentricity");
keep = [props.Area] > 500 & [props.Eccentricity] < 0.5;
bw_filtered = cc2bw(cc, ObjectsToKeep=find(keep));
% 3. bwareafilt for size-only filtering
bw_large = bwareafilt(bw, [500 Inf]); % Area range
bw_top5 = bwareafilt(bw, 5); % N largest objects
```
## Peak / Bright Spot Detection
For finding local intensity peaks (particles, fluorescent spots, stars, etc.):
To improve results from `imregionalmax`, always suppress small peaks first with `imhmax` — without suppression, every noise bump registers as a peak:
```matlab
% Step 1: Suppress peaks with prominence < h
h = 20; % Minimum peak height above surroundings
suppressed = imhmax(gray, h); % Flatten insignificant peaks
% Step 2: Find regional maxima of the suppressed image
peaks = imregionalmax(suppressed); % Now only significant peaks remain
% Step 3 (optional): Sub-pixel localization via weighted centroid
props = regionprops(peaks, gray, "WeightedCentroid");
locations = cat(1, props.WeightedCentroid); % [x, y] sub-pixel positions
```
**Tuning `h`:** too small → noise peaks detected; too large → real peaks merged or missed. Start with a value equal to your expected noise amplitude.
**Alternative:** `imextendedmax(gray, h)` combines both steps (equivalent to `imregionalmax(imhmax(gray, h))`).
**For minima** (dark spots): use `imhmin` + `imregionalmin`, or `imextendedmin`.
## Distance Transform — `bwdist`
Computes the distance from every pixel to the nearest foreground (nonzero) pixel. Foreground pixels get 0:
```matlab
D = bwdist(bw); % Euclidean distance (default)
D = bwdist(bw, "cityblock"); % Manhattan distance
[D, idx] = bwdist(bw); % Also returns linear index of nearest foreground pixel
```
**Common uses:**
- **Watershed segmentation prep:** `watershed(-bwdist(~bw))` separates touching objects
- **Proximity analysis:** find all pixels within distance `d` of foreground — `bwdist(bw) <= d`
- **Grouping nearby objects:** see pattern in `morphological-ops.md`
- **Medial axis:** `bwdist` + local maxima gives a weighted skeleton
**Distance methods:** `"euclidean"` (default), `"cityblock"`, `"chessboard"`, `"quasi-euclidean"`.
## Edge Detection
```matlab
edges = edge(gray, "Canny"); % Default thresholds
edges = edge(gray, "Canny", [0.05 0.15]); % Manual thresholds [low high]
edges = edge(gray, "Canny", [], 2); % Custom sigma ([] = auto threshold)
```
**Choosing a method:**
| Method | Strength | Typical use |
|--------|----------|-------------|
| `"Canny"` | Best general-purpose, thin edges | Default choice |
| `"Sobel"` / `"Prewitt"` | Fast gradient magnitude | When speed matters |
| `"log"` | Good at finding edges at specific scale | Scale-specific detection |
| `"Roberts"` | Diagonal edge emphasis | Rarely preferred |
**Gotcha:** `edge` returns auto-computed thresholds as second output — useful for tuning:
```matlab
[~, thresh] = edge(gray, "Canny"); % Get auto thresholds, then adjust
edges = edge(gray, "Canny", thresh * 0.8); % Slightly more sensitive
```
**Directional gradients:** For `"Sobel"`, `"Prewitt"`, and `"Roberts"`, the four-output syntax returns directional gradients:
```matlab
[BW, thresh, Gx, Gy] = edge(gray, "Sobel"); % Gx = horizontal, Gy = vertical
```
For `"Roberts"`, `Gx` and `Gy` correspond to 135° and 45° from horizontal, respectively. This syntax is not available for `"Canny"` or `"log"`.
### Gradient Magnitude and Direction — `imgradient` / `imgradientxy`
Unlike `edge` (which returns binary edges), these return continuous gradient values — useful for edge strength analysis, orientation maps, and feature computation:
```matlab
[Gmag, Gdir] = imgradient(gray); % Magnitude + direction (degrees, [-180, 180])
[Gmag, Gdir] = imgradient(gray, "sobel"); % Methods: "sobel" (default), "prewitt", "central", "intermediate", "roberts"
[Gx, Gy] = imgradientxy(gray); % Directional gradients (x=horizontal, y=vertical)
[Gx, Gy] = imgradientxy(gray, "sobel"); % Methods: "sobel" (default), "prewitt", "central", "intermediate"
```
**When to use:** `imgradient` for edge strength maps and orientation analysis; `imgradientxy` when you need the directional components separately (e.g., for steering filters or gradient-based features). For 3-D volumes, use `imgradient3` / `imgradientxyz` (see `3d-volume-processing.md`).
## Circle Detection — `imfindcircles`
```matlab
[centers, radii, metric] = imfindcircles(img, [rMin rMax], ...
"ObjectPolarity", "bright", ... % "bright" or "dark" circles on background
"Sensitivity", 0.85); % Default 0.85; higher finds more (more false positives)
```
**Key parameters:**
- **`ObjectPolarity`** — `"bright"` (default) or `"dark"`. Must match the contrast of circular objects relative to the background
- **`Sensitivity`** (default 0.85) — higher values detect more circles but increase false positives
- **`EdgeThreshold`** — controls which edge pixels vote in the accumulator. Default is computed automatically using `graythresh`. Lower it to detect faint or low-contrast circles
- **`Method`** — `"PhaseCode"` (default, typically faster for radius estimation) or `"TwoStage"`
- **Radius range `[rMin rMax]`** — narrowing this range improves performance. Minimum radius ≤ 5 limits accuracy
```matlab
[centers, radii] = imfindcircles(img, [20 40], ...
"Sensitivity", 0.92, "EdgeThreshold", 0.08);
```
**Behavioral notes:**
- Circle centers that fall outside the image are not returned
- Concentric circle detection is limited — the algorithm may not reliably separate circles sharing a center
- RGB input is converted to grayscale internally; binary input is smoothed before processing
**`imfindcirclesYOLO`** (R2026a) — deep learning circle detection that detects circles without a caller-supplied radius range and returns confidence scores. **Requires the Image Processing Toolbox Model for Circle Detection support package** (add-on):
```matlab
[centers, radii, scores] = imfindcirclesYOLO(img);
```
**Alternative: template matching with `normxcorr2`** when gradient-based detection fails entirely (finds center but not radius — combine with edge detection for radius):
```matlab
% For circles with known internal pattern (e.g., quadrant pattern)
template = repelem([0 1; 1 0], 50, 50); % Construct expected pattern
C = normxcorr2(template, gray);
[~, idx] = max(C(:));
[yPeak, xPeak] = ind2sub(size(C), idx);
center = [xPeak, yPeak] - [size(template,2) size(template,1)]/2 + 0.5; % Adjust for template offset
```
### Creating Masks from Detected Circles
After detecting circles, create a binary mask directly (R2024a):
```matlab
[centers, radii] = imfindcircles(img, [20 50]);
mask = circles2mask(centers, radii, size(img, [1 2]));
```
This replaces manual approaches using `viscircles` or loops with `insertShape`.
## Line Detection — Hough Transform
```matlab
bw_edges = edge(gray, "Canny");
[H, theta, rho] = hough(bw_edges);
peaks = houghpeaks(H, numLines);
lines = houghlines(bw_edges, theta, rho, peaks, ...
"FillGap", 10, ... % Bridge gaps up to 10 pixels
"MinLength", 30); % Ignore segments shorter than 30 pixels
```
Each line in the output struct has `.point1` and `.point2` (endpoints as [x, y]).
## Boundary Tracing — `bwboundaries`
```matlab
[B, L] = bwboundaries(bw); % B is cell array of boundaries
% Default: includes holes, [row,col] coordinates, pixelcenter trace
% Each B{k} is N×2 matrix of [row, col] coordinates (NOT [x,y]!)
```
**Default behavior includes holes** — the output contains boundaries for both objects and their holes. Pass `"noholes"` when hole boundaries are not needed, which can also improve performance:
```matlab
B = bwboundaries(bw, 8, "noholes"); % Object boundaries only, faster
```
**Coordinate gotcha:** `bwboundaries` defaults to `[row, col]` (`"yx"`) order — opposite of `regionprops` Centroid which is `[x, y]`. To plot: `plot(B{k}(:,2), B{k}(:,1))` (swap columns). Use `CoordinateOrder="xy"` (R2023a) to get `[x, y]` directly.
### TraceStyle: `"pixeledge"` vs `"pixelcenter"` (R2023a)
| TraceStyle | What it traces | Use when |
|------------|---------------|----------|
| `"pixelcenter"` (default) | Polygon through centers of boundary pixels | General boundary detection, spatial indexing |
| `"pixeledge"` | Polygon along outer edge of boundary pixels | When the downstream calculation requires pixel-edge geometry (e.g., overlay alignment, ROI export) |
These are different trace geometries — match `TraceStyle` to the coordinate convention your downstream calculation expects:
```matlab
B = bwboundaries(bw, 8, "noholes", TraceStyle="pixeledge", CoordinateOrder="xy");
% B{k} is now [x, y] coordinates along the outer pixel edges — ready for plot() directly
```
`CoordinateOrder` and `TraceStyle` were both added in R2023a.
## ROI-Based Processing
### Apply filter only within a region:
```matlab
mask = poly2mask(xVertices, yVertices, imgHeight, imgWidth);
filtered = roifilt2(img, mask, @(x) imgaussfilt(x, 3));
```
### Inpaint a region (fill from surroundings):
```matlab
result = regionfill(img, mask); % Interpolates from boundary values
```
### Create masks:
| Function | Input | Output |
|----------|-------|--------|
| `poly2mask(x, y, m, n)` | Polygon vertices | Binary mask |
| `createMask(roi)` | ROI object (from `drawpolygon` etc.) | Binary mask |
| `roipoly(img)` | Interactive polygon drawing | Binary mask |
## Visualization
```matlab
% Label overlay for display — use imageshow with OverlayData
imageshow(gray, OverlayData=L);
% For generating an RGB array (e.g., saving to file)
rgb = label2rgb(L, "jet", "k", "shuffle");
% Better adjacent-label contrast (R2025a) — maximizes color difference between neighbors
overlay = labeloverlay(gray, L, ColorAssignment="contrasting-neighbors");
```
## When to Escalate to Visual Inspection Toolbox
For the following tasks, the Visual Inspection Toolbox has built-in tools that supplement IPT measurement tools:
- **Shape matching** for part localization or fixturing
- **Gauging and metrology** (caliper measurements, fit a circle, or angle on edges)
- **Anomaly/defect detection** where defect appearance varies
- **Counting** with deep-learning counters (CounTR) or template matching at scale
- **Deployment** to embedded targets, GPUs (TensorRT), or PLCs
**If Visual Inspection Toolbox is installed:** Use its purpose-built tools for these workflows — anomaly detection models, caliper tools, shape matchers, deployment pipelines. No sibling skill covers them.
**If Visual Inspection Toolbox is NOT installed:** Recommend the user consider it. IPT's `regionprops`, `imfindcircles`, and template matching via `normxcorr2` can handle simple cases, but production machine vision metrology (sub-pixel edge detection, calibrated measurements, shape matching for fixturing) benefits significantly from the dedicated library.
## Common Mistakes
| Mistake | Why it's wrong | Correct approach |
|---------|---------------|-----------------|
| `regionprops(BW, ...)` with numeric BW | Numeric [0,1] treated as label matrix (1 object) | Ensure input is `logical` or pass `bwconncomp` output |
| `regionprops(bw, "MeanIntensity")` | Intensity props need the gray image | `regionprops(bw, gray, "MeanIntensity")` |
| Using Centroid as `(row, col)` for indexing | Centroid is `[x, y]` = `[col, row]` | `img(round(c(2)), round(c(1)))` |
| `bwlabel` for 3-D or N-D images | `bwlabel` is 2-D only | Use `bwconncomp` for N-D data |
| Plotting boundaries without swapping | `bwboundaries` returns [row,col] | `plot(B{k}(:,2), B{k}(:,1))` |
| `imfindcircles` finds nothing | `ObjectPolarity` does not match image contrast | Try both `"bright"` and `"dark"` |
| Manual loop to filter by area | Verbose | `bwpropfilt(bw, "Area", [min Inf])` |
| `ismember(L, find(keep))` to filter objects | Verbose (pre-R2024a) | `cc2bw(cc, ObjectsToKeep=find(keep))` |
| Manual circle mask with loops | Slow and verbose | `circles2mask(centers, radii, [m n])` (R2024a) |
| Accessing `props.Image` from table without `{}` | R2022a+: always cell array in table output | Use `props.Image{k}` even for small objects |
| Trusting `Perimeter` or `Circularity` on very small objects | 1-pixel object: Perimeter=0, Circularity=1.0; chain-code approximation degrades below ~10 pixels | Filter out small objects with `bwareaopen` before measuring shape properties |
----
Copyright 2026 The MathWorks, Inc.
----
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |