Skip to content

About features

You are viewing in-progress documentation for v2. Switch to the stable version for the current production release.

A feature is a named, reusable piece of vector geography attached to a domain: the roads, water bodies and buildings in your area, or a set of custom fuelbed polygons you supply yourself. Where a domain fixes where you are working and a grid is the rasterized fuelbed, a feature is the vector layer in between — clean lines and polygons describing things that the fuelbed has to account for but that aren’t themselves a raster.

This page is about the idea of a feature: what it stores, why the v2 API has a distinct resource for vector geometry at all, and the mental model that connects a layerset of fuel polygons, a road network pulled from OpenStreetMap, the building footprints of a town, and the two different things you can do with any of them. It is not a walk-through of any request — the feature how-to guides cover the procedures — and it does not re-teach the rule syntax for masking and removal, which lives in About modifications. Here we stay with the concepts those pages assume.

A feature is a named vector dataset, not a single shape

Section titled “A feature is a named vector dataset, not a single shape”

The word “feature” has two meanings in the v2 API.

  • A Feature (the resource) is one named, persisted dataset: a row of metadata in the database — id, domain_id, type, name, a status, a georeference — that points at a stored blob of vector geometry. A single road Feature can hold thousands of individual road segments.
  • A feature (lowercase, in the GeoJSON sense) is one geometry inside that blob — a single road segment, one lake, one fuelbed polygon.

So a road Feature contains many GeoJSON features. When this page says “feature” it means the resource. When it means one shape it says “geometry” or “polygon.” The API keeps the same separation: the resource is addressed at /domains/{domain_id}/features/{feature_id}, and the geometries inside it are streamed separately (see How the geometry is stored).

Every Feature is exactly one of five types, fixed at creation and never changed:

TypeHoldsSourced from
roadthe road network as footprint polygonsOpenStreetMap (async)
waterlakes and ponds as polygons, rivers and streams buffered into polygons, other waterway lines as LineStringsOpenStreetMap (async)
buildingbuilding footprints as polygons, with each footprint’s height and source datasetOverture Maps (async)
layersetcustom fuelbed polygons carrying fuel propertiesa GeoJSON you upload (sync)
crownone crown outline per detected tree, by tree_ida CHM and the trees detected on it (async)

Roads, water and buildings are geography you fetch. A layerset is fuel you author. A crown Feature is different again: it measures the trees themselves, and its use is to voxelize an inventory with measured crown shapes. That split — fetched reference geometry versus authored fuel input — is the through-line of everything below.

A polygon can be inlined in a grid’s masking rule without persisting anything. The v2 API also makes vector geometry a first-class resource, for two reasons.

Reusability. To fetch roads and water from OpenStreetMap, the server reads a regional extract, clips it to your domain, buffers linework, and reprojects it. Minting the road network once as a Feature runs that work once and turns it into a single source of truth that any number of grids and inventories can reference by id. A road that is the same road across ten resources is stored once, not ten times.

The vector↔raster bridge. Fuel models run on rasters (grids of cells) and point sets (inventories of trees), but the real-world things you need to reason about — a highway, a shoreline, a managed plot — are vector: precise lines and polygons with sharp edges. A road carries no surface fuel and shouldn’t have trees standing in it, but a grid only knows cells and an inventory only knows points. A feature is the clean vector description of that road, held in a form that the raster and point-set consumers can each be reconciled against. It lets you say “the road,” exactly, once, and then apply it to data models that have no native notion of a road at all.

Domain ── the spatial frame: extent + CRS
│
├─ Features ── vector geography (roads, water, buildings, layerset polygons)
│ │
│ ├─ mask ──▶ Grids (raster: zero/scale fuel in cells)
│ └─ remove ─▶ Inventories (points: drop trees inside the shape)
│
└─ a layerset can also be rasterized directly into a Grid

Layersets: vector geography as custom fuel

Section titled “Layersets: vector geography as custom fuel”

A layerset is the specialized feature type for custom fuel inputs, and it inverts the usual direction. Roads and water are reference geometry you mask out of a fuelbed. A layerset is fuelbed — a way to author surface fuel by hand and bring it in.

Concretely, a layerset is a GeoJSON FeatureCollection in which every polygon is a fuelbed, and the polygon’s properties carry that fuelbed’s inputs:

PropertyMeaning
fuel_typea free-form category label ("shrub", "herb", "litter")
fuel_loadingfuel mass per unit ground area
fuel_heightfuel height above the surface
percent_coverfractional cover, in percent (0–100)
distributionhow cover is laid down: homogeneous, uniform_random, or random_clusters
patch_sizeclump diameter — required when distribution is random_clusters
live_fuel_moisture, dead_fuel_moisture, heat_of_combustion, patch_std_devoptional refinements

