Usage

Planning Monthly Planet Composites

plaknit plan queries Planet's Data/STAC API, filters PSScene candidates, tiles the AOI, and picks the smallest monthly set that meets both coverage and clear-observation targets. Planning now only writes/prints a plan; ordering is handled separately by plaknit order.

plaknit plan \
  --aoi /path/to/aoi.gpkg \
  --start 2019-08-01 \
  --end 2019-08-31 \
  --cloud-max 0.05 \
  --sun-elev-min 35 \
  --coverage-target 0.99 \
  --min-clear-fraction 0.9 \
  --min-clear-obs 4 \
  --tile-size-m 1000 \
  --instrument-type PS2.SD \
  --out aug_2019_plan.json

The summary table shows candidate/selected scenes, achieved coverage, and clear observation depth.

Planet limits STAC/Data AOI intersections to 1,500 vertices, so the planner automatically simplifies uploaded AOIs (while preserving topology) until they fit under that threshold and logs how many vertices were removed. Scenes that lack clear/cloud metadata are ignored during scoring so plans only rely on scenes with reliable quality fields.

If you already saved a plan JSON/GeoJSON, submit matching orders later without recomputing coverage:

plaknit order \
  --plan aug_2019_plan.json \
  --aoi /path/to/aoi.gpkg \
  --sr-bands 4 \
  --harmonize-to sentinel2 \
  --order-prefix aug2019

Order output arguments: - --plan: Plan JSON/GeoJSON that defines which scene IDs (and months) are ordered. - --aoi: Geometry used for clipping; the clip AOI is applied to delivered scenes. - --sr-bands: Chooses 4- or 8-band SR bundle; changes the bands in each scene. - --harmonize-to: sentinel2 harmonizes to Sentinel-2; none keeps native SR. - --order-prefix: Prefix for order name and archive filename; batches append _2, _3, etc., and ZIPs end with .zip. - --archive-type: Delivery archive format; Planet currently supports zip only. - --single-archive / --no-single-archive: One ZIP per order vs per-scene files. - -v / -vv: Verbose logging for submissions and retries; no change to output.

The order subcommand loads the stored plan, clips to the provided AOI, and submits orders (chunked at 100 scenes max) while reporting the returned order IDs. If Planet reports any “no access to assets …” errors, plaknit order automatically drops the inaccessible scene IDs and retries so the remaining items can still be delivered.

Mosaic

plaknit mosaic ships with a CLI that is best run in High-Performance Computing Environments. Install the package into the same environment that contains GDAL and Orfeo Toolbox, then run the mosaic workflow:

plaknit mosaic \
  --inputs /path/to/strips \
  --udms /path/to/udms \
  --output /path/to/output/aug_2019.tif \
  --tmpdir /path/to/tmp \
  --jobs 8 \
  --ram 191072

You can call the module directly with python -m plaknit.mosaic if you prefer to pin the interpreter. The progress display stays minimal with four bars: Radiometry (optional) → Mask tiles → Binary mask → Mosaic (shown when rich is installed).

Required arguments

• --inputs / -il: One or more GeoTIFFs or directories. Directories are expanded to all .tif files.
• --output / -out: Destination path for the final mosaic.

Optional arguments

• --udms / -udm: UDM rasters (files or directories). Omit only when --skip-masking is supplied.
• --skip-masking: Use the provided inputs directly without applying the gdal-based UDM mask.
• --harmonize-radiometry: Enable graph-based radiometric harmonization (Harmoni-Planet style) before masking/projection.
• --metadata-jsons / -meta: Metadata JSON files/directories used to build the overlap/time graph; required only when --harmonize-radiometry is enabled.
• --sr-bands: Surface reflectance bundle size (4 or 8).
• --target-crs: Optional CRS override (for example EPSG:32735) applied to every tile before mosaicking.
• --workdir / --tmpdir: Override the locations used for intermediate strips and OTB scratch files. Defaults are automatically managed temp directories.
• --jobs: Number of parallel masking workers (defaults to 4).
• --ram: RAM hint for OTB in MB (defaults to 131072).
• -v/ -vv: Increase logging verbosity.

By default, plaknit mosaic now checks every input CRS and reprojects non-matching rasters to a single target CRS before running OTB. The target is chosen from the majority CRS across inputs; ties are resolved by choosing the CRS from the tile nearest the geographic center of the stack.

Raster/vector distance

Calculate a distance surface from any supported vector source on a projected raster grid:

from plaknit import distance_to_vector

distance_to_vector("template.tif", "features.gpkg", "distance.tif")

The output uses the template grid and stores distances in its CRS map units. Install plaknit[gpu] and pass backend="gpu" to use CuPy.

Random Forest classification

plaknit classify trains and applies a Random Forest to multi-band stacks. The CLI accepts one or more --image paths; you can pass multiple aligned GeoTIFFs directly (or repeat --image) or build a VRT first (gdalbuildvrt stack.vrt band1.tif band2.tif ...). Use --binary-out during prediction to output individual binary masks for each class.

# Train (writes a .joblib model)
plaknit classify train \
  --image /data/stack.vrt /data/mosaic.tif \
  --labels /data/training_points.gpkg \
  --label-column class \
  --model-out /data/rf_model.joblib

# Predict (writes a classified GeoTIFF of class IDs)
plaknit classify predict \
  --image /data/stack.vrt /data/mosaic.tif \
  --model /data/rf_model.joblib \
  --output /data/output/classification.tif \
  --block-shape 512 512 \
  --jobs 8 \
  --smooth mrf \
  --beta 1.0 \
  --neighborhood 4 \
  --icm-iters 3 \
  --block-overlap 0

Python API (same engine, useful for notebooks):

from plaknit import train_rf, predict_rf

