Function References

analyze_components(components::AbstractArray{<:Integer}, f::AbstractComponentAnalysisAlgorithm, args...; kwargs...)
analyze_components(components::AbstractArray{<:Integer}, f::Tuple{AbstractComponentAnalysisAlgorithm, Vararg{AbstractComponentAnalysisAlgorithm}}, args...; kwargs...)

Analyze connected components using algorithm f or sequence of algorithms specified in a tuple fs, and store the results in a DataFrame.

Output

The information about the components is stored in a DataFrame; each row number contains information corresponding to a particular connected component. The columns of the DataFrame will store the measurements that algorithm f or algorithms fs computes.

Examples

Pass an array of labelled connected components and component analysis algorithm to analyze_component.

f = BasicMeasurement()
analyze_components = analyze_component(components, f)

fs = tuple(RegionEllipse(), Contour())
analyze_components!(df, components, fs)

The first example reads as "analyze_components of connected components using algorithm f".

See also analyze_components! for appending information about connected components to an existing DataFrame.

analyze_components!(dataframe::AbstractDataFrame, components::AbstractArray{<:Integer}, f::AbstractComponentAnalysisAlgorithm, args...; kwargs...)
analyze_components!(dataframe::AbstractDataFrame, components::AbstractArray{<:Integer}, fs::Tuple{AbstractComponentAnalysisAlgorithm, Vararg{AbstractComponentAnalysisAlgorithm}}, args...; kwargs...)

Analyze connected components using component analysis algorithm f or sequence of algorithms specified in a tuple fs, and store the results in a DataFrame.

Output

The information about the components is stored in a DataFrame; each row number contains information corresponding to a particular connected component. The DataFrame will be changed in place and its columns will store the measurements that algorithm f or algorithms fs computes.

Examples

Just simply pass an algorithm to analyze_components!:

df = DataFrame()
f = BasicMeasurement()
analyze_components!(df, components, f)

fs = tuple(RegionEllipse(), Contour())
analyze_components!(df, components, fs)

See also: analyze_components

    establish_contour_hierarchy(labels::AbstractArray{<:Integer})

Traces the contour of both the outer boundary and hole boundary of each labelled component and stores the hierarichal relationship among the contours in a tree data structure.

Details

The tree is of type LeftChildRightSiblingTree and you can use the functionality from the AbstractTrees.jl package to iterate over it.

Each Node of the tree has a data field of type DigitalContour.

The parent/child relationship of the tree reflects the nesting of connected components. If a connected component is wholly contained within another connected component, then its contours will be children of the contours of its surrounding connected component.

Example

using ImageComponentAnalysis, TestImages, ImageBinarization, ImageCore, AbstractTrees, Parameters

img = Gray.(testimage("blobs"))
img2 = binarize(img, Otsu())
components = label_components(img2, trues(3,3), 1)
tree = establish_contour_hierarchy(components)

# Iterate over all DigitalContour's in the tree.
for node in PostOrderDFS(tree)
    @unpack id, is_outer, pixels node.data # See Parameters.jl for "@unpack"
    @show id, is_outer, pixels
end

Reference

1. S. Suzuki and K. Abe, “Topological structural analysis of digitized binary images by border following,” Computer Vision, Graphics, and Image Processing, vol. 29, no. 3, p. 396, Mar. 1985.

label_components(tf, [connectivity])
label_components(tf, [region])

Find the connected components in a binary array tf. There are two forms that connectivity can take.

(1) It can be a boolean array of the same dimensionality as tf, of size 1 or 3 along each dimension. Each entry in the array determines whether a given neighbor is used for connectivity analyses. For example, connectivity = trues(3,3) would use 8-connectivity and test all pixels that touch the current one, even the corners.

(2) You can provide a list indicating which dimensions are used to determine connectivity. For example, region = [1,3] would not test neighbors along dimension 2 for connectivity. This corresponds to just the nearest neighbors, i.e., 4-connectivity in 2d and 6-connectivity in 3d. The default is region = 1:ndims(A). The output label is an integer array, where 0 is used for background pixels, and each connected region gets a different integer index.

AbstractComponentAnalysisAlgorithm <: AbstractComponentAnalysis

The root type for ImageComponentAnalysis package.

Any concrete component analysis algorithm shall subtype it to support analyze_components and analyze_components! APIs.

Examples

All component analysis algorithms in ImageComponentAnalysis are called in the following pattern:

# determine the connected components and label them
components = label_components(binary_image)

# generate an algorithm instance
f = BasicMeasurement(area = true, perimiter = true)

# then pass the algorithm to `analyze_components`
measurements = analyze_components(components, f)

# or use in-place version `analyze_components!`
g = BoundingBox(area = true)
analyze_components!(measurements, components, g)

You can run a sequence of analyses by passing a tuple of the relevant algorithms. For example,

# determine the connected components and label them
components = label_components(binary_image)

# generate algorithm instances
p = Contour()
q = MinimumOrientedBoundingBox(oriented_box_aspect_ratio = false)
r = EllipseRegion(semiaxes = true)

