Examples

An index of the worked examples in the repository's examples/ folder: what each one does, what it needs (sample dataset, API key, GPU) and how long it takes where the source says so.

All scripts fetch their inputs with rapidtools.download_dataset() unless noted (dataset names are listed in Installation). "GPU" means a local model or SAM 3 runs on your machine; hosted-model examples run on any machine with a key. Longer write-ups of several examples are on the documentation site; the rows below link to them where they exist.

Aerial imagery

Example	What it does	Needs	Notes
fire_damage_from_aerial.py	Crops each building footprint from a drone orthomosaic, outlines it, and grades it on the CHS damage scale with a local Gemma 4 model; exports GeoJSON.	eaton_patch2, altadena_sample_buildings, aerial_chs_prompts; GPU (a few GB for google/gemma-4-E2B-it)	The Quickstart workflow. Docs: Aerial damage assessment: Eaton Fire.
fire_damage_from_aerial_gemini.py	Same pipeline with the Gemini API instead of a local model.	Same datasets; a Gemini key in api_key.txt in the working directory; no GPU	Shows that only the model line changes.
chs_from_shapefile_example.py	Reads a building inventory from a Shapefile, grades it with Gemini 3.8 Flash (5 m buffer, outline overlay) and writes the result back to a Shapefile.	Your own building Shapefile; aerial_chs_prompts; Gemini key in api_key.txt; no GPU	Uses PhysicalAssetCollection.from_shapefile() / to_shapefile(). See Data Formats and Export.
building_detection_from_bing.py	Takes the extent of a drone raster, stitches a Bing basemap of it (no key), finds roofs with SAM 3, crops around each and refines the masks with BuildingRegularizer.	eaton_patch1; GPU for SAM 3 and the regularizer	Produces a footprint inventory where none exists. Docs: Building footprints from a Bing basemap.
road_detection_from_aerial.py	Masks paved roads in an orthomosaic with SAM 3 and reduces them to connected centrelines with width_ft and azimuth_deg attributes via RoadwayRegularizer.	eaton_patch1; GPU	Docs: Road centrelines from an orthomosaic.
vegetation_detection_from_aerial.py	Maps canopy with SAM3OrthoFeatureExtractor(prompt='vegetation') and low thresholds; writes merged polygons.	Expects eaton_patch_20250214.tiff (the eaton_patch1 file) in the working directory; GPU	Same extractor as the roads example with different thresholds.

Street-level imagery

Example	What it does	Needs	Notes
fire_recovery_analysis_from_street.py	Fetches Mapillary panoramas of each building from two surveys (February and September 2025), grades initial damage from the February views with Gemma 4, keeps the damaged buildings and re-evaluates them for recovery progress.	eaton_patch1_bing_buildings, street_chs_prompts, street_recovery_prompts, mapillary_token; GPU	Longitudinal workflow. Docs: Street-level damage and recovery.
vehicle_detection_from_street.py	Discovers every vehicle in the August 2026 RAPID Mapillary survey of a Spokane, WA neighbourhood from Mapillary's own detections (no image downloads), tracks and triangulates them, folds split outlines and far sightings into one object each, crops the two widest views with a rotated outline, verifies each object with Gemini, merges the pairs Gemini is sure are one vehicle and, optionally, grades condition.	mapillary_token; optional Gemini key via GOOGLE_API_KEY or api_key.txt (verification and condition run only with it); no GPU, CLIP loads on CPU if needed	About 6 minutes and 1.3 GB RAM for the 1 km neighbourhood (around 650 vehicles before verification, 450 after); the whole-survey box in the script's comment takes about 75 minutes just to read detections. Docs: Vehicles along a street-level survey.
label_mapping.py	Translates plain-English object names into Mapillary's label vocabulary with MapillaryLabelMapper backed by a local Gemma 4 model.	GPU; no data	Building block for the street-level detectors.

Single images and the GUI

Example	What it does	Needs	Notes
single_image_vlm_inference.py / .ipynb	Runs one diagnostic prompt on a synthetic landslide image with Gemma 4 and prints the answer.	synthetic_landslide_image; GPU	Prototype prompts here before running them over an inventory. Docs: Single-image inference.
asset_analysis_gui.py	Launches the browser interface (same as rapidtools-gui).	Nothing extra	See Graphical Interface.

Notebooks

Notebook	What it does	Needs
asset_analysis_example.ipynb	Part 1 builds a building inventory from a Bing basemap with SAM 3 and BuildingRegularizer; Part 2 grades the buildings on the drone raster with Gemini. Has an Open in Colab badge.	eaton_patch1, aerial_chs_prompts; Gemini key; GPU for Part 1
asset_analysis_example_generalized.ipynb	The same two parts for any asset type you name (for example building, tree) instead of buildings only.	eaton_patch1, aerial_chs_prompts; Gemini key; GPU for Part 1
longitudinal_analysis_example.ipynb	Three parts: inventory from Bing + SAM 3, aerial damage grading with Gemma 4, then multi-temporal street-level recovery tracking from Mapillary.	eaton_patch1, aerial_chs_prompts, street_recovery_prompts, mapillary_token; GPU

Sample prompt files

The prompt files in the dataset registry ask for a JSON object, so every key becomes an asset attribute under the model's prefix (for example gemma4_chs_level or gemini_chs_level).

Dataset name	Used by	Purpose
aerial_chs_prompts	aerial examples and notebooks	CHS damage level from an aerial crop
street_chs_prompts	fire_recovery_analysis_from_street.py	CHS damage level from street-level views
street_recovery_prompts	fire_recovery_analysis_from_street.py, longitudinal_analysis_example.ipynb	Recovery status of a damaged building

The same three prompts are available in the GUI's prompt library, and its prompt builder can adapt them to another task (Graphical Interface).

Running an example

pip install rapidtools
git clone https://github.com/RAPID-Facility/rAPIdtools.git
cd rAPIdtools
python examples/fire_damage_from_aerial.py

Outputs are written to the working directory or an output/ folder next to it, as GeoJSON plus the image crops the model saw. The older scripts construct provider-specific analyzers such as Gemma4AssetAnalyzer; those classes still work but are deprecated, and the documentation versions of the same examples use AssetAnalyzer(load('gemma4', ...)), which is the form to copy into new code. See Core Concepts.

Related pages

• Aerial Imagery Workflows and Street-Level Imagery Workflows explain the components these examples combine.
• Supported Models lists the registry keys and credentials.
• Troubleshooting and FAQ covers out-of-memory errors and rate limits.