Skip to main content

shapes-overlay

Python Docker Build License Executar no Colab PyPI version

✨ 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)

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?

  1. Acesse o notebook:

  2. 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:

      Interface do notebook

  3. Escolha a operação e parâmetros:

    • Selecione o tipo de operação espacial desejada (intersection, union, identity, symmetric_difference ou difference).
    • Marque/desmarque as opções de keep_geom_type, make_valid e reproject conforme necessário.
  4. 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:

      Download do resultado

  5. Baixe o resultado:

    • O arquivo .zip gerado estará pronto para download diretamente pelo navegador.

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 --how aceita 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):

POST /overlay - Swagger UI

Exemplo visual do Server response:

Server response - Swagger UI

Arquivo de saída gerado

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)

Source distribution for shapes-overlay 0.1.0
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)

Table of built distributions (wheels) for shapes-overlay 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page