2-point cluster function#

Theory#

If an image consists of isolated clusters (‘islands’ of connected pixels with the same value), the 2-point cluster function can be used to quantify the probability that two points are in the same cluster. It is defined as follows:

\[C_2 (\Delta x) = P \big\{ \mathcal{C}(\vec{x}) = \mathcal{C}(\vec{x}+\Delta\vec{x}) \neq 0 \big\}\]

whereby \(\mathcal{C}\) is an indicator with a unique non-zero index for each cluster.

Example#

Note

Like for the 2-point correlation, a mask can be used. Similarly, the average can be extended to that of an ensemble of images.

C2.py

import GooseEYE
import numpy as np

# generate image, extract 'volume-fraction' for plotting
img = GooseEYE.dummy_circles((500, 500))
phi = np.mean(img)

# 2-point probability for comparison
S2 = GooseEYE.S2((101, 101), img, img)

# determine clusters, based on the binary image
C = GooseEYE.clusters(img)

# 2-point cluster function
C2 = GooseEYE.C2((101, 101), C, C)

C2.cpp

#include <GooseEYE/GooseEYE.h>
#include <highfive/H5Easy.hpp>

#define MYASSERT(expr) MYASSERT_IMPL(expr, __FILE__, __LINE__)
#define MYASSERT_IMPL(expr, file, line) \
    if (!(expr)) { \
        throw std::runtime_error( \
            std::string(file) + ':' + std::to_string(line) + \
            ": assertion failed (" #expr ") \n\t"); \
    }

int main()
{
    // generate image
    auto I = GooseEYE::dummy_circles({500, 500});

    // determine clusters, based on the binary image
    auto C = GooseEYE::clusters(I);

    // 2-point cluster function
    auto C2 = GooseEYE::C2({101, 101}, C, C);

    // check against previous versions
    H5Easy::File data("C2.h5", H5Easy::File::ReadOnly);
    MYASSERT(xt::all(xt::equal(I, H5Easy::load<decltype(I)>(data, "I"))));
    MYASSERT(xt::all(xt::equal(C, H5Easy::load<decltype(C)>(data, "C"))));
    MYASSERT(xt::allclose(C2, H5Easy::load<decltype(C2)>(data, "C2")));

    return 0;
}