NL Maps Library

De meest actuele kaart nu beschikbaar

Terug naar NL MapsBekijk op GitHub

NL Maps

Inhoud

  1. Doel
  2. Gebruiksvoorbeeld
  3. Opzetten
  4. API documentatie
  5. Geavanceerd gebruik
  6. Ruwe tegel URL's
  7. Ontwikkelen

Doel

Met de nlmaps JavaScript-bibliotheek kun je kaartlagen van de BRT-Achtergrondkaart maken voor Leaflet, Maplibre GL JS en OpenLayers. Je hoeft daardoor niet zelf de tegel-URL's te kennen.

Gebruiksvoorbeeld

let map = nlmaps.createMap({style: 'grijs', target: 'nlmaps-holder'});

Beschikbare kaartstijlen:

  • standaard: de standaard BRT-Achtergrondkaart, in kleur
  • pastel: in pasteltinten
  • grijs: met lage verzadiging
  • luchtfoto: luchtfoto's

Opzetten

Wizard

De NL Maps wizard maakt het heel eenvoudig om te beginnen. Het genereert code-voorbeelden die je laten zien hoe je een werkende kaart kunt krijgen. Het is aanbevolen om de output van de wizard te raadplegen, ook al ga je nlmaps handmatig gebruiken.

Handmatige browser-configuratie

Wil je nlmaps gebruiken in een webpagina, dan heb je ook Leaflet nodig. nlmaps detecteert automatisch of deze bibliotheek al aanwezig is (en beschouwt het momenteel als een fout als meer dan één aanwezig is). Voor meer informatie over het gebruik van Leaflet raadpleeg de eigen documentatie.

Tenslotte heb je nog de nlmaps bibliotheek zelf nodig. Deze kun je downloaden van de laatse release op Github. Download en extraheer de broncode en selecteer het bestand dist/nlmaps.iife.js. Voeg het toe aan je webpagina als volgt: 

<script src="url_of_nlmaps.iife.js"></script>

Node.js

nlmaps is ontwikkeld met Node.js versie 20.14.0 

npm install -S @geo-frontend/nlmaps
//CommonJS
let nlmaps = require('@geo-frontend/nlmaps');

//ES2015 Modules
import nlmaps from '@geo-frontend/nlmaps';

Leaflet, MapLibre GL JS of OpenLayers zullen ook beschikbaar moeten zijn in je webpagina. Een manier om dit voor elkaar te krijgen is om een package te installeren die je kaartbibliotheek wrapt voor Node: dat doe je met npm install -S <package-naam> (bijvoorbeeld, leaflet, maplibre-gl or ol). Je kan je kaartbibliotheek ook natuurlijk als script zetten in het html-bestand waar je app output in terecht komt.

API documentation

nlmaps.createMap(options<object>)

Maakt een kaart met gebruik van Leaflet, waar een BRT-Achtergrondkaartlaag al aan is toegevoegd als achtergrondlaag. De kaart wordt geconfigureerd met een options object met de volgende eigenschappen:

  • target: string (verplicht). De id van div waar de kaart in moet worden gemaakt.
  • center: object (optioneel). Het object met de eigenschappen latitude en longitude om het initiële kaartbeeld in te stellen. De standaardwaarde is het centrum van Nederland.
  • zoom: number (optioneel). Het zoomniveau voor het initiële kaartbeeld. De standaardwaarde is 8.
  • style: string (optioneel). De stijl van de referentiekaart. Gebruik er een van 'standaard', 'pastel', 'grijs' of 'luchtfoto'. De standaardwaarde is 'standaard'.
  • marker: boolean or object (optioneel). Gebruik 'true' of 'false' om in te stellen of er een marker wordt getoond op de locatie van center. De standaardwaarde is 'false'. Om de positie expliciet in te stellen, geef een object met de eigenschappen latitude en longitude.
  • overlay: string (optioneel). Hiermee stel je een kaart in, die over de BRT-Achtergrondkaart of luchtfoto wordt getoond. Gebruik er een van 'adressen', 'drone-no-fly-zones', 'gebouwen', 'gemeenten', 'hoogte', 'land' 'percelen' of 'provincies'.
  • search: boolean (optioneel). Gebruik 'true' of 'false' om in te stellen of er een zoekveld voor plaatsen en adressen wordt getoond. De standaardwaarde is 'false'.

Geeft een map object terug.

Voorbeeld

