MapTiler SDK: Mappe JavaScript con gli steroidi

Pubblicato il 05 maggio 2023

Che cos'è l'SDK di MapTiler?

MapTiler ha creato un ecosistema cartografico completo per le aziende, che comprende strumenti di elaborazione avanzati come Desktop/Engine, servizi di archiviazione ed elaborazione dei dati, plugin QGIS, servizi di geocodifica e geolocalizzazione, librerie JavaScript, strumenti per lo styling delle mappe e altro ancora. Finora ci siamo affidati principalmente alla comunità open-source e a MapLibre per la visualizzazione delle mappe sul web. Anche se continueremo a farlo, stiamo passando a un livello superiore creando il nostro SDK per integrare meglio le nostre mappe con il vostro sito web. L'SDK di MapTiler è un nuovo SDK JavaScript e TypeScript creato su misura per MapTiler Cloud.

In questo articolo, forniremo maggiori dettagli sul nostro nuovo SDK, illustrandone il target, la costruzione, le caratteristiche principali, la possibilità di iniziare e la nostra visione per il futuro.

Perché creare un proprio SDK?

Prima di iniziare lo sviluppo dell'SDK, abbiamo affrontato numerose discussioni interne sulla sua creazione: Dobbiamo costruire qualcosa di completamente nuovo da zero o basarci su una soluzione esistente? In tal caso, quali sono le opzioni più adatte?

Da un punto di vista commerciale, volevamo una soluzione che non richiedesse un anno di sviluppo, poiché la funzione principale dell'SDK è quella di facilitare altre idee (sia nostre che vostre). A quel tempo, avevamo già alcuni progetti che si sarebbero integrati bene con un SDK. Rapidamente, MapLibre GL è emerso come il candidato migliore. È veloce, ben mantenuto e sia noi che la nostra comunità lo conoscevamo già, il che lo rendeva la base ideale per il nostro progetto!

Ora vi chiederete: "Perché non contribuire direttamente a MapLibre?". - Le ragioni principali sono due:

• Vogliamo che il nostro SDK sia completamente integrato con il nostro stack di dati e i nostri servizi per fornire un'esperienza di sviluppo senza soluzione di continuità e senza attriti. Sarebbe inopportuno che MapLibre, un progetto gestito dalla comunità, fosse fortemente influenzato da uno specifico fornitore di dati.

• Come azienda, MapTiler ha una propria tabella di marcia per il rilascio dei prodotti. Abbiamo funzioni che vogliamo rilasciare prima e non vogliamo interrompere o influenzare la direzione dello sviluppo della comunità di MapLibre con la nostra tabella di marcia.

Per quanto riguarda il secondo punto, il nostro SDK è rilasciato sotto una licenza open-source (BSD-3), quindi alcuni dei suoi componenti potrebbero essere trasferiti a MapLibre nel prossimo futuro.

Un'altra domanda che abbiamo anticipato riguarda la compatibilità: "Se ho i miei dati (ad esempio, tileset, file GeoJSON, ecc.) sul mio server o su un server di un fornitore di dati diverso da MapTiler, funzioneranno con MapTiler SDK?". - Sì, potete sicuramente continuare a utilizzare i vostri dati!

Fin dal primo giorno, ci siamo assicurati che il nostro SDK, se basato su MapLibre, rimanesse pienamente compatibile con MapLibre. Il nostro SDK aggiunge scorciatoie e funzioni, ma l'utente non è obbligato a usarle. Quindi, sentitevi liberi di usare i vostri dati da un server personalizzato o da un'altra fonte; dipende solo da voi!

Un ultimo punto da affrontare prima di approfondire il nostro SDK è l'evoluzione di MapLibre. Abbiamo intenzione di mantenere attivamente l'SDK, che è stato progettato per adattarsi e crescere con le future versioni di MapLibre, beneficiando dei suoi progressi.

Ora entriamo nei dettagli!

Creare la prima mappa con l'sdk MapTiler

Se avete già familiarità con MapLibre, la curva di apprendimento del nostro SDK sarà quasi piatta!

Prima di tutto è necessario ottenere una chiave API. È facile e il livello gratuito è piuttosto generoso, quindi create un account MapTiler Cloud e poi andate alla sezione API per ottenere la chiave.

Quindi, per installare e utilizzare l'SDK nel vostro progetto JS/TS, avete due opzioni:

• utilizzare il nostro CDN e una semplice pagina HTML come questa:

