How tree voxelization works

Voxelization turns a tree inventory into a 3D canopy fuel grid. Each live tree in the inventory becomes a cluster of voxels holding its foliage, and the trees’ voxels are combined into one grid over the domain. This page explains each step, the settings that change it, and the parts of the model that are fixed.

For one tree, voxelization:

1. Builds the crown envelope: the solid the crown occupies, cut into voxels. Each voxel records the fraction of its volume inside the crown.
2. Chooses the occupied voxels: a weighted random draw that leaves gaps inside the envelope, so the crown is porous rather than solid.
3. Spreads the tree’s foliage mass over the occupied voxels, giving each a bulk density.

Then it adds the tree to the grid, summing with any crowns it overlaps.

The three steps for one ponderosa pine (45 cm DBH, 22 m tall, crown ratio 0.6), shown as a vertical section through the stem at 0.5 m. 1: the envelope, shaded by the fraction of each voxel inside the crown. 2: the probability that each voxel is chosen. 3: the voxels chosen, 1,469 of the envelope’s 2,939. 4: the tree’s 50.1 kg of foliage spread over them. A voxel only partly inside the crown holds a matching share of the density.

The crown envelope

Every crown runs from the crown base up to the tree’s height. The crown base is height × (1 − crown_ratio), so a tree 20 m tall with a crown ratio of 0.4 has a crown 8 m long that starts at 12 m. Between those heights, the envelope is a solid of revolution around the stem. Its shape comes from the crown profile model, and its width from the maximum crown radius.

Crown profile models

crown_profile_model gives the radius of the crown at each height. The models differ in where the crown is widest and how it narrows toward the top and the base.

crown_profile_model	Shape	Widest at
purves (default)	species-specific profile from Purves et al. (2007)	the crown base
beta	species-group beta distribution, after Ferrarese et al. (2015)	inside the crown, by species group
cone	right circular cone	the crown base
cylinder	right circular cylinder	the same radius top to bottom
single_ellipsoid	half-ellipsoid of revolution	the crown base
dual_ellipsoid	two half-ellipsoids joined at the crown midpoint	the midpoint
single_paraboloid	paraboloid of revolution	the crown base
dual_paraboloid	two paraboloids joined at the crown midpoint, the LANL Trees crown shape	the midpoint

purves and beta are fitted to measured crowns. purves gives each species its own taper. beta assigns each species to one of ten species groups and uses a beta-distribution curve fitted to that group. The six geometric shapes are the same for every species, which makes them useful when you want to match another model’s crowns or test how sensitive a fire simulation is to crown shape.

The crown envelope of one ponderosa pine under each crown_profile_model, as a vertical section through the stem at 0.5 m. The line is the profile’s radius at each height; each voxel is shaded by the fraction of its volume inside it. Every profile but beta has the same maximum radius, so only the shape changes. Drawn with fastfuels-core 0.17.1, the release the voxelization service runs.

Maximum crown radius

The profile model gives the crown’s shape relative to its widest point. max_crown_radius_source sets how wide that point is:

• allometry (default): the Purves et al. (2007) maximum crown radius, from species, DBH, height and crown ratio. Every profile except beta uses it, so a tree is equally wide under each of them and only the shape changes. beta computes its own radius from the crown’s length.
• inventory_column: a radius in meters read from a column of the inventory, such as the crown_radius that CHM crown segmentation measures, or radii you measured in the field. The profile model still sets the shape. A tree with no value in the column gets its allometric radius.

Where crown geometry comes from

The crown can be drawn entirely from the tree’s attributes, or partly from a canopy height model (CHM) of the stand. There are three levels:

Level	What it needs	What it measures	What stays modelled
Allometric crowns	species, DBH, height and crown ratio	nothing about the crown	width and shape
Measured crown radius	the above, plus a crown-radius column	each crown’s width	shape
Measured crown shape	the above, plus a crown Feature from a CHM	each crown’s outline and top surface	the crown’s bottom

Allometric crowns are the default and work with any inventory. Every tree of the same species, size and crown ratio gets the same crown. The equations describe an average tree, so in a stand whose crowns are wider or narrower than average, the canopy is too open or too closed.

Measured crown radius sets max_crown_radius_source to a radius column. It fixes how much ground each crown covers, but every crown is still a solid of revolution centred on its stem. A crown that leans into a gap becomes a circle, and circles of neighbouring trees can overlap where the real crowns only touch.

Measured crown shape sets crown_geometry_source to a crown Feature, which records each crown’s outline on a CHM. Each tree with a crown in the Feature gets:

• Outline: the crown’s CHM cells, wherever they lie around the stem.
• Top: the CHM height of each of those cells.
• Bottom: the crown profile model, rising from the crown base. A profile widest at the crown base gives a flat bottom. beta and the two dual_ profiles give a bottom that rises toward the crown’s edge.

