shapes-overlay
✨ Objetivo
Este aplicativo realiza operações espaciais entre dois arquivos Shapefile (.shp) utilizando a função overlay da biblioteca GeoPandas. A entrada consiste em dois shapefiles (ou .zip contendo o shapefile completo) e a saída é um novo shapefile resultante da operação escolhida.
Índice
- ⚙️ Operações disponíveis (
--how) - 🧠 O que o projeto realmente faz (trecho principal de código)
- 📥 Parâmetros disponíveis
- 🚀 Como usar
- 📦 Resultados e arquivos de saída
- 🧪 Exemplo de Teste Realizado via API
- 🖼️ Exemplos Visuais (Swagger e Resposta)
⚙️ Operações disponíveis (--how)
Operação (how) |
Descrição |
|---|---|
intersection |
Retorna apenas as áreas comuns entre os dois shapes |
union |
Retorna toda a área combinada dos dois shapes |
identity |
Retorna os polígonos de input_shape1, divididos por input_shape2 |
symmetric_difference |
Retorna as áreas exclusivas de cada shape, sem interseção |
difference |
Retorna apenas as áreas de input_shape1 que não estão em input_shape2 |
🧠 O que o projeto realmente faz (trecho principal de código)
Abaixo, o trecho real que encapsula a execução da função gpd.overlay, incluindo a reprojeção de CRS quando necessário:
if reproject and gdf1.crs != gdf2.crs:
print(f'🔁 Convertendo CRS de gdf2 ({gdf2.crs}) para coincidir com gdf1 ({gdf1.crs})')
gdf2 = gdf2.to_crs(gdf1.crs)
resultado = gpd.overlay(
gdf1, gdf2,
how=how,
keep_geom_type=keep_geom_type,
make_valid=make_valid,
use_sindex=use_sindex
)
Este código garante que as operações geométricas sejam realizadas com precisão e segurança, mesmo quando os arquivos têm sistemas de coordenadas diferentes ou geometrias imperfeitas.
📥 Parâmetros disponíveis
| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| --input_shape1 | str | ✅ | — | Caminho para o primeiro shapefile (ex: CAR) |
| --input_shape2 | str | ✅ | — | Caminho para o segundo shapefile |
| --output_shape | str | ✅ | — | Caminho onde o shapefile de saída será salvo |
| --how | str | ✅ | — | Tipo de operação espacial: intersection, union, identity, symmetric_difference ou difference |
| --reproject | bool | ❌ | true | Reprojetar input_shape2 para o CRS de input_shape1 |
| --keep_geom_type | bool | ❌ | true | Manter o tipo original da geometria (evita mistura de tipos) |
| --make_valid | bool | ❌ | true | Corrigir geometrias inválidas automaticamente |
🚀 Como usar
1️⃣ Execução via Python (direto)
python overlay.py \
--input_shape1 path/para/shape1.shp \
--input_shape2 path/para/shape2.shp \
--output_shape path/para/overlayed.shp \
--how intersection
2️⃣ Execução via Docker Compose
docker compose build INPUT_SHAPE1=shape1.shp \
INPUT_SHAPE2=shape2.shp \
OUTPUT_SHAPE=overlayed.shp \
HOW=intersection \
docker compose up overlay
3️⃣ Execução via Google Colab (Notebook Interativo)
Além das formas tradicionais de uso, você pode executar o projeto diretamente no navegador, sem instalar nada, utilizando o notebook interativo no Google Colab. Esta é a maneira mais simples e acessível para testar rapidamente as operações de overlay entre shapefiles.
Como funciona?
-
Acesse o notebook:
- Clique no badge "Executar no Colab" no topo deste README ou acesse diretamente aqui.
-
Faça upload dos arquivos:
-
O notebook apresenta uma interface gráfica para upload de dois arquivos
.zip, cada um contendo um shapefile completo (com.shp,.shx,.dbf,.prj, etc). -
Exemplo da interface:
-
-
Escolha a operação e parâmetros:
- Selecione o tipo de operação espacial desejada (
intersection,union,identity,symmetric_differenceoudifference). - Marque/desmarque as opções de
keep_geom_type,make_validereprojectconforme necessário.
- Selecione o tipo de operação espacial desejada (
-
Execute o overlay:
-
Clique no botão Executar Overlay.
-
O notebook irá processar os arquivos, realizar a operação escolhida e gerar um novo shapefile compactado (
resultado_overlay.zip). -
Exemplo de mensagem de sucesso e botão de download:
-
-
Baixe o resultado:
- O arquivo
.zipgerado estará pronto para download diretamente pelo navegador.
- O arquivo
Vantagens do uso via Colab
- Não requer instalação de dependências locais.
- Interface amigável e interativa.
- Ideal para testes rápidos e demonstrações.
Dica: O notebook utiliza as mesmas opções e lógica do código principal do projeto, garantindo resultados idênticos aos obtidos via linha de comando ou API.
Nota: O parâmetro
--howaceita apenas os seguintes valores:intersection,union,identity,symmetric_difference,difference. Qualquer outro valor resultará em erro.
4️⃣ Execução via API
Como iniciar
docker compose up -d api
Acesse: http://localhost:8383/docs para ver a documentação Swagger.
Endpoint: POST /overlay
Envia dois arquivos .zip (cada um contendo os arquivos do shapefile completo) e retorna o shapefile resultante da operação.
Campos esperados (multipart/form):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| input_shape1 | UploadFile (.zip) | ✅ | Primeiro shapefile compactado |
| input_shape2 | UploadFile (.zip) | ✅ | Segundo shapefile compactado |
| how | str | ✅ | Tipo de operação: intersection, union, identity, symmetric_difference ou difference |
| reproject | bool | ❌ | Reprojetar ou não (true por padrão) |
| keep_geom_type | bool | ❌ | Manter tipo de geometria (true por padrão) |
| make_valid | bool | ❌ | Corrigir geometrias inválidas (true por padrão) |
Exemplo via curl:
curl -X POST http://localhost:8383/overlay \
-F "input_shape1=@shape1.zip" \
-F "input_shape2=@shape2.zip" \
-F "how=union" \
--output resultado_union.zip
curl -X POST http://localhost:8383/overlay \
-F "input_shape1=@shape1.zip" \
-F "input_shape2=@shape2.zip" \
-F "how=identity" \
--output resultado_identity.zip
5️⃣ Importação como módulo Python
Você pode usar a função diretamente:
from overlay import overlay
overlay(
input_shape1="shape1.shp",
input_shape2="shape2.shp",
output_shape="overlayed.shp",
how="difference"
)
📦 Resultados e arquivos de saída
O resultado é um novo shapefile salvo no caminho definido em --output_shape ou retornado compactado via API. Ele inclui os arquivos:
overlayed.zip
├── overlayed.shp
├── overlayed.shx
├── overlayed.dbf
└── overlayed.prj
🧪 Exemplo de Teste Realizado via API
Abaixo está um exemplo real de teste realizado utilizando o endpoint POST /overlay da API, via Swagger.
Parâmetros utilizados
- input_shape1:
Biomas_BR_ABC_2021.zip - input_shape2:
Brasil.zip - how:
intersection - keep_geom_type:
true(padrão) - make_valid:
true(padrão) - reproject:
true(padrão)
Requisição via Swagger (código gerado)
curl -X 'POST' \
'http://192.168.5.179:8383/overlay' \
-H 'accept: application/json' \
-H 'Content-Type: multipart/form-data' \
-F 'input_shape1=@Biomas_BR_ABC_2021.zip;type=application/zip' \
-F 'input_shape2=@Brasil.zip;type=application/zip' \
-F 'how=intersection' \
-F 'keep_geom_type=true' \
-F 'make_valid=true' \
-F 'reproject=true'
🖼️ Exemplos Visuais (Swagger e Resposta)
Exemplo visual do POST (Swagger UI):
Exemplo visual do Server response:
Arquivo de saída gerado
intersection.zip— resultado do teste (tempo de execução: menos de 1 min)
O arquivo de saída contém o shapefile resultante da operação de interseção entre os biomas e o shape do Brasil.
📝 Licença
MIT — consulte o arquivo LICENSE para mais detalhes.
Metadata
Release files for shapes-overlay 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| shapes_overlay-0.1.0.tar.gz | 5.4 kB | Without provenance | Details for shapes_overlay-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shapes_overlay-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for shapes_overlay-0.1.0-py3-none-any.whl |
Total release size: 10.8 kB
Release files / shapes_overlay-0.1.0.tar.gz
| Download URL | shapes_overlay-0.1.0.tar.gz |
|---|---|
| Size | 5.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
90db9e610052907b165e1a8551ffe4ca20a096043147eebb8641130959827516
|
|
BLAKE2b-256 checksum How to use checksums |
db72d192c23a514e53f8ec6649fe89ead8edcd983f5bea005a28104dc4ac56fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.0
|
Release files / shapes_overlay-0.1.0-py3-none-any.whl
| Download URL | shapes_overlay-0.1.0-py3-none-any.whl |
|---|---|
| Size | 5.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c150f9ba93293f6a28759fe97b17498dcd45a6ca88b16d9f05eb398fa82f404b
|
|
BLAKE2b-256 checksum How to use checksums |
60bfe796c3f1132d2504ee8d52a848a05a6b0d0795b1aa94465f46f2c00df81d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.0
|
Security for shapes-overlay 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.