These names map one-to-one onto fastfuels_core.rasterize_layerset, the function that turns the polygons into a gridded surface-fuel array. A layerset is the rasterizer’s input table expressed as geography — each polygon a row, each property a column. That’s why the upload contract is strict about them (every fuelbed must carry the required columns, percent_cover must be in [0, 100], a random_clusters fuelbed must declare its patch_size): the API is validating that the polygons will rasterize.

Because a layerset already is fuel, it has a path the other types don’t: it can be rasterized directly into a grid rather than only masking one. The SDK exposes this as feature.rasterize(...), which is valid only for layerset features and returns a new fuel grid. So a layerset participates in fuel modeling in two modes — as a polygon you can mask or remove against like any other feature, and as a fuelbed you can turn into a grid outright.

Two ways to source a feature: fetch and upload

Section titled “Two ways to source a feature: fetch and upload”

How a feature comes into being depends on its type, and the two paths trade off flexibility against immediacy.

Fetching (road, water and building) is asynchronous. Creating a road, water or building feature kicks off a background job. The create call returns immediately with status: "pending". The job then walks pending → running → completed (or failed). While it runs, the server reads the source data for your domain’s footprint (OpenStreetMap for roads and water, Overture Maps for buildings), builds the geometry, reprojects it into the domain’s CRS, and clips it to the domain’s extent. Only when it lands on completed is the feature’s georeference (its CRS and bounding box) populated and its geometry readable. You poll until then. The trade-off is flexibility for time: you get a road network or a set of building footprints for any CONUS domain with a single call, but you wait for the fetch and you take whatever the source has (see Fetched geography is incomplete).

Uploads (layersets) are synchronous. Posting a layerset validates and stores it in the same request: the call returns 201 already completed, with its georeference set. There is no job and no polling — but the burden of correctness is on you. The GeoJSON must already be in a projected CRS (a layerset in a geographic CRS like EPSG:4326 is rejected, because rasterization needs cell sizes in meters), the geometries must be polygons, and every fuelbed must carry valid properties. Immediacy in exchange for doing the preparation yourself.

OpenStreetMap stores roads as centerlines — one-dimensional lines with no width. A line has no area, and “the fuel under the road” or “the trees on the road” are questions about an area. So the extractor buffers each centerline into a footprint polygon, widening it by road class: a footpath gets a meter or so, a residential street a few meters, a motorway tens of meters. The result is a polygon that approximates the road’s on-the-ground footprint, which is what every downstream test needs. (Water keeps lakes and ponds as polygons and buffers rivers, canals, streams, drains, and ditches into polygons by class. Other waterway lines come back as LineStrings.)

This is why a completed road feature holds polygons, not lines, and why an intersects test with target: "cell" catches every grid cell the road’s footprint overlaps. It also matters for the two uses below: a road footprint has area but is thin, and a thin polygon interacts differently with cells than with points.

Building footprints need no such step. The source datasets map buildings as polygons, so a building feature stores each footprint as the source drew it, reprojected and clipped to the domain.

A feature’s geometry doesn’t live in the feature document — that holds only metadata. The geometry is written to a separate GeoParquet blob, partitioned into row groups so a feature with thousands of geometries can be read in pieces rather than all at once. Two endpoints expose it:

  • GET .../data/metadata returns the shape of the dataset: total_features (how many geometries the feature holds), partition_count, and the per- partition row counts. It reads only the Parquet footer.
  • GET .../data/{partition_index} returns one partition as GeoJSON (application/geo+json) in the feature’s stored CRS, so a large feature is read one partition at a time, from 0 to partition_count - 1.

total_features is how you find out whether a feature is empty before you rely on it — the verification step described below — without downloading any geometry.

The two uses: mask a grid, remove from an inventory

Section titled “The two uses: mask a grid, remove from an inventory”

Once a feature exists, there are two things you do with it, and they are different actions on different data models.

Masking a grid changes the value of cells the feature touches. A grid is a raster — a fixed lattice where a cell always exists at its position. You cannot delete a cell. The lattice has to stay rectangular and complete. So masking scales or zeroes a fuel band in the affected cells: replace the load with 0 where a road runs (no fuel under the highway), or multiply it by 0.1 to thin fuel along a vegetated shoulder. The cells remain and their fuel drops. There is no “remove” for grids.

Removing from an inventory deletes trees the feature contains. An inventory is a point set — a list of individual trees, each at an (x, y). A point can be dropped from the list. So a remove action against a water feature deletes every tree whose point falls inside the (buffered) water polygon: there shouldn’t be trees standing in a lake, so they’re gone, not scaled.

A building feature is used both ways. Masking zeroes the surface fuel under each footprint. Removal matters most for an inventory detected from a canopy height model. A CHM that keeps buildings, as the NAIP CHM does, records a roof as a raised surface like a crown, and tree detection places treetops on it. Removing the trees inside the footprints takes those rooftop detections back out.

Same feature, two data models, two verbs:

