satellit_sam.cli.label

Auto-generated from satellit_sam/src/satellit_sam/cli/label.py by satellit_sam/scripts/generate_api_docs.py.

Label command group and command handlers for the satellit CLI.

Back to API index

Functions

weak

def weak(
    image_tif: Annotated[
        Path, typer.Option("--image-tif", help="Path to orthophoto GeoTIFF.")
    ],
    inventory_csv: Annotated[
        Path | None,
        typer.Option(
            "--inventory-csv", help="Path to inventory CSV (semicolon-delimited)."
        ),
    ] = None,
    inventory_shp: Annotated[
        Path | None,
        typer.Option(
            "--inventory-shp", help="Path to inventory ESRI Shapefile (.shp)."
        ),
    ] = None,
    output_dir: Annotated[
        Path,
        typer.Option(
            "--output-dir", help="Output directory for labels and optional tiles."
        ),
    ] = ...,
    tile_size: Annotated[
        int, typer.Option("--tile-size", help="Tile size in px.")
    ] = 1024,
    overlap: Annotated[
        int, typer.Option("--overlap", help="Tile overlap in px.")
    ] = 128,
    x_field: Annotated[
        str,
        typer.Option(
            "--x-field",
            help="Inventory field containing x coordinate (CSV or SHP attribute).",
        ),
    ] = "PX",
    y_field: Annotated[
        str,
        typer.Option(
            "--y-field",
            help="Inventory field containing y coordinate (CSV or SHP attribute).",
        ),
    ] = "PY",
    tree_id_field: Annotated[
        str, typer.Option("--tree-id-field", help="Inventory field containing tree id.")
    ] = "TreeID",
    species_field: Annotated[
        str, typer.Option("--species-field", help="Inventory field containing species.")
    ] = "Latin",
    status_field: Annotated[
        str, typer.Option("--status-field", help="Inventory field containing status.")
    ] = "Status",
    status_filter: Annotated[
        str,
        typer.Option(
            "--status-filter",
            help="Only keep rows with this status (case-insensitive). Empty disables filter.",
        ),
    ] = "alive",
    dbh_field: Annotated[
        str,
        typer.Option(
            "--dbh-field", help="Inventory field containing diameter at breast height."
        ),
    ] = "DBH",
    dbh_unit: Annotated[
        DbhUnit, typer.Option("--dbh-unit", help="Unit of DBH values in CSV.")
    ] = "mm",
    default_crown_radius_m: Annotated[
        float,
        typer.Option(
            "--default-crown-radius-m",
            help="Fallback crown radius in meters when DBH is unavailable (common for SHP-only input).",
        ),
    ] = 2.5,
    min_dbh_cm: Annotated[
        float,
        typer.Option(
            "--min-dbh-cm", help="Exclude trees with DBH below this threshold (in cm)."
        ),
    ] = 0.0,
    max_dbh_cm: Annotated[
        float,
        typer.Option(
            "--max-dbh-cm",
            help="Exclude trees with DBH above this threshold (in cm). Use 0 to disable.",
        ),
    ] = 0.0,
    deduplicate_tree_id: Annotated[
        bool,
        typer.Option(
            "--deduplicate-tree-id",
            is_flag=True,
            help="Keep only one row per tree id (highest DBH).",
        ),
    ] = False,
    crown_model: Annotated[
        CrownModel, typer.Option("--crown-model", help="Crown radius model.")
    ] = "linear",
    linear_factor_m_per_cm: Annotated[
        float,
        typer.Option(
            "--linear-factor-m-per-cm",
            help="Linear model slope: crown_radius_m = intercept + factor * dbh_cm.",
        ),
    ] = 0.08,
    linear_intercept_m: Annotated[
        float,
        typer.Option("--linear-intercept-m", help="Linear model intercept in meters."),
    ] = 0.0,
    power_a: Annotated[
        float,
        typer.Option(
            "--power-a", help="Power model factor: crown_radius_m = a * (dbh_cm ^ b)."
        ),
    ] = 0.15,
    power_b: Annotated[
        float, typer.Option("--power-b", help="Power model exponent.")
    ] = 0.8,
    min_crown_radius_m: Annotated[
        float,
        typer.Option("--min-crown-radius-m", help="Lower clamp for crown radius."),
    ] = 0.5,
    max_crown_radius_m: Annotated[
        float,
        typer.Option("--max-crown-radius-m", help="Upper clamp for crown radius."),
    ] = 15.0,
    bbox_padding_px: Annotated[
        float,
        typer.Option(
            "--bbox-padding-px",
            help="Extra padding (in px) added to each weak-label crown bbox.",
        ),
    ] = 4.0,
    export_visualizations: Annotated[
        bool,
        typer.Option(
            "--export-visualizations",
            is_flag=True,
            help="Generate labeling visualization PNGs.",
        ),
    ] = False,
) -> None:
Generate weak labels from tree inventory data.