# then pass the algorithm to `analyze_components`
measurements = analyze_components(components, tuple(p, q, r))

# or use in-place version `analyze_components!`
analyze_components!(measurements, components, tuple(p, q, r))

Most algorithms receive additional information as an argument, such as area or perimeter of BasicMeasurement. In general, arguments are boolean flags that signal whether or not to include a particular feature in the analysis.

# you can explicit specify whether or not you wish to report certain
# properties
f = BasicMeasurement(area = false, perimiter = true)

For more examples, please check analyze_components, analyze_components! and concrete algorithms.

    BasicMeasurement <: AbstractComponentAnalysisAlgorithm
    BasicMeasurement(; area = true,  perimeter = true)
    analyze_components(components, f::BasicMeasurement)
    analyze_components!(dataframe::AbstractDataFrame, components, f::BasicMeasurement)

Takes as input an array of labelled connected components and returns a DataFrame with columns that store basic measurements, such as area and perimeter, of each component.

Details

The area and perimeter measures are derived from bit-quad patterns, which are certain 2 × 2 pixel patterns described in [1]. Hence, the function adds six bit-quad patterns to the DataFrame under column names Q₀, Q₁, Q₂, Q₃, Q₄ and Qₓ.

The function returns two measures for the perimeter, perimiter₀ and perimter₁, which are given by equations 18.2-8b and 18.2-7a in [2]

Example

using ImageComponentAnalysis, TestImages, ImageBinarization, ColorTypes

img = Gray.(testimage("blobs"))
img2 = binarize(img, Otsu())
components = label_components(img2, trues(3,3), 1)
measurements = analyze_components(components, BasicMeasurement(area = true, perimeter = false))

References

1. S. B. Gray, “Local Properties of Binary Images in Two Dimensions,” IEEE Transactions on Computers, vol. C–20, no. 5, pp. 551–561, May 1971.
2. Pratt, William K., Digital Image Processing, New York, John Wiley & Sons, Inc., 1991, p. 629.

    BasicTopology <: AbstractComponentAnalysisAlgorithm
    BasicTopology(; holes = true,  euler_number = true)
    analyze_components(components, f::BasicTopolgy)
    analyze_components!(dataframe::AbstractDataFrame, components, f::BasicTopolgy)

Takes as input an array of labelled connected components and returns a DataFrame with columns that store basic topological properties for each component, such as the euler_number and the total number of holes.

The function returns two variants of the euler_number: euler₄ and euler₈ which correspond to a 4-connected versus 8-connected neighbourhood.

The euler_number and number of holes are derived from bit-quad patterns, which are certain 2 × 2 pixel patterns described in [1]. Hence, the function adds six bit-quad patterns to the DataFrame under column names Q₀, Q₁, Q₂, Q₃, Q₄ and Qₓ.

Example

using ImageComponentAnalysis, TestImages, ImageBinarization, ColorTypes

img = Gray.(testimage("blobs"))
img2 = binarize(img, Otsu())
components = label_components(img2, trues(3,3), 1)
measurements = analyze_components(components, BasicTopology(holes = true, euler_number = true))

Reference

1. S. B. Gray, “Local Properties of Binary Images in Two Dimensions,” IEEE Transactions on Computers, vol. C–20, no. 5, pp. 551–561, May 1971.

    BoundingBox <: AbstractComponentAnalysisAlgorithm
    BoundingBox(;  box_area = true)
    analyze_components(components, f::BoundingBox)
    analyze_components!(df::AbstractDataFrame, components, f::BoundingBox)

Takes as input an array of labelled connected components and returns a DataFrame with columns that store a tuple of StepRange types that demarcate the minimum (image axis-aligned) bounding box of each component.

The function can optionally also return the box area.

Example

using ImageComponentAnalysis, TestImages, ImageBinarization, ColorTypes

img = Gray.(testimage("blobs"))
img2 = binarize(img, Otsu())
components = label_components(img2, trues(3,3), 1)
measurements = analyze_components(components, BoundingBox(box_area = true))

    MinimumOrientedBoundingBox <: AbstractComponentAnalysisAlgorithm
    MinimumOrientedBoundingBox(;  oriented_box_area = true, oriented_box_aspect_ratio = true)
    analyze_components(components, f::MinimumOrientedBoundingBox)
    analyze_components!(df::AbstractDataFrame, components, f::MinimumOrientedBoundingBox)

Takes as input an array of labelled connected components and returns a DataFrame with columns that store a length-4 vector containing the four corner points of the minimum oriented bounding box of each component. It optionally also returns the area and aspect ratio of the minimum oriented bounding box.

Example

using ImageComponentAnalysis, TestImages, ImageBinarization, ColorTypes

img = Gray.(testimage("blobs"))
img2 = binarize(img, Otsu())
components = label_components(img2, trues(3,3), 1)
algorithm = MinimumOrientedBoundingBox(oriented_box_area = true, oriented_box_aspect_ratio = true)
measurements = analyze_components(components, algorithm)