Converter KMZ para CSV

Arquivo KMZ raramente nasce com quem está tentando abrir ele. Chega como anexo de um topógrafo, uma concessionária, uma secretaria de planejamento, um órgão de turismo ou um contratado, gerado pela ferramenta que aquela organização adotou, e pressupondo Google Earth do outro lado. Se você tem uma ordem de serviço para abrir ou uma contagem para conferir, instalar um visualizador de globo para ler quarenta coordenadas é uma troca ruim.

É para essa situação que esta conversão existe. Ela abre o arquivo, lê o documento interno e devolve posições e nomes em linhas — o bastante para colar uma coordenada num formulário, cruzar contra um cadastro de ativos ou confirmar que o arquivo de fato contém os dezoito pontos que o e-mail prometia. O que ela não vai dar é o mapa em si, e se o mapa é o entregável, o Google Earth é realmente a ferramenta certa.

Não existe um modelo de dado próprio do KMZ. O formato é um arquivo ZIP cujo membro principal é um documento KML, e tudo que um KMZ consegue expressar é expresso por esse KML. O arquivo compactado existe para um mapa viajar como um único arquivo junto com as imagens que ele referencia — ícone de alfinete customizado, uma sobreposição de foto, uma planta digitalizada georreferenciada sobre o terreno — em vez de uma pasta que quebra se um arquivo ficar para trás.

O leitor procura `doc.kml`, que é o nome que o Google Earth grava, e recorre ao primeiro membro terminado em `.kml` se esse nome não existir. Esse recurso não é enfeite defensivo: a especificação só exige que o documento principal do arquivo seja um KML, e ferramentas diferentes exportam com nomes como `Locais_Fase2.kml`. Se nenhum membro terminar em `.kml`, a conversão para e avisa em vez de gerar uma tabela vazia.

Um KMZ de 4 MB quase nunca é 4 MB de coordenada. O grosso costuma ser uma pasta `files/` ou `images/` guardando PNG de ícone, uma sobreposição JPEG, às vezes uma planta digitalizada com milhares de pixels. Nada disso aparece no CSV, e não é um descarte por descuido — uma tabela não tem onde colocar uma imagem raster, e uma coluna de nomes de arquivo apontando para arquivos que você não tem mais seria pior do que nada.

A consequência prática é que um KMZ cujo conteúdo real é uma imagem converte para um CSV quase vazio. Uma planta georreferenciada com dois marcadores de canto entrega duas linhas e nada da planta. Se é isso que você encontrar, o arquivo é um documento, não um conjunto de dados, e descompactar na mão para olhar a imagem é a resposta, não um conversor diferente.

Cada linha carrega um tipo, um nome, uma latitude, uma longitude, uma elevação e um horário. O tipo distingue um ponto solto de um vértice de uma linha desenhada, e é o primeiro filtro útil: um KMZ de localização de ativo deveria ser inteiramente linhas de ponto, e um bloco grande de linhas de trajeto significa que o arquivo também contém rota ou limite de área.

O nome é a etiqueta que o marcador carregava, repetido em cada vértice de uma linha para que filtrar um único elemento num arquivo grande não exija nenhum cruzamento de tabela. Latitude e longitude são graus decimais, o que uma caixa de busca de mapa, um sistema de frota e uma API de geocodificação aceitam direto. Elevação e horário costumam ficar vazios, porque um mapa desenhado normalmente não registra nenhum dos dois, e vazio é a saída correta para um valor que a origem nunca tinha.

Trocar a extensão para `.zip` e dar duplo clique é um jeito legítimo de chegar ao conteúdo, e vale saber porque não custa nada e confirma o que o arquivo de fato é. Qualquer sistema operacional de mesa abre isso, e você vai ver o KML junto com as imagens que viajaram com ele.

O que você tem então é XML: coordenadas escritas como trincas `longitude,latitude,altitude` juntas dentro de um único elemento, envolvidas em estrutura de marcador e pasta, com a longitude primeiro. Isso é legível para quem está caçando um número e inutilizável como conjunto de dados. A conversão faz a segunda metade — percorrer a árvore de pastas, separar a coordenada, inverter para latitude primeiro — que é a parte chata de fazer à mão e fácil de errar.

