CLI Application

The CLI entrypoint is python -m satellit_sam.main, exposed by Pixi as:

pixi run satellit -- [COMMAND] [OPTIONS]

No commands currently use positional arguments; all inputs are passed via options.

Command Tree

satellit
├── label
│   ├── weak
│   ├── validate-predictions
│   └── by-bounding-boxes
├── predict
│   └── image-masks
└── process
    └── tiles

Root Command: satellit

Usage:

pixi run satellit -- --help

Global options:

Option Type Description
--install-completion flag Install shell completion for the current shell.
--show-completion flag Print completion script for the current shell.
--help flag Show help and exit.

Command Group: label

Usage:

pixi run satellit -- label --help

Subcommands:

  • weak
  • validate-predictions
  • by-bounding-boxes

Command: label weak

Usage:

pixi run satellit -- label weak [OPTIONS]

Description: Generate weak labels from a forest inventory and image tiles.

Validation rules:

  • Provide exactly one of --inventory-csv or --inventory-shp.
  • --image-tif and --output-dir are required.

Options:

Option Type Required Default Description
--image-tif path yes - Path to orthophoto GeoTIFF.
--inventory-csv path no None Inventory CSV path (semicolon-delimited).
--inventory-shp path no None Inventory ESRI Shapefile (.shp) path.
--output-dir path yes - Output directory for labels and optional tiles.
--tile-size int no 1024 Tile size in pixels.
--overlap int no 128 Tile overlap in pixels.
--x-field str no PX Inventory x-coordinate field name.
--y-field str no PY Inventory y-coordinate field name.
--tree-id-field str no TreeID Inventory tree-id field name.
--species-field str no Latin Inventory species field name.
--status-field str no Status Inventory status field name.
--status-filter str no alive Keep rows with this status (case-insensitive). Empty string disables filter.
--dbh-field str no DBH Inventory DBH field name.
--dbh-unit enum (mm,cm,m) no mm Unit for DBH values.
--default-crown-radius-m float no 2.5 Fallback crown radius when DBH is unavailable.
--min-dbh-cm float no 0.0 Minimum DBH (cm) filter.
--max-dbh-cm float no 0.0 Maximum DBH (cm) filter; 0 disables upper bound.
--deduplicate-tree-id flag no False Keep only one row per tree id (highest DBH).
--crown-model enum (linear,power) no linear Crown radius model.
--linear-factor-m-per-cm float no 0.08 Linear model slope.
--linear-intercept-m float no 0.0 Linear model intercept.
--power-a float no 0.15 Power model coefficient a.
--power-b float no 0.8 Power model exponent b.
--min-crown-radius-m float no 0.5 Lower clamp for crown radius.
--max-crown-radius-m float no 15.0 Upper clamp for crown radius.
--bbox-padding-px float no 4.0 Extra padding in pixels for each weak-label crown bounding box.
--export-visualizations flag no False Export labeling visualization PNG files.
--help flag no - Show help and exit.

Example:

pixi run satellit -- label weak \
  --image-tif ../data/Traunstein/orthophoto_wgs84_utm33n_agg200mm.tif \
  --inventory-shp ../data/Traunstein/inventory/processed/shifted_new_tree_positions_UTM33N.shp \
  --output-dir output/inventory_from_shp \
  --tile-size 1024 \
  --overlap 128 \
  --deduplicate-tree-id \
  --export-visualizations

Command: label validate-predictions

Usage:

pixi run satellit -- label validate-predictions --image-tif <PATH> [OPTIONS]

Description: Validate SAM3 strong-label masks against inventory stem positions from
merged NPZ and/or per-tile NPZ artifacts.

Validation rules:

  • Provide exactly one of --inventory-csv or --inventory-shp.
  • Provide at least one of --predictions-npz or --predictions-tiles-dir.
  • --predictions-npz must contain a masks array with shape (N, H, W).
  • --predictions-tiles-dir can be partial/incomplete (for interrupted runs) and discovers tile_x*_y*.npz directly.
  • If both prediction sources are provided, merged NPZ is preferred.
  • label_id is the zero-based SAM3 mask index; once matched, labels are not reused.

Options:

Option Type Required Default Description
--image-tif file path yes - Orthophoto GeoTIFF used for coordinate projection.
--predictions-npz file path no None Optional merged SAM3 prediction file (for example masks/image_masks.npz).
--predictions-tiles-dir directory path no None Optional per-tile prediction NPZ directory (for example masks/tiles).
--inventory-csv file path no None Inventory CSV path (semicolon-delimited).
--inventory-shp file path no None Inventory ESRI Shapefile (.shp) path.
--output-csv path no output/validation/label_validation.csv Validation output CSV path.
--x-field str no PX Inventory x-coordinate field (CSV offset or SHP attribute).
--y-field str no PY Inventory y-coordinate field (CSV offset or SHP attribute).
--tree-id-field str no TreeID Inventory tree-id field name.
--stem-id-field str no StemTag Inventory stem-id field name; fallback chain is field -> stemtag -> tree id.
--species-field str no Latin Inventory species field name.
--status-field str no Status Inventory status field name.
--status-filter str no alive Keep rows with this status (case-insensitive). Empty string disables filter.
--dbh-field str no DBH Inventory DBH field name.
--dbh-unit enum (mm,cm,m) no mm Unit for DBH values.
--min-dbh-cm float no 0.0 Minimum DBH (cm) filter.
--max-dbh-cm float no 0.0 Maximum DBH (cm) filter; 0 disables upper bound.
--deduplicate-tree-id flag no False Keep only one row per tree id (highest DBH).
--help flag no - Show help and exit.

Example:

