GIS-koppeling en plugins: de GEORIZON viewer integreren met de Viewer API

Met de Viewer API stuurt een GIS-toepassing, plugin of eigen webapplicatie de GEORIZON viewer aan en hoort ze terug wat de gebruiker doet. Denk aan een plugin voor een GIS-pakket, een webkaart (bijvoorbeeld op basis van OpenLayers), een desktopprogramma of een beheersysteem. De toepassing opent foto's op een plek, legt eigen objecten over elke weergave en laat de gebruiker meten. De viewer meldt terug wat er gemeten wordt, waar de cursor staat, waar elke weergave naar kijkt en waar foto's zijn genomen, zodat je dat op je eigen kaart kunt tekenen.

Wil je de viewer insluiten (embedden) in je eigen webpagina, portaal of plugin? Dat kan met de webcomponent of de koppeling via postMessage en WebSocket, zoals hieronder beschreven.

Dit artikel is de Nederlandse inleiding. Het volledige protocol, het JSON Schema en een werkend voorbeeld staan op argos.georizon.cloud/docs.

Welke koppeling kies je?

• Deep link. Je opent de viewer op een plek, zonder dat je iets terughoort. Zie het artikel Deep links vanuit een GIS-viewer koppelen.
• Viewer API. Tweerichtingsverkeer tussen je toepassing en de viewer. Dit artikel.
• OGC API en bestands-API. Data uit Georizon ophalen in je eigen software. Zie Georizon OGC API.
• MCP. Georizon koppelen aan een AI-assistent. Zie Georizon koppelen aan een AI-assistent (MCP).

Begrippen

• Host. Jouw toepassing, bijvoorbeeld de GIS-software of plugin.
• Viewer. Eén GEORIZON viewer (een tabblad of frame) met één project geladen.
• Sessie. De verbinding tussen host en viewer. Die duurt tot een van beide haar sluit of de viewer verdwijnt.

Kies hoe je de viewer toont

De berichten zijn in alle drie de gevallen hetzelfde. Houd één viewer open en stuur die met view.goTo naar elke nieuwe plek, in plaats van de viewer voor elk adres opnieuw te openen.

• Webcomponent. Voor een webpagina waarin de viewer naast je eigen kaart staat. Je plaatst een argos-viewer element in de pagina.
• Eigen browsertabblad. Je pagina opent de viewer met window.open en praat ermee via postMessage.
• WebSocket. Voor een desktopprogramma of plugin. Je programma luistert op de eigen computer van de gebruiker en opent de viewer in de browser, met het adres van de WebSocket in de link.

Alle drie werken in Chrome, Edge, Firefox en Safari en vragen niets van je eigen site.

Projectadres en token

Elke koppeling begint met het adres van het project in de viewer: https://argos.georizon.cloud/<tenant>/<projectid>.

• Openbaar project. Geen token nodig.
• Niet-openbaar project. Je hebt een projecttoegangstoken nodig, aan te maken in Georizon. De viewer werkt dan alleen met dat token en nooit met het account van de gebruiker. Je toepassing bereikt dus precies wat het token toestaat.
• Veiligheid van het token. Iedereen die kan zien hoe je toepassing de viewer opent, kan het token lezen. Gebruik daarom een alleen-lezen token dat je los kunt intrekken.

Waar de viewer begint

De viewer kan direct op een plek openen, met weergaven al open. Dezelfde parameters werken voor alle drie de manieren. Alles is optioneel.

• x, y. Waarheen, in het coördinatenstelsel van het project.
• z. De hoogte, om te kiezen tussen foto's die boven elkaar zijn genomen.
• views. Wat er opengaat, gescheiden door komma's: pano, oblique, nadir, aerial, pointcloud of mesh. Met @ erachter beperk je een item tot een periode (oblique@2023) of tot een dataset via het id.
• t. De periode, voor een project met tijdreizen.
• lang. De taal van de interface: en (Engels) of nl (Nederlands). Die geldt voor dit bezoek en laat de eigen taalkeuze van de gebruiker staan.