Crowns from a Feature never overlap, because each CHM cell belongs to one crown, and the top of the canopy follows the CHM cell by cell. A tree with no crown in the Feature, whose crown does not contain its stem, or with no CHM height above its crown base is drawn with a parametric crown instead. The grid’s source.crown_geometry_counts records how many trees each case applied to.

A 100 m square of an open stand north of the Blackfoot River, Montana, at each level. Top left: a 0.6 m lidar CHM with the crown Feature’s outlines and the tree tops. The other panels colour each column by the tree that owns its highest voxel; a tree keeps its colour across panels. Across the whole 400 m domain, the CHM is above 2 m over 28 % of the ground; allometric crowns cover 25 % and measured crowns 28 %.

A 100 m vertical slice through each grid, with the lidar CHM as a line. Allometric crowns sit inside the CHM’s crowns and miss some of them. Measured radii fill each crown and spill past its edges. Measured shapes fill each crown up to the CHM line.

One Douglas-fir from the same stand (21.5 m tall, 29 cm DBH) at each level, at 1 m. Its crown covers 24 m² of ground with allometric crowns, 40 m² with its measured 3.1 m radius, and 32 m² with its measured outline. The foliage mass is the same, about 21 kg, so the wider crowns are paler.

The measured levels are only as good as the CHM. A CHM sees only the top of the canopy, and a CHM from aerial imagery, such as NAIP, is itself a model of canopy height. A tree that shares its CHM cells with a taller neighbour gets no crown in the Feature. For how the CHM source changes the trees you detect, see Generate a tree inventory from a CHM.

Which voxels are occupied

A real crown is not a solid block of foliage. To leave gaps, voxelization fills only part of the envelope, choosing voxels at random with a weight for each one. Three parameters, from the FastFuels crown occupancy model (Marcozzi et al. 2025), control the draw:

• alpha sets the horizontal weight. Each voxel’s weight rises with its distance from the crown’s center line toward its edge, raised to the power alpha. At 0 every distance is equally likely. Larger values move foliage toward the outside of the crown and away from the stem.
• beta sets the vertical weight: the voxel’s height above the crown base, raised to the power beta. At 0 every height is equally likely. Larger values move foliage toward the top of the crown.
• rho is the share of the envelope’s voxels that are filled. The rest of the envelope is left empty.

The weights multiply, and voxels are drawn without replacement until the share rho is reached. The API uses alpha = 0.5, beta = 0.5 and rho = 0.5 for every crown, parametric or measured, except that a crown of fewer than 16 voxels is filled completely. These values are fixed; the request has no field for them.

The ponderosa pine from the figures above under different alpha (top), beta (middle) and rho (bottom), each with the other two at the API’s values. Each voxel is shaded by how often it is occupied over 200 draws with different seeds. The charts average that share by distance in from the crown’s edge (alpha) or by height (beta and rho). Drawn with fastfuels-core 0.17.1.

The draw is random, so the request’s seed decides which voxels are chosen. The same inventory, settings and seed always give the same grid, and the seed is stored on the grid as source.seed. A different seed gives another realization with the same statistics: the same mass in each tree, spread over a different set of voxels.

How much foliage, and where it goes

Foliage mass

biomass_source sets the allometric equations that give each tree’s foliage mass, in kilograms of dry weight:

• nsvb (default): the USDA Forest Service National Scale Volume and Biomass equations (Westfall et al. 2023), from species, DBH and height.
• jenkins: the national equations of Jenkins et al. (2003), from DBH and species group.

Foliage mass from each set of equations for four species, across DBH. The trees have a crown ratio of 0.5 and a height that rises with DBH to about 34 m, because the NSVB equations also use height. Drawn with fastfuels-core 0.17.1.

The choice of equations changes how much fuel the canopy holds, by more than a factor of two for a large Douglas-fir. It does not change where the foliage goes.

Live and dead

Voxelization uses only live trees. A tree whose fia_status_code is anything other than 1 (live) is left out. A tree with no status counts as live.

component_states splits each tree’s foliage into a live share and a dead share, the same for every tree. The default is all live. With a split of 0.9 live and 0.1 dead, each voxel’s foliage goes 90 % to bulk_density.foliage.live and 10 % to bulk_density.foliage.dead.

Foliage is the only component that can be voxelized today. The request accepts branchwood and fine, but the job fails.

Spreading the mass

The tree’s foliage mass is spread evenly over its occupied voxels: every fully occupied voxel gets the same bulk density, and a voxel only partly inside the crown gets the same share of it as its volume fraction. The total is exactly the tree’s mass. This is the uniform method of the FastFuels paper; the API has no other.

Because the mass is fixed and the volume is not, everything that changes the crown’s volume changes its density. A wider crown, a measured crown, or a higher rho spreads the same foliage over more voxels, so each holds less.