const opts = {
  style: 'grijs',
  target: 'nlmaps-holder',
  center: {
    longitude: 5.4534,
    latitude: 52.3112
  },
  zoom: 15,
  marker: true,
  overlay: 'gemeenten',
  search: true
};
let map = nlmaps.createMap(opts);

nlmaps.geoLocate(map<map object>, options<object>)

Maakt een geolocator control en voegt deze toe aan de kaart. Een klik op de control initialiseert een verzoek aan de browser geolocation API en centreert de kaart op de resulterende locatie. De geolocator kan ook worden ingesteld om meteen een geolocation verzoek uit te voeren, zonder te wachten tot de gebruiker op de control klikt.

  • map: object map (verplicht). De map waar de geolocator aan moet worden toegevoegd.
  • options object (optioneel). Een object met een toegestane eigenschap: start: true|false. Indien de waarde true is ingesteld, dan wordt meteen een geolocation verzoek uitgevoerd.

Geeft een geolocator object terug. Zie de nlmaps-geolocator package voor meer informatie.

Voorbeeld

const map = nlmaps.createMap();
const geolocator = nlmaps.geoLocate(map, {start: true})

nlmaps.leaflet.bgLayer([style<string>])

Maakt een laag voor Leaflet die tegels opvraagt voor de tegelset style. Als style wordt weggelaten, vraagt het de 'standaard' tegelset op.

Argumenten:

  • style: string (optioneel). Naam van de tegelset die geladen moet worden. Een van 'standaard', 'pastel','grijs' of 'luchtfoto'; standaardwaarde is 'standaard'.

Geeft een layer object terug.

Voorbeeld

const layer = nlmaps.leaflet.bgLayer();
layer.addLayer(map);

nlmaps.leaflet.markerLayer([coords<object>])

Maakt een laag voor Leaflet om een marker op de locatie coords te plaatsen.

Arguments:

  • coords: object (verplicht). Dit object heeft de eigenschappen latitude en longitude om de locatie van de marker in te stellen.

Geeft een layer object terug.

Voorbeeld

const marker = nlmaps.leaflet.markerLayer({
  longitude: 5.4534,
  latitude: 52.3112
});
marker.addTo(map);

nlmaps.leaflet.overlayLayer([overlay<string>])

Maakt een laag voor Leaflet die afbeeldingen opvraagt voor een van de standaard overlay kaarten.

Argumenten:

  • overlay: string (verplicht). Naam van de kaart die geladen moet worden. Gebruik een van 'adressen', 'drone-no-fly-zones', 'gebouwen', 'gemeenten', 'hoogte', 'land''percelen' of 'provincies'.

Geeft een layer object terug.

Voorbeeld

const overlay = nlmaps.leaflet.overlayLayer('gemeenten');

nlmaps.leaflet.overlayLayer([overlay<string>],[endpoint<object>])

Maakt een laag voor Leaflet die afbeeldingen opvraagt voor een aanpasbare overlay Web Mapping Service (WMS). De service moet voldoen aan de OGC WMS specificatie en de Spherical Mercator (EPSG:3857) projectie ondersteunen.

Argumenten:

  • overlay: string (verplicht). Naam van de kaart die geladen moet worden.
  • endpoint: object (verplicht). Dit object heeft de eigenschappen url, layerName en styleName om de Web Mapping Service (WMS) in te stellen.

Geeft een layer object terug.

Voorbeeld

const endpoint = {
  url: 'https://service.pdok.nl/ez/fysischgeografischeregios/wms/v1_0?',
  layerName: 'fysischgeografischeregios',
  styleName: 'fysischgeografischeregios'
};
const overlay = nlmaps.leaflet.overlayLayer('fysisch-geografische-regios', endpoint);
overlay.addTo(map);

nlmaps.leaflet.geoLocatorControl(geolocator)

Maakt een control voor Leaflet die communiceert met de opgegeven geolocator. De control heeft een hele simpele interface: klik om een geolocation verzoek te initialiseren en de kaart op het resultaat te laten centreren. De aangemaakte control moet je zelf toevoegen aan de kaart.

Argumenten:

  • geolocator object geolocator (verplicht). De geolocator waar de control mee verbonden moet worden. Als je deze methode gebuikt, zul je waarschijnlijk de geolocator ook zelf aanmaken met de @geo-frontend/nlmaps-geolocator package.

Geeft een geolocator control terug.

Voorbeeld

