ICC.md

Briefing técnico para agente IA

Projeto: Índice de Coerência Cicloviária (ICC)

1. Objetivo do projeto

Construir um sistema automatizado para calcular o Índice de Coerência Cicloviária (ICC) de cidades ou áreas urbanas a partir de dados abertos do OpenStreetMap (OSM).

O índice deve medir o quanto a infraestrutura cicloviária existente é adequada à função da via onde está localizada, considerando uma regra simples de coerência entre classe viária e tipologia cicloviária.

O projeto deve permitir calcular, para cada cidade ou área analisada, uma nota final entre 0 e 1, ou entre 0 e 100, indicando a proporção ponderada da malha viária que possui infraestrutura cicloviária adequada.

2. Conceito central

O ICC não mede apenas a quantidade total de ciclovias ou ciclofaixas. Ele mede se a infraestrutura cicloviária está disponível nos lugares onde ela é necessária, conforme a função da via.

A lógica básica é:

• vias estruturais exigem maior proteção;
• vias alimentadoras exigem proteção intermediária;
• vias locais admitem qualquer estrutura cicloviária reconhecida.

Assim, uma cidade não deve ser bem avaliada apenas por possuir muitos quilômetros de infraestrutura cicloviária se essa infraestrutura estiver concentrada em vias locais e ausente nas vias mais importantes ou mais críticas.

3. Nome do indicador

Nome principal recomendado:

Índice de Coerência Cicloviária (ICC)

Definição sintética:

O Índice de Coerência Cicloviária mede a proporção ponderada da malha viária urbana que possui infraestrutura cicloviária mínima adequada ao tipo de via, dando maior peso às vias estruturais.

Definição simples:

O índice avalia se as ciclovias e ciclofaixas estão onde deveriam estar, de acordo com a importância da via.

4. Escopo territorial

O sistema deve permitir calcular o ICC para:

1. uma cidade inteira;
2. um município;

Para outro momento, plano futuro:

3. uma área urbana delimitada por polígono;
4. recortes internos, como bairros, zonas, regionais ou áreas de planejamento.

5. Fontes de dados

A fonte principal será o OpenStreetMap (OSM).

Dados necessários:

1. malha viária;
2. infraestrutura cicloviária mapeada;
3. limites territoriais da área analisada.

Ferramentas possíveis:

• Overpass API (preferida);
• Geofabrik;
• pyrosm;
• osmnx;
• osmium;
• PostGIS;
• GeoPandas;
• Shapely;
• NetworkX, se necessário.

6. Unidades de análise

A unidade principal de análise deve ser o segmento da malha viária.

Cada segmento de via deve receber os seguintes atributos derivados:

• identificador único;
• geometria;
• comprimento em metros;
• classe OSM original;
• classe viária adaptada;
• presença ou ausência de infraestrutura cicloviária adequada;
• tipologia cicloviária associada;
• status de coerência/adequação;
• classe de ponderação.

7. Classificação das vias

O agente deve criar uma classificação adaptada das vias OSM em três classes:

1. Estrutural
2. Alimentadora
3. Local

7.1 Classe estrutural

A classe estrutural representa vias de maior importância na circulação urbana.

Sugestão inicial de mapeamento OSM:

• motorway
• trunk
• primary
• respectivas variações _link, quando fizerem sentido no contexto urbano

7.2 Classe alimentadora

A classe alimentadora representa vias intermediárias, que conectam bairros e distribuem fluxos.

Sugestão inicial de mapeamento OSM:

• secondary
• tertiary

7.3 Classe local

A classe local representa vias de acesso local, ruas residenciais e vias de baixo fluxo.

Sugestão inicial de mapeamento OSM:

• residential
• unclassified, quando em contexto urbano

7.4 Vias a excluir inicialmente

Salvo decisão metodológica contrária, excluir:

• living_street
• service,
• pedestrian,
• footway
• path,
• steps
• track, salvo contexto urbano específico;
• vias privadas, se access=private;
• vias em construção, se highway=construction;
• geometrias inválidas ou sem comprimento relevante.

8. Classificação da infraestrutura cicloviária

