Convertire KML in CSV

KML è stato costruito per disegnare su un globo. Un file di placemark porta molto più delle posizioni — uno stile per ogni icona, un fumetto descrittivo con HTML dentro, un albero di cartelle che li raggruppa, a volte una sovrapposizione del terreno dietro di essi. Ma un gran numero di file KML in circolazione sono usati come un elenco vestito da mappa : quaranta sedi di filiali, un insieme di siti di indagine, i luoghi che qualcuno ha contrassegnato in Google Earth in un anno.

Per quel file, un CSV è il contenitore più onesto. Ogni placemark diventa una riga di nome e coordinate, che è ciò che un geocoder, un ottimizzatore di percorsi, un import CRM o un `GROUP BY` consuma effettivamente. Tutto ciò che lo rendeva un disegno viene lasciato indietro, e questa è una perdita deliberata piuttosto che una limitazione : una colonna per un URL di icona non aiuterebbe nessuno, e non c’è forma di colonna che sopravviva a un fumetto descrittivo HTML.

KML scrive una coordinata come `longitudine,latitudine,altitudine` in un’unica stringa separata da spazi. Quasi ogni altro formato in questa famiglia, GPX e TCX inclusi, nomina la latitudine prima, e questa inversione è il modo più comune in cui una conversione KML va storta : la coppia viene trasposta piuttosto che spostata, quindi Berlino a 13.4, 52.5 esce come 52.5, 13.4 e atterra nel Mar Arabico.

La conversione le scambia, quindi le colonne del CSV sono `latitude` poi `longitude`. Questo vale la pena verificare piuttosto che fidarsi, e c’è un controllo di un secondo : per qualunque posto nell’Europa occidentale la latitudine va da circa 36 a 71 e la longitudine da circa -10 a 30, quindi se la prima colonna delle coordinate è piccola e la seconda è grande, qualcosa a monte le ha scambiate di nuovo.

Un KML annida. Un `<Document>` contiene elementi `<Folder>`, che contengono altre cartelle e infine gli elementi `<Placemark>` che portano la geometria. Il lettore percorre quell’albero piuttosto che guardare un solo livello in basso, perché un KML esportato da uno strumento di mappatura mette abitualmente i suoi placemark tre livelli di profondità, e un parser che controlla solo la cima del documento riporta un file vuoto che invece è pieno.

Ciò che la passeggiata non fa è preservare la struttura delle cartelle. Un pin in `Siti / Fase 2 / Confermati` esce come una riga indistinguibile da uno al livello superiore, perché il CSV ha una colonna `name` e appartiene al placemark. Se il raggruppamento è l’informazione, deve essere codificato nei nomi dei placemark prima della conversione, o recuperato dal KML dopo.

Un Placemark che contiene un `<Point>` diventa una riga tipizzata `waypoint`. Un Placemark che contiene un `<LineString>` diventa una corsa di righe tipizzate `track`, una per vertice, tutte che condividono il nome del placemark. Quei due coprono la stragrande maggioranza del KML in circolazione e entrambi passano con i loro nomi intatti.

Due cose non producono nulla, ed entrambe vale la pena conoscerle prima di convertire. Un `<Polygon>` — una regione ombreggiata, un confine di proprietà, un’area di servizio — mantiene il suo contorno dentro elementi di confine annidati che questo parser non scende, quindi un’area non contribuisce righe. Un `<MultiGeometry>` che avvolge diverse linee in un placemark viene saltato per la stessa ragione strutturale. Un KML fatto interamente di aree fallisce con il messaggio che non sono stati trovati track o waypoint, il che è accurato e non è un problema del file.

Un LineString è una forma senza nozione di quando. Se il KML viene da un export GPS piuttosto che da un disegno, può invece contenere un `gx :Track`, l’estensione di Google che memorizza elenchi paralleli di timestamp `<when>` e posizioni `<coord>`. Il lettore lo gestisce come un caso distinto piuttosto che trattarlo come una linea, e i timestamp arrivano nella colonna `time`.

L’indizio che ne avete uno è che la colonna `time` è popolata. Se ogni cella in essa è vuota, la sorgente conteneva LineString, e nessun convertitore può recuperare tempi che un file non ha mai memorizzato. Questo è anche il motivo per cui il terzo valore di coordinata dentro un gx :Track è separato da uno spazio piuttosto che da una virgola — lo stesso documento usa due separatori diversi per due geometrie diverse, che è una genuina stranezza del formato piuttosto che un errore in un file.

