Image segment ingest processor

The image_segment ingest processor runs semantic image segmentation and indexes each detected region as a spatial shape.

It is the segmentation sibling of image_tiling. Where tiling slices an image into a grid and emits one bbox_xy_shape per tile, image_segment sends the image to a segmentation model and emits one entry per detected region, carrying a mask_xy_shape polygon, a centroid_xy_shape point, a label, a score, and the region's area.

This turns "find imagery over this area" into "find imagery containing a region of this kind, here" — the same spatial index now answers questions about what an image contains, whether that is a lung nodule in a CT or a building in a satellite scene.

Coordinates — the part worth understanding

A model works in the only frame it has: the picture. It returns vertices in unit image space, where (0.25, 0.5) means a quarter across and half down. That is a description of a picture, not a place.

When the image is georeferenced, this processor converts those vertices into the raster's own CRS before emitting them — using the tile's bbox in block mode, or the raster's geo-transform in reference mode — and records the CRS alongside them.

That conversion is what makes a downstream reproject step mean anything.

info

reproject converts one CRS to another and knows nothing about images. Unit coordinates handed to it are read as degrees, so every mask collapses into a one-degree box off the coast of Africa — a valid geo_shape in entirely the wrong place.

Images with no georeferencing — a photograph, a plain PNG, a CT slice — have nowhere to be put, so their coordinates stay in unit space and no CRS is claimed. Set georeference: false to force that behaviour for georeferenced rasters too.

Request fields

Field	Type	Description	Required
field	String	Document field holding the image blocks to segment. Defaults to extracted.blocks.	No
target_field	String	Field that receives the emitted regions. Defaults to segments.	No
source_uri_field	String	Document field holding the source raster URI, for reference mode.	No
provider	String	Registered inference provider to call.	No
model_id	String	Model to run on that provider.	No
min_score	Double	Discards regions scoring below this. Defaults to 0.0.	No
max_regions	Integer	Ceiling on emitted regions. Defaults to 256.	No
max_image_bytes	Long	Ceiling on image size sent to the model.	No
georeference	Boolean	Convert unit coordinates into the raster's CRS. Defaults to true.	No
on_failure_action	String	skip (default) or fail.	No

The provider must be registered with task type image_segment. The model is fully pluggable and bring-your-own — point provider_config.endpoint at any service that speaks the contract.

Example

PUT /_ingest/pipeline/segment-imagery
{
  "description": "Segment imagery and project the masks to WGS84",
  "processors": [
    {
      "image_segment": {
        "field": "extracted.blocks",
        "target_field": "segments",
        "provider": "my-vision-provider",
        "model_id": "segmentation-v1",
        "min_score": 0.4,
        "max_regions": 64
      }
    },
    {
      "reproject": {
        "field": "segments",
        "shape_field": "mask_xy_shape",
        "target_field": "mask"
      }
    }
  ]
}

Each emitted region carries:

Field	Description
label	The class the model assigned.
score	Model confidence.
area_fraction	Region area as a fraction of the image.
bbox	Bounding box of the region.
mask_xy_shape	The region outline as a polygon.
centroid_xy_shape	The region centroid as a point.
crs	Coordinate reference system, when georeferenced.
segment_id, segment_index	Identify the region within the document.
source_uri, parent_uri, source_block	Provenance back to the image the region came from.

Choosing between image_segment and vectorize

Use	When
image_segment	The regions must be inferred — buildings, vessels, anatomy, anything a model has to find.
vectorize	The pixel values already carry the classes — land cover, cloud masks, flood extent, change detection.

Both emit the same fields, so a pipeline can swap one for the other without changing mappings, queries, or tile layers.

Related

• Vectorize processor — the deterministic sibling, no model required
• Image tiling processor
• Reprojection processor
• Geospatial