A infraestrutura cicloviária deve ser classificada em tipologias compatíveis com o CicloMapa ou com a taxonomia adotada pelo projeto.

Classes mínimas sugeridas:

1. Ciclovia
2. Ciclofaixa
3. Outra estrutura cicloviária
4. Sem estrutura cicloviária reconhecida

8.1 Ciclovia

Representa infraestrutura segregada ou separada do tráfego motorizado.

Possíveis tags OSM:

• highway=cycleway
• cycleway=track
• cycleway:left=track
• cycleway:right=track
• cycleway:both=track
• cycleway=separate, quando houver geometria separada correspondente
• bicycle=designated em via exclusiva, conforme contexto
• segregated=yes, quando associado a infraestrutura cicloviária

8.2 Ciclofaixa

Representa faixa cicloviária na pista, usualmente delimitada por pintura.

Possíveis tags OSM:

• cycleway=lane
• cycleway:left=lane
• cycleway:right=lane
• cycleway:both=lane
• cycleway=opposite_lane

8.3 Outras estruturas cicloviárias

Representam estruturas ou condições cicláveis menos protegidas, aceitas apenas em vias locais no cálculo inicial.

Possíveis tags OSM:

• cycleway=shared_lane
• cycleway=sharrow
• bicycle=designated em vias compartilhadas
• highway=path com bicycle=designated, se aplicável
• ciclorrotas ou vias compartilhadas reconhecidas em base complementar

8.4 Sem estrutura reconhecida

Todos os segmentos que não apresentarem tags confiáveis de infraestrutura cicloviária devem ser classificados como sem estrutura reconhecida.

9. Regra de coerência por classe viária

A coerência é definida pela relação entre a classe da via e a tipologia cicloviária mínima exigida.

Classe da via	Estrutura mínima adequada	Estruturas consideradas adequadas
Estrutural	Ciclovia	Ciclovia
Alimentadora	Ciclofaixa	Ciclovia ou ciclofaixa
Local	Qualquer estrutura cicloviária reconhecida	Ciclovia, ciclofaixa ou outras estruturas

Regras:

1. Em vias estruturais, apenas ciclovias contam como adequadas.
2. Em vias alimentadoras, ciclovias e ciclofaixas contam como adequadas.
3. Em vias locais, qualquer estrutura cicloviária reconhecida conta como adequada.
4. Infraestruturas inferiores à exigência da classe da via devem ser ignoradas no numerador, embora possam ser registradas para diagnóstico.

Exemplo:

Se uma cidade possui 100 km de vias estruturais, sendo 10 km com ciclovia e 5 km com ciclofaixa, apenas os 10 km com ciclovia entram como adequados. A disponibilidade adequada estrutural será 10 / 100 = 0,10.

10. Cálculo da disponibilidade adequada por classe

Para cada classe viária k, calcular:

• L_k: comprimento total das vias daquela classe;
• A_k: comprimento das vias daquela classe com infraestrutura adequada;
• D_k: disponibilidade adequada daquela classe.

Fórmula:

D_k = A_k / L_k

Onde:

• D_k varia de 0 a 1;
• se L_k = 0, o sistema deve tratar o caso de forma explícita, evitando divisão por zero.

Tratamento sugerido para L_k = 0:

1. registrar a classe como inexistente no território;
2. redistribuir o peso proporcionalmente entre as demais classes, ou
3. manter o peso e atribuir nulo, conforme decisão metodológica.

A opção recomendada para comparabilidade é redistribuir os pesos entre classes existentes, mas o sistema deve permitir configurar esse comportamento.

11. Ponderação do índice final

O índice final deve combinar as disponibilidades adequadas por classe com pesos definidos metodologicamente.

Pesos iniciais:

• 60% para vias estruturais;
• 25% para vias alimentadoras;
• 15% para vias locais.

Fórmula:

ICC = 0,60 * D_estrutural + 0,25 * D_alimentadora + 0,15 * D_local

Ou, de forma geral:

ICC = Σ (w_k * D_k)

Onde:

• w_k é o peso da classe viária;
• D_k é a disponibilidade adequada da classe;
• a soma dos pesos deve ser igual a 1.

