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, astatus, ageoreference— 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:
| Type | Holds | Sourced from |
|---|---|---|
road | the road network as footprint polygons | OpenStreetMap (async) |
water | lakes and ponds as polygons, rivers and streams buffered into polygons, other waterway lines as LineStrings | OpenStreetMap (async) |
building | building footprints as polygons, with each footprint’s height and source dataset | Overture Maps (async) |
layerset | custom fuelbed polygons carrying fuel properties | a GeoJSON you upload (sync) |
crown | one crown outline per detected tree, by tree_id | a 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.
Why features exist
Section titled “Why features exist”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 GridLayersets: 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:
| Property | Meaning |
|---|---|
fuel_type | a free-form category label ("shrub", "herb", "litter") |
fuel_loading | fuel mass per unit ground area |
fuel_height | fuel height above the surface |
percent_cover | fractional cover, in percent (0–100) |
distribution | how cover is laid down: homogeneous, uniform_random, or random_clusters |
patch_size | clump diameter — required when distribution is random_clusters |
live_fuel_moisture, dead_fuel_moisture, heat_of_combustion, patch_std_dev | optional 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.
From centerline to footprint
Section titled “From centerline to footprint”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.
How the geometry is stored
Section titled “How the geometry is stored”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/metadatareturns 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, from0topartition_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… |
|---|---|---|---|
| Grid | raster of cells | mask (scale/zero a band) | a cell can’t be deleted — only revalued |
| Inventory | set of points | remove (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.
Lifecycle, mutability, and relationships
Section titled “Lifecycle, mutability, and relationships”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.
Where to go next
Section titled “Where to go next”The procedures that put all of this to work are the feature how-to guides:
- Create road and water features from OpenStreetMap
— the async fetch, polling to
completed, and reading the geometry back. - Create building features — fetching footprints, checking the count, and reading each footprint’s height and source dataset.
- Upload a GeoJSON to create a layerset — the synchronous upload, the per-feature property contract, and the CRS rule.
- Remove surface fuel under roads, water and buildings — zero or thin surface fuel where roads, water and buildings cross a grid.
- Remove trees with road, water and building features — drop trees that fall near a feature, optionally filtered by DBH, and rooftop detections inside building footprints.
- Create a crown Feature from a CHM — outline each detected tree’s crown for measured-crown voxelization.
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.