Guia de Roteirização¶

Este guia percorre, passo a passo, o uso do painel logis — Roteirização: como preparar as camadas de entrada, como preencher as duas abas do painel — TSP, a rota de Caixeiro Viajante de um único veículo, e CVRP, a roteirização de uma frota com capacidade a partir de um depósito — e como ler os resultados de cada uma.

Os botões do painel são apenas orquestradores: chamam os algoritmos logis:vrp_tsp e logis:vrp_cvrp do Processing e escrevem o retorno no painel de resultados. A referência técnica dos algoritmos (parâmetros, fórmulas, complexidade, bibliografia) está em Algoritmos de Roteirização; aqui o foco é o uso do painel.

1. Preparar as camadas de entrada¶

O painel não baixa dados: ele consome camadas já carregadas no projeto. São quatro insumos possíveis na aba TSP — a camada de rede viária, por ficar no topo do painel, vale também para a aba CVRP, cujos insumos estão na seção 7.

Insumo	Obrigatória?	Papel
Camada do ponto inicial (Pontos)	Sim	O algoritmo usa a primeira feição válida da camada; o ideal é uma camada com uma única feição (garagem, CD, depósito).
Camada de pontos a visitar (Pontos)	Sim	Cada feição é uma parada visitada exatamente uma vez. Os atributos originais são preservados na saída.
Camada do ponto final (Pontos)	Não	Se vazia, a rota fecha no ponto inicial (tour fechado). Se preenchida, a rota termina nesse ponto (caminho aberto — garagem diferente, aterro, transbordo, CD de destino). Também usa a primeira feição válida.
Camada de rede viária (Linhas)	Não	Na aba TSP a camada só entra no cálculo quando o Modo de cálculo da distância está em Pela rede viária (Dijkstra); no modo padrão, Linha reta (euclidiana), ela é ignorada mesmo se estiver selecionada (na aba CVRP vale sempre). Com rede, as distâncias são reais (Dijkstra sobre `QgsGraph`, matriz OD) e os trechos da saída seguem a geometria das ruas; sem rede, tudo é distância euclidiana e os trechos são segmentos retos. A rede pode ser a `osm_links_<code_muni>` do pipeline OSM — ver o Guia de Logística Urbana.

CRS de cálculo. O cálculo é sempre feito em CRS métrico. Quando há rede viária, o algoritmo reprojeta para EPSG:5880 (SIRGAS 2000 / Brazil Polyconic); sem rede, ele só mantém o CRS da camada de pontos se as unidades desse CRS já forem metros, e reprojeta para EPSG:5880 em qualquer outro caso. Se a transformação para EPSG:5880 falhar, o algoritmo adota o UTM SIRGAS da zona dos pontos (por exemplo, EPSG:31983 em São Paulo), com aviso no log. Por isso as distâncias das saídas e do painel estão sempre em metros. Toda transformação é conferida com um ponto de prova: o log registra, por transformação aceita, uma linha "Transformação EPSG:xxxx → EPSG:yyyy ok (prova ...)" com o ponto antes/depois.

CRS das saídas. As camadas de saída do TSP (Ordem de visita e Rota (trechos)) e do CVRP (Rotas geradas e Paradas por rota) são sempre gravadas em EPSG:4674 (SIRGAS 2000), independentemente do CRS métrico usado no cálculo — os atributos de distância continuam em metros.

Pontos sem SRC ou com SRC inconsistente. Camadas de pontos sem SRC definido são tratadas como EPSG:4674 quando as coordenadas caem no Brasil (com aviso no log); camada que declara SRC métrico mas guarda graus, ou pontos fora da área da rede, são recusados com mensagem que diz como corrigir.

2. Abrir o painel¶

Complementos → logis → Roteirização. O painel abre ancorado à direita da janela do QGIS; se for fechado, reabra pela mesma entrada de menu (ou por Ver → Painéis).