Para nota de 0 a 100:

ICC_100 = ICC * 100

12. Exemplo numérico

Suponha uma cidade com:

Classe	Total de vias	Estrutura adequada	D_k
Estrutural	100 km	10 km de ciclovia	0,10
Alimentadora	200 km	40 km de ciclovia/ciclofaixa	0,20
Local	700 km	140 km de qualquer estrutura	0,20

Cálculo:

ICC = 0,60 * 0,10 + 0,25 * 0,20 + 0,15 * 0,20
ICC = 0,06 + 0,05 + 0,03
ICC = 0,14
ICC_100 = 14

Resultado: a cidade teria ICC = 0,14, ou 14/100.

13. Matching espacial entre infraestrutura e vias

O sistema deve associar infraestrutura cicloviária aos segmentos de via que ela atende.

Há dois casos principais.

13.1 Infraestrutura mapeada na própria via

Quando a infraestrutura está registrada como tag do próprio segmento viário, por exemplo cycleway=lane ou cycleway=track, a associação é direta.

Procedimento:

1. identificar a tag cicloviária no segmento;
2. classificar a tipologia;
3. aplicar a regra de coerência conforme a classe viária;
4. marcar o segmento como adequado ou inadequado.

13.2 Infraestrutura mapeada como geometria separada

Quando a infraestrutura aparece como highway=cycleway, ela deve ser associada à via que atende.

Procedimento recomendado:

1. selecionar ciclovias separadas;
2. criar buffer de busca em torno da ciclovia ou da via;
3. identificar vias próximas candidatas;
4. filtrar por distância máxima;
5. filtrar por paralelismo aproximado, quando possível;
6. usar nome da via, quando disponível, como critério auxiliar;
7. associar a ciclovia à via mais provável;
8. marcar o trecho correspondente da via como atendido por ciclovia.

Critérios sugeridos:

• distância máxima inicial: 20 m a 30 m em contexto urbano;
• preferência por vias com classe estrutural ou alimentadora quando a ciclovia estiver paralela a múltiplas vias;
• evitar associar ciclovias de parques ou orlas a vias próximas se elas não servirem diretamente a uma via de tráfego.

O algoritmo deve registrar incertezas de associação.

14. Evitar dupla contagem

O numerador deve representar a extensão de vias atendidas por infraestrutura adequada, não a soma bruta da extensão da infraestrutura.

Regra importante:

O cálculo deve somar o comprimento dos segmentos viários considerados adequadamente atendidos, e não simplesmente o comprimento das geometrias cicloviárias.

Isso evita que uma via com ciclovia bidirecional em geometria separada ou com duas ciclofaixas laterais seja contada duas vezes.

Cada segmento viário deve contribuir no máximo com 100% de seu comprimento para o numerador da respectiva classe.

15. Segmentação geométrica

Para maior precisão, o agente deve segmentar vias quando apenas parte de um segmento estiver coberta por infraestrutura adequada.

Exemplo:

• um segmento viário tem 1.000 m;
• apenas 400 m são acompanhados por ciclovia;
• apenas 400 m devem entrar no numerador, não o segmento inteiro.

Soluções possíveis:

1. usar interseção linear entre buffers;
2. projetar trechos de ciclovia sobre a via associada;
3. dividir segmentos viários em trechos menores;
4. usar PostGIS com ST_LineSubstring, ST_Intersection, ST_Buffer, ST_DWithin e funções de projeção linear.

Para uma primeira versão, pode-se aceitar aproximação por segmento inteiro, desde que a limitação seja documentada. Para versão robusta, usar cobertura parcial.

16. Pipeline mínimo do sistema

O agente deve implementar um pipeline com as seguintes etapas:

1. Entrada da área de análise;
2. Download ou leitura dos dados OSM;
3. Limpeza e padronização das geometrias;
4. Projeção para sistema métrico adequado;
5. Extração da malha viária;
6. Classificação das vias em estrutural, alimentadora e local;
7. Extração da infraestrutura cicloviária;
8. Classificação da tipologia cicloviária;
9. Associação entre infraestrutura separada e via atendida;
10. Marcação dos segmentos adequados;
11. Cálculo de L_k, A_k e D_k;
12. Aplicação dos pesos;
13. Cálculo do ICC final;
14. Geração de tabelas, mapas e arquivos de saída;
15. Registro de logs e alertas de qualidade dos dados.