Zonder plek start de viewer waar het project start. Zie Deep links (XY integratie) voor de uitleg per parameter.

Veelgestelde vragen over insluiten (embed) en integratie

• Kan ik de viewer insluiten (embedden) in mijn eigen website of portaal? Ja. Laad de webcomponent met één script en plaats het element argos-viewer in je pagina. De viewer staat dan ingebed naast je eigen kaart en je stuurt hem aan met JavaScript.
• Werkt een iframe? Nee. De viewer weigert om veiligheidsredenen in een gewoon iframe te worden geladen. Gebruik de webcomponent om de viewer in een pagina te integreren.
• Kan ik de viewer koppelen aan mijn eigen plugin of GIS-software? Ja, elke plugin, webkaart (bijvoorbeeld OpenLayers) of desktoptoepassing die JavaScript, postMessage of een WebSocket kan gebruiken, kan de viewer aansturen.
• Is er een SDK of bibliotheek? De webcomponent is beschikbaar op npm als @georizon/argos-viewer, met TypeScript-types. Het volledige protocol is beschreven in een JSON Schema.
• Hoe open ik de viewer op een locatie vanuit mijn eigen applicatie? Met view.goTo, of met een deep link als je geen antwoord van de viewer nodig hebt.

Voorbeeld: de webcomponent

<script type="module" src="https://argos.georizon.cloud/argos-viewer.js"></script>

<argos-viewer
  src="https://argos.georizon.cloud/360geo/019afd05-e413-70c9-bac8-cc7ab4be4722"
  host-name="Mijn GIS"
  subscribe="view,measurements"
  style="width: 650px; height: 450px">
</argos-viewer>

<script type="module">
  const viewer = document.querySelector("argos-viewer");
  // Open een panorama op de plek waar de gebruiker klikte.
  viewer.goTo({ position: [136450, 455390], views: ["pano"] });
  // Luister naar elke meting van de gebruiker.
  viewer.addEventListener("measurement-created", (e) => console.log(e.detail.measurement));
</script>

De webcomponent is ook beschikbaar op npm als @georizon/argos-viewer, met TypeScript-types. Het element is bedoeld voor afmetingen vanaf circa 650 bij 450 pixels. In een kleiner element toont de viewer één weergave tegelijk met een schakelaar. Met het attribuut map toont de viewer ook zijn eigen kaart, voor een pagina zonder eigen kaart.

Wat je kunt sturen

• Navigeren. view.goTo gaat naar een plek en opent weergaven. view.lookAt draait de geopende foto's naar een positie. photo.open opent één foto uit je eigen lijst.
• Foto's opvragen. photos.query geeft de fotoposities binnen een rechthoek, zodat je ze op je eigen kaart tekent. Je ziet alleen wat het token toestaat.
• Lagen. layer.create, layer.update, layer.remove en de bijbehorende functies voor objecten.
• Meten. measure.setPolicy, measure.start en measure.stop.
• Instellingen en interface. settings.update, ui.setInteractive om de viewer tijdelijk te vergrendelen en ui.notify voor een korte melding.

Wat de viewer terugmeldt

• view.changed en view.closed. Waar elke weergave naar kijkt, met camera, foto en voetafdruk op de grond.
• cursor.moved. De positie van de cursor in de wereld, met de manier waarop de hoogte is bepaald.
• measurement.created, updated en deleted. Elke meting die de gebruiker maakt, wijzigt of verwijdert, met per punt de methode en de standaardafwijking.
• measure.changed. Wanneer het meetgereedschap aan of uit gaat.
• project.changed. Het project is gewijzigd, bijvoorbeeld door een nieuwe dataset.

Je kiest zelf waarop je je abonneert: view, cursor en measurements. Meldingen waar je niet om vraagt, krijg je niet.

Eigen objecten over de weergaven leggen

Een laag is een benoemde set objecten van je toepassing, getekend in elke weergave en door de gebruiker per weergave aan en uit te zetten. De viewer tekent ze, wijzigt ze nooit en stuurt ze niet terug.