O painel tem duas abas: TSP (um único veículo, sem capacidade) e CVRP (frota com capacidade a partir de um depósito). O seletor Camada de rede viária (Linhas - opcional) fica no topo do painel, fora das abas, e vale para as duas — na aba CVRP sempre, na aba TSP quando o Modo de cálculo da distância está em Pela rede viária (Dijkstra); o painel Resultados da Roteirização, logo abaixo das abas, também é compartilhado e é limpo a cada execução, seja de qual aba for.

3. Passo a passo da aba TSP¶

Os controles aparecem nesta ordem:

Camada do ponto inicial (Pontos) — obrigatória.
Camada de pontos a visitar (Pontos) — obrigatória.
Camada do ponto final (Pontos - opcional, vazio fecha no ponto inicial) — o seletor aceita entrada vazia.
Camada de rede viária (Linhas - opcional) — no topo do painel, fora das abas; também aceita vazia.
Modo de cálculo da distância — seletor da aba TSP, com duas opções: Linha reta (euclidiana), o padrão, e Pela rede viária (Dijkstra). É ele que decide se a camada de rede do topo do painel entra no cálculo: no modo padrão a camada é ignorada; no modo pela rede ela é obrigatória — sem camada escolhida, o painel abre o aviso "O modo pela rede viária exige uma camada de rede viária no topo do painel" e não executa.
Aplicar busca local (2-opt e Or-opt) — caixa marcada por padrão; refina a sequência inicial do Vizinho Mais Próximo. Desmarcar entrega a rota bruta do Vizinho Mais Próximo, mais rápida e pior.
Botão Calcular Rota (TSP).

O painel limpa os resultados a cada execução. O cálculo corre em segundo plano, no gerenciador de tarefas do QGIS: a tela continua utilizável, a barra de progresso acompanha as etapas e o botão Cancelar interrompe. As duas camadas de saída (Ordem de visita e Rota (trechos)) são gravadas no GeoPackage da camada de referência quando houver um, ou criadas como camadas temporárias quando não houver — ver a seção 8.

Ponto inicial e pontos a visitar são obrigatórios: sem eles, o painel abre um aviso e não executa. O backend OR-Tools é usado automaticamente quando instalado, com fallback silencioso para a heurística Python — o backend efetivamente usado aparece no resultado.

4. Ler o painel de resultados do TSP¶

Linha do painel	Campo de origem	Significado
Pontos visitados	`stop_count`	Quantidade de pontos da camada de visita atendidos no percurso.
Distância total do tour	`tour_dist`	Distância total do percurso, do ponto inicial ao encerramento (retorno ou ponto final).
Custo de acesso	`access_dist`	Distância da perna do ponto inicial até o primeiro ponto a visitar — deslocamento improdutivo.
Custo de retorno	`return_dist`	Distância da perna final, de volta ao ponto inicial (tour fechado) ou até o ponto final (caminho aberto) — também improdutiva.
Razão de deadhead (dead_ratio)	`dead_ratio`	Fração do percurso que é deslocamento improdutivo, entre 0 e 1.
Fechamento	`closed`	"Sim (fecha no ponto inicial)" ou "Não (termina no ponto final)".
Modo de distância	`dist_mode`	`rede` quando o cálculo correu sobre a rede viária (Dijkstra), `euclidiana` quando correu em linha reta — confirma qual modo o algoritmo de fato usou.
Backend de otimização	`backend`	`ortools` quando o OR-Tools resolveu a instância, ou `python` quando caiu no fallback da heurística nativa.

Aviso de trechos retos. No modo pela rede, quando alguma perna não teve o caminho reconstruído na malha (campo leg_geom da camada Rota (trechos) em reta, em vez de rede), o painel acrescenta em amarelo a linha "Aviso: N trecho(s) caíram no segmento reto por falta de caminho na malha." — as distâncias continuam vindo da rede, mas a geometria desses N trechos é o segmento reto entre os dois nós.

5. Ler a camada Ordem de visita¶

A sequência de visita não está na ordem de armazenamento das feições: abra a tabela de atributos da camada Ordem de visita e ordene pelo campo visit_seq (clique no cabeçalho da coluna).