The Lubrecht domain at each level of crown geometry. Left: the foliage in each 1 m layer of height, nearly the same at every level. Right: how many voxels hold each bulk density. The three grids hold 39.7 t, 39.2 t and 39.6 t of foliage. Allometric crowns fill 193,000 voxels at a median 0.19 kg/m³; measured radii fill 760,000 at 0.047 kg/m³; measured shapes fill 716,000 at 0.052 kg/m³.

Capping bulk density

A small crown that holds a lot of foliage can produce a few very dense voxels. max_bulk_density sets an upper limit. In any voxel above it, the bulk density is lowered to the limit, keeping its live and dead split, and leaf_area_density is lowered with it. The foliage above the limit is removed from the grid, so a capped grid holds less mass than the trees.

Voxel bulk density in the Lubrecht measured-crown grid, without a limit (blue) and with max_bulk_density: 2 (orange). Below the limit the two grids are the same. The 29 voxels above it are lowered to 2 kg/m³, which removes 32 kg of the stand’s 39.6 t of foliage.

Combining trees into one grid

Each tree’s voxels are added to the grid at the tree’s position. Where crowns overlap, the bands combine in one of two ways:

• Summed: the bulk density bands and leaf_area_density. Two crowns sharing a voxel give it the foliage of both.
• Taken from the tallest tree: spcd, tree_id, savr.foliage and the fuel moisture bands. The voxel records the tallest tree that occupies it.

The grid’s vertical extent runs from the ground to the tallest crown top. It stores height above ground, not elevation, so combine it with a topography grid to place it on the terrain.

Resolution

resolution sets the voxel size: horizontal for x and y, vertical for z. The default, 2 m by 1 m, is also QUIC-Fire’s default. A finer lattice traces each crown’s outline and inner gaps more closely, and a crown of fewer than 16 voxels is filled solid, which happens more often at coarse resolutions. Halving both sizes gives eight times as many voxels to store and compute.

The same trees and seed on two lattices, from a TreeMap inventory on the Blue Mountain domain. The crowns keep their positions and heights. The finer lattice traces each crown’s outline and gaps at four times the detail per section, for eight times the voxels over the whole grid.

Every grid in a combined export shares one lattice, so the canopy grid’s horizontal resolution is usually the one the fire model will run at.

Bands

Band	Unit	What it holds
bulk_density.foliage.live	kg/m**3	live foliage per voxel volume, summed over crowns
bulk_density.foliage.dead	kg/m**3	dead foliage, from component_states
leaf_area_density	1/m	one-sided leaf area per voxel volume: foliage mass × the species’ specific leaf area
savr.foliage	1/m	the foliage surface-area-to-volume ratio of the tallest tree’s species group
fuel_moisture.live, fuel_moisture.dead	%	the uniform moisture set in moisture_model; live defaults to 100, dead to 10
spcd		the FIA species code of the tallest tree in the voxel
tree_id		the inventory tree_id of the tallest tree in the voxel; 0 where there is none

Each requested band is stored on the same lattice, in the order requested. Only foliage bulk density carries mass; the other bands describe the voxels that hold it.

Note

A voxel grid is built from its inventory, so to change the canopy, change the inventory and voxelize again. 3D grids do not take the cell-level modifications that 2D grids do. If you need canopy bulk density, base height, height and cover for a 2D fire model, see Canopy fuel variables.

References

• Ferrarese, J., Affleck, D., and Seielstad, C. (2015). Conifer crown profile models from terrestrial laser scanning. Silva Fennica 49(1).
• Jenkins, J. C., Chojnacky, D. C., Heath, L. S., and Birdsey, R. A. (2003). National-scale biomass estimators for United States tree species. Forest Science 49(1), 12–35.
• Marcozzi, A., Wells, L., Parsons, R., Mueller, E., Linn, R., and Hiers, J. K. (2025). FastFuels: Advancing wildland fire modeling with high-resolution 3D fuel data and data assimilation. Environmental Modelling & Software 183, 106214.
• Purves, D. W., Lichstein, J. W., and Pacala, S. W. (2007). Crown plasticity and competition for canopy space: a new spatially implicit model parameterized for 250 North American tree species. PLoS ONE 2(9), e870.
• Westfall, J. A., Coulston, J. W., Gray, A. N., Shaw, J. D., Radtke, P. J., et al. (2023). A national-scale tree volume, biomass, and carbon modeling system for the United States. Gen. Tech. Rep. WO-104, USDA Forest Service.

Where to go next

• Voxelize a tree inventory into a 3D canopy grid — the request for each setting on this page.
• Create a crown Feature from a CHM — outline each crown for measured crown shapes.
• Generate a tree inventory from a CHM — detect trees and measure their crown radii.
• API reference — every field of the voxelize request.