You have a…which is a…so the action is…because…
Gridraster of cellsmask (scale/zero a band)a cell can’t be deleted — only revalued
Inventoryset of pointsremove (drop trees)a point can be deleted outright

This also explains an asymmetry in buffering. Test a narrow footprint against a grid with cell-targeting and it catches every cell it overlaps, because cells have area. Test the same footprint against tree points and a bare within catches only the trees whose point falls inside it. A footprint narrower than the spacing between trees catches few of them, and a zero-width line, such as an unbuffered waterway LineString, catches none. That’s why removing trees near a feature usually needs a buffer_m to give the geometry width, while masking a grid with cell-targeting doesn’t. The shape didn’t change. The consumer’s geometry did.

The full vocabulary for expressing these actions — the within/intersects/ outside operators, cell-versus-centroid targeting for grids, buffer_m semantics, ANDing conditions within a rule and ORing across rules, and when to reference a Feature by id versus inlining a one-off geometry — is the subject of About modifications. That page is the reference for how to write the rule. This section is only about why masking and removal are different acts.

Fetched geography is incomplete: verify before you trust

Section titled “Fetched geography is incomplete: verify before you trust”

A fetched feature is a copy of a dataset that someone else maintains, and no such dataset is complete.

OpenStreetMap is volunteer-contributed, and its coverage is uneven. Urban and suburban areas are mapped densely. Wilderness, remote terrain, and small water bodies are often sparse or absent entirely. A domain deep in a roadless area can return a road feature with zero geometries — a valid completed feature that contains nothing. Tagging conventions also vary by region, so the same physical feature can be classified differently from place to place.

Building footprints carry those gaps and add their own. Overture Maps combines OpenStreetMap buildings with Microsoft ML Buildings, footprints that Microsoft extracted from aerial imagery with a machine-learning model. A building is missing when neither dataset has it, as with construction newer than the imagery. Height is sparser than the footprints. A footprint keeps its row when no dataset records a height, so height is null for part of a building feature. The dataset that supplied a height (height_source) also need not be the one that supplied the footprint (source_dataset), so a single building can combine an OpenStreetMap outline with a Microsoft height.

This gap fails silently. A grid modification or inventory removal that references a feature with zero geometries treats it as an empty geometry: within and intersects select nothing, and outside selects everything. The grid or inventory completes as if the feature weren’t there, so a domain with no mapped roads produces a road mask that changes nothing. That is why the how-to guides read total_features from data/metadata before they use a feature (see Check the footprint count). A zero means the source has nothing for the extent. extent_buffer_m reaches at most 100 m past the domain, so when the data isn’t there, the alternative is geometry you supply yourself, as a layerset or an upload.

A feature’s existence and its completed status tell you the fetch succeeded, not that it found anything. total_features tells you whether it found anything.

A feature belongs to exactly one domain, and that ownership shapes everything about its lifecycle. Road, water, building, and crown features are stored in the domain’s CRS. A layerset keeps the projected CRS it was uploaded in.

Mutable versus immutable. A feature has the same sharp split a domain does. Its descriptive metadata — name, description, tags — is freely editable. Updating it advances modified_on and changes nothing about the geometry. The geometry itself is immutable. Once a feature is built, you cannot re-fetch or re-shape it in place. To change the geometry you delete the feature and create a new one. The geometry is frozen for the same reason a domain’s frame is: grids and inventories reference features by id, and a rule that masks “the roads” should keep naming the shape it was applied with. If geometry could shift underneath a reference, the id stored in a rule would no longer describe what that rule did.

Building features have a second reason to be frozen. Overture keeps only its recent releases online, about two months of them, so each request reads the latest release and records it in source.release. Once that release goes offline, the stored feature is the only copy of those footprints. A new request for the same domain reads a newer release, which can add, drop, or redraw buildings.

Referenced, not owned. Grids and inventories don’t contain a feature. They hold a feature_id that points at it, resolved at processing time. The binding is validated to be same-domain: a grid or inventory can only reference a feature in its own domain, and a cross-domain reference is rejected. This is the same scoping rule that governs everything in v2 — a domain is the unit of geographic scope, and “the same place, in the same CRS” is only guaranteed within one domain. A feature reaching across domains would break that guarantee.

The reference is resolved when the rule is applied. Deleting the feature later does not change a grid or inventory already built with it, but the stored rule then names a feature that no longer exists. See Reproducibility and persistence in About modifications.

The procedures that put all of this to work are the feature how-to guides:

For the rule syntax the mask and remove guides assume — conditions, actions, operators, buffer_m, and feature-versus-inline geometry — see About modifications.

The sibling resource-explanation pages put a feature in context: About domains is the spatial frame a feature attaches to. About grids covers what masking acts on, and About inventories covers what removal acts on. A feature is the vector layer that connects the clean geometry of the real world to both.