Campo	Significado
(campos originais)	Atributos da camada de pontos a visitar; nulos nas feições de ponto inicial e de ponto final.
`visit_seq`	Posição do nó na sequência de visita.
`node_role`	Papel do nó: `inicio`, `parada` ou `fim`.
`leg_role`	Papel da perna que chega a este nó (`acesso`, `rota` ou `retorno`); vazio na feição de `inicio`.
`leg_dist`	Distância da perna que chega a este nó.
`cum_dist`	Distância acumulada desde o ponto inicial até este nó.

6. Quanto do percurso foi deslocamento improdutivo¶

Os três papéis de `leg_role`¶

Na camada Rota (trechos), cada perna do percurso é classificada em um de três papéis:

acesso — a primeira perna, do ponto inicial ao primeiro ponto a visitar.
rota — as pernas intermediárias, entre pontos a visitar — distância produtiva.
retorno — a última perna, de volta ao ponto inicial (tour fechado) ou até o ponto final (caminho aberto).

acesso e retorno são o deslocamento improdutivo (deadhead): nenhum atendimento ocorre nessas pernas.

Como estilizar por `leg_role`¶

Para ver o improdutivo no mapa, clique com o botão direito na camada Rota (trechos) → Propriedades → Simbologia → mude Símbolo Único para Categorizado → em Valor, escolha o campo leg_role → Classificar. Dê às classes acesso e retorno uma cor/tracejado distintos de rota, para que o deslocamento improdutivo salte no mapa.

Como somar¶

Os campos access_dist, service_dist, return_dist, tour_dist, dead_ratio, stop_count, closed e backend já vêm repetidos em todas as feições com o total do percurso — não é preciso somar nada à mão; basta abrir a tabela de atributos e ler qualquer feição.

A soma manual dos leg_dist das feições com leg_role em (acesso, retorno) — por exemplo com a calculadora de campo ou pelo resumo estatístico com o filtro "leg_role" IN ('acesso','retorno') — dá exatamente access_dist + return_dist.

A identidade que fecha as contas¶

\[\texttt{tour\_dist} = \texttt{access\_dist} + \texttt{service\_dist} + \texttt{return\_dist}\]

\[\texttt{dead\_ratio} = \frac{\texttt{access\_dist} + \texttt{return\_dist}}{\texttt{tour\_dist}}\]

dead_ratio fica entre 0 e 1. Quanto mais perto de 0, mais do percurso é atendimento; perto de 1, o veículo gasta o percurso se deslocando sem atender. dead_ratio alto sugere ponto inicial mal localizado em relação à nuvem de paradas — gancho para localização de instalações.

Os demais campos da camada Rota (trechos)¶

Campo	Significado
`leg_seq`	Número de ordem da perna no percurso.
`from_seq`	`visit_seq` do nó de origem da perna.
`to_seq`	`visit_seq` do nó de destino da perna. Na última perna de um tour fechado vale `1`, explicitando o retorno ao ponto inicial.
`leg_role`	`acesso`, `rota` ou `retorno`.
`leg_dist`	Distância desta perna.
`cum_dist`	Distância acumulada do início do percurso até o fim desta perna.

7. Roteirizar uma frota com capacidade (aba CVRP)¶

Quando usar CVRP em vez de TSP¶

A aba TSP sequencia as visitas de um único veículo, sem capacidade: toda parada entra no mesmo percurso, custe o que custar em carga. A aba CVRP parte de uma frota de veículos idênticos, cada um com uma capacidade máxima, e reparte os clientes em várias rotas — a partir de um ou mais depósitos (CDs, garagens, transbordos). Cada rota sai de um depósito, atende um subconjunto de clientes cuja soma de demandas cabe no veículo, e volta a esse mesmo depósito.

O número de rotas não é um parâmetro: ele é resultado do cálculo, e depende da carga total, da capacidade informada e da distribuição geográfica dos clientes.

Regra prática: se um veículo só dá conta de tudo e o que interessa é a ordem de visita, use a aba TSP; se há uma capacidade a respeitar (toneladas, m³, caixas, contêineres, vagas) e a operação vai se dividir em vários veículos ou várias viagens, use a aba CVRP.

Os insumos da aba CVRP¶

