Metadata-Version: 2.4
Name: pvsp
Version: 0.1.0
Summary: Biblioteca para extração de perfis viários a partir de dados LIDAR da cidade de São Paulo.
Author-email: João Victor de Almeida Braga <joaovab@al.insper.edu.br>
License-Expression: MIT
Keywords: perfil,viario,lidar,gis,sp,splaz
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: splaz
Requires-Dist: laspy>=2.4.0
Requires-Dist: geopandas>=0.13.0
Requires-Dist: shapely>=2.0.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: matplotlib>=3.6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# pvsp - Perfil Viario de Sao Paulo

Biblioteca Python para extracao, classificacao espacial e visualizacao de perfis transversais viarios a partir de nuvens de pontos LIDAR e dados cartograficos da cidade de Sao Paulo.

---

## Visao Geral

A biblioteca `pvsp` automatiza o fluxo completo de amostragem geometrica de logradouros publicos:
1. Localiza e baixa quadrantes LIDAR oficiais da Prefeitura de Sao Paulo atraves da biblioteca `splaz`.
2. Le e recorta espacialmente as camadas vetoriais de eixos de logradouros e calcadas no sistema de coordenadas SIRGAS 2000 / UTM zone 23S (EPSG 31983).
3. Gera laminas poligonais de amostragem transversais e perpendiculares aos eixos das vias.
4. Classifica as secoes transversais em **Leito Carrocavel** (asfalto) e **Passeio** (calcada).
5. Extrai a nuvem de pontos 3D de forma nativa e vetorizada em C (via `laspy` e `shapely.contains_xy`), projetando as coordenadas no plano transversal relativo da via ($X_{relativo}$ e $Z_{relativo}$).
6. Fornece calculo automatico de metricas fisicas da via (largura total, largura do asfalto, largura de calcadas e contagem de pontos) e geracao de graficos 2D em escala real (1:1).

---

## Requisitos e Instalacao

### Requisitos
- Python 3.9 ou superior.
- Camadas vetoriais municipais de eixos de logradouros e calcadas no formato GeoPackage (`.gpkg`) ou Shapefile (`.shp`).

### Instalacao
Instale a biblioteca diretamente via `pip`:

```bash
pip install pvsp
```

---

## Guia de Utilizacao

### 1. Exemplo Basico

```python
import pvsp

# 1. Obtem o perfil viario a partir de um endereco
perfil = pvsp.get_perfil(
    endereco="Rua Quata, 300",
    largura_rua=40.0,
    espessura_lamina=1.0,
    max_z=3.5,
)

# 2. Calcula as metricas geometricas da via
metricas = perfil.compute_metrics()
print("Largura Total:", metricas["largura_total"], "m")
print("Leito Carrocavel:", metricas["largura_asfalto"], "m")
print("Calcadas:", metricas["largura_calcadas"], "m")
print("Total de Pontos:", metricas["total_pontos"])

# 3. Exporta os pontos classificados para CSV
perfil.to_csv("perfil_quata.csv")

# 4. Gera e salva o grafico 2D
perfil.plot(filename="perfil_quata.png")
```

---

## Referencia da API

### Funcao Principal: `pvsp.get_perfil`

```python
pvsp.get_perfil(
    endereco: str,
    data_root: str = "data",
    caminho_eixos: Optional[str] = None,
    caminho_calcadas: Optional[str] = None,
    largura_rua: float = 40.0,
    espessura_lamina: float = 1.0,
    epsg_alvo: int = 31983,
    max_z: float = 3.5,
    rua_alvo: Optional[str] = None,
    splaz_client: Optional[Any] = None,
    splaz_geo_client: Optional[Any] = None,
) -> PerfilResult
```

#### Parametros:
- `endereco` (*str*): Endereco em Sao Paulo (ex.: `"Rua Quata, 300"`, `"Av. Paulista, 1000"`) ou codigo de quadrante (ex.: `"3316-151"`).
- `data_root` (*str*): Diretorio raiz dos dados vetoriais locais. Padrao: `"data"`.
- `caminho_eixos` (*str*, opcional): Caminho customizado para o arquivo de eixos viarios.
- `caminho_calcadas` (*str*, opcional): Caminho customizado para o arquivo de calcadas.
- `largura_rua` (*float*): Largura transversal estimada da via em metros. Padrao: `40.0`.
- `espessura_lamina` (*float*): Espessura longitudinal da lamina de corte em metros. Padrao: `1.0`.
- `epsg_alvo` (*int*): Codigo EPSG do sistema de coordenadas. Padrao: `31983` (SIRGAS 2000 / UTM 23S).
- `max_z` (*float*): Altura vertical maxima considerada acima do nivel da via para corte de ruidos (edificacoes/arvores). Padrao: `3.5`.
- `rua_alvo` (*str*, opcional): Nome especifico do logradouro a ser filtrado (caso nao informado, extraido automaticamente do endereco).

---

### Classe: `PerfilResult`

Objeto retornado por `pvsp.get_perfil`.

#### Atributos:
- `points` (*pandas.DataFrame*): Tabela com os pontos LIDAR extraidos contendo as colunas:
  - `nome_rua`: Nome do logradouro.
  - `classe`: Classe de terreno (`"Leito Carroçavel"`, `"Passeio"` ou `"Outros"`).
  - `X_Relativo`: Posicao transversal normalizada da via em metros (iniciando em 0.0).
  - `Z_Relativo`: Elevacao vertical normalizada em metros (iniciando em 0.0 no ponto mais baixo).
  - `X_original`, `Y_original`, `Z_original`: Coordenadas brutas no sistema SIRGAS 2000.
- `cortes` (*geopandas.GeoDataFrame*): Poligonos 2D das laminas transversais classificadas.
- `eixos` (*geopandas.GeoDataFrame*): Segmentos de eixos utilizados no recorte.
- `metadata` (*dict*): Metadados da execucao (endereco, codigo do quadrante, limites do bounding box e parametros utilizados).

#### Metodos:
- `compute_metrics(max_z=None, rua_alvo=None) -> Dict[str, float]`:
  Retorna um dicionario contendo:
  - `largura_total`: Largura total transversal observada (metros).
  - `largura_asfalto`: Extensao do leito carrocavel (metros).
  - `largura_calcadas`: Extensao estimada das calcadas laterais (metros).
  - `total_pontos`: Quantidade total de pontos filtrados.
  - `pontos_asfalto`: Quantidade de pontos no asfalto.
  - `pontos_passeio`: Quantidade de pontos na calcada.
- `to_csv(path: str, index: bool = False, **kwargs)`:
  Exporta a tabela de pontos processados para arquivo CSV formatado em UTF-8.
- `plot(filename: Optional[str] = None, rua_alvo: Optional[str] = None, max_z: Optional[float] = None, show_metrics: bool = True, **kwargs)`:
  Gera a figura 2D da secao transversal da via com diferenciacao de cores para asfalto e calcada, quadro de metricas e proporcao fisica 1:1. Se `filename` for informado, salva a imagem em disco em 300 DPI; caso seja `None`, exibe interativamente na tela via `plt.show()`.

---

## Execucao dos Testes Unitarios

A biblioteca conta com uma suite de testes unitarios cobrindo validacao de parametros, calculo de metricas, operacoes geometricas, plotagem e funcoes de entrada e saida.

Para executar os testes:

```bash
pytest tests/tests.py -v
```

---

## Autor

- **Autor**: João Victor de Almeida Braga
- **E-mail**: joaovab@al.insper.edu.br
- **Instituicao**: Insper - Instituto de Ensino e Pesquisa