import geoLocator from '@geo-frontend/nlmaps-geolocator';
import geoLocatorControl from '@geo-frontend/nlmaps-leaflet';
const geolocator = geoLocator();
const control = geoLocatorControl(geolocator);
control.addTo(map);

Geavanceerd gebruik

Als je al een kaartbibliotheek gebruikt in jouw project, kan je de bgLayer() functie van de betreffende bibliotheek gebruiken om een layer object te maken die je aan je bestaande kaart kunt toevoegen. Daarvoor moet je eerst zelf een kaart maken en het kaartbeeld instellen. Dit is wat createMap onder water doet met wat standaardinstellingen.

Voorbeeld

let map = L.map('map').setView( new L.LatLng(52.20936, 5.970745), 10);
let mylayer = nlmaps.leaflet.bgLayer('grijs').addTo(map);
let marker = nlmaps.leaflet.markerLayer({longitude: 5.5, latitude: 52.5}).addTo(map);

Neem alleen bibliotheek-specifieke functies op

Als je zoveel mogelijk bytes wil besparen, kun je in plaats van de hele nlmaps package de sub-module voor jouw kaartbibliotheek direct toevoegen. Deze module heeft een bgLayer() functie die een laag voor de betreffende bibliotheek teruggeeft, en een geoLocatorControl() functie die een control voor de geolocator maakt.

Web browser:

Download de nlmaps-leaflet.iife.jsrelease. Download de broncode en pak het uit, en selecteer het bestand uit de dist map. Als je deze nu als script laadt in je webpagina, zul je een bgLayer() en geoLocatorControl() functie hebben die werkt met Leaflet.

Node.js:

npm install --save @geo-frontend/nlmaps-ol
//CommonJS
let bgLayer = require('@geo-frontend/nlmaps-ol').bgLayer;
let marker = require('@geo-frontend/nlmaps-ol').markerLayer;

//ES2015
import { bgLayer, markerLayer } from '@geo-frontend/nlmaps-ol';

Deze functies kunnen vervolgens op dezelfde manier worden gebruikt als de functies uit de nlmaps package.

De kaart of kaartlaag verwijderen of bewerken

Als je de kaart of kaartlaag wilt verwijderen of verder bewerken kun je de methodes gebruiken die de kaartbibliotheek beschikbaar stelt. De objecten die worden teruggegeven door createMap() en bgLayer() zijn gewoon map en layer objecten van de betreffende bibliotheken. Bijvoorbeeld: Leaflet heeft een map.remove() functie die de kaart verwijderd en alle event listeners wist.

De geolocator en de geoLocatorControls

Je kunt ook de nlmaps-geolocator package zelf gebruiken, in plaats van deze aan te roepen met nlmaps.geoLocate. Hiermee heb je de mogelijkheid om je eigen control te maken. De sub-packages voor elke kaartbibliotheek bieden elk een control aan die praat met de nlmaps-geolocator API, maar het zijn vrij simpele controls die momenteel met hard-coded css worden gestyled. In de toekomst zal nlmaps misschien ook een los css bestand leveren, maar voor nu kun je, indien je de plaatsing van de control wilt veranderen, beter je eigen css leveren en/of een eigen control maken.

Ruwe tegel URL's

De URL's naar de kaarttegels die nlmaps configureert volgen deze sjablonen:

Voor de BRT-Achtergrondkaart serie:

https://service.pdok.nl/brt/achtergrondkaart/wmts/v2_0/standaard/EPSG:3857/{z}/{x}/{y}.png

Voor de luchtfoto's:

https://service.pdok.nl/hwh/luchtfotorgb/wmts/v10/Actueelortho25/EPSG:3857/{z}/{x}/{y}.jpeg

Ontwikkelen

Zie ook CONTRIBUTING.

Algemene informatie over ontwikkelen

nlmaps is ontwikkeld als monorepo met behulp van Nx and pnpm. De website is gemaakt op basis van Vue.js.

Installatie/configuratie

Om aan nlmaps te werken, installeer je pnpm globaal: 

npm install -g pnpm

Vervolgens installeer je Nx globaal:

pnpm add -g nx

Clone de repository:

git clone git@github.com:geo-frontend/nlmaps.git
cd nlmaps

Installeer de dependencies:

pnpm install

Om de website lokaal te serveren:

npx nx dev @geo-frontend/nlmaps-website

Om de voorbeelden lokaal te serveren:

npx nx dev @geo-frontend/nlmaps-examples

Om de website, voorbeelden en packages te bouwen:

npx nx run-many --target=build --all