Insumo	Obrigatório?	Papel
Camada de depósitos (Pontos) — origem/destino das rotas	Sim	Ponto(s) de partida e de chegada das rotas. Pode conter uma única feição (depósito central) ou múltiplos depósitos (CDs, garagens, transbordos).
Campo ID do depósito (opcional)	Não	Campo que identifica cada depósito (ex.: `id`, `codigo`). Se omitido, o algoritmo utiliza o `feat.id()` de cada feição. Obrigatório caso o campo de depósito da demanda seja informado.
Camada de demanda / clientes (Pontos)	Sim	Cada feição é um cliente atendido exatamente uma vez, por uma única rota. Os atributos originais são preservados na saída.
Campo do depósito de cada ponto (opcional — vazio: depósito mais próximo)	Não	Campo na camada de demanda que indica para qual depósito aquele cliente é destinado (ex.: `1` ou `2`). Deixado vazio ou nulo, o cliente é atribuído automaticamente pela regra do depósito mais próximo.
Campo de peso/demanda (opcional, default = 1,0)	Não	Campo numérico com a carga de cada cliente. Deixado vazio — ou nulo/não numérico na feição —, a demanda vale 1,0, e a capacidade passa a contar paradas por rota. Valor negativo é tratado como zero.
Capacidade do veículo	Sim	Carga máxima de um veículo em uma rota; vem preenchida com 100,0 e precisa ser maior que zero. Tem que estar na mesma unidade do campo de peso.
Camada de rede viária (Linhas)	Não	O seletor do topo do painel, compartilhado com a aba TSP: com rede, as distâncias são reais (Dijkstra sobre `QgsGraph`, matriz OD); sem rede, são euclidianas. Vale aqui a mesma nota de CRS de cálculo da seção 1.
Aplicar busca local (2-opt e Or-opt)	Não	Caixa marcada por padrão; refina cada rota construída pelas economias de Clarke-Wright. Desmarcar entrega as rotas brutas, mais rápido e pior.

Passo a passo do preenchimento¶

Camada de rede viária (Linhas - opcional) — no topo do painel, antes de abrir a aba; vale para as duas abas.
Abra a aba CVRP.
Camada de depósitos (Pontos) — obrigatória; selecione a camada com os depósitos.
Campo ID do depósito (opcional) — selecione o campo identificador de cada depósito, ou deixe vazio para usar o ID sequencial da feição.
Camada de demanda / clientes (Pontos) — obrigatória; selecione os clientes.
Campo do depósito de cada ponto (opcional) — selecione o campo que indica o depósito de cada cliente, ou deixe vazio para que cada um vá para o depósito mais próximo.
Campo de peso/demanda (opcional, default = 1,0) — o seletor aceita campo vazio, e a lista de campos acompanha a camada de demanda escolhida no passo anterior.
Capacidade do veículo — na mesma unidade do campo de peso.
Aplicar busca local (2-opt e Or-opt) — marcada por padrão.
Backend de otimização — combo com três opções:
Automático (OR-Tools quando disponível) — o padrão; usa OR-Tools se instalado, senão heurística Python pura.
Python puro (heurística) — força a heurística nativa, sem importar o OR-Tools em momento nenhum (modo seguro quando o carregamento da biblioteca derruba o QGIS).
OR-Tools — força OR-Tools; cai no fallback Python se não disponível.
Botão Executar Roteirização (CVRP).

Depósito e demanda são obrigatórios: sem eles, o painel abre um aviso e não executa. Como no TSP, o cálculo corre em segundo plano, com barra de progresso e botão Cancelar. As duas camadas de saída (Rotas geradas e Paradas por rota) são gravadas no GeoPackage da camada de referência quando houver um, ou criadas como camadas temporárias quando não houver — ver a seção 8.

Exemplo de uso com dois depósitos (Multi-Depot CVRP)¶

Suponha uma operação logística com dois depósitos (por exemplo, 1 e 2 no campo id da camada de depósitos) atendendo uma rede de clientes:

