Train and Segment One Area¶
Train a model on a labeled area and segment another area using the resulting bundle.
Inputs¶
Supply your own training imagery, canopy height, first-return density, and crown polygons, plus imagery and lidar rasters for inference. The example paths below are placeholders; these data files are not included in the repository. See Data Preparation for raster requirements and Training for crown annotations. The required base checkpoint is linked in Training.
Run this notebook in an environment where samstars is installed. It can run outside a repository checkout.
from pathlib import Path
from samstars import train, segment
Set Paths and Image Bands¶
Set the directories containing your rasters and annotations. This example assumes the training and inference images have the same band order.
training_dir = Path("data/training").resolve()
inference_dir = Path("data/inference").resolve()
sam_base_ckpt = Path("models/sam_vit_l_0b3195.pth").resolve()
model_dir = Path("models/crowns").resolve()
rgb_bands = (1, 2, 3) # One-based red, green, blue indices in the source images.
nir_band = None # Set to a near-infrared band index when available.
device = "cpu"
inference_run_dir = Path("runs/segmentation").resolve()
Train a Model Bundle¶
These reduced epoch counts provide an initial run for inspection. Evaluate segmentation quality on separate areas before selecting final training settings. Persistent training products are saved under the model directory in the _training folder.
model = train(
img=training_dir / "image.tif",
chm=training_dir / "chm.tif",
den=training_dir / "first_return_density.tif",
crowns=training_dir / "crowns.gpkg",
sam_base_ckpt=sam_base_ckpt,
out=model_dir,
rgb_bands=rgb_bands,
nir_band=nir_band,
sam_epochs=3,
stardist_epochs=10,
storage="persistent",
device=device,
)
print(model.root)
Segment an Area¶
The bundle supplies the band settings used during training. Source rasters are prepared automatically.
result = segment(
model=model,
img=inference_dir / "image.tif",
chm=inference_dir / "chm.tif",
den=inference_dir / "first_return_density.tif",
out=inference_run_dir,
storage="persistent",
device=device,
)
print(result.crowns)
Inspect Crowns¶
Open the resulting GeoPackage in GIS software to inspect crown boundaries, or read it with GeoPandas.
import geopandas as gpd
crowns = gpd.read_file(result.crowns, layer="crowns")
crowns.head()
Optional Tuning¶
The defaults are suitable for checking the workflow on a small area. The settings below can be added to the training or segmentation calls when needed.
| Setting | Purpose |
|---|---|
| Training epochs | Increase sam_epochs and stardist_epochs to extend training, assessing results on held-out areas. |
| Training chips | Set chip_size and chip_stride in pixels to control the training windows. |
| Seed detection | Set seed_d_min, seed_min_dist_px, and seed_min_canopy_height during training or tile preparation; see Data Preparation. |
| Texture band | Set texture_band during training to use a specific source band instead of mean RGB intensity. Use the same setting for later tile preparation. |
| Refinement thresholds | Pass stardist_prob_thr and stardist_nms_thr together to segmentation, or omit both to use model thresholds. |
See the API reference for parameter details and Installation for accelerator setup.