📚Référence de l'API

L'API JavaScript de Jakartowns permet d'intégrer le jumeau numérique Jakartowns dans des applications web tierces. Le script JavaScript contient le code informatique de l'API avec toutes ses fonctions et méthodes pour manipuler le jumeau numérique.

L'API facilite ainsi l'interaction avec le jumeau numérique en fournissant des méthodes pour définir la position, la rotation, le tilt, le champ de vision de la vue, ainsi que l'image panoramique affichée.

L'API s'applique sur un conteneur HTML de la page web applicative.

Une fois l'API récupérée, la fonction create_jakartowns est disponible pour créer une instance du jumeau numérique Jakartowns dans un conteneur spécifique sur la page web.

window.jakartowns.app.create_jakartowns('#app', options, callback)

Cette fonction est responsable de créer le jumeau numérique Jakartowns dans le conteneur spécifié, avec les options de configuration spécifiées, et exécute la fonction de rappel une fois que le jumeau numérique est prêt à être utilisé. Cela permet aux développeurs d'interagir avec le jumeau numérique et de personnaliser son comportement en fonction de leurs besoins spécifiques. \

Voici une explication détaillée de chaque paramètre de cette fonction :

1. '#app': C'est le sélecteur CSS de l'élément sur la page HTML où vous souhaitez afficher le jumeau numérique. Dans ce cas, l'élément avec l'ID "app" sera utilisé comme conteneur pour le jumeau numérique.

2. options: C'est un objet JavaScript contenant les options de configuration pour le jumeau numérique. Ces options permettent de contrôler si l'en-tête et la mini-carte du jumeau numérique sont activés ou désactivés.

3. callback: C'est une fonction de rappel (callback) qui est appelée une fois que l'instance du jumeau numérique est créée et prête à être utilisée. Cette fonction de rappel peut être définie comme une fonction anonyme (arrow function) qui prend un paramètre viewer. Ce paramètre viewer correspond à l'instance du jumeau numérique créée. Vous pouvez utiliser cette instance pour effectuer des actions et des opérations spécifiques sur le jumeau numérique, par exemple, ajouter des écouteurs pour les événements de mise à jour de position, rotation, tilt et fov.

Fonctions pour interagir avec le jumeau numérique

Les fonctions suivantes sont disponibles sur l'instance viewer renvoyée dans le callback de create_jakartowns.

viewer.setPosition({ latitude, longitude }, options)

Définit la position de la vue du jumeau numérique sur la carte en utilisant les coordonnées de latitude et de longitude spécifiées.

Cette fonction renvoie une promesse résolue avec un objet contenant :

• uid : l'identifiant technique de l'image sélectionnée

• distance : la distance entre la position demandée et l'image panoramique sélectionnée

• nearest : l'entité GeoJSON représentant l'image panoramique retenue

• features : la liste des panoramas candidats retournés par la recherche

Options disponibles :

• keepPreviousAngles : conserve l'orientation actuelle si la valeur est true pendant la transition (default: false)

• observerShift : permet d'avancer ou reculer dans la trajectoire avec { direction: 'forward' | 'backward', steps: number }

• dateFilter : permet de filtrer les images par date, par exemple { date: '2024-05-21' }

• maxDistance : distance maximale de recherche, en mètres

Exemple :

const result = await viewer.setPosition(
	{ latitude: 45.5017, longitude: -73.5673 },
	{
		keepPreviousAngles: true,
		dateFilter: { date: '2024-05-21' },
		maxDistance: 25,
	},
)

console.log(result.uid)

viewer.setImage(uid)

Affiche directement une image panoramique donnée à partir de son identifiant technique uid.

Cette méthode est particulièrement utile lorsque plusieurs acquisitions sont disponibles à une même position et que vous souhaitez laisser l'utilisateur choisir l'image à afficher, par exemple selon sa date de prise de vue.

viewer.setTilt(wantedTilt)

Définit l'inclinaison verticale de la vue du jumeau numérique en utilisant la valeur spécifiée. Cette fonction renvoie la nouvelle inclinaison.

viewer.setPan(wantedPan)

Définit la rotation horizontale de la vue du jumeau numérique en utilisant la valeur spécifiée. Cette fonction renvoie la nouvelle rotation.

viewer.setFov(wantedFov)

Définit le champ de vision (FOV) de la vue du jumeau numérique en utilisant la valeur spécifiée. Cette fonction renvoie la nouvelle valeur de FOV.

viewer.setMarkers(geojsonDisplay)

Affiche des marqueurs dans le viewer à partir d'un objet GeoJSON. Cette méthode est utile pour projeter dans l'image panoramique des points d'intérêt issus de votre propre application.

Choisir une image par date

Lorsqu'il existe plusieurs images panoramiques pour une même position, l'API permet de construire un sélecteur d'images côté application.

Le principe est le suivant :

1. votre application écoute l'événement position

2. l'événement expose l'image courante et la liste des images disponibles à cet endroit

3. vous affichez ces options dans une liste déroulante

4. lorsque l'utilisateur sélectionne une autre image, vous appelez viewer.setImage(uid)

Exemple avec Vue 3 :

import { ref, watch } from 'vue'

const currentImageId = ref(null)
const availableImages = ref([])

window.jakartowns.app.create_jakartowns(
	'#detail-panel__jakartowns__app',
	jakartownsOptions,
	(viewer) => {
		window.jakartowns_instance = viewer

		window.addEventListener('position', (event) => {
			availableImages.value = (event.detail.multipassAtLocation || []).map(
				({ properties: { image_id: imageUid, date } }) => ({
					imageUid,
					date,
				}),
			)

			currentImageId.value =
				event.detail.currentSphereInfo?.properties?.image_id || null
		})

		watch(currentImageId, (newImageId) => {
			if (!newImageId) return
			window.jakartowns_instance.setImage(newImageId)
		})
	},
)

Si vous connaissez déjà la date cible au moment du positionnement, vous pouvez aussi la demander directement avec viewer.setPosition() via l'option dateFilter.

Événements

position

Cet événement est déclenché lorsque l'utilisateur change de position dans le jumeau numérique. Il fournit notamment :

• uid : l'identifiant technique de l'image affichée

• latitude et longitude : les coordonnées de la position courante

• currentSphereInfo : les métadonnées de l'image actuellement affichée

• multipassAtLocation : la liste des images disponibles à cette position, utile pour construire un sélecteur par date ou par identifiant d'image

rotation

Cet événement est déclenché lorsque l'utilisateur change la rotation horizontale de la vue du jumeau numérique. Il fournit la nouvelle valeur de rotation.

tilt

Cet événement est déclenché lorsque l'utilisateur change l'inclinaison verticale de la vue du jumeau numérique. Il fournit la nouvelle valeur d'inclinaison.

fov

Cet événement est déclenché lorsque l'utilisateur change le champ de vision (FOV) de la vue du jumeau numérique. Il fournit la nouvelle valeur de FOV.