healpix_analyse.components ========================== .. py:module:: healpix_analyse.components .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: healpix_analyse.components.torch Functions --------- .. autoapisummary:: healpix_analyse.components.connected_components healpix_analyse.components.component_size healpix_analyse.components.healpix_cell_area healpix_analyse.components.component_area healpix_analyse.components.remove_small_components Module Contents --------------- .. py:data:: torch :value: None .. py:function:: 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) 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: * :py:class:`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** (:py:class:`int`) -- Number of foreground components. .. admonition:: Notes This operation is discrete and non-differentiable. Torch inputs are accepted, processed internally on CPU, and returned on the original device. .. py:function:: component_size(labels: numpy.typing.ArrayLike) 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. .. admonition:: Example For:: labels = [1, 1, 0, 2, 2, 2] the result is:: [0, 2, 3] .. py:function:: healpix_cell_area(refinement_level: int, *, ellipsoid: str = 'WGS84') -> float 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. .. py:function:: component_area(labels: numpy.typing.ArrayLike, refinement_level: int, *, ellipsoid: str = 'WGS84') 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 .. py:function:: 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') 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: :py:class:`numpy.ndarray` or :py:class:`torch.Tensor` -- Boolean mask after removing components below the selected threshold.