easy-eo 0.4.0__tar.gz → 0.4.2__tar.gz

{easy_eo-0.4.0 → easy_eo-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easy-eo
-Version: 0.4.0
+Version: 0.4.2
 Summary: A lightweight Earth Observation utilities library for chainable raster operations
 Project-URL: Homepage, https://github.com/tommy-burns/easy-eo
 Project-URL: Repository, https://github.com/tommy-burns/easy-eo

{easy_eo-0.4.0 → easy_eo-0.4.2}/eeo/__init__.py

@@ -40,4 +40,4 @@ __all__ = [
     "MissingDependencyError",
 ]
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"

{easy_eo-0.4.0 → easy_eo-0.4.2}/eeo/analysis/indices.py

@@ -27,12 +27,8 @@ here: any normalized-difference index can be expressed with it directly.
 import numpy as np
 import rasterio as rio
 
-from eeo.common import (
-    align_raster_to_target,
-    apply_nodata_contract,
-    get_nodata,
-    resolve_band_index,
-)
+from eeo.common import align_raster_to_target, resolve_band_index
+from eeo.core.blockwise import BlockSource, apply_blockwise
 from eeo.core.core import EEORasterDataset
 from eeo.core.decorators import eeo_raster_op
 from eeo.core.exceptions import AlignmentError, ValidationError
@@ -57,15 +53,15 @@ def _safe_ratio(numerator, denominator):
     return np.where(denominator != 0, quotient, np.float32(0)).astype(rio.float32)
 
 
-def _resolve_band(ds, spec, *, auto_align, method):
-    """Resolve a band spec to ``(band_float32, band_raw, nodata)``.
+def _resolve_band(ds, spec, *, auto_align, method) -> BlockSource:
+    """Resolve a band spec to the :class:`BlockSource` that reads it.
 
     ``spec`` is a 1-based ``int`` band index into ``ds``, the ``str`` name of
     one of ``ds``'s bands, or a separate ``EEORasterDataset`` (its first band
     is used, aligned onto ``ds``'s grid when ``auto_align`` is True). Index and
     name specs both go through the shared resolver, so a string is always a
-    name and never an index. ``band_raw`` keeps its source dtype so the nodata
-    mask compares against the declared sentinel exactly.
+    name and never an index. The source reads the band in its own dtype, so
+    the nodata mask compares against the declared sentinel exactly.
     """
     if isinstance(spec, EEORasterDataset):
         other = spec
@@ -76,56 +72,35 @@ def _resolve_band(ds, spec, *, auto_align, method):
                 raise AlignmentError(
                     _ALIGN_MISMATCH.format(other=other.get_shape(), ds=ds.get_shape())
                 )
-        raw = other.get_band(1)
-        nodata = get_nodata(other)
-    elif isinstance(spec, (int, str)) and not isinstance(spec, bool):
-        raw = ds.get_band(resolve_band_index(ds, spec))
-        nodata = get_nodata(ds)
-    else:
-        raise ValidationError(
-            "band must be an EEORasterDataset, a 1-based int band index, or a "
-            f"band name; got {type(spec).__name__}"
-        )
-    return raw.astype(rio.float32), raw, nodata
+        return BlockSource.from_dataset(other, band=1)
+    if isinstance(spec, (int, str)) and not isinstance(spec, bool):
+        return BlockSource.from_dataset(ds, band=resolve_band_index(ds, spec))
+    raise ValidationError(
+        "band must be an EEORasterDataset, a 1-based int band index, or a "
+        f"band name; got {type(spec).__name__}"
+    )
 
 
 def _compute_index(ds, band_specs, formula, *, auto_align, method, name=None):
-    """Resolve band specs, apply ``formula``, and package the float32 result.
+    """Resolve band specs, apply ``formula`` block-wise, and package the result.
 
     ``band_specs`` is the ordered list of band specs; the first is the primary
-    band. ``formula`` maps the list of float32 band arrays to a 2D result. The
-    result is masked per the nodata contract (contagious across every band) and
-    returned as a single-band float32 ``EEORasterDataset`` whose band carries
-    ``name`` (unnamed when ``name`` is None).
+    band. ``formula`` maps the list of float32 band arrays to a 2D result, and
+    is called once per window rather than once over the whole scene, so an
+    index never holds more than a block of each band in memory. The result is
+    masked per the nodata contract (contagious across every band) and returned
+    as a single-band float32 ``EEORasterDataset`` whose band carries ``name``
+    (unnamed when ``name`` is None).
     """
     ds = ds.to_rasterio()
-    resolved = [
-        _resolve_band(ds, spec, auto_align=auto_align, method=method) for spec in band_specs
-    ]
-    floats = [band for band, _raw, _nodata in resolved]
-    operands = [(raw, nodata) for _band, raw, nodata in resolved]
-    primary_nodata = resolved[0][2]
+    sources = [_resolve_band(ds, spec, auto_align=auto_align, method=method) for spec in band_specs]
 
-    result = formula(floats)
+    def compute(*blocks):
+        # The formulas are written against float32 bands; the engine masks
+        # against these raw blocks, which keep their source dtype.
+        return formula([block.astype(rio.float32) for block in blocks])
 
-    index, out_nodata = apply_nodata_contract(
-        result, operands, fractional=True, ds_nodata=primary_nodata
-    )
-
-    data = index[np.newaxis, ...] if index.ndim == 2 else index
-    meta = ds.get_metadata().copy()
-    meta.update(
-        driver="GTiff",
-        dtype="float32",
-        nodata=out_nodata,
-        height=data.shape[-2],
-        width=data.shape[-1],
-        count=data.shape[0],
-    )
-    memfile = rio.io.MemoryFile()
-    out_ds = memfile.open(**meta)
-    out_ds.write(data)
-    result = EEORasterDataset.from_rasterio(out_ds)
+    result = apply_blockwise(ds, compute, sources=sources, fractional=True)
     if name is not None:
         result.set_band_name(1, name)
     return result
@@ -189,7 +164,6 @@ def normalized_difference(
 
     Notes
     -----
-    Reads both rasters fully into memory rather than streaming block-wise.
     Nodata pixels are masked before the ratio; separately, a zero denominator
     (``ds + other == 0``) is guarded by setting those pixels to 0.
 
@@ -205,38 +179,19 @@ def normalized_difference(
         else:
             raise AlignmentError(_ALIGN_MISMATCH.format(other=other.get_shape(), ds=ds.get_shape()))
 
-    ds_nodata = get_nodata(ds)
-    other_nodata = get_nodata(other)
-    a_raw = ds.read()
-    b_raw = other.read()
-    a = a_raw.astype(rio.float32)
-    b = b_raw.astype(rio.float32)
+    def difference(a_block, b_block):
+        # Masking is the engine's job and happens after this returns, so a
+        # masked pixel is NaN regardless of the ratio computed for it here.
+        a = a_block.astype(rio.float32)
+        b = b_block.astype(rio.float32)
+        return _safe_ratio(a - b, a + b)
 
-    nd = _safe_ratio(a - b, a + b)
-
-    # Mask nodata last so a masked pixel is NaN regardless of its ratio.
-    nd, out_nodata = apply_nodata_contract(
-        nd,
-        [(a_raw, ds_nodata), (b_raw, other_nodata)],
+    result = apply_blockwise(
+        ds,
+        difference,
+        sources=[BlockSource.from_dataset(ds), BlockSource.from_dataset(other)],
         fractional=True,
-        ds_nodata=ds_nodata,
     )
-
-    meta = ds.get_metadata().copy()
-    meta.update(
-        driver="GTiff",
-        dtype="float32",
-        nodata=out_nodata,
-        height=nd.shape[-2],
-        width=nd.shape[-1],
-        count=nd.shape[0],
-    )
-
-    memfile = rio.io.MemoryFile()
-    out_ds = memfile.open(**meta)
-    out_ds.write(nd)
-
-    result = EEORasterDataset.from_rasterio(out_ds)
     if name is not None:
         if result.get_count() != 1:
             raise ValidationError(
@@ -309,11 +264,6 @@ def ndvi(
         If a band argument is not an ``EEORasterDataset``, an int index, or a
         band name, or if a band name is unknown or matches more than one band.
 
-    Notes
-    -----
-    Reads the required bands fully into memory rather than streaming
-    block-wise.
-
     Examples
     --------
     >>> ndvi = nir_ds.ndvi(red_ds)          # separate band rasters
@@ -393,9 +343,7 @@ def ndwi(
 
     Notes
     -----
-    Reads the required bands fully into memory rather than streaming
-    block-wise. This is McFeeters' water NDWI; the moisture variant is
-    :meth:`ndmi`.
+    This is McFeeters' water NDWI; the moisture variant is :meth:`ndmi`.
 
     Examples
     --------
@@ -475,8 +423,7 @@ def ndmi(
 
     Notes
     -----
-    Reads the required bands fully into memory rather than streaming
-    block-wise. Sentinel-2's SWIR1 (B11) is 20 m; pass ``auto_align=True``
+    Sentinel-2's SWIR1 (B11) is 20 m; pass ``auto_align=True``
     (the default) to resample it onto a 10 m NIR grid.
 
     Examples
@@ -558,8 +505,7 @@ def ndbi(
 
     Notes
     -----
-    Reads the required bands fully into memory rather than streaming
-    block-wise. Sentinel-2's SWIR1 (B11) is 20 m; pass ``auto_align=True``
+    Sentinel-2's SWIR1 (B11) is 20 m; pass ``auto_align=True``
     (the default) to resample it onto a 10 m NIR grid.
 
     Examples
@@ -648,11 +594,6 @@ def evi(
         If a band argument is not an ``EEORasterDataset``, an int index, or a
         band name, or if a band name is unknown or matches more than one band.
 
-    Notes
-    -----
-    Reads the required bands fully into memory rather than streaming
-    block-wise.
-
     Examples
     --------
     >>> evi = nir_ds.evi(red_ds, blue_ds)             # separate band rasters
@@ -740,11 +681,6 @@ def savi(
         If a band argument is not an ``EEORasterDataset``, an int index, or a
         band name, or if a band name is unknown or matches more than one band.
 
-    Notes
-    -----
-    Reads the required bands fully into memory rather than streaming
-    block-wise.
-
     Examples
     --------
     >>> savi = nir_ds.savi(red_ds, soil_factor=0.5)   # separate band rasters

{easy_eo-0.4.0 → easy_eo-0.4.2}/eeo/analysis/stats.py

@@ -1,14 +1,71 @@
-"""Per-pixel statistics and coordinate sampling."""
+"""Per-pixel statistics and coordinate sampling.
+
+Each of these reports a value *and* where it occurs, which is why they stream
+rather than reduce: the value comes from a streaming reduction over the band
+(:mod:`eeo.core.streaming`), and a second streaming pass finds the pixel that
+carries it. Memory is bounded by the block in both, so a statistic can be taken
+over a scene far larger than memory.
+
+Ties are broken exactly as ``numpy.nanargmin`` breaks them — first in
+row-major order — regardless of how the raster happens to be cut into blocks,
+so a position never depends on the block shape.
+"""
 
 import numpy as np
+from rasterio.windows import Window
 
-from eeo.common import get_nodata, mask_nodata
+from eeo.common import get_nodata, resolve_band_index
 from eeo.core.core import EEORasterDataset
 from eeo.core.decorators import eeo_raster_op
 from eeo.core.exceptions import ValidationError
+from eeo.core.streaming import stream_windows, valid_mean_std, valid_percentiles
 
 Coordinate = tuple[float, float] | list[float]
 
+_NO_VALID_PIXELS = "band {band} has no valid pixels, so {what} is undefined"
+
+
+def _locate(ds, band_idx, score, what):
+    """Stream the band and return ``(value, row, col)`` minimising ``score``.
+
+    ``score`` maps a block of pixels to a block of comparison values; the
+    smallest wins. Because a block is a contiguous rectangle, block-local
+    row-major order agrees with global row-major order inside it, so taking
+    the first minimum per block and then breaking ties on ``(row, col)``
+    reproduces ``numpy.nanargmin`` over the whole band for any block shape.
+
+    Returns the *pixel's* value, not its score, so a caller searching for the
+    pixel nearest a target gets the measurement rather than the distance.
+    """
+    band = resolve_band_index(ds, band_idx)
+    best = None
+    for window, block, valid in stream_windows(ds, band):
+        if not valid.any():
+            continue
+        # Score in float64, never in the block's own dtype: negating a uint8
+        # or uint16 block to turn a maximum into a minimum wraps instead of
+        # changing sign, which silently returns the *smallest* pixel whenever
+        # the band contains a zero.
+        scored = np.where(valid, score(block.astype(np.float64)), np.inf)
+        flat = int(np.argmin(scored))
+        local_row, local_col = np.unravel_index(flat, scored.shape)
+        row = int(window.row_off) + int(local_row)
+        col = int(window.col_off) + int(local_col)
+        candidate = (float(scored[local_row, local_col]), row, col)
+        if best is None or candidate < best[:3]:
+            best = (*candidate, block[local_row, local_col])
+    if best is None:
+        raise ValidationError(_NO_VALID_PIXELS.format(band=band_idx, what=what))
+    _score, row, col, value = best
+    return value, row, col
+
+
+def _position(ds, row, col, as_pixel_coordinate):
+    """Render a pixel location as ``(row, col)`` or as world coordinates."""
+    if as_pixel_coordinate:
+        return (row, col)
+    return ds.get_transform() * (col, row)
+
 
 @eeo_raster_op
 def extract_value_at_coordinate(
@@ -45,8 +102,9 @@ def extract_value_at_coordinate(
 
     Notes
     -----
-    Reads the selected band into memory. Coordinates are ``(x, y)`` in CRS
-    units, distinct from the ``(row, col)`` pixel indexing used elsewhere.
+    Reads a single pixel, not the band: sampling one location never costs the
+    scene. Coordinates are ``(x, y)`` in CRS units, distinct from the
+    ``(row, col)`` pixel indexing used elsewhere.
 
     Examples
     --------
@@ -67,7 +125,10 @@ def extract_value_at_coordinate(
     row, col = backend.index(x, y)
     row, col = int(row), int(col)
 
-    value = ds.get_band(band_idx)[row, col]
+    # A 1x1 window, so sampling a point in a 10980x10980 scene reads one
+    # pixel rather than the 241 MB band around it.
+    window = Window(col, row, 1, 1)
+    value = ds.read(resolve_band_index(ds, band_idx), window=window)[0, 0]
 
     # Report nodata as NaN rather than the raw pixel value, so a fill value that
     # sits near real measurements is never mistaken for one.
@@ -118,26 +179,22 @@ def get_maximum_pixel(
 
     Notes
     -----
-    Reads the band into memory. Nodata pixels are masked to NaN and ignored.
+    Streams the band block by block, so memory is bounded by the block rather
+    than the band. Nodata pixels are excluded.
 
     Examples
     --------
     >>> peak = ds.get_maximum_pixel()
     >>> peak["value"], peak["position"]
     """
-    band = mask_nodata(ds, ds.get_band(band_idx))
-
-    # get max value
-    value = float(np.nanmax(band))
-    row, col = np.unravel_index(np.nanargmax(band), band.shape)
-
-    if return_position_as_pixel_coordinate:
-        position = (row, col)
-    else:
-        transform = ds.get_transform()
-        position = transform * (col, row)
-
-    return {"value": value, "position": position}
+    ds = ds.to_rasterio()
+    # Negating turns the search for a maximum into the same minimisation the
+    # other three do, tie-breaking included.
+    value, row, col = _locate(ds, band_idx, lambda block: -block, "a maximum")
+    return {
+        "value": float(value),
+        "position": _position(ds, row, col, return_position_as_pixel_coordinate),
+    }
 
 
 @eeo_raster_op
@@ -178,26 +235,21 @@ def get_minimum_pixel(
 
     Notes
     -----
-    Reads the band into memory. Nodata pixels are masked to NaN and ignored.
+    Streams the band block by block in two passes — one to measure, one to
+    locate — so memory is bounded by the block rather than the band. Nodata
+    pixels are excluded from both.
 
     Examples
     --------
     >>> low = ds.get_minimum_pixel()
     >>> low["value"], low["position"]
     """
-    band = mask_nodata(ds, ds.get_band(band_idx))
-
-    # get min value
-    value = float(np.nanmin(band))
-    row, col = np.unravel_index(np.nanargmin(band), band.shape)
-
-    if return_position_as_pixel_coordinate:
-        position = (row, col)
-    else:
-        transform = ds.get_transform()
-        position = transform * (col, row)
-
-    return {"value": value, "position": position}
+    ds = ds.to_rasterio()
+    value, row, col = _locate(ds, band_idx, lambda block: block, "a minimum")
+    return {
+        "value": float(value),
+        "position": _position(ds, row, col, return_position_as_pixel_coordinate),
+    }
 
 
 @eeo_raster_op
@@ -239,27 +291,22 @@ def get_mean_pixel(
 
     Notes
     -----
-    Reads the band into memory. Nodata pixels are masked to NaN and ignored.
+    Streams the band block by block in two passes — one to measure, one to
+    locate — so memory is bounded by the block rather than the band. Nodata
+    pixels are excluded from both.
 
     Examples
     --------
     >>> centre = ds.get_mean_pixel()
     >>> centre["value"], centre["position"]
     """
-    band = mask_nodata(ds, ds.get_band(band_idx))
-
-    mean_value = float(np.nanmean(band))
-    diff = np.abs(band - mean_value)
-
-    row, col = np.unravel_index(np.nanargmin(diff), diff.shape)
-
-    if return_position_as_pixel_coordinate:
-        position = (row, col)
-    else:
-        transform = ds.get_transform()
-        position = transform * (col, row)
-
-    return {"value": mean_value, "position": position}
+    ds = ds.to_rasterio()
+    mean_value, _std = valid_mean_std(ds, resolve_band_index(ds, band_idx))
+    _value, row, col = _locate(ds, band_idx, lambda block: np.abs(block - mean_value), "a mean")
+    return {
+        "value": mean_value,
+        "position": _position(ds, row, col, return_position_as_pixel_coordinate),
+    }
 
 
 @eeo_raster_op
@@ -304,24 +351,21 @@ def get_percentile_pixel(
 
     Notes
     -----
-    Reads the band into memory. Nodata pixels are masked to NaN and ignored.
+    Streams the band block by block in two passes — one to measure, one to
+    locate — so memory is bounded by the block rather than the band. Nodata
+    pixels are excluded from both.
 
     Examples
     --------
     >>> p95 = ds.get_percentile_pixel(95)
     >>> p95["value"], p95["position"]
     """
-    band = mask_nodata(ds, ds.get_band(band_idx))
-
-    perc_value = float(np.nanpercentile(band, percentile))
-    diff = np.abs(band - perc_value)
-
-    row, col = np.unravel_index(np.nanargmin(diff), diff.shape)
-
-    if return_position_as_pixel_coordinate:
-        position = (row, col)
-    else:
-        transform = ds.get_transform()
-        position = transform * (col, row)
-
-    return {"value": perc_value, "position": position}
+    ds = ds.to_rasterio()
+    (perc_value,) = valid_percentiles(ds, (percentile,), resolve_band_index(ds, band_idx))
+    _value, row, col = _locate(
+        ds, band_idx, lambda block: np.abs(block - perc_value), "a percentile"
+    )
+    return {
+        "value": perc_value,
+        "position": _position(ds, row, col, return_position_as_pixel_coordinate),
+    }

{easy_eo-0.4.0 → easy_eo-0.4.2}/eeo/common.py

@@ -19,12 +19,11 @@ def is_rasterio_backed(ds: EEORasterDataset) -> bool:
     """Return True if ``ds`` is backed by the rasterio adapter.
 
     Detection is based on the adapter type, not the class of the backend
-    object. A rasterio-backed dataset's ``backend`` may be a
-    ``rasterio.io.DatasetReader`` (opened from a file) or a
-    ``rasterio.io.DatasetWriter`` (produced in memory by an operation, e.g.
-    the result of any algebra op or ``to_rasterio()``); both are valid
-    rasterio backends. Checking ``isinstance(backend, DatasetReader)`` misses
-    the writer case and wrongly rejects genuinely rasterio-backed datasets.
+    object. A rasterio-backed dataset's ``backend`` is usually a
+    ``rasterio.io.DatasetReader`` — from a file, or an in-memory result, which
+    the library reopens read-only — but a ``rasterio.io.DatasetWriter`` wrapped
+    with ``EEORasterDataset.from_rasterio`` is equally valid. Checking
+    ``isinstance(backend, DatasetReader)`` would wrongly reject that case.
 
     Parameters
     ----------
@@ -164,7 +163,7 @@ def _declared_nodata_mask(array, nodata):
     return array == nodata
 
 
-def _output_dtype(result, *, fractional: bool):
+def resolve_output_dtype(result, *, fractional: bool):
     """Return the output dtype for a pixel-wise result per the dtype policy.
 
     Fractional-result ops are always float32. Exact arithmetic keeps the
@@ -178,63 +177,85 @@ def _output_dtype(result, *, fractional: bool):
     return dtype
 
 
-def apply_nodata_contract(result, operands, *, fractional: bool, ds_nodata):
-    """Apply the library nodata & dtype contract to a pixel-wise result.
+def _combined_nodata_mask(operands):
+    """Boolean mask of pixels that are nodata in any operand, or None if none are.
+
+    Nodata is contagious: the masks of every operand that declares one are
+    OR-ed together. Returns None when no operand declares a nodata value,
+    which is the same condition as the contract producing no output nodata.
+    """
+    combined = None
+    for array, nodata in operands:
+        mask = _declared_nodata_mask(array, nodata)
+        if mask is None:
+            continue
+        combined = mask if combined is None else (combined | mask)
+    return combined
 
-    Masks the pixels that are nodata in any operand (nodata is contagious),
-    casts to the contract's output dtype, and reports the nodata value to
-    record in the output metadata.
+
+def resolve_output_nodata(operand_nodatas, *, out_dtype, ds_nodata):
+    """Return the nodata value a pixel-wise result should record, or None.
+
+    Decided from declared nodata values and the output dtype alone — no pixel
+    data — so a block-wise operation can fix one nodata value for the whole
+    output before reading the first block.
 
     Parameters
     ----------
-    result : array-like
-        Values computed over every pixel. Nodata pixels are overwritten here,
-        so computing them first (then masking) is equivalent to masking first
-        for element-wise operations.
-    operands : list of tuple
-        ``(array, nodata)`` for each raster operand; scalar operands are
-        omitted since they carry no nodata.
-    fractional : bool
-        True for operations whose result is inherently fractional (float32
-        output regardless of input dtype).
+    operand_nodatas : iterable
+        Declared nodata value (or None) of each raster operand.
+    out_dtype : numpy.dtype
+        Dtype the output will be written in.
     ds_nodata : int, float, or None
         The primary operand's declared nodata, used as the sentinel for
         integer outputs.
 
     Returns
     -------
-    tuple
-        ``(final_array, out_nodata)`` — the masked, correctly typed array and
-        the nodata value for the output metadata (``float('nan')`` for
-        floating outputs, the integer sentinel for integer outputs, or None
-        when no operand declares nodata).
+    float or int or None
+        ``float('nan')`` for floating outputs, the integer sentinel for
+        integer outputs, or None when no operand declares nodata.
     """
-    out_dtype = _output_dtype(result, fractional=fractional)
-    is_float_out = np.issubdtype(out_dtype, np.floating)
+    declared = [nodata for nodata in operand_nodatas if nodata is not None]
+    if not declared:
+        # No operand declared nodata: every pixel is valid, nothing to record.
+        return None
+    if np.issubdtype(out_dtype, np.floating):
+        return float("nan")
+    sentinel = ds_nodata if ds_nodata is not None else declared[0]
+    return np.array(sentinel, dtype=out_dtype).item()
 
-    combined = None
-    declared = []
-    for array, nodata in operands:
-        if nodata is not None:
-            declared.append(nodata)
-        mask = _declared_nodata_mask(array, nodata)
-        if mask is None:
-            continue
-        combined = mask if combined is None else (combined | mask)
 
-    result = result.astype(out_dtype)
+def apply_nodata_mask(result, operands, *, out_dtype, out_nodata):
+    """Cast a pixel-wise result to ``out_dtype`` and mark its nodata pixels.
+
+    The dtype and nodata value are supplied rather than derived, so every
+    block of a block-wise run lands in the same dtype and uses the same
+    marker even when a block happens to contain no nodata pixels at all.
 
+    Parameters
+    ----------
+    result : array-like
+        Values computed over every pixel of the block.
+    operands : list of tuple
+        ``(array, nodata)`` for each raster operand, over the same pixels as
+        ``result``; scalar operands are omitted since they carry no nodata.
+    out_dtype : numpy.dtype
+        Dtype to cast the result to.
+    out_nodata : float, int, or None
+        Marker written into nodata pixels, from :func:`resolve_output_nodata`.
+        None means no operand declares nodata and nothing is masked.
+
+    Returns
+    -------
+    array-like
+        The masked result in ``out_dtype``.
+    """
+    result = result.astype(out_dtype)
+    if out_nodata is None:
+        return result
+    combined = _combined_nodata_mask(operands)
     if combined is None:
-        # No operand declared nodata: nothing to mask, no output nodata.
-        return result, None
-
-    if is_float_out:
-        marker = np.array(np.nan, dtype=out_dtype)
-        out_nodata: float = float("nan")
-    else:
-        sentinel = ds_nodata if ds_nodata is not None else declared[0]
-        marker = np.array(sentinel, dtype=out_dtype)
-        out_nodata = marker.item()
-
-    final = np.where(combined, marker, result).astype(out_dtype)
-    return final, out_nodata
+        return result
+    marker = np.array(out_nodata, dtype=out_dtype)
+    return np.where(combined, marker, result).astype(out_dtype)