Camada de depósitos: Contém 2 pontos com o campo id preenchido como 1 e 2.
Camada de demanda: Contém os clientes com o campo destino indicando 1 ou 2. Se alguns clientes estiverem com o campo vazio ou NULL, eles serão associados automaticamente ao depósito mais próximo (menor custo de rede viária ou euclidiana).
Preenchimento no painel:
Camada de depósitos: camada dos 2 depósitos.
Campo ID do depósito: id.
Camada de demanda / clientes: camada de clientes.
Campo do depósito de cada ponto: destino.
Agrupa primeiro, roteiriza depois: O algoritmo particiona as demandas por depósito e executa a roteirização do CVRP para cada grupo separadamente. Clientes do depósito 1 só entram em rotas que partem e voltam ao depósito 1, e clientes do depósito 2 em rotas do depósito 2. Os clientes nunca trocam de depósito durante a otimização das rotas.

O que muda no resumo do painel: Cada linha de rota ganha ao final a indicação | depósito {id}:

-> Rotas geradas: 4
-> Paradas atendidas: 28
-> Carga total: 140.00
-> Distância total: 42350.80 m
Rota 1: 7 paradas | carga 35.00 | distância 10240.50 m | depósito 1
Rota 2: 8 paradas | carga 40.00 | distância 11120.30 m | depósito 1
Rota 3: 6 paradas | carga 30.00 | distância 9850.00 m | depósito 2
Rota 4: 7 paradas | carga 35.00 | distância 11140.00 m | depósito 2
Backend de otimização: python

O que muda nas camadas de saída: O campo depot_id é preenchido em todas as rotas e paradas:
Em Rotas geradas: indica qual depósito originou aquela rota.
Em Paradas por rota: indica a qual depósito aquele cliente e sua rota pertencem.

Ler o painel de resultados do CVRP¶

O painel abre com quatro totais e, em seguida, uma linha por rota:

Linha do painel	Campo de origem	Significado
Rotas geradas	contagem de `route_id`	Quantos veículos/viagens o plano exige.
Paradas atendidas	soma de `stop_count`	Total de clientes atendidos, somando todas as rotas.
Carga total	soma de `route_load`	Soma das demandas atendidas, na unidade do campo de peso (ou o número de paradas, quando o campo fica vazio).
Distância total	soma de `route_dist`	Quilometragem do plano inteiro, na unidade do CRS de cálculo (metros).
Rota N: k paradas \| carga L \| distância D \| depósito ID	`route_id`, `stop_count`, `route_load`, `route_dist`, `depot_id`	Uma linha por rota gerada com o depósito ao qual pertence — é por aqui que se vê o equilíbrio da frota: rotas com carga muito abaixo da capacidade, ou uma rota muito mais longa que as demais.
Backend de otimização	`backend`	`ortools` quando o OR-Tools resolveu a instância, ou `python` quando caiu no fallback da heurística nativa.

Ler as camadas de saída¶

Rotas geradas (linhas) — uma feição por rota, com a geometria do percurso depósito → clientes → depósito:

Campo	Significado
`route_id`	Identificador da rota, de 1 até o número de rotas.
`stop_count`	Quantidade de clientes atendidos nessa rota.
`route_load`	Carga total transportada na rota — comparar com a capacidade informada mostra a folga do veículo.
`route_dist`	Distância total da rota, ida e volta ao depósito.
`backend`	Backend efetivamente utilizado na otimização: `ortools` ou `python`.
`depot_id`	Identificador do depósito de partida e retorno desta rota.

Paradas por rota (pontos) — uma feição por cliente, com os atributos originais da camada de demanda acrescidos de:

Campo	Significado
`route_id`	Rota à qual o cliente foi atribuído — bom campo para uma simbologia Categorizada, que pinta cada rota de uma cor.
`stop_seq`	Posição da parada dentro da rota, de 1 até `stop_count`.
`cum_load`	Carga acumulada no veículo depois de atender esta parada; na última parada da rota, iguala o `route_load`.
`depot_id`	Identificador do depósito ao qual o cliente e sua rota foram atribuídos.

A sequência de visita está na tabela de atributos. Como no TSP, a ordem de armazenamento das feições não é a ordem de atendimento: abra a tabela de atributos de Paradas por rota e ordene por route_id e depois por stop_seq (clique nos cabeçalhos das colunas) para ler o roteiro de cada veículo, parada a parada.

