Installation

How to install rapidtools 0.2.0 from PyPI or source, set up PyTorch for your GPU, and supply the credentials that hosted models, gated Hugging Face weights and Mapillary need.

Requirements

Item	Requirement
Python	3.11 or newer (3.11, 3.12 and 3.13 are tested)
Operating system	Linux, macOS or Windows
Core dependencies	torch, torchvision, transformers>=5.15, accelerate, bitsandbytes, huggingface-hub, rasterio, shapely>=2.0, pyproj, pyshp, pandas, pillow, scikit-image, networkx, matplotlib, mapbox_vector_tile, requests, tqdm
GPU	Optional. Needed for local vision-language models and for fast SAM 3 detection. Hosted models (Gemini, Claude, OpenAI, Muse Spark, Qwen) run without one.

PyTorch and Transformers are hard dependencies today, so pip install rapidtools always pulls them in. Importing the package is still fast (about 2 s) because model classes load on first use.

Install from PyPI

pip install rapidtools

In a fresh conda environment:

conda create -n rapidtools python=3.11
conda activate rapidtools
pip install rapidtools

GPU users: install PyTorch first

pip picks a default torch wheel that may not match your CUDA driver. Install torch and torchvision from the PyTorch index for your CUDA version before installing rapidtools, and take both from the same index. Mixing a CUDA torch with a default torchvision wheel makes every model module fail with operator torchvision::nms does not exist.

# CPU-only example; pick the matching CUDA index from pytorch.org for a GPU
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install rapidtools

4-bit loading (load_in_4bit=True) uses bitsandbytes and works only on CUDA GPUs.

Install from source

git clone https://github.com/RAPID-Facility/rAPIdtools.git
cd rAPIdtools
pip install -e ".[dev]"

Extras: test (pytest, pytest-cov, requests-mock), docs (Sphinx and the Book theme) and dev (both plus ruff, black, mypy). See Contributing and Development.

Verify the installation

import rapidtools as rt
from rapidtools.models import list_providers

print(rt.PhysicalAssetCollection)
print(list_providers(kind='api'))    # ['gemini', 'claude', 'openai', 'muse_spark', 'qwen']
print(list_providers(kind='local'))  # ['gemma4', 'llama', 'muse_glimmer', 'qwen_vl', 'hf']

The GUI is installed as a console script; rapidtools-gui or python -m rapidtools.gui opens it in a browser. See Graphical Interface.

Credentials

Hosted model API keys

Pass api_key= to rapidtools.models.load() (a key string or the path of a file holding the key), or set one of the environment variables below. The first variable listed is the primary name; the second is an accepted alias.

Provider	Registry key	Environment variable(s)
Google Gemini	'gemini'	GOOGLE_API_KEY, GEMINI_API_KEY
Anthropic Claude	'claude'	ANTHROPIC_API_KEY
OpenAI	'openai'	OPENAI_API_KEY
Meta Muse Spark	'muse_spark'	MODEL_API_KEY, META_API_KEY
Alibaba Qwen (Model Studio)	'qwen'	DASHSCOPE_API_KEY, QWEN_API_KEY

import rapidtools as rt

model = rt.models.load('gemini')                    # key from GOOGLE_API_KEY
model = rt.models.load('claude', api_key='sk-ant-...')

Hugging Face (local models)

Gemma and Llama weights are gated. Log in once; the token is cached for later sessions:

import rapidtools as rt
rt.login()           # reuses a token cached by `huggingface-cli login`
rt.login('hf_...')   # or pass a token explicitly

Local wrappers call rapidtools.ensure_huggingface_login() themselves before downloading weights, so this step is optional. Accept the model licence on the Hugging Face model page first.

Mapillary

Google Street View and the Bing and Google aerial basemaps need no key. Mapillary needs a free access token from mapillary.com/developer, passed as access_token= to MapillaryImageExtractor, MapillaryFeatureExtractor and MapillaryObjectImageExtractor. The examples download a shared token with download_dataset('mapillary_token').

Sample data

Every example fetches its inputs through rapidtools.download_dataset(), which saves files into a directory of your choice and skips files that already exist:

from rapidtools import download_dataset

raster, footprints, prompt = download_dataset(
    ['eaton_patch2', 'altadena_sample_buildings', 'aerial_chs_prompts'],
    output_dir='data',
)

Name	Contents
eaton_patch1, eaton_patch2	Drone orthomosaics (GeoTIFF) of Altadena, CA after the January 2025 Eaton Fire
altadena_sample_buildings, eaton_patch1_bing_buildings	Building footprints (GeoJSON)
aerial_chs_prompts, street_chs_prompts, street_recovery_prompts	Prompt files used by the examples
synthetic_landslide_image	One PNG for single-image inference

Next steps

• Quickstart runs a complete aerial damage assessment.
• Supported Models lists every provider, model ID and default.
• Troubleshooting and FAQ covers CUDA, memory and credential problems.
• The full API reference is at https://rapid-facility.github.io/rAPIdtools/.