Arguments

  • image_tif: Orthophoto GeoTIFF path. inventory_csv: Optional inventory CSV path. inventory_shp: Optional inventory shapefile path. output_dir: Output directory for generated artifacts. tile_size: Tile size in pixels. overlap: Tile overlap in pixels. x_field: Inventory x-coordinate field. y_field: Inventory y-coordinate field. tree_id_field: Inventory tree id field. species_field: Inventory species field. status_field: Inventory status field. status_filter: Optional status filter. dbh_field: Inventory DBH field. dbh_unit: DBH input unit. default_crown_radius_m: Fallback radius for missing DBH. min_dbh_cm: Minimum DBH filter. max_dbh_cm: Maximum DBH filter. deduplicate_tree_id: Keep one row per tree id. crown_model: Crown radius model. linear_factor_m_per_cm: Linear model slope. linear_intercept_m: Linear model intercept. power_a: Power model factor. power_b: Power model exponent. min_crown_radius_m: Lower crown-radius clamp. max_crown_radius_m: Upper crown-radius clamp. bbox_padding_px: Extra bbox padding in pixels. export_visualizations: Whether visualization files are exported.

Exceptions

  • typer.BadParameter: If inventory sources are misconfigured.

validate_predictions

def validate_predictions(
    image_tif: Annotated[
        Path, typer.Option("--image-tif", help="Path to orthophoto GeoTIFF.")
    ],
    predictions_npz: Annotated[
        Path | None,
        typer.Option(
            "--predictions-npz",
            help="Optional path to merged SAM3 output NPZ (for example masks/image_masks.npz). If provided together with --predictions-tiles-dir, --predictions-npz is preferred.",
            exists=False,
            file_okay=True,
            dir_okay=False,
            readable=False,
        ),
    ] = None,
    predictions_tiles_dir: Annotated[
        Path | None,
        typer.Option(
            "--predictions-tiles-dir",
            help="Optional path to per-tile prediction NPZ directory (for example output/predict/masks/tiles). Useful for partial/interrupted predict runs.",
            exists=False,
            file_okay=False,
            dir_okay=True,
            readable=False,
        ),
    ] = None,
    inventory_csv: Annotated[
        Path | None,
        typer.Option(
            "--inventory-csv", help="Path to inventory CSV (semicolon-delimited)."
        ),
    ] = None,
    inventory_shp: Annotated[
        Path | None,
        typer.Option(
            "--inventory-shp", help="Path to inventory ESRI Shapefile (.shp)."
        ),
    ] = None,
    output_csv: Annotated[
        Path,
        typer.Option("--output-csv", help="Output CSV path for validation results."),
    ] = Path("output/validation/label_validation.csv"),
    x_field: Annotated[
        str,
        typer.Option(
            "--x-field",
            help="Inventory field containing x coordinate (CSV offset or SHP attribute).",
        ),
    ] = "PX",
    y_field: Annotated[
        str,
        typer.Option(
            "--y-field",
            help="Inventory field containing y coordinate (CSV offset or SHP attribute).",
        ),
    ] = "PY",
    tree_id_field: Annotated[
        str, typer.Option("--tree-id-field", help="Inventory field containing tree id.")
    ] = "TreeID",
    stem_id_field: Annotated[
        str,
        typer.Option(
            "--stem-id-field",
            help="Inventory field containing stem id. Fallback chain: explicit field -> stemtag -> tree_id.",
        ),
    ] = "StemTag",
    species_field: Annotated[
        str, typer.Option("--species-field", help="Inventory field containing species.")
    ] = "Latin",
    status_field: Annotated[
        str, typer.Option("--status-field", help="Inventory field containing status.")
    ] = "Status",
    status_filter: Annotated[
        str,
        typer.Option(
            "--status-filter",
            help="Only keep rows with this status (case-insensitive). Empty disables filter.",
        ),
    ] = "alive",
    dbh_field: Annotated[
        str,
        typer.Option(
            "--dbh-field", help="Inventory field containing diameter at breast height."
        ),
    ] = "DBH",
    dbh_unit: Annotated[
        DbhUnit, typer.Option("--dbh-unit", help="Unit of DBH values in inventory.")
    ] = "mm",
    min_dbh_cm: Annotated[
        float,
        typer.Option(
            "--min-dbh-cm", help="Exclude trees with DBH below this threshold (in cm)."
        ),
    ] = 0.0,
    max_dbh_cm: Annotated[
        float,
        typer.Option(
            "--max-dbh-cm",
            help="Exclude trees with DBH above this threshold (in cm). Use 0 to disable.",
        ),
    ] = 0.0,
    deduplicate_tree_id: Annotated[
        bool,
        typer.Option(
            "--deduplicate-tree-id",
            is_flag=True,
            help="Keep only one row per tree id (highest DBH).",
        ),
    ] = False,
) -> None:
Validate SAM3 strong labels against inventory stem positions.