• Push-laag. Je stuurt de objecten zelf. Geschikt voor kleine sets, zoals de objecten van één werkorder.
• Pull-laag. De viewer vraagt objecten op per gebied terwijl de gebruiker beweegt, in een vast raster van 100 meter. Geschikt voor grote bestanden zoals de volledige BGT.
• Stijl. Lijnkleur, vulling, puntkleur en lijndikte, eventueel per waarde van een eigenschap.
• Formaat. Objecten zijn JSON-FG, een uitbreiding van GeoJSON. Projecteer je coördinaten naar het projectstelsel of geef het stelsel van de laag op. Houd een bericht onder 1 MB.

Meten in je eigen toepassing

Met measure.setPolicy bepaal je welke metingen de gebruiker mag doen en hoe een punt gemeten mag worden. Een host die zelf lijnen en vlakken opbouwt, staat alleen punten toe en ontvangt elk punt zodra het gemeten is. Met keep bepaal je of metingen ook in de eigen lijst van de viewer blijven. Met sidebar verberg je de meetzijbalk als je zelf alle meetgereedschap aanbiedt. Wil je alleen nauwkeurige punten, dan beperk je de methoden, bijvoorbeeld tot voorwaartse insnijding.

Coördinaten, hoeken en tijd

• Coördinaten. Altijd in het stelsel van het project, met X naar het oosten, Y naar het noorden en Z omhoog in meters. Een positie zonder Z komt op het maaiveld te liggen.
• Richting. Een kompasrichting ten opzichte van het gridnoorden, met de klok mee: 0 is noord, 90 oost, 180 zuid en 270 west. Hoeken zijn in graden. Het gridnoorden wijkt licht af van het ware noorden.
• Tijd. Tijdstippen zijn RFC 3339 in UTC. Een periode is een label dat je van de viewer krijgt, vandaag een jaartal. Vergelijk het als tekst en ga er niet van uit dat het altijd een jaar is.

Beveiliging

• De viewer praat alleen met de host waarnaar hij verwezen is: de pagina die het tabblad opende, de pagina met de webcomponent of de WebSocket uit de link.
• Een WebSocket in de link moet op dezelfde computer draaien (127.0.0.1, [::1] of localhost). Elke andere bestemming wordt geweigerd.
• Een host die zelf luistert, accepteert een verbinding alleen als de Origin-header een Argos-origin is en een geheim in de link klopt. Elke webpagina kan namelijk proberen een poort op de computer van de gebruiker te bereiken.
• Chrome en Edge vragen de gebruiker eenmalig of een site met zijn eigen computer mag verbinden. Beheerde computers kunnen dat vooraf toestaan met het beleid LocalNetworkAccessAllowedForUrls.

Goed om te weten

• Elke start begint opnieuw. Na een herlaad van de viewer, je pagina of een verbroken verbinding stuurt de viewer een nieuwe handshake (session.hello). Stuur je lagen en meetbeleid daarna opnieuw.
• Geen korte time-outs. Sommige antwoorden wachten op het netwerk of op de gebruiker.
• Maximaal twee panelen. De viewer toont maximaal twee panelen naast de kaart. Ga er niet van uit dat een nieuwe weergave altijd past.
• Een browsertabblad kan zichzelf niet naar voren halen. Na een opdracht moet de gebruiker zelf naar het tabblad schakelen.
• Versies. Een nieuwere viewer blijft met een oudere host werken. Onbekende waarden lees je als onbekend, niet als fout.

Documentatie en voorbeeld

• Documentatie van de Viewer API: het protocol, alle berichten en foutcodes.
• Voorbeeld: de viewer naast een OpenLayers-kaart in één HTML-bestand dat je kunt kopiëren en uitproberen.
• JSON Schema van het protocol, te downloaden van de documentatiepagina, om getypte code te genereren.
• Vragen over een integratie of een plugin? Gebruik Stel een vraag of geef feedback.