densityMap

R2026b

Density map of object count generated using CounTR deep learning model

Since R2025a

collapse all in page

Syntax

densMap = densityMap(counter,I)
dsDensMap = densityMap(counter,ds)
densMap = densityMap(___,Name=Value)

Description

Add-On Required: This feature requires the Visual Inspection Toolbox Model for CounTR Object Counting add-on.

densMap = densityMap(counter,I) computes the object count density map for an image I.

Note

This functionality requires Deep Learning Toolbox™.

example

dsDensMap = densityMap(counter,ds) computes the object count density map for datastores of images, ds.

densMap = densityMap(___,Name=Value) specifies options using additional name-value arguments in addition to any combination of arguments from previous syntaxes. For example, MiniBatchSize=4 specifies the mini-batch size as 4 when you specify an input datastore of images, ds.

Examples

collapse all

This example uses:

Open Live Script

Load an exemplar image that contains objects to count, cell nuclei, into the workspace. The exemplar image and the test image in this example are cropped from an image of lymph node cells (patient_000_node_1.tif) in the CAMELYON-17 data set.

exemplarI = imread("nuclei.png");

Define exemplar bounding boxes, which signify the locations of sample cells to count.

exemplarBoxes = ...
         [272   23   38   30
          302  193   30   24
          66   83   30   28
          108  243   38   32
          168   61   30   30];

Display the exemplar image together and the exemplar bounding boxes using the insertShape function.

annotatedImage = insertShape(exemplarI,"rectangle",exemplarBoxes,"LineWidth",4);
imshow(annotatedImage)

Figure contains an axes object. The hidden axes object contains an object of type image.

Create CounTR Model

Create a CounTR object counter model using the exemplar image and exemplar bounding boxes.

counter = counTRObjectCounter(exemplarI,exemplarBoxes);

Count Objects in Test Image

Load a test image containing more cell nuclei into the workspace.

I = imread("nucleiTest.png");

Display the test timage in which to count objects.

imshow(I)

Figure contains an axes object. The hidden axes object contains an object of type image.

Compute the number of objects in the test image using the countObjects object function.

count = countObjects(counter,I);
count
count = single

496

Create Density Map of Object Count

Compute the density map of the object count in the test image using the densityMap object function.

densMap = densityMap(counter,I);

Display the object count density map overlaid over the test image using the anomalyMapOverlay function. Display the approximate object count on the overlaid image using the insertText function.

densityOverlayImage = anomalyMapOverlay(I,densMap,"Blend","equal");
fontSize = min(floor(size(densityOverlayImage,2)/30),200);
gutterWidth = fontSize*9;
densityOverlayImageWText = insertText(densityOverlayImage,[size(densityOverlayImage,2)-gutterWidth 5],...
sprintf("count=%0.2f",count),FontSize=fontSize);
imshow(densityOverlayImageWText)

Figure contains an axes object. The hidden axes object contains an object of type image.

Input Arguments

collapse all

CounTR object counter model, specified as a counTRObjectCounter object.

Image for which to create an object count density map, specified as one of these values:

Image TypeData Format
GrayscaleH-by-W numeric matrix
BinaryH-by-W logical matrix
RGBH-by-W-by-3 numeric array

Datastore of images, specified as a datastore such as an ImageDatastore or CombinedDatastore object, for which to create object count density maps. If calling the datastore with the read function returns a cell array, then the image data must be in the first cell.

Name-Value Arguments

expand all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: densityMap(counter,ds,MiniBatchSize=4) specifies the mini-batch size as 4 when you specify an input datastore of images, ds.

Options for All Image Formats

expand all

Hardware resource on which to process images with the network, specified as one of the execution environment options in this table.

ExecutionEnvironmentDescription
"auto"Use a GPU if available. Otherwise, use the CPU. The use of a GPU requires Parallel Computing Toolbox™ and a CUDA® enabled NVIDIA® GPU. For information about the supported compute capabilities, see GPU Computing Requirements (Parallel Computing Toolbox).
"gpu"Use the GPU. If a suitable GPU is not available, the function returns an error message. Using a GPU requires Parallel Computing Toolbox and a CUDA enabled NVIDIA GPU. If Parallel Computing Toolbox or a suitable GPU is not available, then the function returns an error. For information about the supported compute capabilities, see GPU Computing Requirements (Parallel Computing Toolbox).
"cpu"Use the CPU.

Options for Datastore Inputs

expand all

Number of observations returned in each batch, specified as a positive integer. If you set a higher MiniBatchSize, density map computation requires more memory, which can cause errors if your system does not have sufficient memory.

You can specify this argument only when you specify an input datastore of images, ds.

Location to store writable data, specified as a string scalar or character vector. The specified folder must have write permissions. If the folder already exists, the densityMap function creates a new folder and adds a suffix to the folder name with the next available number. The default write location is fullfile(pwd,OutputFolderName), where pwd is the current working directory and OutputFolderName is specified by the OutputFolderName name-value argument.

You can specify this argument only when you specify an input datastore of images, ds.

Data Types: char | string

Output folder name for density map results, specified as a string scalar or a character vector. This folder is in the location specified by the value of the WriteLocation name-value argument.

If the output folder already exists, the function creates a new folder with the string "_1" appended to the end of the name. Set OutputFoldername to "" to write all the results to the folder specified by WriteLocation.

You can specify this argument only when you specify an input datastore of images, ds.

Prefix applied to output filenames, specified as a string scalar or character vector. The image files are named as follows:

  • <prefix>_<N>.png, where N corresponds to the index of the input image file, imds.Files(N).

You can specify this argument only when you specify an input datastore of images, ds.

Suffix to add to the output image filename, specified as a string scalar or a character vector. The function appends the specified suffix to the output filename as:

  • <prefix>_<N><suffix>.png, where N corresponds to the index of the input image file, ds.Files(N).

If you do not specify the suffix, the function uses the input filenames as the output file suffixes. The function extracts the input filenames from the info output of the read object function of the datastore. When the datastore does not provide the filename, the function does not add a suffix.

You can specify this argument only when you specify an input datastore of images, ds.

Visible progress display, specified as a numeric or logical 1 (true) or 0 (false).

You can specify this argument only when you specify an input datastore of images, ds.

Output Arguments

collapse all

Density map of object count, returned as a P-by-Q numeric matrix when you specify an input image I, or a datastore containing R density maps of size P-by-Q when you specify a datastore input ds. R is the number of images in the datastore.

References

[1] Liu, Chang, Yujie Zhong, Andrew Zisserman, and Weidi Xie. “CounTR: Transformer-Based Generalised Visual Counting.” arXiv, June 2, 2023. https://doi.org/10.48550/arXiv.2208.13721.

[2] grand-challenge.org. “CAMELYON17 - Grand Challenge.” Accessed November 8, 2024. https://camelyon17.grand-challenge.org/Data/.

Version History

Introduced in R2025a

expand all

See Also

|

Topics