RS-Visao-Real
Python reference architecture: from satellite scene to emergency-response map in RS
git clone https://github.com/fernandofatech/ref-rs-visao-real.gitListen to guide
generated on playGenerated only on first play
Powered by Amazon Polly + OmniVoice
RS-Visão-Real is a Python reference architecture for turning public satellite imagery into an operational emergency view of Rio Grande do Sul — it came out of the May 2024 floods, when the question "where is the water right now?" had no timestamped answer.
Why this repository exists
In May 2024, 478 of Rio Grande do Sul's 497 municipalities declared a state of emergency or public calamity. Anyone who took part in the response those weeks — civil defense, city halls, volunteers on boats — hit the same wall: information arrived by WhatsApp, phone photos and rumor. Goodwill was not the shortage; a datum with a timestamp and a coordinate was.
Satellites answer that. Sentinel-1 revisited the region every 12 days in its 2024 configuration (a single satellite in orbit) and sees through cloud, because it is radar (SAR), not a camera — and flood rain comes with an overcast sky. Sentinel-2 delivers the optical image once the sky clears. The data is public and free on the Copernicus Data Space. What was missing was not imagery — it was a reproducible path from raw scene to a polygon a shelter coordinator can open on a phone.
This repository is my answer to that, shaped as a reference architecture: Python code in src/, tests in tests/, and the pipeline discipline inherited from fernandofatech/platform. It does not try to replace the Copernicus Emergency Management Service or official mapping. It tries to show how a small team stands up, in days rather than months, the pipeline that turns imagery into a decision — and keeps it running on every new satellite pass without anyone clicking.
What this repository delivers
src/ and tests/ from the first commit: the layout that takes CI, lint and release without rework.platform: pr-lint, CI, security scanning and a semantic release derived from commits — nobody types a version number by hand.From raw scene to operational map
The flow the reference architecture describes. SAR is the primary source because it sees through cloud; optical comes in as confirmation once the sky clears.
- Sentinel-1 · cena SAR GRD
- Sentinel-2 · cena ótica
- Ingestão · download + recorte da AOI
- Detecção de água · limiar SAR + diff pré-evento
- Vetorização · GeoTIFF → GeoJSON
- tests/ · valida cada etapa
- Mapa operacional · QGIS / camada web
Install and run
- 1
Clone the repository
git clone https://github.com/fernandofatech/ref-rs-visao-real.git && cd ref-rs-visao-real. No submodules and no bundled data — satellite scenes weigh gigabytes and do not belong in git. - 2
Create the virtual environment and install dependencies
python3 -m venv .venv && source .venv/bin/activatefollowed bypip install -r requirements.txt. Use the.venveven on a throwaway machine: geospatial libraries (GDAL and its dependents) clash with system versions more often than you want to discover at 2 AM. - 3
Read `src/` before running anything
The README documents only the environment and the layout. The entry point, the area-of-interest parameters and the output format live in the code — open
src/and follow from the main module down. Assuming a feature from the repository name is the fastest way to lose an afternoon. - 4
Run the tests
python -m pytest tests/(ifrequirements.txtships pytest) proves the environment is sound before you download the first scene. Green tests here are worth more than a fast download: a corrupted SAR scene fails silently and becomes a wrong polygon.
git clone https://github.com/fernandofatech/ref-rs-visao-real.git
cd ref-rs-visao-real
# Ambiente isolado: biblioteca geoespacial não perdoa versão de sistema
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Prove o ambiente antes de gastar banda com imagem de satélite
python -m pytest tests/
# Ponto de entrada, parâmetros da AOI e formato de saída estão em src/
ls src/How the architecture works
The design has four stages, and the order matters.
Ingestion: the area of interest (AOI) is a polygon — the whole state or a basin like the Guaíba's — and the scene is clipped to it before any processing. A full Sentinel-1 GRD scene exceeds 1 GB; clipping first is the difference between running on a laptop and needing a dedicated machine.
Water detection: in radar, calm water shows up dark because it reflects the signal away from the sensor. A backscatter threshold in dB separates water from land across most of the scene. The part the threshold gets wrong is the part that matters: wind roughens the surface and brightens the water; a building aligned with the orbit produces double-bounce and glows. That is why this stage compares against a pre-event scene — without that baseline, every reservoir, lagoon and the Guaíba itself become "flood" on the map.
Vectorization: the raster mask (GeoTIFF) becomes a polygon (GeoJSON) with the pass time written as an attribute. That timestamp is the product's most valuable datum: a map without a time is a map nobody trusts by day three.
Publishing: GeoJSON is the format that opens in QGIS, in a web layer and on a phone. No server, no spatial database, no cloud account — by design. In a crisis, every extra dependency is one more thing that can be down.
tests/ validates each stage against a small reference scene, which lets you change the threshold or the raster library without discovering the regression on the day of the next flood.
Thin README, calibrated expectations
The README documents the virtual environment, requirements.txt and the src/ + tests/ layout — nothing beyond that. This guide describes the design the reference architecture follows; the exact list of modules, parameters and supported formats lives in the code, and that is where you confirm before relying on any stage. A reference repository is a starting point, not an on-call-ready product.
Frequently asked questions
Does it work for a region other than Rio Grande do Sul?
Yes. The area of interest is an input polygon, not a constant. RS is the case because it was the crisis that motivated the repository and because Sentinel-1 covers the whole state — swap the polygon and the rest of the flow stays the same.
Do I need a cloud account or paid imagery?
No. Sentinel-1 and Sentinel-2 are free on the Copernicus Data Space after registration, and the pipeline runs locally on a laptop with disk space for the clipped scene. Higher-resolution commercial imagery comes in when you need to tell a house from a street; to know where the water reached, public data is enough.
Why a Python pipeline and not just QGIS?
QGIS is the analyst's tool for looking at one scene. The pipeline is for repeating the same processing on every satellite pass, with the same threshold and the same tests, without anyone clicking at 5 AM. Use QGIS to check the result; use the pipeline to produce it.
References
Who it's for
Use this repository when: you need a timestamped water view over a large area, the sky is overcast (which rules out optical), and the team has one person who reads Python — no remote-sensing specialist required. Don't use it when what you need is meter-level resolution to count rooftops, or when an official Copernicus EMS product has been activated for the event — in that case consume the official one and use this pipeline for the passes between activations. The cost that matters here is not building the pipeline; it's keeping it validated for the next flood, and that is what tests/ is for.
Architecture, AWS, AI and market deep dives — straight to your inbox. Free.
No spam · unsubscribe anytime