rf = train_rf(
    image_path="planet_stack.tif",
    shapefile_path="training_data.geojson",
    label_column="class_id",
    model_out="planet_rf.joblib",
    n_estimators=600,
    test_fraction=0.3,
    n_jobs=32,
    training_buffer_meters=250.0,
)

predict_rf(
    image_path="planet_stack_2024.tif",
    model_path="planet_rf.joblib",
    output_path="planet_stack_2024_classified.tif",
)

Training samples pixels under each polygon window-by-window to keep RAM in check. training_buffer_meters includes surrounding pixels in the training sample while preserving the source geometry label. Prediction streams over raster blocks (--block-shape overrides block size) so it works on laptops and HPC nodes alike; add --jobs to parallelize block prediction with multiple worker processes (watch for CPU oversubscription if the model was trained with n_jobs > 1). Classified rasters store numeric class IDs; inspect rf.label_decoder to map each ID back to its label. Training holds out a fraction of samples for evaluation; prediction logs the holdout confusion matrix plus band importance from the stored model and writes *_metrics.txt next to the output raster (raw + smoothed confusion matrices and misclassified validation IDs when available). See docs/hpcenv.md for a Singularity/Apptainer job template that binds the stack, labels, model, and venv for training + prediction.

Boosted Regression Tree (BRT) Ensemble classification

plaknit brt trains and applies Boosted Regression Tree (BRT) models to multi-band stacks. Training labels use Bernoulli coding: presence is 1 and absence is 0. Ensemble prediction writes unweighted mean probability and confidence-interval rasters.

Training

# Basic ensemble training (5 models, 200 boosting rounds each)
plaknit brt train \
  --image /data/stack.vrt /data/mosaic.tif \
  --labels /data/training_points.gpkg \
  --label-column class \
  --ensemble-dir /data/brt_ensemble/

# Advanced training with hyperparameter tuning
plaknit brt train \
  --image /data/stack.vrt /data/mosaic.tif \
  --labels /data/training_points.gpkg \
  --label-column class \
  --ensemble-dir /data/brt_ensemble/ \
  --n-models 10 \
  --n-estimators 300 \
  --max-depth 8 \
  --learning-rate 0.05 \
  --subsample 0.8 \
  --colsample-bytree 0.9 \
  --test-fraction 0.3 \
  --grid-size 500 \
  --random-state 42 \
  --gpu

Prediction

# Prediction writes mean, lower, and upper probability rasters
plaknit brt predict \
  --image /data/stack.vrt /data/mosaic.tif \
  --ensemble-dir /data/brt_ensemble/ \
  --output-dir /data/output/ \
  --jobs 8

Python API

from plaknit import BRTEnsemble

# Training phase
ensemble = BRTEnsemble(
    n_models=5,
    n_estimators=200,
    max_depth=6,
    learning_rate=0.1,
    random_state=42,
    gpu=True,
)
ensemble.fit(
    image_path="planet_stack.tif",
    shapefile_path="training_data.geojson",
    label_column="class_id",
    ensemble_dir="./brt_ensemble/",
    grid_size=None,
)

# Prediction phase
ensemble.predict(
    image_path="planet_stack_2024.tif",
    ensemble_dir="./brt_ensemble/",
  output_dir="./probability_outputs/",
  feature_importance_out="predictor_importance.csv",
    jobs=8,
)

Key Features

• Ensemble Diversity: Each model in the ensemble is trained with a different random seed, ensuring diverse predictions.
• Unweighted Summaries: Class probabilities are averaged equally across all models, with t-based lower and upper confidence bounds.
• Model Assessment: Holdout ROC AUC is recorded for each member in ensemble metadata and optional model-summary CSV output.
• Predictor Ranking: Optional feature-importance CSVs summarize each input band's unweighted split importance across the ensemble.
• GPU Support: Add --gpu flag to use XGBoost's GPU acceleration (requires plaknit[gpu] installation); gracefully falls back to CPU if unavailable.
• Probability Output: mean_probabilities.tif, lower_probabilities.tif, and upper_probabilities.tif are written to the output directory. One-member ensembles write only the mean raster.
• Spatial Sampling: Use --grid-size to spatially thin training samples for improved generalization.

Hyperparameter Guide

• --n-models: Number of models in the ensemble (5-15 recommended). More models increase ensemble diversity.
• --n-estimators: Boosting rounds per model (100-500). More rounds capture complex patterns but risk overfitting.
• --max-depth: Tree depth (4-8). Shallower trees prevent overfitting; deeper trees capture interactions.
• --learning-rate: Step size for boosting updates (0.01-0.3). Lower rates are more conservative.
• --subsample: Fraction of samples per round (0.5-1.0). Lower values add stochasticity and reduce overfitting.
• --colsample-bytree: Fraction of features per tree (0.5-1.0). Lower values increase diversity.
• --test-fraction: Holdout fraction for evaluation (0.2-0.4). Per-model accuracy is recorded as a diagnostic.

Use --feature-importance-out predictor_importance.csv during ensemble prediction to write unweighted per-band summary statistics. mean_importance is a relative split-contribution ranking, not a linear coefficient or a causal effect.

Comparing BRT Ensemble vs Random Forest

Feature	BRT Ensemble	Random Forest
Model Type	Gradient boosting	Bagging (ensemble)
Training Time	Medium	Fast
Prediction Accuracy	High	High
Interpretability	Low	Medium
GPU Support	Yes	No
Hyperparameter Tuning	More involved	Less involved
Ensemble within Ensemble	Yes (multiple BRTs)	Yes (multiple trees)

Both classifiers are suitable for PlanetScope data; choose BRT for potentially higher accuracy on complex scenes, or Random Forest for faster training with good accuracy.