A referência técnica do algoritmo — formulação, economias de Clarke-Wright, backend OR-Tools, complexidade e bibliografia — está em Algoritmos de Roteirização §1.

8. Execução em segundo plano e destino das saídas¶

A tela continua utilizável¶

TSP e CVRP não rodam mais dentro do laço da interface: os dois botões despacham o algoritmo para o gerenciador de tarefas do QGIS, e o cálculo corre numa thread de trabalho. Enquanto ele corre, a janela do QGIS continua respondendo — dá para navegar no mapa, abrir uma tabela de atributos, ler o log.

As duas barras andam juntas. A barra do próprio painel, logo acima do campo de resultados, e a barra do gerenciador de tarefas do QGIS, no canto inferior direito da janela, mostram o mesmo número: ambas vão de 0 a 100 conforme as etapas do algoritmo (grafo → matriz OD → solver → saídas; as faixas de cada etapa estão em Algoritmos de Roteirização). Enquanto a tarefa corre, os botões Calcular Rota (TSP) e Executar Roteirização (CVRP) ficam desabilitados — uma execução de cada vez — e o botão Cancelar, logo abaixo da barra, fica habilitado.

O botão Cancelar¶

Cancelar interrompe o cálculo: as etapas consultam o pedido de cancelamento entre os passos, a execução para sem gravar saída nenhuma e o painel registra em amarelo "Cálculo cancelado pelo usuário.". A barra some, os botões voltam a ficar habilitados e nada é adicionado ao projeto.

Se o cálculo falhar — ao iniciar ou no meio da execução —, a mensagem de erro do algoritmo aparece em vermelho no campo de resultados, a barra some e os botões voltam a ficar habilitados para uma nova tentativa, sem nada adicionado ao projeto.

Limite conhecido — cancelar no meio da busca do OR-Tools. Com o backend OR-Tools, o pedido de cancelamento só é lido quando o solver devolve uma solução nova — é no retorno de cada solução que o plugin manda o solver encerrar a busca corrente. Se a busca entrar numa fase nativa longa sem produzir solução nova, clicar em Cancelar destrava a interface na hora (o painel dá o cálculo por cancelado e os botões voltam), mas a thread de trabalho só encerra de fato quando o limite de tempo interno do solver — 10 segundos — se esgota. Não há dado perdido nem saída gravada: é apenas uma thread que segue ocupada por alguns segundos. Com o backend Python puro (heurística) o cancelamento é consultado a cada rodada de busca local, sem essa espera.

Onde a saída é gravada¶

As camadas de saída deixaram de ser apenas de memória. O destino é decidido pela camada de referência: a camada de rede viária do topo do painel quando houver uma e, quando não houver, a camada de pontos a visitar (TSP) ou de demanda / clientes (CVRP).

Origem da camada de referência	Onde as saídas vão parar
Arquivo `.gpkg`	No mesmo GeoPackage, como camadas novas, recarregadas dali para o projeto.
Qualquer outra origem (memória, shapefile, PostGIS, serviço)	Camada temporária, adicionada ao projeto — salve-a em disco antes de fechar o projeto.

O painel diz onde a saída foi parar na linha Destino das saídas: — o nome do arquivo .gpkg ou "camada temporária". Se a gravação no GeoPackage falhar (disco cheio, arquivo somente leitura, GPKG aberto por outro programa), o painel avisa em amarelo e a execução cai na camada temporária em vez de perder o resultado.

Como as camadas se chamam¶

O nome é montado a partir do tipo de execução, do modo de distância e do nome da camada de referência em slug (minúsculas, sem acento; espaços e _ viram -):

Execução	Camada de linhas	Camada de pontos
TSP, pela rede viária	`TSP-rede_<ref>` — Rota (trechos)	`TSP-rede_<ref>_pontos` — Ordem de visita
TSP, linha reta	`TSP-euclidiana_<ref>`	`TSP-euclidiana_<ref>_pontos`
CVRP, pela rede viária	`CVRP-rede_<ref>` — Rotas geradas	`CVRP-rede_<ref>_pontos` — Paradas por rota
CVRP, linha reta	`CVRP-euclidiana_<ref>`	`CVRP-euclidiana_<ref>_pontos`