A compressão torna o tamanho do arquivo em disco um péssimo indicador do que tem dentro. KML é texto repetitivo, que comprime de forma incomum: um KML de cerca de 258 KB medido aqui comprimiu para cerca de 47 KB dentro do arquivo, um fator de cinco e meio. Um KMZ de 3 MB pode, portanto, guardar algo como 15 MB de KML e várias centenas de milhares de coordenadas.

O teto gratuito de 100 MB se aplica ao KMZ como ele está em disco, então na prática o limite que você encontra primeiro é a memória da aba do navegador, não o número. Se um arquivo grande travar, o diagnóstico útil é renomear para `.zip` e olhar o tamanho descompactado do membro KML — esse número, não o tamanho do arquivo compactado, é o que precisa ser analisado e mantido em memória.

Duas falhas distintas produzem algo que parece nada. Se o arquivo não tem membro KML, a conversão diz isso explicitamente, e a causa quase sempre é um arquivo renomeado em vez de exportado. Se o KML está presente mas não gera geometria nenhuma, a mensagem é que nenhum trajeto ou ponto foi encontrado, um problema diferente com uma correção diferente.

A causa mais comum do segundo caso é que o arquivo é feito de polígonos. Área — limite de lote, zona de inundação, área de cobertura — guarda o contorno dentro de um elemento `<Polygon>` que este leitor não percorre, então um KMZ só de regiões sombreadas gera nenhuma linha. Links de rede, que buscam o conteúdo numa URL em vez de guardar ele, voltam vazios pelo motivo mais fundamental de que o arquivo de fato não contém dado nenhum.

O nome de cada marcador atravessa. Quase nada mais do que uma exportação profissional carrega vem junto, e nesse tipo de arquivo essa é a omissão mais provável de importar: o número do ativo, o diâmetro da tubulação, a data de inspeção, a referência do lote e a nota do topógrafo geralmente moram no balão `<description>` ou num bloco `<ExtendedData>`, e nenhum dos dois é lido. Um KMZ que parecia denso de informação no Google Earth pode converter para uma tabela de nomes e números com toda a substância faltando.

Duas rotas recuperam isso. Renomeie o arquivo para `.zip`, extraia o KML e leia — os campos estendidos são verbosos mas perfeitamente legíveis, e um elemento `<SimpleData name="asset_id">` diz o que é. Ou peça a quem enviou a tabela que gerou o KMZ, que quase sempre existe, porque um arquivo com um esquema personalizado veio de um banco de dados, não de alguém desenhando num globo.

Latitude e longitude são escritas como graus decimais com seis casas, cerca de 11 centímetros — bem mais fino do que o dado de origem justifica e grosso o bastante para manter o arquivo legível. Esse formato entra direto na caixa de busca de qualquer site de mapa, num sistema de frota ou despacho, e numa API de geocodificação sem conversão, que costuma ser o motivo imediato de alguém querer a tabela.

A única coisa a observar é a ordem que o destino espera. Escrito como `48.137154, 11.576124`, uma busca de mapa lê latitude primeiro e cai onde você quis. Um sistema construído sobre GeoJSON ou sobre uma biblioteca de SIG costuma querer longitude primeiro, e trocar o par move um ponto de São Paulo para o meio do oceano — longe o bastante para o erro ser óbvio na primeira vez e fácil de passar despercebido quando acontece numa linha entre quatrocentas.

O arquivo é descompactado, analisado e reescrito dentro desta aba do navegador. Nada é transmitido, o que o painel de rede confirma durante uma conversão, e a página continua funcionando com a conexão desligada. Não existe conta para criar e nenhum arquivo esperando numa fila depois.

Para este par o argumento é tão contratual quanto pessoal. Um KMZ vindo de um cliente, uma concessionária ou um órgão público costuma chegar sob termos sobre onde pode ser armazenado, e colar isso num conversor gratuito na web é exatamente o tipo de transferência que esses termos existem para impedir. Fazer a conversão localmente significa que não há terceiro para nomear, e nenhum acordo de processamento de dado para ir atrás.