Training¶
Training creates a model bundle that can be reused by samstars.segment(...).
The bundle contains the trained model files and the band settings used to prepare new imagery.
Inputs¶
Provide imagery, a canopy height model, a first-return density raster, and crown polygons for a labeled training area. The raster requirements and band choices are described in Data Preparation. Training also requires a base initialization checkpoint.
Base Checkpoint¶
The current training implementation requires the SAM ViT-L checkpoint, sam_vit_l_0b3195.pth, available from the official checkpoint list.
Save it locally and pass its path as sam_base_ckpt.
Prepare Crown Annotations¶
Delineate individual crown boundaries in GIS software and save them in a GeoPackage, with one feature per crown. The layer should have a defined coordinate reference system and align with the training imagery. Species labels and additional attribute fields are not required.
Use training areas with complete crown annotations. During refinement training, pixels outside the supplied polygons are treated as background, so crop the training rasters to the annotated area.
For one training area, pass the GeoPackage path through crowns.
For tiled training, save the annotations for each tile as crowns.gpkg inside its tile directory.
Reserve separate areas for evaluating the trained model.
Train From One Labeled Area¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | |
train(...) prepares the cost raster and seed points, builds training samples, and trains the proposal and refinement stages.
The example uses RGB imagery. For imagery with a near-infrared band, pass nir_band to include an NDVI cue in the cost surface.
Band indices are one-based; rgb_bands lists red, green, and blue in that order.
Train From Labeled Tiles¶
1 2 3 4 5 6 7 8 9 10 11 12 | |
Each subdirectory in training_tiles must use one of these layouts:
| Layout | Required files |
|---|---|
| Raw labeled tile | img.tif, chm.tif, den.tif, crowns.gpkg |
| Prepared labeled tile | img.tif, chm.tif, cost.tif, seeds.gpkg, crowns.gpkg |
Use the same layout for all tiles. Raw tiles are prepared automatically.
For prepared tiles, the three image channels and cost settings must already match the intended model inputs; training does not select their bands again.
When creating a bundle from prepared tiles, supply the original source rgb_bands, nir_band, and texture_band settings if the bundle will later be used to prepare source rasters.
Training Controls¶
| Parameter | Purpose |
|---|---|
rgb_bands |
Source band indices in red, green, blue order; default (1, 2, 3). |
nir_band |
Optional near-infrared band for the NDVI cost term. |
texture_band |
Optional band for image texture; otherwise use the mean RGB intensity. |
sam_epochs, sam_lr |
Proposal training duration and learning rate; defaults 15 and 5e-5. |
fg_extra |
Maximum extra foreground points per seed; nonnegative integer, default 80. Set 0 to use only the seed as foreground. |
stardist_epochs |
Refinement training duration; default 50. |
chip_size, chip_stride |
Training window size and spacing in pixels; defaults 512 and 384. |
val_fraction |
Fraction of refinement records used for validation; default 0.2. |
The record split is not a spatially independent evaluation; use separate held-out areas for that purpose. Seed controls are described in Data Preparation, and the full parameter list is in the API reference.
Foreground Prompts¶
Pass fg_extra=0 to train(...) or SamStars.train(...) to use the seed as
the only foreground point. Positive values cap the number of extra points
selected from high CHM pixels within the prompt box; fewer are used when fewer
pixels qualify. The default remains 80. Negative-point sampling and box
prompts are unchanged.
The same count is used for SAM decoder training and for the proposals used to
train StarDist. It is saved as defaults.fg_extra in manifest.json and reused
automatically by subsequent segmentation. The lower-level train_decoder(...)
also accepts fg_extra, and its CLI accepts --fg-extra.
Model Bundle and Saved Outputs¶
The bundle contains manifest.json, decoder.pth, config.json, weights.h5, and, when available, thresholds.json.
Pass the bundle directory to segment(model=...); see Segmentation.
With storage="persistent", preparation, training samples, and proposal outputs are saved under models/crowns/_training/.
Use storage="temp" to retain only the finished bundle.
Use a new bundle directory for a new training experiment.
See Examples for notebook walkthroughs and Advanced Workflows for inspecting or rerunning individual stages.