healpix_analyse.components#

Connected-component analysis for NESTED HEALPix masks.

This module implements generic connected-component operations on binary fields defined over HEALPix cells.

Only NESTED HEALPix indexing is currently supported.

Connectivity#

Two HEALPix connectivity definitions are supported.

"edge"

Cells are connected only when they share a HEALPix cell edge.

This is the HEALPix analogue of Cartesian 4-connectivity.

"edge_or_vertex"

Cells are connected when they share either a HEALPix edge or vertex.

This is the HEALPix analogue of Cartesian 8-connectivity.

These are semantic correspondences: HEALPix is not a Cartesian square grid.

Topology backend#

Immediate-neighbour lookup is delegated to the private healpix_analyse._topology module.

That module currently uses healpy as a temporary compatibility backend. It is intended to move to healpix-geo / CDSHEALPix once directional neighbour access becomes available there.

Torch#

NumPy arrays and PyTorch tensors are accepted.

Connected-component analysis is a discrete operation and is therefore not differentiable. Torch inputs are processed on CPU internally and returned on the original device.

Attributes#

torch

Functions#

connected_components(mask, cell_ids, refinement_level, *)

Label connected foreground regions of a NESTED HEALPix mask.

component_size(labels)

Return the number of HEALPix cells in each component.

healpix_cell_area(→ float)

Return the equal HEALPix cell area in square metres.

component_area(labels, refinement_level, *[, ellipsoid])

Return the physical area of each component in square metres.

remove_small_components(mask, cell_ids, ...[, ...])

Remove connected components smaller than a threshold.

Module Contents#

healpix_analyse.components.torch = None#
healpix_analyse.components.connected_components(mask: numpy.typing.ArrayLike, cell_ids: numpy.typing.ArrayLike, refinement_level: int, *, connectivity: healpix_analyse._topology.Connectivity = 'edge', domain: numpy.typing.ArrayLike | None = None)[source]#

Label connected foreground regions of a NESTED HEALPix mask.

Parameters:

  • mask – One-dimensional boolean mask.

    True indicates foreground/active cells.

  • cell_ids – NESTED HEALPix cell identifier corresponding to each mask value.

  • refinement_level – HEALPix refinement level.

  • connectivity –

    "edge"

    Connect cells sharing a HEALPix edge only.

    "edge_or_vertex"

    Connect cells sharing either an edge or a vertex.

  • domain – Optional subset of cell_ids defining the valid processing topology.

    domain=None means domain=cell_ids.

    Cells outside the domain are absent from the graph. Connectivity must never pass through them.

    Output order follows the exact domain order.

Returns:

  • labels – Integer component labels in output-domain order.

    0 denotes background.

    Foreground components are numbered 1, 2, ....

    Component numbering is deterministic and follows the first foreground cell encountered in domain order.

  • n_components (int) – Number of foreground components.

Notes

This operation is discrete and non-differentiable.

Torch inputs are accepted, processed internally on CPU, and returned on the original device.

healpix_analyse.components.component_size(labels: numpy.typing.ArrayLike)[source]#

Return the number of HEALPix cells in each component.

The returned array is indexed directly by component label.

sizes[0] is always zero because label zero represents background.

Example

For:

labels = [1, 1, 0, 2, 2, 2]

the result is:

[0, 2, 3]
healpix_analyse.components.healpix_cell_area(refinement_level: int, *, ellipsoid: str = 'WGS84') → float[source]#

Return the equal HEALPix cell area in square metres.

At one refinement level all HEALPix cells have equal area.

The selected ellipsoid’s total surface area is divided by:

12 * nside**2

where:

nside = 2**refinement_level

For the Sentinel-2 HEALPix processing chain, WGS84 is the intended reference ellipsoid.

healpix_analyse.components.component_area(labels: numpy.typing.ArrayLike, refinement_level: int, *, ellipsoid: str = 'WGS84')[source]#

Return the physical area of each component in square metres.

The returned array is indexed by component label.

areas[0] is always zero.

Because HEALPix cells at one refinement level are equal-area:

component area
    =
component cell count * HEALPix cell area
healpix_analyse.components.remove_small_components(mask: numpy.typing.ArrayLike, cell_ids: numpy.typing.ArrayLike, refinement_level: int, *, min_cells: int | None = None, min_area_m2: float | None = None, connectivity: healpix_analyse._topology.Connectivity = 'edge', domain: numpy.typing.ArrayLike | None = None, ellipsoid: str = 'WGS84')[source]#

Remove connected components smaller than a threshold.

Exactly one threshold must be supplied:

min_cells

Minimum number of HEALPix cells.

min_area_m2

Minimum physical component area in square metres.

Parameters:

  • mask – Binary foreground mask.

  • cell_ids – NESTED HEALPix cell ids corresponding to mask.

  • refinement_level – HEALPix refinement level.

  • min_cells – Minimum component size in cells.

  • min_area_m2 – Minimum component area in square metres.

  • connectivity – "edge" or "edge_or_vertex".

  • domain – Optional processing domain.

    Output follows exact domain order.

  • ellipsoid – Reference ellipsoid used for physical-area thresholds. Default is "WGS84".

Returns:

numpy.ndarray or torch.Tensor – Boolean mask after removing components below the selected threshold.