Il terzo valore in una coordinata KML è l’altitudine in metri, e la conversione lo scrive nella colonna `elevation` quando è presente. Ciò che non fa è consultare `<altitudeMode>`, l’elemento fratello che dice come l’altitudine debba essere interpretata — bloccata al suolo, relativa ad esso, o assoluta.

Questo conta perché il predefinito di Google Earth è `clampToGround`, sotto il quale il valore di altitudine viene ignorato del tutto ed è molto spesso scritto come `0`. Quindi un KML disegnato a mano su un terreno collinare tende a produrre una colonna di elevazione piena di zero che significano «sulla superficie», non «a livello del mare». Si tratti una colonna di zeri come assente piuttosto che come dato, e si prenda l’elevazione da un GPX o un TCX se è il numero per cui si è venuti.

L’output mette ogni riga `waypoint` prima di ogni riga `track`, indipendentemente dall’ordine in cui apparivano nel documento. È una comodità per il caso comune : un KML di pin si converte in un file le cui righe sono tutte waypoint, e un KML misto di pin più un percorso disegnato dà i pin in cima dove possono essere selezionati senza scorrere.

Il costo è che l’ordine del documento non è preservato attraverso i due tipi. Se la sequenza di feature nel KML portava significato — l’ordine in cui un’indagine ha visitato i suoi siti, per dire — quell’ordinamento deve venire dai nomi dei placemark o dalla colonna `time`, non dai numeri di riga. All’interno di ciascun tipo, l’ordine originale è mantenuto esattamente.

I nomi dei placemark sono il campo che ha più probabilità di rompere un CSV ingenuo, perché sono testo libero scritto da una persona. `Magazzino 3, Ingresso posteriore` contiene il delimitatore, e un indirizzo usato come nome ne contiene diversi. Lo scrittore mette tra virgolette qualsiasi valore contenente una virgola, una virgoletta o un ritorno a capo, e raddoppia le virgolette interne, che è ciò che RFC 4180 richiede e ciò che ogni foglio di calcolo e libreria CSV rilegge correttamente.

Le coordinate non hanno mai bisogno di virgolette, quindi il file resta leggibile in un editor di testo. Se si sta controllando l’output a occhio, i nomi tra virgolette sono le righe che vale la pena guardare : un nome contenente una virgoletta non bilanciata nel KML sorgente è l’unico caso in cui il file originale era già malformato e la conversione porta fedelmente questo attraverso.

KML definisce un elemento `<address>` su un Placemark, e Google Earth lo compila quando un pin è stato creato cercando un luogo piuttosto che cliccando sul globo. Non viene letto qui, quindi l’output porta un nome e delle coordinate e nulla che assomigli a un indirizzo postale anche dove il documento sorgente ne aveva uno.

Per la maggior parte delle destinazioni non è una perdita, perché una latitudine e una longitudine sono una chiave più forte di una riga di indirizzo e ogni servizio di routing, mappatura e geocoding ne accetta una direttamente. Dove un indirizzo è genuinamente richiesto — una spedizione, un manifesto di consegna — deve venire da un passo di geocoding inverso contro le coordinate, e una manciata di risultati vale la pena controllarli a occhio : un pin lasciato cadere nel mezzo di un parcheggio si risolve nell’edificio più vicino, che spesso non è quello che stava marcando.

La conversione gira interamente in questa scheda del browser — il KML viene letto, percorso e riscritto in locale, e nessuna richiesta lo porta da qualche parte. Non c’è account, coda o politica di conservazione da leggere, perché non c’è nulla su un server da conservare.

Il motivo per cui questo importa è ciò che un elenco di placemark di solito è. Un KML di pin è frequentemente un elenco di clienti, un insieme di indirizzi di consegna, siti di pazienti o clienti, o le posizioni di asset che qualcuno preferirebbe non pubblicare. Convertirlo in CSV lo rende più portatile e più leggibile allo stesso tempo, quindi l’output merita lo stesso trattamento del foglio di calcolo di cui sta per diventare parte.