# RS-Visao-Real

Esqueleto Python de referência para GIS e imagem de satélite em emergências no RS

- URL: https://fernando.moretes.com/open-source/RS-Visao-Real

- Markdown: https://fernando.moretes.com/open-source/RS-Visao-Real/guide.md?lang=pt

- GitHub: https://github.com/fernandofatech/ref-rs-visao-real

- Homepage: https://fernando.moretes.com

- Language: Python

- Topics: brazil, emergency-response, gis, moretes, open-source, portfolio, python, rio-grande-do-sul, satellite-imagery

- Stars: 5

- Forks: 0

- Updated: 2026-09-29T16:37:49Z

---

RS Visão Real é uma arquitetura de referência em Python, ainda em estágio de esqueleto, para trabalhar com imagem de satélite e GIS aplicados à resposta a emergências no Rio Grande do Sul.

## Por que este repositório existe

As enchentes de maio de 2024 no Rio Grande do Sul expuseram um problema que quem trabalha com dados conhece bem: a imagem de satélite existe, o mapa existe, mas entre o dado bruto e uma decisão de campo ficam horas de trabalho manual. O nome e os tópicos deste repositório (`satellite-imagery`, `gis`, `emergency-response`, `rio-grande-do-sul`) apontam para esse espaço: transformar imagem em leitura objetiva do que está acontecendo no território.

Quero ser direto sobre o estado atual. O README descreve o tipo do projeto (arquitetura de referência), a stack (Python), como montar o ambiente e a estrutura `src/` e `tests/`. Ele não documenta pipeline de processamento, fonte de imagem, formato de saída nem API. Este guia não vai inventar essas partes.

O que dá para afirmar com segurança é o contrato de engenharia: ambiente isolado em `venv`, dependências declaradas em `requirements.txt`, código separado de teste e uma esteira de CI herdada de um repositório central.

**Por que isso importa:** em resposta a emergência, o código que sobrevive não é o mais esperto, é o que outra pessoa consegue rodar às duas da manhã sem precisar falar comigo. Um esqueleto previsível vale mais que uma demo brilhante que só roda na minha máquina.

## O que você encontra hoje

- **Stack:** Python puro, com ambiente isolado em `.venv` e dependências em `requirements.txt`.
- **Layout:** código em `src/`, testes em `tests/`, sem nada misturado na raiz.
- **Domínio:** GIS e imagem de satélite para resposta a emergências no Rio Grande do Sul, segundo os tópicos do repositório.
- **Esteira:** `pr-lint`, CI, segurança e release vêm dos workflows reutilizáveis do `platform`.
- **Versionamento:** a versão sai dos Conventional Commits; ninguém escreve número de versão à mão.

## Como o repositório está organizado

A estrutura é deliberadamente mínima:

```
src/
tests/
requirements.txt
```

**`src/`:** onde mora o código do projeto. Separar o código de produção num diretório próprio evita o erro clássico de importar o módulo local em vez do instalado e mascarar bug de empacotamento.

**`tests/`:** testes isolados do código. Em projeto geoespacial isso pesa mais que o normal: uma mudança de projeção cartográfica ou de ordem de coordenadas (latitude/longitude contra longitude/latitude) não quebra nada em tempo de execução, só desloca o resultado no mapa. Teste é o único lugar onde esse tipo de erro silencioso aparece.

**`requirements.txt`:** a lista de dependências. Abra esse arquivo antes de assumir qualquer biblioteca. O ecossistema geoespacial em Python é rico, mas não afirmo aqui quais bibliotecas este repositório usa: quem decide é o arquivo, não o guia.

A escolha de Python não é acidental para esse domínio. É a linguagem em que a maior parte das ferramentas de sensoriamento remoto e análise espacial tem binding maduro, e é a que analista de geoprocessamento já lê. Num cenário de emergência, isso reduz o tempo entre alguém novo chegar e alguém novo contribuir.

> **Instalação geoespacial pode falhar fora do Python:** Se o `requirements.txt` trouxer bibliotecas com dependência nativa (GDAL, por exemplo), o `pip install` pode exigir pacotes de sistema que o `venv` não instala. O erro aparece como falha de compilação, não como dependência faltando. Confira o arquivo e o sistema operacional antes de culpar o código.

## Instalar e usar

1. **Clone o repositório**: `git clone https://github.com/fernandofatech/ref-rs-visao-real.git` e entre no diretório com `cd ref-rs-visao-real`.

2. **Crie o ambiente isolado**: `python3 -m venv .venv && source .venv/bin/activate`. Nunca instale direto no Python do sistema: conflito de versão de biblioteca geoespacial é difícil de desfazer.