17. Entradas esperadas

O sistema deve aceitar ao menos uma das seguintes entradas:

1. nome da cidade;
2. código ou identificador territorial;
3. polígono GeoJSON;
4. arquivo shapefile ou geopackage;
5. bounding box;
6. relação OSM do município, quando disponível.

Parâmetros configuráveis:

• pesos do índice;
• mapeamento OSM para classe viária;
• mapeamento OSM para tipologia cicloviária;
• distância máxima de associação;
• regras para redistribuição de pesos;
• inclusão ou exclusão de determinadas classes OSM;
• unidade de saída: 0 a 1 ou 0 a 100.

18. Saídas esperadas

O sistema deve gerar:

18.1 Saída tabular resumida

Campos mínimos:

• cidade ou área;
• data de extração dos dados OSM;
• extensão total de vias estruturais;
• extensão adequada em vias estruturais;
• disponibilidade adequada estrutural;
• extensão total de vias alimentadoras;
• extensão adequada em vias alimentadoras;
• disponibilidade adequada alimentadora;
• extensão total de vias locais;
• extensão adequada em vias locais;
• disponibilidade adequada local;
• ICC final;
• ICC em escala 0–100.

18.2 Saída geográfica

Arquivos sugeridos:

• GeoPackage com segmentos viários classificados;
• GeoJSON com trechos adequados e inadequados;
• camada de infraestrutura cicloviária classificada;
• camada de associações entre ciclovias separadas e vias atendidas.

18.3 Mapas

Gerar mapas com:

• vias estruturais sem ciclovia;
• vias alimentadoras sem ciclovia ou ciclofaixa;
• vias locais com e sem infraestrutura;
• trechos adequados e inadequados;
• distribuição espacial da coerência cicloviária.

18.4 Relatório

Gerar relatório automático em Markdown, HTML ou PDF com:

• metodologia;
• parâmetros usados;
• tabela de resultados;
• mapas;
• limitações;
• data da base OSM;
• recomendações de interpretação.

22. Testes mínimos

Criar testes automatizados para garantir que:

1. uma via estrutural com ciclovia seja adequada;
2. uma via estrutural com ciclofaixa seja inadequada;
3. uma via alimentadora com ciclofaixa seja adequada;
4. uma via alimentadora com ciclovia seja adequada;
5. uma via local com qualquer estrutura reconhecida seja adequada;
6. uma via sem estrutura seja inadequada;
7. a fórmula de ponderação retorne o valor esperado;
8. não haja dupla contagem de segmentos;
9. a ausência de uma classe viária seja tratada corretamente.

23. Cuidados metodológicos

23.1 Qualidade do OSM

O resultado depende da completude e qualidade do mapeamento no OSM. O relatório deve sempre registrar a data de extração e alertar para possíveis lacunas.

23.2 Diferenças locais de classificação viária

A classificação OSM pode variar entre cidades. O sistema deve permitir ajustes locais sem alterar o código.

23.3 Ciclovias separadas

A associação de highway=cycleway a uma via próxima pode gerar erros. O sistema deve registrar associações incertas e permitir auditoria posterior.

23.4 Rodovias e vias não urbanas

É necessário cuidado para não penalizar indevidamente cidades que possuam longos trechos de rodovias rurais dentro do limite municipal. Como sinalizar isso?

23.5 Infraestrutura não mapeada

Infraestruturas existentes mas ausentes do OSM serão consideradas inexistentes pelo sistema. Isso deve ser tratado como limitação da fonte.

24. Indicadores complementares recomendados

Além do ICC final, o sistema deve apresentar:

• disponibilidade adequada estrutural;
• disponibilidade adequada alimentadora;
• disponibilidade adequada local;
• extensão de ciclovias em vias estruturais;
• extensão de ciclofaixas em vias estruturais, mesmo quando inadequadas;
• extensão de vias estruturais sem infraestrutura adequada;
• ranking de corredores prioritários para intervenção;
• percentual do índice perdido por classe.

