drb-chunk-image 0.1.0

GDAL-backed physical chunk model for the drb:image class

drb-chunk-image

GDAL-backed physical chunk model for the drb:image class, built on top of the drb-chunk add-on.

What it is

drb-chunk-image teaches drb-chunk how to read a GDAL raster (GeoTIFF, BigTIFF, COG, JP2, PNG, and any other format GDAL/rasterio can open) on its native block boundaries instead of on whatever grid a product descriptor happens to declare. It targets the generic drb:image topic class, not a single product family — it is the first format chunk add-on, sibling to the product-specific ones (drb-chunk-sentinel1, drb-chunk-sentinel2).

Concretely, it registers a PhysicalTilingProvider (gdal-blocks) that probes a raster's block layout — tile shape if the file is internally tiled, strip shape otherwise — via rasterio, without loading the full raster.

How it self-activates

Installing the package is enough; there is no product-side wiring:

• It registers GdalBlocksProvider under the drb.chunk.physical entry-point group (drb.addons.chunk.image.provider:GdalBlocksProvider), the seam the drb-chunk core uses to discover physical-tiling providers lazily, and a matching raster physical reader via register_physical_reader.
• It ships a cortex.ttl carrying a single triple — <http://www.gael.fr/drb#image> drb:physicalTiling "gdal-blocks" — declared under the drb.topic entry-point group. The core's ManagerDao merges every installed drb.topic descriptor into one RDF graph, so this triple lands on the existing drb:image topic without touching the driver or any other package.

Once both are installed, any chunk descriptor whose drb:source resolves to a GDAL-readable file automatically gets a physical chunk model: the core resolves the source's format topic, reads drb:physicalTiling, looks up gdal-blocks, and calls probe().

The two-layer model

drb-chunk separates the physical chunk model — the source's native chunking, discovered (never declared), the unit of I/O this add-on provides — from the logical chunk model — the output representation a product chunk declares (a regular N-D grid today; burst, and later healpix, for other formats). A chunk descriptor with no declared logical geometry (drb:chunkShape/drb:tilingScheme) simply adopts the physical grid as its logical grid. A descriptor that declares its own grid (e.g. a Sentinel-2 512×512 tile over a 1024×1024-tiled JP2) keeps that logical grid, but reads are still issued on the physical boundaries and remapped into the requested logical window — so adjacent logical tiles that share a native block only pay for that block once. probe() also accepts a multiplier (default 1), reserved for a future drb:nativeMultiplier descriptor predicate to request an exact multiple of the native block as the physical unit; it is not wired into the engine yet in this release. For untiled rasters (strips), the provider falls back to the strip band shape (rows_per_strip × width) — there is no "tile" to multiply.

Installation

pip install drb-chunk-image

Requires drb-chunk>=0.4.0,<1, rasterio and numpy (installed as dependencies).

Usage

No API of its own to call — once installed alongside drb-chunk, any product add-on's Chunk.select(...) over a GDAL-backed source picks up the physical model transparently:

from drb.topics import resolver
from drb.addons.addon import AddonManager
from drb.chunk.selection import WindowSelection

topic, node = resolver.resolve("/path/to/product.SAFE")
addon = AddonManager().get_addon("chunk")

chunk = addon.apply(node, chunk_name="B04_10m")   # e.g. drb-chunk-sentinel2
window = WindowSelection(x=0, y=0, w=512, h=512)
array = chunk.select(window).get_impl(numpy.ndarray)

Reads over B04_10m above are issued on the JP2's native block boundaries (e.g. 192×192), cached per source node, and remapped into the requested 512×512 window — not read once per 512×512 tile.

Limitations

• Read-only probing: this add-on discovers the native chunking, it does not write or re-tile rasters.
• Single reference band: block shape is probed from band 1 (ds.block_shapes[0]); mixed per-band block layouts are not modelled.
• drb:nativeMultiplier is a reserved predicate, not yet read by the core engine — probe(node, multiplier=1) only ever runs with the default today.

Reference

See docs/dev/writing-a-physical-tiling-provider.md in drb-chunk for the PhysicalTilingProvider contract and how to write a provider for another format; this add-on is the reference implementation.