📚API References

The Jakartowns JavaScript API enables integration of the Jakartowns digital twin into third-party web applications. The JavaScript script contains the API’s code, including all its functions and methods to manipulate the digital twin.

The API facilitates interaction with the digital twin by providing methods to set the position, rotation, tilt, field of view, and displayed panoramic image.

The API is applied to an HTML container within the web application page.

Once the API is retrieved, the create_jakartowns function is available to create an instance of the Jakartowns digital twin in a specific container on the web page.

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

This function is responsible for creating the Jakartowns digital twin in the specified container, with the given configuration options, and executes the callback function once the digital twin is ready for use. This allows developers to interact with the digital twin and customize its behavior according to specific needs.

Here’s a detailed explanation of each parameter of this function:

1. '#app': This is the CSS selector of the HTML element where you want to display the digital twin. In this case, the element with the ID "app" will be used as the container for the digital twin.

2. options: This is a JavaScript object containing configuration options for the digital twin. These options control whether the digital twin’s header and mini-map are enabled or disabled.

3. callback: This is a callback function that is called once the digital twin instance is created and ready for use. The callback function can be defined as an anonymous function (arrow function) that takes a viewer parameter. The viewer parameter corresponds to the created digital twin instance. You can use this instance to perform specific actions and operations on the digital twin, such as adding listeners for position, rotation, tilt, and FOV update events.

Functions to Interact with the Digital Twin

The following functions are available on the viewer instance returned in the create_jakartowns callback.

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

Sets the digital twin view position on the map using the specified latitude and longitude coordinates.

This function returns a promise resolved with an object containing:

• uid: the technical identifier of the selected image

• distance: the distance between the requested position and the selected panoramic image

• nearest: the GeoJSON feature representing the selected panoramic image

• features: the list of panorama candidates returned by the search

Available options:

• keepPreviousAngles: keeps the current orientation if set to true during the transition (default: false)

• observerShift: moves forward or backward in the trajectory with { direction: 'forward' | 'backward', steps: number }

• dateFilter: filters images by date, for example { date: '2024-05-21' }

• maxDistance: maximum search distance, in meters

Example:

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)

Displays a specific panoramic image directly from its technical uid.

This method is especially useful when multiple acquisitions are available at the same location and you want to let the user choose which image to display, for example based on capture date.

viewer.setTilt(wantedTilt)

Sets the vertical tilt of the digital twin view using the specified value. This function returns the new tilt.

viewer.setPan(wantedPan)

Sets the horizontal rotation of the digital twin view using the specified value. This function returns the new rotation.

viewer.setFov(wantedFov)

Sets the field of view (FOV) of the digital twin view using the specified value. This function returns the new FOV value.

viewer.setMarkers(geojsonDisplay)

Displays markers in the viewer from a GeoJSON object. This method is useful for projecting points of interest from your own application into the panoramic image.

Choose an Image by Date

When multiple panoramic images exist for the same location, the API allows you to build an image selector in your application.

The workflow is as follows:

1. your application listens to the position event

2. the event exposes the current image and the list of available images at that location

3. you render those options in a dropdown

4. when the user selects another image, you call viewer.setImage(uid)

Example with 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)
		})
	},
)

If you already know the target date when positioning the viewer, you can also request it directly with viewer.setPosition() through the dateFilter option.

Events

position

This event is triggered when the user changes position in the digital twin. It provides, among other things:

• uid: the technical identifier of the displayed image

• latitude and longitude: the coordinates of the current position

• currentSphereInfo: the metadata of the currently displayed image

• multipassAtLocation: the list of images available at this location, useful for building a selector by date or image identifier

rotation

This event is triggered when the user changes the horizontal rotation of the digital twin’s view. It provides the new rotation value.

tilt

This event is triggered when the user changes the vertical tilt of the digital twin’s view. It provides the new tilt value.

fov

This event is triggered when the user changes the field of view (FOV) of the digital twin’s view. It provides the new FOV value.