<ref> é o slug da camada de referência: uma rede chamada osm_links_3106200 vira osm-links-3106200, e o par de saídas de um TSP pela rede sai como TSP-rede_osm-links-3106200 (linhas) e TSP-rede_osm-links-3106200_pontos (pontos).

Reexecutar substitui o resultado anterior de mesmo nome¶

Rodar de novo com os mesmos insumos produz o mesmo nome de camada — e a gravação substitui a camada homônima dentro do GeoPackage, em vez de criar uma segunda. Antes de gravar, o plugin remove do projeto a camada já carregada com aquele nome (sem isso o arquivo fica travado no Windows) e a recarrega depois da gravação.

A consequência a conhecer: o resultado anterior de mesmo nome se perde. Para comparar dois cenários, renomeie ou salve à parte a saída da primeira execução antes de rodar a segunda — ou mude o que entra no nome (a camada de referência ou o modo de cálculo da distância).

9. Limitações¶

A aba TSP é um TSP de um único veículo: não há capacidade, janela de tempo nem frota. Para frota com capacidade, use a aba CVRP (logis:vrp_cvrp).
Solução boa, não ótima: heurística Vizinho Mais Próximo + 2-opt/Or-opt (ou OR-Tools com limite de 10 segundos). Escala testada: até 1.000 pontos; o custo cresce com o quadrado do número de pontos (matriz de distâncias N×N).
Sem rede viária, as distâncias são euclidianas e subestimam o percurso real.
Com rede viária, os pontos são aproximados (snap) ao vértice mais próximo do grafo; ponto que não se amarra à rede e par de pontos sem caminho entre si interrompem a execução com erro, em vez de entrar no cálculo como custo enorme.
Ponto inicial e ponto final usam apenas a primeira feição válida da camada — feições extras são ignoradas em silêncio.
Feições de geometria vazia na camada de pontos a visitar são puladas; polígonos entram pelo centroide.
Camadas de saída temporárias quando a camada de referência não vem de um .gpkg: perdem-se ao fechar o projeto sem salvar (ver a seção 8).
CVRP — demanda maior que a capacidade: nenhum cliente pode ter demanda maior que a capacidade do veículo; nesse caso o algoritmo recusa a execução com a mensagem "A demanda do nó excede a capacidade máxima do veículo". Não há entrega fracionada: ou o cliente cabe em um veículo, ou a instância é inviável.
CVRP — frota homogênea e sem janela de tempo: todos os veículos têm a mesma capacidade, não há limite de jornada, tempo de serviço, janela de atendimento nem número máximo de veículos.
CVRP — solução boa, não ótima: heurística de economias de Clarke-Wright + 2-opt/ Or-opt, em Python puro. Escala testada: até 1.000 pontos de demanda.

10. Problemas comuns¶

Sintoma	Causa provável
"Por favor, selecione a camada do ponto inicial."	Nenhuma camada escolhida no seletor de ponto inicial.
"Por favor, selecione a camada de pontos a visitar."	Nenhuma camada escolhida no seletor de pontos a visitar.
"QGIS Processing não está disponível no ambiente atual."	O painel foi instanciado fora de uma sessão do QGIS Desktop.
"A camada de pontos a visitar está vazia."	Nenhuma feição com geometria válida na camada de pontos a visitar.
"Nenhum ponto final válido encontrado na camada fornecida."	A camada de ponto final foi selecionada, mas nenhuma feição nela tem geometria válida.
Trechos retos na saída apesar de haver rede selecionada	O Modo de cálculo da distância ficou em Linha reta (euclidiana), que é o padrão — nesse modo a camada de rede do topo do painel é ignorada. No modo pela rede, são pernas isoladas cujo caminho não pôde ser reconstruído na malha (`leg_geom` = `reta`), contadas no aviso do painel de resultados.
A rota muda de uma execução para outra com OR-Tools instalado	A metaheurística `GUIDED_LOCAL_SEARCH` roda até o limite de 10 segundos; pequenas variações de tempo podem mudar o resultado entre rodadas.

