Metadata-Version: 2.4
Name: drb-chunk-image
Version: 0.1.0
Summary: GDAL-backed physical chunk model for the drb:image class
Author: GAEL Systems
Author-email: drb-python@gael.fr
License: LGPLv3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Plugins
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Requires-Dist: drb-chunk<1,>=0.5.0
Requires-Dist: rasterio
Requires-Dist: numpy
Dynamic: license-file

# drb-chunk-image

GDAL-backed physical chunk model for the `drb:image` class, built on top of
the [drb-chunk](../../core/README.md) 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

```bash
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:

```python
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`](../../core/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.