( Questo esempio e molti altri sono disponibili nelle pagine della documentazione dell'SDK).

• oppure installarlo nel progetto con NPM:

npm install --save @maptiler/sdk

Quindi, in una delle pagine del frontend o in un componente React, importare questi elementi dall'SDK:

import { Map, MapStyle, config } from '@maptiler/sdk';


// Set your MapTiler CLoud API key
config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';


const map = new Map({
  container: 'map', // Div container ID HTML element, or React ref
  style: MapStyle.STREETS, // Pick one of the built-in styles
  center: [16.62662018, 49.2125578], // position [lng, lat]
  zoom: 14,
});

Come si può notare, questa operazione è abbastanza simile all'inizializzazione di MapLibre. Da qui, la differenza principale è il modo in cui si imposta il token dell'API (che prima faceva parte dell'URL dello stile) e l'attributo stile che ora è un valore autocompilato da un gran numero di stili incorporati.

Il partner perfetto per lo stack di MapTiler Data

MapTiler è un prolifico creatore di dati! Molti layer sono sviluppati internamente e il nostro team di geodati è sempre impegnato! Penso a MapTiler Planet, Geocoding, Ocean, terreni 3D personalizzati e molti altri (basta guardare gli altri articoli in questa sezione di notizie)! Siamo anche attivi nella creazione di partnership con alcuni grandi operatori per fornire dati eccezionali ai nostri utenti; sarebbe un peccato se questi non venissero facilmente inseriti nei prodotti dei nostri clienti.

Una delle caratteristiche principali del nostro SDK è la facilità di accesso ai dati!

Ecco cosa si ottiene con un account gratuito di MapTiler Cloud

• tutti gli stili e i tileset premium, gestiti dai nostri cartografi
• uno strumento per creare i propri stili partendo da zero o clonando uno esistente
• un servizio di hosting per i vostri dati geo (.geojson, .gpx, .kml, .shp, .zip shapefile) memorizzati come geojson
• un servizio per consumare i dati (API REST e libreria TypeScript del cliente)
• un servizio di geocodifica (API REST e libreria client TypeScript)
• un servizio di geolocalizzazione IP (API REST e libreria client TypeScript)
• un sacco di tutorial per iniziare e fare cose più avanzate sulla mappa!
• quote generose, più che sufficienti per i vostri progetti collaterali!

Stili di mappa semplificati

La progettazione di mappe non è un compito semplice, soprattutto quando la mappa deve trasmettere intenzioni chiare riducendo al minimo il disordine visivo. Ma noi ci siamo!

Il team di cartografi e designer di MapTiler crea continuamente nuovi stili per vari scopi: orientamento stradale, escursionismo e sci, visualizzazione di dati, orientamento oceanico e altro ancora! Attualmente disponiamo di un ampio elenco di stili, ciascuno con caratteristiche e applicazioni uniche.

Per rendere questi stili facili da incorporare nei vostri progetti, abbiamo deciso di creare delle abbreviazioni che si completano automaticamente con le descrizioni quando si usa TypeScript. Vediamo come funziona:

import { Map, MapStyle } from '@maptiler/sdk';

this.map = new Map({
  container: someDiv,
  style: MapStyle.DATAVIZ.DARK,
})

Il stile nella proprietà Mappa è ora opzionale (mentre è obbligatorio in MapLibre) e, se non viene fornito, utilizzerà il nostro costruttore strade-v2 stile (abbreviato: MapStyle.STREETS).

Ecco i vantaggi dell'uso della stenografia rispetto allo stile URL:

• non è necessario ricordare l'URL, le abbreviazioni sono autocompletate
• Non c'è bisogno di sapere qual è l'ultima versione, si usa la più recente (streets-v2? o forse v3?)
• non è necessario concatenare la chiave API
• le varianti di stile sono più facili da raggiungere

Ecco come si presenta il completamento automatico in VSCode con un progetto TypeScript:

Completamento automatico che mostra tutti gli stili

Completamento automatico che mostra tutte le varianti per un determinato stile Tuttavia, essendo MapTiler SDK completamente retrocompatibile con MapLibre, è ancora possibile utilizzare un URL o una descrizione dello stile dell'oggetto.

Una parola sulle varianti di stile: se si digita MapStyle.DATAVIZ in VSCode, si vedrà il completamento automatico con quanto segue:

• MapStyle.DATAVIZ.DEFAULT: uno stile minimalista con solo un piccolo tocco di colore, equivalente all'uso di MapStyle.DATAVIZ
• MapStyle.DATAVIZ.LIGHT: un'alternativa minimalista in grigio chiaro
• MapStyle.DATAVIZ.DARK: un'alternativa minimalista in modalità scura grigia

La maggior parte degli stili prevede più varianti e tutte le varianti dello stesso stile visualizzano gli stessi dati; cambia solo la combinazione di colori. Esistono anche varianti per stili diversi, per esempio un SCURO esiste una modalità per lo stile DATAVIZ e anche per lo stile STRADE, LUMINOSO, BASIC, ecc.

Ecco quattro dei nostri stili più popolari:

MapStyle.STREETS	MapStyle.SATELLITE
MapStyle.DATAVIZ.DARK	MapStyle.OUTDOOR

Il terreno, reso ancora più facile!

Uno dei vantaggi della visualizzazione delle mappe con WebGL è la possibilità di sfruttare le sue capacità di mesh per il rendering di elementi 3D, come le montagne. Sorprendentemente, nonostante il terreno 3D sia disponibile da tempo, non è mai stato particolarmente semplice da attivare. Di solito è necessario aggiungere una fonte con l'URL dei set di piastrelle del terreno, quindi incorporare questa fonte nella mappa in un modo molto specifico. Se si desidera modificare l'esagerazione, si deve in qualche modo riavviare parte di questo processo, che può essere piuttosto macchinoso.

Noi di MapTiler possediamo e forniamo i dati del terreno, il che ci consente di offrire un accesso diretto e di semplificare notevolmente l'uso del terreno 3D! È possibile abilitare il terreno 3D già al momento dell'istanziazione del file Mappa:

const map = new Map({
  container: someDiv,
  style: MapStyle.OUTDOOR,
  terrain: true,            // OPTIONAL. This is false by default
  terrainExaggeration: 1.5, // OPTIONAL. This is 1 by default
})

o più tardi, dopo che la mappa è stata istanziata:

// Without param, the exaggeration factor is 1
map.enableTerrain();

// Or with an exaggeration of more than 1, to have even bigger mountains
map.enableTerrain(1.5);

Per disattivare il terreno e smettere di recuperare le tessere del terreno sotto il cofano, basta usare map.disableTerrain().

Giocare con l'esagerazione del terreno su MapStyle.WINTER

Oltre il Data

Un principio di progettazione fondamentale per noi è incapsulare la complessità in modo che non sia necessario. Ciò include la creazione di ponti diretti con il nostro stack di dati, come già detto, e altro ancora. Nella sezione seguente troverete altri esempi di come ci atteniamo a questo principio guida.

Per una vita più semplice (Dev)

Ora sappiamo che c'è un accesso diretto allo stack di dati di MapTiler Cloudche rende semplice sbloccare stili e terreni. Tuttavia, ci sono altri aiutanti, quindi diamo un'occhiata più da vicino:

• geolocalizzazione: specificare geolocalizzazione: true (predefinito: falso) nel Mappa e la mappa viene centrata sulla posizione dell'utente. Sotto il cofano, si utilizza l'API di geolocalizzazione IP di MapTiler Cloud. Si tenga presente che questa è meno precisa di un GPS, ma non ha nemmeno bisogno di concedere l'accesso all'API di localizzazione del browser, quindi il flusso non viene interrotto.

• lingua: Per impostazione predefinita nell'SDK, le istanze della mappa useranno le impostazioni del browser per utilizzare la lingua preferita dall'utente. È possibile modificarla con l'opzione Mappa opzione del costruttore lingua: Lingua.INGLESE o un'altra delle 78 scorciatoie linguistiche incorporate. Dopo la creazione della mappa, è possibile utilizzare il nuovo metodo map.setLanguage(Language.SPANISH) per aggiornarlo.

• controlli: Storicamente, i controlli sono un altro attrito e il più delle volte devono essere istanziati e poi aggiunti alla mappa dall'interno del callback dell'evento "load". Per l'SDK, abbiamo deciso di semplificare questo aspetto e di rendere disponibili tutti i controlli classici dal costruttore. Per ognuno di essi, è possibile specificare vero / falso e una posizione come in alto a sinistra o in basso a destra. Ecco l'elenco di Mappa opzioni del costruttore:

  • navigazioneControllo (predefinito: vero, mostrando sul in alto a destra) mostra i pulsanti di zoom/cuscinetto/rotazione
  • terrenoControllo (predefinito: falso, mostrando sul in alto a destra quando vero) mostra un pulsante per attivare il terreno 3D.
  • geolocalizzazioneControllo (predefinito: vero, mostrando sul in alto a destra) mostra un pulsante per geolocalizzare l'utente utilizzando l'API di localizzazione del browser (probabilmente il GPS).
  • controllo della scala (predefinito: falso, mostrando sul in basso a destra quando vero) mostra un righello in scala
  • fullscreenControl (predefinito: falso, mostrando sul in alto a destra quando vero) mostra un pulsante per attivare lo schermo intero.

• geocodifica: L'SDK di MapTiler include il linguaggio TypeScript MapTiler Cloud Libreria client API e lo espone anche. Ciò significa che possiamo facilmente utilizzare funzioni come la geocodifica: geocoding.forward("paris")

Qual è il vantaggio rispetto a... tu_nome_it?

L'obiettivo dell'SDK di MapTiler, abbinato ai nostri dati, è quello di ridurre la curva di apprendimento con un ottimo pacchetto iniziale e speriamo che renda la mappatura interattiva una cosa più facile da fare, in modo che più persone possano mostrare i loro dati al mondo. Tuttavia, ci sono alcune alternative popolari che si possono prendere in considerazione, e sono tutte popolari per un motivo, ma cerchiamo di vedere in una matrice di confronto come l'SDK si distingue:

Cercate assistenza?

L'SDK è dotato di una documentazione completa e di numerosi esempi, che costituiscono un ottimo punto di partenza! Se si utilizzano funzioni come la geocodifica, la geolocalizzazione IP o il recupero dei dati da MapTiler Cloud, si tenga presente che l'SDK include la libreria API Client, anch'essa ben documentata!

Vogliamo anche incorporare il vostro feedback nell'SDK!

• Avete notato qualche problema?
• Volete vedere una nuova funzione?

Fatecelo sapere direttamente tramite GitHub Issues e faremo del nostro meglio per rispondere prontamente!

Le ultime parole

In sintesi, il nostro obiettivo è ridurre la complessità e rendere più facile per tutti, compresi gli sviluppatori junior, creare mappe e visualizzazioni di dati geografici di grande effetto!

I metodi per raggiungere questo obiettivo possono sembrare semplici e riguardano principalmente:

• Riduzione della distanza tra voi e i dati di cui avete bisogno
• Trasformare gli elementi costitutivi più comuni in battute singole
• Comprese le comode impostazioni predefinite
• Fornire una documentazione utile, sia online che all'interno dell'editor di codice.

Per esperienza, capiamo che incapsulare la complessità può essere un'impresa che richiede tempo e spesso sforzi ingegneristici non banali, ma è proprio questa la direzione che vogliamo dare al nostro SDK!

Trovate l'SDK di MapTiler là fuori

Provatelo voi stessi; è open source (BSD-3) e ricordate che MapTiler Cloud ha un livello gratuito molto generoso che offre stili di mappe e tileset sempre nuovi!

Ecco alcuni link che potrebbero essere interessanti:

• Pagina principale dell'SDK di MapTiler
• Documentazione di riferimento
• Esempi ufficiali
• Su GitHub
• Su NPM
• Pagina principale della libreria MapTiler Client (non è necessario installarla, è inclusa nell'SDK)

Non vediamo l'ora di vedere cosa costruirete con il nostro nuovo SDK, quindi fatecelo sapere su Twitter @maptiler!

Il futuro di MapTiler SDK

Il concetto di "ecosistema" è qualcosa a cui teniamo molto. Ogni volta che abbiamo un'idea per una nuova funzionalità, ci chiediamo sempre: "Dovrebbe far parte dell'SDK?". Non esiste una risposta universale; a volte è un "sì" e la realizziamo o la aggiungiamo alla nostra roadmap, mentre altre volte è un "no". Quindi, qual è la prossima mossa? Abbiamo deciso di sviluppare dei "moduli" che funzionano perfettamente con il nostro SDK, consentono un facile accesso ai dati senza ulteriori complessità e introducono nuove funzionalità nella vostra applicazione. In un certo senso, i moduli sono come dei "booster pack"!

In conclusione, l'SDK è solo all'inizio! Continueremo ad aggiungere nuove funzionalità direttamente collegate ai dati di MapTiler e alla semplificazione di alcuni componenti di MapLibre per ridurre ulteriormente l'attrito tra gli sviluppatori e la loro prossima applicazione!

Anche noi di MapTiler siamo sviluppatori e, proprio come tutti, apprezziamo la semplicità. Ogni volta che ci imbattiamo in una stranezza e ci troviamo a scavare a fondo in StackOverflow o nel codice sorgente di una libreria per capire perché le cose non funzionano come previsto, vediamo l'opportunità di rendere le cose più semplici! Prendiamo ad esempio i layer di MapLibre: alcuni sono molto belli e personalizzabili, ma non sempre facili da configurare, giusto? Forse qualcosa da affrontare nella prossima versione di MapTiler SDK!

Nel frattempo, ci vediamo là fuori!