countEachLabel

R2026b

Counts number of pixel labels for each class

collapse all in page

    Syntax

    counts = countEachLabel(bimds)
    counts = countEachLabel(___,Name=Value)

    Description

    counts = countEachLabel(bimds) counts the occurrence of each pixel label in all the blocks represented by the blocked image datastore bimds.

    example

    counts = countEachLabel(___,Name=Value) specifies additional name-value arguments.

    If bimds contains categorical data, countEachLabel obtains the class names from the categories specified in the InitialValue property of the first blocked image. In this case, do not specify the Classes and PixelLabelIDs name-value arguments. If bimds contains numeric data, you must provide values for the Classes and PixelLabelIDs name-value arguments.

    example

    Examples

    collapse all

    Open Live Script

    Create a blocked image from a sample label image.

    bim = blockedImage("yellowlily-segmented.png",BlockSize=[512 512]);
b = bigimageshow(bim);
showlabels(b,bim)

    Figure contains an axes object. The axes object contains an object of type bigimageshow.

    Create a blocked image datastore from the blocked image.

    bimds = blockedImageDatastore(bim);

    Count the labels in the blocked image datastore. Labels 0 and 3 both map to "Background".

    countEachLabel(bimds, ...
      Classes=["Background" "Flower" "Leaf" "Background"], ...
      PixelLabelIDs=[0 1 2 3])
    ans = 3×3 table
    "Background"    2370646    3145728
        "Flower"     433490    1572864
          "Leaf"     341592    2097152
    Open Live Script

    Load pixel label data.

    load("buildingPixelLabeled.mat");

    Create a blockedImage to manage the pixel label data.

    blockedLabeledImage = blockedImage(label,BlockSize=[200 150]);
bigimageshow(blockedLabeledImage)

    Figure contains an axes object. The axes object contains an object of type bigimageshow.

    Create a blockedImageDatastore that reads blocks of size 200-by-150 pixels at the finest resolution level from blockedLabeledImage.

    blockLabelDS = blockedImageDatastore(blockedLabeledImage);

    Count the number of pixel labels for each class.

    tbl = countEachLabel(blockLabelDS)
    tbl = 4×3 table
    "building"    180359    450000
       "grass"     32983    150000
    "sidewalk"     10491    150000
         "sky"     81525    180000

    Balance the classes by using uniform prior weighting.

    prior = 1/height(tbl);
uniformClassWeights = prior ./ tbl.PixelCount
    uniformClassWeights = 4×1
10-4 ×

    0.0139
    0.0758
    0.2383
    0.0307

    Balance the classes by using inverse frequency weighting.

     totalNumberOfPixels = sum(tbl.PixelCount);
 freq = tbl.PixelCount / totalNumberOfPixels;
 invFreqClassWeights = 1./freq
    invFreqClassWeights = 4×1

     1.6931
     9.2580
    29.1067
     3.7456

    Balance the classes by using median frequency weighting.

    freq = tbl.PixelCount ./ tbl.BlockPixelCount;
medFreqClassWeights = median(freq) ./ freq
    medFreqClassWeights = 4×1

    0.7743
    1.4114
    4.4373
    0.6852

    Input Arguments

    collapse all

    Blocked image datastore, specified as a blockedImageDatastore object.

    Name-Value Arguments

    collapse 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: countEachLabel(lbimds,Classes=["Background","Flower","Leaf","Background"],PixelLabelIDs=[0,1,2,3]) counts pixels per class in lbimds, where Class defines each class label and order and PixelLabelsIDs specifies the value for each class to the corresponding pixel IDs.

    Class names, specified as a string array or a cell array of character vectors.

    Example: ["Background","Flower","Leaf"]

    Data Types: char | string | cell

    Values for each label, specified as a numeric array of values with the same length as Classes. This name-value argument provides the mapping from numeric values to the label class.

    Example: [0 1 2 3]

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Option to perform computations in parallel using a parallel pool of workers, specified as one of these values:

    • "off" — Run in serial on the MATLAB® client.

    • "auto" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, then run in serial on the MATLAB client.

    • "on" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, then throw an error.

    Before R2026b: To run in parallel, set UseParallel to true (1).

    If you do not have a parallel pool open and automatic pool creation is enabled, then MATLAB opens a pool using the default cluster profile. To use a parallel pool to run computations in MATLAB, you must have Parallel Computing Toolbox™. For more information, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

    Data Types: char | string

    Output Arguments

    collapse all

    Counts of the occurrence of each pixel label in all blocks represented by the blocked image datastore, returned as a table that contains three variables.

    Pixel Count VariablesDescription
    NamePixel label class name
    PixelCountNumber of pixels of a given class in all blocks
    BlockPixelCountTotal number of pixels in blocks that have an instance of the given class

    Note

    If the blockedImageDatastore is created from a blockedImage with a nonzero BorderSize, pixels in the overlapping border regions are counted once for each block that contains them. As a result, overlapping pixels contribute multiple times to PixelCount and BlockPixelCount.

    To avoid double-counting, trim the border region from each block before counting labels. For an example of this workflow, see Detect and Count Cell Nuclei in Whole Slide Images.

    Tips

    You can use the label information returned by countEachLabel to calculate class weights for class balancing. For example, for labeled pixel data information in tbl:

    • Uniform class balancing weights each class such that each contains a uniform prior probability:

      numClasses = height(tbl)
prior = 1/numClasses;
classWeights = prior./tbl.PixelCount

    • Inverse frequency balancing weights each class such that underrepresented classes are given higher weight:

      totalNumberOfPixels = sum(tbl.PixelCount)
frequency = tbl.PixelCount / totalNumberOfPixels;
classWeights = 1./frequency

    • Median frequency balancing weights each class using the median frequency. The weight for each class c is defined as median(imageFreq)/imageBlockFreq(c), where imageBlockFreq(c) is the number of pixels of a given class divided by the total number of pixels in image blocks that had an instance of the given class c. 

      imageBlockFreq = tbl.PixelCount ./ tbl.BlockPixelCount
classWeights = median(imageBlockFreq) ./ imageBlockFreq

    Extended Capabilities

    expand all

    Version History

    Introduced in R2021a

    expand all

    See Also

    |