Imagery and geospatial

Two processors handle raster data. image_tiling cuts imagery into tiles you can index and retrieve; vectorize turns a categorical raster into geometry without a model. Both can read a Cloud Optimized GeoTIFF over HTTP range requests, which is what makes them usable against imagery far too large to move.

Why COG streaming matters

A GeoTIFF of a satellite scene is routinely tens of gigabytes. Downloading it to index a 512-pixel tile is absurd, and in many deployments impossible — the data cannot leave its bucket, its region, or its building.

A Cloud Optimized GeoTIFF is laid out so that its header tells you where every tile lives in the file. Combined with HTTP range requests, that means fetching only the bytes you actually need:

   ┌──────────────────────────────────────────────┐
   │  scene.tif  (38 GB, in a bucket)             │
   │  ┌────┬────┬────┬────┬────┬────┬────┬────┐   │
   │  │    │    │ ██ │ ██ │    │    │    │    │   │
   │  ├────┼────┼────┼────┼────┼────┼────┼────┤   │
   │  │    │    │ ██ │ ██ │    │    │    │    │   │
   │  └────┴────┴────┴────┴────┴────┴────┴────┘   │
   └──────────────────────────────────────────────┘
          ▲                ▲
          │                └── 4 tiles actually read
          └── header read once: where every tile lives

      2 range requests instead of a 38 GB download

Every fetch goes through the source access controller. The URI comes from a document, so it is exactly the SSRF surface that guard exists for — COG streaming and the access allowlist are the same concern, not two.

image_tiling

Cuts an image into overlapping tiles and writes them as chunks, ready to be embedded and retrieved.

{
  "image_tiling": {
    "source_uri_field": "scene_url",
    "profile": "rag",
    "tile_format": "jpeg"
  }
}

Profiles

A profile sets three defaults at once, because tile size, overlap and tile count are not independent choices — halving the tile size roughly quadruples the count.

Profile	tile_size	overlap	max_tiles	For
rag (default)	512	64	100	Retrieval: overlap so a feature on a seam still lands whole in one tile
detail	256	32	400	Small objects; four times the tiles for the same area
overview	1024	128	25	Coarse scanning of a large scene
geo_search	512	0	200	Spatial indexing: zero overlap so tiles tile the plane exactly, without double-counting

geo_search has no overlap on purpose. Overlap helps retrieval and hurts geometry — a feature counted twice because it fell in two tiles is a defect when the tiles are being used as spatial extents.

Options

Option	Default	Meaning
field	extracted.blocks	Blocks from content_extract to tile.
target_field	chunks	Where tiles are written.
source_uri_field	—	Fetch and tile this URI instead of using field.
region_field	—	Field naming a sub-region, so only part of a scene is read.
profile	rag	rag, detail, overview, geo_search.
tile_size	from profile	Must be > 0.
overlap	from profile	>= 0 and strictly less than tile_size.
max_tiles	from profile	Must be > 0. A ceiling, so one huge scene cannot produce unbounded documents.
tile_format	jpeg	jpeg or png.
tile_quality	0.85	JPEG quality, 0.0–1.0.

Every constraint is checked when the pipeline is created, not when a document arrives — so overlap >= tile_size is a configuration error you find immediately.

vectorize

Turns a categorical raster into indexable geometry — no model, no GPU, no endpoint.

{
  "vectorize": {
    "source_uri_field": "raster_url",
    "band": 0,
    "target_field": "segments"
  }
}

For a whole class of imagery the labels are already in the pixels. A USDA CDL pixel of 75 is "Almonds"; a Sentinel-2 SCL pixel of 9 is "cloud high probability". Flood masks, burn scars, NLCD and CORINE land cover, and most change-detection products are the same shape of data. Asking a neural network to rediscover a label the file already states is wasteful anywhere, and disqualifying in an air-gapped deployment where it would make a GPU mandatory in order to read an integer.

Options

Option	Default	Meaning
source_uri_field	source_uri	Field holding the raster URI.
target_field	segments	Where the emitted geometry goes.
band	0	Which band carries the class values.
max_regions	256	Ceiling on regions emitted per document.
streaming	true	Read via range requests rather than fetching the whole file.
holes	true	Emit interior holes in a region rather than filling them.
window_field	—	Field naming a pixel window to restrict the read.
captured_at	—	Override the capture timestamp rather than reading it from metadata.
on_failure_action	fail	What to do when a raster cannot be read.

holes: true matters more than it sounds. A lake inside a forest polygon is not forest, and a geometry that fills it in will match spatial queries it should not.

Together

The two compose: tile a scene for retrieval, and vectorize the classified product derived from it, so the same document carries both what the imagery looks like and what it is.