Code Explorer

Modern Python web framework used to expose the /classify endpoint.

FastAPI turns Python functions into HTTP endpoints. It auto-generates interactive /docs (OpenAPI/Swagger), validates request and response bodies using Pydantic, and handles async I/O so file uploads don't block other requests.

FastAPI helpers that accept a file from a multipart form upload.

`UploadFile` is a streaming wrapper around an uploaded file (so huge satellite TIFFs don't have to fit in RAM at once). `File(...)` marks the parameter as required form data. The browser sends bytes as multipart/form-data; FastAPI parses them for you.

Python keywords that let the server handle other requests while reading the upload.

`async def` declares a coroutine. `await file.read()` pauses this request to release the worker; FastAPI can then serve other classify calls in parallel. Without async, slow uploads would block the whole API.

Data-validation library that defines the JSON shape of responses.

Classes that inherit from `BaseModel` describe required fields and their types. Pydantic rejects malformed data automatically and feeds the schema to FastAPI's /docs page so students can see the exact JSON contract.

Pydantic field constraint — here, 'must be between 0 and 1 inclusive'.

`ge` = greater-or-equal, `le` = less-or-equal. Used on `confidence` so a buggy model output like 1.7 is rejected before reaching the frontend. The `...` means the field is required.

Python typing trick that locks a string to a fixed set of allowed values.

`Literal['GREEN','YELLOW','RED']` means the placard string MUST be one of those three. Pydantic enforces it at runtime, and editors autocomplete the allowed values — much safer than a free-form string.

Open Neural Network Exchange — a portable file format for trained AI models.

ONNX (.onnx) is a framework-agnostic container. A model trained in PyTorch or TensorFlow is exported to ONNX so it can be served anywhere — no need to ship the original training code or huge framework. The damage model in this project is `damage_v1.onnx`.

Microsoft's high-performance engine that executes ONNX graphs.

Imported as `import onnxruntime as ort`. It loads the .onnx file, builds an optimized computation graph, and runs inference on CPU or GPU. Much smaller and faster to start than PyTorch.

An in-memory, ready-to-run instance of the ONNX model.

Created once at app startup: `ort.InferenceSession(path, providers=[...])`. Each `.run()` call is a forward pass. Reusing the session avoids paying the multi-second weight-loading cost on every request.

Tells onnxruntime to run the model on the CPU.

Other providers include `CUDAExecutionProvider` (NVIDIA GPU), `CoreMLExecutionProvider` (Apple), etc. CPU is fine for the small damage model and avoids needing a GPU server during the workshop.

Python Imaging Library — opens and resizes JPEG/PNG photos.

`Image.open(BytesIO(raw)).convert('RGB').resize((512,512))` decodes the bytes, forces 3 channels, and resizes to match the model's training resolution.

GIS library for reading georeferenced satellite imagery (GeoTIFF).

Built on GDAL, Rasterio understands multi-band TIFFs that may have 7+ bands at 16-bit precision plus geospatial metadata (CRS, transform). We only need three bands for false-color RGB.

Rasterio helper that opens raw bytes as if they were a file on disk.

Lets us read an uploaded TIFF directly from memory — no temp files, no disk I/O, no race conditions between concurrent uploads.

TIFF image that also stores geographic coordinates and projection info.

The format satellites like Landsat use. Each `.tif` can contain many spectral bands (visible, near-infrared, shortwave-infrared) plus the GPS bounding box of the scene.

Separate channels capturing different wavelengths of light.

Landsat 8/9 has bands for Coastal, Blue, Green, Red, NIR, SWIR, etc. `src.read([5, 3, 2])` picks NIR + Red + Green — the classic vegetation-and-structures false-color combination used for damage assessment.

Light just past red — invisible to humans but reflected strongly by vegetation.

Healthy vegetation glows bright in NIR; damaged/collapsed structures, soil, and debris look very different. That contrast is exactly what the damage-classification model learns from.

An RGB image where one or more channels come from non-visible bands.

Mapping NIR→R, Red→G, Green→B produces the iconic red-vegetation look. It isn't 'real' colour, but it surfaces damage patterns that natural-color photos hide.

Raw, un-normalized scores the model outputs — one per class.

For 4 classes you get 4 numbers like `[2.31, -0.42, -1.10, -3.05]`. They can be negative or large; they are not probabilities yet. Softmax converts them to a probability distribution.

Function that turns logits into probabilities that sum to 1.

Formula: `softmax(x)_i = exp(x_i) / Σ exp(x_j)`. We subtract `x.max()` first for numerical stability (so `exp()` doesn't overflow). After softmax, the largest value is the model's confidence in its top class.

Returns the index of the largest value in an array.

`probs.argmax()` gives the position (0–3) of the most confident class. Combined with `LABELS[...]` it becomes the readable name like `'minor-damage'`.

Multi-dimensional numeric array — the standard input/output of neural networks.

A scalar is 0-D, a vector 1-D, a matrix 2-D. An image batch is 4-D: (N, C, H, W). In Python it's a numpy `ndarray` of dtype float32.

How the axes of an image tensor are ordered.

HWC = Height × Width × Channels (what Pillow returns). CHW = Channels first (PyTorch/ONNX convention). NCHW adds the batch dimension N at the front. The preprocessor transposes HWC → CHW, then expands to NCHW.

Extra leading axis that lets the model accept many images at once.

Even when classifying a single image, the model expects shape `(1, 3, 512, 512)` — the leading `1` is a batch of one. `np.expand_dims(chw, axis=0)` adds it.

Python's numerical-array library; backbone of all the math here.

`numpy` provides fast C-backed N-dimensional arrays plus operations like `exp`, `argmax`, `transpose`. Both onnxruntime and the preprocessing pipeline pass data around as `np.ndarray` of dtype `float32`.

Numeric precision used at different stages.

Standard photos store pixels as 8-bit ints (0–255). Satellite GeoTIFFs use 16-bit ints (0–65535) for more dynamic range. The model expects 32-bit floats in [0, 1], so we divide by 255 or 65535 and cast to `float32`.

Post-earthquake building safety evaluation standard from the Applied Technology Council.

After a disaster, inspectors tag every building with a placard: GREEN (safe), YELLOW (restricted use), or RED (unsafe — do not enter). This model automates the first-pass screening so human engineers can focus on borderline cases.

The three ATC-20 safety tags returned to the user.

GREEN = routine entry allowed. YELLOW = limited/restricted entry, engineer review needed. RED = unsafe, do not enter. The `to_placard()` rule downgrades any low-confidence prediction to YELLOW for safety.

Below this probability the system refuses to issue GREEN or RED.

Engineering safety principle: when the model is unsure, fail to YELLOW so a human inspects. The threshold is tunable — higher = more YELLOWs but fewer dangerous misses.

The first few bytes of a file that uniquely identify its real format.

JPEG starts with `FF D8 FF`, PNG with `89 50 4E 47`, TIFF with `II*\0` or `MM\0*`. Checking these is much safer than trusting the filename extension — attackers can rename `evil.exe` to `photo.jpg`.

HTTP content-type used to upload binary files alongside form fields.

When a browser submits `<input type='file'>`, the body is split into boundary-separated parts (one per field). FastAPI parses each part and hands the file one to `UploadFile`.