Skip to content

Statistics Modules

Function for calculating statistics about a whole image, for example number of grains or surface roughness.

image_statistics(image: npt.NDArray, filename: str, pixel_to_nm_scaling: float, n_grains: int) -> dict[str, int | str | float]

Calculate statistics pertaining to the whole image.

Calculates the size of the image in pixels and metres, the root-mean-squared roughness and the grains per metre squared.

Parameters:

Name Type Description Default
image ndarray

Numpy 2D image array of the image to calculate stats for.

 required
filename str

The name of the file being processed.

 required
pixel_to_nm_scaling float

Float of the scaling factor between pixels and nanometres.

 required
n_grains int

Number of grains in image.

 required

Returns:

Type Description
dict[str, int | str | float]

Dictionary of image statistics.
Source code in topostats\statistics.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def image_statistics(
    image: npt.NDArray, filename: str, pixel_to_nm_scaling: float, n_grains: int
) -> dict[str, int | str | float]:
    """
    Calculate statistics pertaining to the whole image.

    Calculates the size of the image in pixels and metres, the root-mean-squared roughness and the grains per metre
    squared.

    Parameters
    ----------
    image : np.ndarray
        Numpy 2D image array of the image to calculate stats for.
    filename : str
        The name of the file being processed.
    pixel_to_nm_scaling : float
        Float of the scaling factor between pixels and nanometres.
    n_grains : int
        Number of grains in image.

    Returns
    -------
    dict[str, int | str | float]
        Dictionary of image statistics.
    """
    image_stats = {
        "image": filename,
        "image_size_x_m": image.shape[1] * pixel_to_nm_scaling * 1e-9,
        "image_size_y_m": image.shape[0] * pixel_to_nm_scaling * 1e-9,
        "image_area_m2": None,
        "image_size_x_px": image.shape[1],
        "image_size_y_px": image.shape[0],
        "image_area_px2": None,
        "grains": n_grains,
        "grains_per_m2": None,
        "rms_roughness": None,
    }
    # Calculate areas
    image_stats["image_area_m2"] = image_stats["image_size_x_m"] * image_stats["image_size_y_m"]
    image_stats["image_area_px2"] = image_stats["image_size_x_px"] * image_stats["image_size_y_px"]
    # Calculate the RMS roughness of the sample on the flattened image.
    image_stats["rms_roughness"] = roughness_rms(image=image) * 1e-9

    # ns-rse 2025-12-19 Need to reconcile grain density per threshold level, challenging as conceivably there could be >
    # 2
    image_stats["grains_per_m2"] = image_stats["grains"] / image_stats["image_area_m2"]

    return image_stats

roughness_rms(image: np.ndarray) -> float

Calculate the root-mean-square roughness of a heightmap image.

Parameters:

Name Type Description Default
image ndarray

2-D numpy array of heightmap data to calculate roughness.

 required

Returns:

Type Description
float

The RMS roughness of the input array.
Source code in topostats\statistics.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def roughness_rms(image: np.ndarray) -> float:
    """
    Calculate the root-mean-square roughness of a heightmap image.

    Parameters
    ----------
    image : np.ndarray
        2-D numpy array of heightmap data to calculate roughness.

    Returns
    -------
    float
        The RMS roughness of the input array.
    """
    return np.sqrt(np.mean(np.square(image)))