Deep links (XY integratie): rechtstreeks naar een locatie linken

Een deep link is een projectlink met een locatie erin, en optioneel met wat je daar wilt zien. Zo geeft een ander systeem een plek door aan de viewer, en zo deel je een plek met een collega. Denk aan een melding uit je meldingensysteem, een object uit je beheerpakket of een regel uit een inspectielijst: de link brengt de ontvanger meteen op de juiste plek in beeld.

De viewer leest een deep link één keer, bij het laden van de pagina. Daarna wordt de adresbalk niet meer bijgewerkt. Een link blijft dus zeggen wat de afzender bedoelde, ook als de gebruiker daarna verder navigeert.

https://<host>/tenant/<tenant-uuid>/projects/<project-uuid>?x=93521&y=437865

Positie

• x en y zijn het doelpunt in het coördinaatstelsel van het project zelf: x is de oostwaarde, y de noordwaarde. Voor Nederlandse projecten is dat doorgaans Rijksdriehoek. Beide zijn verplicht. Een link met maar één van de twee, of met een waarde die geen getal is, heeft helemaal geen positie.
• z is de hoogte op dat punt en is optioneel. Die telt op plekken waar opnamen boven elkaar liggen, zoals een viaduct over een straat. Zonder z is de dichtstbijzijnde foto de dichtstbijzijnde in het platte vlak, en dat kan bij zo’n viaduct zowel het onderliggende als het bovenliggende niveau zijn. Met z zoekt de viewer bij voorkeur een foto op ongeveer dezelfde hoogte.

Een link met alleen een positie centreert de kaart op het punt, zoomt in tot een venster van ongeveer 200 meter breed en zet er een paar seconden een markering neer. Er wordt geen foto geopend. Wil je dat wel, vraag er dan om met views.

Views: wat er opengaat

views is een lijst met komma’s van wat er op dat punt geopend moet worden, in de volgorde waarin je de panelen wilt hebben.

?x=93521&y=437865&views=pano,oblique

De viewer toont maximaal twee panelen naast de kaart. De items worden op volgorde geprobeerd en de eerste twee die iets vinden krijgen een paneel. Levert een item op die plek niets op, dan wordt het overgeslagen, krijgt de gebruiker een melding en gaat de viewer door naar het volgende. Een lijst van drie of vier is dus een prima manier om te zeggen: welke van deze hier ook bestaat.

Elk item begint met een van deze woorden, hoofdletters maken niet uit.

Een obliek-, nadir- of luchtfoto opent gericht op het punt en ingezoomd tot ongeveer hetzelfde venster van 200 meter als de kaart, dus niet op de volledige breedte van de foto.

Een item verfijnen

Met @ achter het woord beperk je het item tot een jaar of tot één dataset.

?x=93521&y=437865&views=oblique@2023
?x=93521&y=437865&views=oblique@Vlucht%20noord

Precies vier cijfers achter de @ betekenen een jaartal. Alles anders is een dataset. Die wordt eerst tegen dataset-id’s gelegd en daarna tegen datasetnamen, waarbij hoofdletters niet meetellen. Gebruik het id als de link een hernoeming moet overleven, en de naam als een mens de link leest. Een dataset waarvan de naam zelf uit vier cijfers bestaat, is alleen via het id bereikbaar.

Het woord en de dataset moeten bij elkaar passen. Een link met pano@ en een dataset met schuine luchtfoto’s wordt overgeslagen, met een melding die vertelt wat de dataset werkelijk bevat. Zo opent er nooit stilzwijgend een andere viewer dan de link zegt.

Een jaar en een dataset delen dezelfde plek achter de @, dus een item noemt het een of het ander, nooit allebei. Dat volgt de viewer zelf: die biedt jaren aan als tijdreizen aanstaat en datasets als het uitstaat. In een project met tijdreizen opent een datasetitem als zijn eigen datatype en doet het jaar de verfijning.

De lijst goed schrijven

Codeer elk item apart en plak ze aan elkaar met gewone komma’s. Zo komt een komma in een datasetnaam mee als onderdeel van die naam, in plaats van dat hij het item in tweeën splitst. In JavaScript is dat encodeURIComponent per item.

?views=oblique@Vlucht%20noord%2C%202021,pointcloud

Alleen de eerste @ in een item scheidt het woord van de verfijning. Een latere @ hoort bij de datasetnaam, dus namen met een @ erin vragen geen extra behandeling.

Tijd

Projecten met tijdreizen bevatten meerdere jaren aan data, en een link kan zeggen welk jaar hij bedoelt. Met t zet je het jaar voor de hele link.

?x=93521&y=437865&views=pano&t=2019

Een item dat zijn eigen jaar noemt, gaat voor t. Zo zet je dezelfde plek in twee jaren naast elkaar.

?x=93521&y=437865&views=pano@2019,pano@2023

Een jaar waarvoor het project geen data heeft, valt terug op het meest recente jaar dat wel data heeft. Je krijgt dus geen leeg venster. In een project zonder tijdreizen worden jaartallen genegeerd.

Bookmarks

Met bookmark herstel je een opgeslagen weergave, inclusief de volledige indeling zoals die was toen de bookmark werd gemaakt. Een bookmark gaat voor al het bovenstaande: draagt een link zowel een bookmark als een positie, dan wordt de bookmark hersteld en de positie genegeerd.

Als iets niet klopt

Elk onderdeel van een link staat op zichzelf. Een waarde die de viewer niet kan lezen wordt genegeerd en de rest van de link geldt gewoon. Een verkeerd geschreven jaartal brengt je dus nog steeds op de juiste plek. Items die niets opleveren worden overgeslagen, met een korte melding over wat er ontbrak.

Voorbeelden

Let op bij oudere links

Links die vóór deze opzet zijn gemaakt gebruikten alleen x en y, en openden automatisch het dichtstbijzijnde panorama. Die links centreren nu alleen de kaart. Voeg views=pano toe om precies het oude gedrag terug te krijgen.