11. Quando o QGIS fecha sozinho ao calcular a rota¶

Em algumas máquinas o QGIS fecha sem aviso no meio do cálculo da rota: nenhuma mensagem de erro, nenhuma linha no log de Processing, a janela simplesmente some. Quase sempre a culpa não é do logis, e sim do carregamento do OR-Tools — o import de uma biblioteca compilada pode derrubar o processo inteiro do QGIS, e nesse caso não há exceção para capturar. Esta seção mostra como confirmar isso e como seguir trabalhando.

Onde fica o `diagnostico.log`¶

O plugin registra as etapas da execução em diagnostico.log, no diretório de cache do logis — QStandardPaths.CacheLocation → .../logis/, a mesma pasta descrita em Onde ficam o cache e o GeoPackage (o caminho exato varia por sistema operacional). Cada linha tem quatro campos separados por |:

2026-09-19T14:03:11.482913 | 48211 | tsp-build-graph | camada com 12834 feicoes

— data/hora ISO 8601, PID do processo do QGIS, etapa e detalhe. Cada marca é gravada e descarregada em disco na hora (flush + fsync), justamente para sobreviver a um fechamento abrupto.

Como ler a última linha¶

A última linha do arquivo é a última etapa que o plugin alcançou antes de o QGIS morrer — é ela que diz onde a execução parou. Terminando em tsp-ortools-import, o processo morreu carregando o OR-Tools (a suspeita principal); terminando em tsp-build-graph ou tsp-od-matrix, foi a construção do grafo da rede — reduzir a área ou usar uma camada de rede menor resolve.

No terminal:

find "$HOME/.cache" -name diagnostico.log -exec tail -n 1 {} +

No Console Python do QGIS (Complementos → Console Python), que dispensa saber o caminho — a primeira linha o imprime, a segunda mostra as últimas cinco etapas:

from logis.core.crashlog import trace_path, read_tail
print(trace_path()); print("".join(read_tail(5)))

Escolher “Python puro” no seletor de backend¶

No painel logis — Roteirização, aba TSP, o seletor Backend de otimização tem três opções: Automático (OR-Tools quando disponível) — o padrão —, Python puro (heurística) e OR-Tools. Escolher Python puro (heurística) é o modo seguro: o cálculo não importa o OR-Tools em momento nenhum, então um travamento causado por ele deixa de acontecer. A rota sai pela heurística nativa (Vizinho Mais Próximo + 2-opt/Or-opt) — solução boa, não necessariamente ótima —, e a linha Backend de otimização do painel de resultados passa a mostrar python.

O mesmo seletor existe no diálogo do algoritmo logis:vrp_tsp, no parâmetro BACKEND (ver Algoritmos de Roteirização).

O teste de uma linha que aponta o culpado¶

Ainda no Console Python do QGIS, com o painel de roteirização fechado, execute apenas isto:

from ortools.constraint_solver import pywrapcp

O que acontece	O que significa
O QGIS fecha na hora	A culpa é do OR-Tools, não do plugin — o mesmo import derruba o QGIS fora do logis. Siga com Python puro, ou reinstale/remova o pacote.
Sai um `ImportError` / `ModuleNotFoundError`	O OR-Tools não está instalado; o plugin já vinha usando a heurística Python e o fechamento tem outra causa.
Não acontece nada (nenhuma saída)	O import funciona: o OR-Tools está sadio e o problema está em outro ponto — guarde as últimas linhas do `diagnostico.log` para o relato.

Depois de um fechamento, o OR-Tools fica desativado sozinho¶

Se o QGIS morreu justamente durante o carregamento do OR-Tools, o plugin o desativa por conta própria na sessão seguinte, para não repetir o tombo: a roteirização passa a usar a heurística Python e o painel de resultados abre com o aviso em amarelo "O OR-Tools está desativado por ter derrubado a sessão anterior. O rearme fica no diálogo de Dependências." Como isso funciona e onde fica o botão Reativar OR-Tools está em OR-Tools (backend opcional).