Arguments

  • image_tif: Orthophoto GeoTIFF path. predictions_npz: Optional merged SAM3 output NPZ path. predictions_tiles_dir: Optional per-tile SAM3 NPZ directory path. inventory_csv: Optional inventory CSV path. inventory_shp: Optional inventory shapefile path. output_csv: CSV path for validation rows. x_field: Inventory x-coordinate field. y_field: Inventory y-coordinate field. tree_id_field: Inventory tree id field. stem_id_field: Inventory stem id field. species_field: Inventory species field. status_field: Inventory status field. status_filter: Optional status filter. dbh_field: Inventory DBH field. dbh_unit: DBH input unit. min_dbh_cm: Minimum DBH filter. max_dbh_cm: Maximum DBH filter. deduplicate_tree_id: Keep one row per tree id.

Exceptions

  • typer.BadParameter: If inventory sources or prediction payload are invalid.

by_bounding_boxes

def by_bounding_boxes(
    image_path: Annotated[
        Path,
        typer.Option(
            "--image",
            help="Path to the input image file (e.g., GeoTIFF)",
            exists=True,
            file_okay=True,
            dir_okay=False,
            readable=True,
        ),
    ],
    tile_size: Annotated[
        int,
        typer.Option(
            "--tile-size", help="Size of tiles to split the image into (in pixels)"
        ),
    ] = 2048,
    overlap: Annotated[
        int, typer.Option("--overlap", help="Overlap between tiles (in pixels)")
    ] = 64,
    output_path: Annotated[
        Path,
        typer.Option(
            "--output-path", help="Directory path where output tiles will be saved"
        ),
    ] = Path("output/test_tiles"),
    bbox_prompts: Annotated[
        list[str] | None,
        typer.Option(
            "--bbox",
            help="Bounding-box prompt in image coordinates as x1,y1,x2,y2. Repeat --bbox to provide multiple boxes.",
        ),
    ] = None,
    weak_labels_csv: Annotated[
        Path | None,
        typer.Option(
            "--weak-labels-csv",
            help="Path to labels_tiles.csv generated by 'label weak'. Uses stored per-tree tile-local bboxes as box prompts.",
            exists=True,
            file_okay=True,
            dir_okay=False,
            readable=True,
        ),
    ] = None,
) -> None:
Generate label overlays from explicit or weak-label box prompts.

Deprecated:
Use predict image-masks to persist strong labels as NPZ artifacts:
predict image-masks --bbox ... or
predict image-masks --weak-labels-csv ....

Arguments

  • image_path: Input image path. tile_size: Tile size in pixels. overlap: Tile overlap in pixels. output_path: Output directory for generated tiles. bbox_prompts: Optional image-space box prompts. weak_labels_csv: Optional weak-label CSV with tile-local prompts.

Exceptions

  • typer.BadParameter: If prompt arguments are invalid.

Classes

No public classes.

PreviousAPI Reference Nextsatellit_sam.cli.predict