pixi run satellit -- label validate-predictions \
  --image-tif ../data/Traunstein/orthophoto_wgs84_utm33n_agg200mm.tif \
  --predictions-npz output/predict/masks/image_masks.npz \
  --inventory-shp ../data/Traunstein/inventory/processed/shifted_new_tree_positions_UTM33N.shp \
  --output-csv output/validation/label_validation.csv

pixi run satellit -- label validate-predictions \
  --image-tif ../data/Traunstein/orthophoto_wgs84_utm33n_agg200mm.tif \
  --predictions-tiles-dir output/predict/masks/tiles \
  --inventory-shp ../data/Traunstein/inventory/processed/shifted_new_tree_positions_UTM33N.shp \
  --output-csv output/validation/label_validation.csv

Command: label by-bounding-boxes

Usage:

pixi run satellit -- label by-bounding-boxes --image <PATH> [OPTIONS]

Description: Generate label overlays from bounding-box prompts.

Status: Deprecated. Use predict image-masks --bbox ... or
predict image-masks --weak-labels-csv ... for canonical strong-label persistence.

Options:

Option Type Required Default Description
--image file path yes - Input image file (for example, GeoTIFF).
--tile-size int no 2048 Tile size in pixels.
--overlap int no 64 Overlap between tiles in pixels.
--output-path path no output/test_tiles Output directory for generated tiles/results.
--bbox str (repeatable) no None Bounding box in x1,y1,x2,y2 format. Repeat flag for multiple boxes.
--weak-labels-csv file path no None Weak-label CSV from label weak containing tile-local bboxes.
--help flag no - Show help and exit.

Examples:

pixi run satellit -- label by-bounding-boxes \
  --image ../data/Traunstein/orthophoto_wgs84_utm33n_agg200mm.tif \
  --output-path output/predict \
  --tile-size 2048 \
  --overlap 64

pixi run satellit -- label by-bounding-boxes \
  --image ../data/Traunstein/orthophoto_wgs84_utm33n_agg200mm.tif \
  --weak-labels-csv output/inventory_from_shp/labels_tiles.csv

Migration guidance:

  • Explicit prompts: pixi run satellit -- predict image-masks --image <PATH> --bbox x1,y1,x2,y2
  • Weak prompts: pixi run satellit -- predict image-masks --image <PATH> --weak-labels-csv labels_tiles.csv

Command Group: predict

Usage:

pixi run satellit -- predict --help

Subcommands:

  • image-masks

Command: predict image-masks

Usage:

pixi run satellit -- predict image-masks --image <PATH> [OPTIONS]

Description: Predict and visualize image masks from text, bbox, and/or point prompts.
Inference is streamed over image tiles by default.

Validation rules:

  • Provide at least one prompt source from --text, --bbox, --point, or --weak-labels-csv.
  • --model sam2 does not support --text.
  • --model dinov3 requires --text and supports text prompts only (no --bbox, --point, or --weak-labels-csv).
  • --tile-overlap must be smaller than --tile-size.

Options:

Option Type Required Default Description
--image file path yes - Input image file.
--output-path path no output/predict Output directory for prediction artifacts.
--text str no None Text prompt for segmentation filtering (for example tree).
--bbox str (repeatable) no None Bounding-box prompt in x1,y1,x2,y2 image coordinates.
--point str (repeatable) no None Point prompt in x,y image coordinates. For sam3, points are approximated as boxes.
--model enum (sam3,sam2,dinov3) no sam3 Segmentation backend. dinov3 currently supports --text only.
--threshold float (0.0 <= x <= 1.0) no 0.5 Confidence threshold for keeping predicted masks.
--tile-size int (>= 1) no 640 Tile size in pixels for streamed prediction.
--tile-overlap int (>= 0) no 64 Overlap between neighboring prediction tiles in pixels.
--merge-iou-threshold float (0.0 <= x <= 1.0) no 0.5 IoU threshold used to merge cross-tile detections via global NMS.
--weak-labels-csv file path no None Weak-label CSV from label weak containing tile-local bboxes.
--help flag no - Show help and exit.

Examples:

pixi run satellit -- predict image-masks \
  --image ../data/Traunstein/orthophoto_wgs84_utm33n_agg200mm.tif \
  --text "tree crowns" \
  --tile-size 640 \
  --tile-overlap 64

pixi run satellit -- predict image-masks \
  --model sam2 \
  --image ../data/Traunstein/orthophoto_wgs84_utm33n_agg200mm.tif \
  --point 1200,900

pixi run satellit -- predict image-masks \
  --model dinov3 \
  --image ../data/Traunstein/orthophoto_wgs84_utm33n_agg200mm.tif \
  --text "tree"

Outputs under --output-path:

  • image_masks_visualization.png
  • masks/image_masks.npz with masks, boxes, scores, image_size, source_tile_x, source_tile_y
  • masks/tiles/index.csv with tile_id,x0,y0,width,height,count
  • masks/tiles/tile_x{X}_y{Y}.npz with tile_id,tile_origin,tile_size,masks,boxes,scores

Command Group: process

Usage:

pixi run satellit -- process --help

Subcommands:

  • tiles

Command: process tiles

Usage:

pixi run satellit -- process tiles --image <PATH> [OPTIONS]

Description: Split one image into tiles and save them to disk.

Options:

Option Type Required Default Description
--image file path yes - Input image file.
--output-path path no output/tiles Output directory for generated tile outputs.
--tile-width int (>= 1) no 2048 Tile width in pixels.
--tile-height int (>= 1) no 2048 Tile height in pixels.
--overlap int (>= 0) no 64 Overlap between neighboring tiles in pixels.
--help flag no - Show help and exit.
PreviousIntroduction NextKnowledge Base