Data Preparation¶
Data preparation requires imagery, a canopy height model (CHM), and a first-return density raster.
samstars uses these to generate crown prompts and boundary cues that help separate neighboring crowns.
train(...) and segment(...) can create the cost surface and seed points automatically from these rasters.
The examples below show how to create them separately for inspection, or prepare them together as tiles.
Required Inputs¶
| Input | What to provide |
|---|---|
img |
A georeferenced RGB or multiband imagery raster. |
chm |
A single-band raster of canopy height above ground, in meters. |
den |
A single-band raster of first lidar returns per cell, or per square meter. |
crowns |
One polygon per labeled tree crown, required only for training. |
Image Bands¶
rgb_bands identifies the red, green, and blue bands using one-based indices.
The default (1, 2, 3) assumes the source image already has those bands in RGB order.
For a BGR image, use rgb_bands=(3, 2, 1).
For a multiband image, select the three corresponding source bands explicitly; the sensor is not inferred from band count.
An optional nir_band adds a near-infrared band for the NDVI cost cue.
texture_band selects a separate band for image texture; by default, texture uses the mean of the selected RGB channels.
These arguments are available in build_cost_surface(...), build_tiles(...), train(...), and segment(...).
See Advanced Workflows for a multispectral example.
Prepared images contain the three selected RGB channels. Use the same channel content and cost settings during training and segmentation.
Prepare Lidar Rasters¶
The CHM and first-return density raster can be derived from LAS/LAZ point clouds with any suitable processing tool:
- Height above ground. Normalize point heights using classified ground points or a terrain model.
- Canopy height model. Calculate the maximum height above ground in each raster cell.
- First-return density. Select points with
ReturnNumber == 1and count them in each raster cell. For returns per square meter, divide each count by the cell area in square meters.
Export both outputs as single-band GeoTIFFs. Keep density units and cell size consistent between training and segmentation, since seed detection uses the raster values directly.
For implementation details, see PDAL's height normalization and raster output tools, or the PyForestScan Python example.
Align and Check the Rasters¶
- Use a projected coordinate system in meters and north-up imagery with square pixels.
- Cover the same area in all three rasters and mark missing data as NoData.
- Check that canopy features line up between the imagery and lidar rasters.
build_tiles(...), and the preparation performed by train(...) and segment(...), reproject and resample the CHM and density raster to the imagery grid.
This matches coordinate systems and pixels; it does not correct positional offsets between surveys.
For the individual cost-surface and seed examples below, first align the rasters to the same CRS, pixel size, grid origin, and extent using your GIS software or Rasterio. These lower-level functions expect already aligned inputs.
Create a Cost Surface¶
A cost surface is a raster with values from 0 to 1 that highlights likely crown boundaries.
Higher values discourage grouping seed points across those areas and reduce segmentation scores there.
For RGB imagery, it combines canopy-height changes and image texture.
When nir_band is supplied, it also includes an NDVI cue for canopy gaps and non-vegetated areas.
The weights of the available terms are rescaled to sum to one.
Create cost.tif from an aligned image and CHM:
1 2 3 4 5 6 7 8 9 10 11 | |
Create Seed Points¶
Seed points are candidate tree-crown centers used as automatic prompts. The detector finds peaks in the CHM and first-return density raster, filters low-canopy points, and groups nearby candidates using the cost surface.
Using the cost raster created above:
1 2 3 4 5 6 7 8 9 10 11 12 13 | |
min_canopy_height is in meters. Other useful SeedParams controls are:
| Parameter | Meaning |
|---|---|
d_min |
Minimum peak value, applied to both height and density rasters; default 4.5. Interpret this against the units of each raster. |
min_dist_px |
Peak-search radius in pixels; default 4. |
gauss_sigma |
Smoothing scale in pixels before finding peaks; default 2. |
merge_radius |
Controls grouping of nearby candidates using distance and cost; default 3.0 in projected coordinate units. |
Overlay cost.tif and seeds.gpkg on the imagery in your GIS to inspect the boundary cues and candidate crown centers.
Build Prepared Tiles¶
For large scenes or reusable inputs, build_tiles(...) aligns the rasters and generates the cost surface and seeds for each tile in one call.
You can use this directly without running the individual examples above.
1 2 3 4 5 6 7 8 9 10 11 12 13 | |
tile and overlap use the imagery CRS units: with a CRS in meters, this creates approximately 500-meter tiles with 20 meters of overlap.
The example assumes RGB imagery. If training used nir_band or texture_band, supply the same settings when building inference tiles.
Each tile directory contains:
| File | Contents |
|---|---|
img.tif |
The selected red, green, and blue bands, in that order. |
chm.tif |
Canopy heights on the tile grid. |
cost.tif |
Boundary cues and, when NIR is supplied, an NDVI gap cue. |
seeds.gpkg |
Candidate crown-center points. |
Training tiles also need crowns.gpkg; see Training for preparing labeled tiles.
See Large Raster Runs to run segmentation from the prepared tiles.