merge

lazymerge.merge

ensure_virtualized

ensure_virtualized(
    source_id: str,
    callback: Callable[[str, SourceEntry, Any, list[str]], None],
    entry: SourceEntry,
    store: Any,
    bands: list[str],
) -> None

Ensure a source is virtualized exactly once, blocking until complete.

merge

merge(
    store: Any,
    crs: str,
    bbox: tuple[float, float, float, float],
    resolution: float,
    chunk_size: tuple[int, int] = (512, 512),
    source_index: ScanIndex | None = None,
    resampling: str = "nearest",
    bands: list[str] | str | None = None,
    datafusion: bool = False,
    sortby: str | None = None,
    nodata: float | None = None,
    sql_filter: str | None = None,
    dtype: str = "float32",
    temporal_grouping: str | None = None,
    virtualize: Callable[[str, SourceEntry, Any, list[str]], None]
    | None = None,
) -> tuple[Array, SpatialAttrs, ProjAttrs, ndarray | None]

Lazily merge geospatial Zarr arrays into a single target grid.

Defines a target grid from the given CRS, bounding box, and resolution, then returns a lazy Cubed array. No data is read until .compute() is called -- at that point only the source regions that intersect each output chunk are fetched, reprojected, and composited.

Parameters:

• store (Any) –

  Zarr-compatible store (e.g. LocalStore, S3Store, IcechunkStore) containing the source arrays.

• crs (str) –

  Target CRS as an EPSG string (e.g. "EPSG:32618").

• bbox (tuple[float, float, float, float]) –

  Target bounding box (xmin, ymin, xmax, ymax) in the target CRS.

• resolution (float) –

  Target pixel size in the target CRS units.

• chunk_size (tuple[int, int], default: (512, 512) ) –

  (rows, cols) chunk dimensions for the output array.

• source_index (ScanIndex | None, default: None ) –

  Pre-built in-memory index from scan_store(). Mutually exclusive with datafusion=True.

• resampling (str, default: 'nearest' ) –

  Resampling method ("nearest").

• bands (list[str] | str | None, default: None ) –

  Band name(s) to merge. A single string produces a 2-D (y, x) output; a list produces a 3-D (band, y, x) output.

• datafusion (bool, default: False ) –

  If True, discover sources via DataFusion SQL queries against a /meta group in the store.

• sortby (str | None, default: None ) –

  Column name to sort DataFusion results by (e.g. "datetime"). Controls compositing priority -- earlier entries take precedence.

• nodata (float | None, default: None ) –

  Source nodata value. Pixels equal to this value are treated as transparent during compositing.

• sql_filter (str | None, default: None ) –

  Additional SQL predicate appended to the DataFusion query (e.g. '"eo:cloud_cover" < 20').

• dtype (str, default: 'float32' ) –

  NumPy dtype string for the output array.

• temporal_grouping (str | None, default: None ) –

  ISO 8601 duration string for time-based binning (e.g. "P1D", "P1M"). Requires datafusion=True. Adds a leading time dimension to the output.

• virtualize (Callable[[str, SourceEntry, Any, list[str]], None] | None, default: None ) –

  Optional callback that virtualizes a source on-the-fly before its data is read. Called once per source with signature (source_id, entry, store, bands). Use :func:~lazymerge.virtualize.default_virtualizer to create a callback that converts COGs to virtual Zarr references via VirtualiZarr.

Returns:

• tuple[Array, SpatialAttrs, ProjAttrs, ndarray | None] –

  A tuple of (result, spatial_attrs, proj_attrs, time_coords) where result is a lazy Cubed array, spatial_attrs and proj_attrs describe the target grid, and time_coords is an array of datetime64 values (or None if temporal grouping is not used).