Esses indicadores ajudam a interpretar o resultado e orientar políticas públicas.

25. Priorização de intervenção

O sistema pode gerar uma lista de trechos prioritários para intervenção.

Critério inicial:

1. vias estruturais sem ciclovia;
2. vias estruturais com apenas ciclofaixa;
3. vias alimentadoras sem ciclovia ou ciclofaixa;
4. vias locais sem qualquer estrutura, se relevante.

A saída pode conter:

• nome da via;
• classe viária;
• extensão inadequada;
• infraestrutura existente;
• infraestrutura mínima recomendada;
• prioridade.

26. Produto mínimo viável

O MVP deve:

1. receber uma cidade ou polígono;
2. baixar dados OSM;
3. classificar vias em três classes;
4. identificar infraestrutura cicloviária na própria via;
5. associar highway=cycleway por proximidade simples;
6. calcular D_estrutural, D_alimentadora, D_local e ICC;
7. exportar uma tabela CSV;
8. exportar um GeoPackage com os segmentos classificados;
9. gerar um relatório Markdown simples.

27. Versão avançada

A versão avançada deve incluir:

1. matching por distância e paralelismo;
2. segmentação parcial de vias;
3. interface CLI;
4. dashboard web;
5. execução em lote para várias cidades;
6. comparação temporal com diferentes datas do OSM;
7. integração com CicloMapa ou bases locais;
8. validação visual interativa;
9. API para consulta pública;
10. relatório automatizado com mapas.

28. Possível comando de CLI

Exemplo de uso desejado:

icc calculate --city "Recife, Pernambuco, Brazil" --output outputs/recife

Ou:

icc calculate --polygon data/areas/recife.geojson --config config/default.yaml --output outputs/recife

Execução em lote:

icc batch --cities data/cities.csv --config config/default.yaml --output outputs/batch

29. Ficha metodológica resumida

Nome: Índice de Coerência Cicloviária Sigla: ICC Unidade: número adimensional entre 0 e 1, ou nota entre 0 e 100 Fonte: OpenStreetMap Unidade territorial: município, cidade, área urbana ou polígono definido Periodicidade possível: conforme atualização da base OSM Fenômeno medido: disponibilidade de infraestrutura cicloviária adequada à classe da via Classes consideradas: estrutural, alimentadora e local Pesos: 60%, 25% e 15%, respectivamente Interpretação: quanto maior o valor, maior a coerência entre a rede viária e a infraestrutura cicloviária disponível.

30. Formulação final do índice

D_E = A_E / L_E
D_A = A_A / L_A
D_L = A_L / L_L

ICC = 0,60 * D_E + 0,25 * D_A + 0,15 * D_L
ICC_100 = ICC * 100

Onde:

• D_E: disponibilidade adequada em vias estruturais;
• D_A: disponibilidade adequada em vias alimentadoras;
• D_L: disponibilidade adequada em vias locais;
• A_E: extensão de vias estruturais com ciclovia;
• A_A: extensão de vias alimentadoras com ciclovia ou ciclofaixa;
• A_L: extensão de vias locais com qualquer estrutura cicloviária reconhecida;
• L_E: extensão total de vias estruturais;
• L_A: extensão total de vias alimentadoras;
• L_L: extensão total de vias locais.

31. Orientação final ao agente IA

O agente deve priorizar clareza metodológica, código reprodutível e parametrização. Todas as decisões metodológicas devem ficar explícitas em arquivos de configuração e no relatório final.

O sistema deve ser construído de forma incremental:

1. primeiro calcular corretamente para uma cidade;
2. depois melhorar o matching espacial;
3. depois permitir análise em lote;
4. depois gerar mapas e relatórios;
5. por fim, empacotar como ferramenta reutilizável.

O mais importante é garantir que o índice final represente exatamente a pergunta metodológica central:

Quanto da malha viária possui infraestrutura cicloviária adequada à função da via, considerando maior peso para as vias estruturais?