3. **Instale as dependências**: `pip install -r requirements.txt`. Se falhar na compilação, veja o aviso acima sobre dependências nativas.

4. **Leia `src/` e `tests/` antes de rodar**: Como o README não documenta ponto de entrada, os testes são a melhor descrição do comportamento esperado. Comece por eles.

5. **Rode os testes**: Se o `pytest` estiver nas dependências, `python -m pytest tests` roda a suíte. Se não estiver, instale no `venv` antes.

6. **Contribua seguindo a convenção**: Branch no formato `<tipo>/<escopo>` (`feat/`, `fix/`, `chore/`, `docs/`) e título de PR em Conventional Commits. O `pr-lint` recusa o resto.

_Quickstart: do clone ao ambiente pronto_

```bash
git clone https://github.com/fernandofatech/ref-rs-visao-real.git
cd ref-rs-visao-real
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
ls src tests
# se o pytest estiver instalado / if pytest is installed
python -m pytest tests
```

## Como o repositório funciona hoje

O fluxo real documentado: ambiente local isolado, código e testes separados, e uma esteira que vem de fora do repositório.

### 💻 Local: ambiente

- .venv Python isolado (compute)
- requirements.txt dependências (storage)
- src/ código (compute)
- tests/ verificação (ci)

### 🔧 CI: platform

- pr-lint Conventional Commits (ci)
- CI + segurança workflows reutilizáveis (security)
- release versão pelos commits (ci)

### 🌐 Externo

- fernandofatech/platform fonte da régua (external)

### Fluxos

- dev -> venv: cria e ativa
- req -> venv: pip install -r
- venv -> src: executa
- tests -> src: verifica
- dev -> lint: abre PR
- lint -> ci: título válido
- ci -> release: merge na main
- platform -> ci: define a régua

## Convenções e esteira

Este repositório não define a própria esteira. Ele segue as convenções de [`fernandofatech/platform`](https://github.com/fernandofatech/platform), e isso é uma decisão de manutenção, não de preguiça.

**Branch:** `<tipo>/<escopo>`, com `feat/`, `fix/`, `chore/` ou `docs/`.

**Commit e título de PR:** [Conventional Commits](https://www.conventionalcommits.org). O `pr-lint` barra o que não segue o formato.

**Versão:** sai dos commits. Ninguém escreve número de versão à mão, então não existe o PR que esquece de subir a versão nem o que sobe duas vezes.

**Pipeline:** `pr-lint`, CI, segurança e release vêm de workflows reutilizáveis. Corrigir a régua é mudar um arquivo lá, não aqui.

O custo de manter CI não é escrever o primeiro YAML, é manter dezenas de cópias alinhadas por anos. Com vários repositórios de referência no portfólio, cada um com sua própria esteira, uma correção de segurança no scanner viraria dezenas de PRs quase idênticos. Centralizar troca isso por uma mudança só. O trade-off é real: quem clona este repositório sozinho não vê a definição da esteira localmente e precisa ir ao `platform` para entender por que um PR foi recusado.

## Perguntas frequentes

### Posso usar isto em produção numa emergência real?

Não como está. É uma arquitetura de referência em estágio de esqueleto: o README não documenta pipeline, fonte de imagem nem formato de saída. Use como ponto de partida estruturado, não como ferramenta pronta.

### Qual satélite ou fonte de imagem o projeto usa?

O README não diz. Leia `src/` e `requirements.txt` para ver o que está de fato implementado antes de assumir uma fonte.

### Como contribuo?

Abra uma branch `<tipo>/<escopo>`, escreva commits em Conventional Commits e abra o PR. A esteira do `platform` faz lint, CI, segurança e release.

## Referências

- [GitHub: fernandofatech/ref-rs-visao-real](https://github.com/fernandofatech/ref-rs-visao-real)
- [Fernando Moretes (homepage)](https://fernando.moretes.com)
- [fernandofatech/platform](https://github.com/fernandofatech/platform)
- [Conventional Commits](https://www.conventionalcommits.org)

## Para quem é

Use este repositório quando você quer começar um projeto Python de GIS ou imagem de satélite para resposta a emergência e precisa de uma base com ambiente isolado, testes separados e esteira padronizada desde o primeiro commit. Não use quando você precisa de uma ferramenta pronta para analisar imagem amanhã: o esqueleto entrega disciplina de engenharia, não processamento geoespacial documentado.

## Links

- [GitHub repository](https://github.com/fernandofatech/ref-rs-visao-real)
- [Homepage](https://fernando.moretes.com)