From 752a12ce73d3918b0e5a867a3082444333047a61 Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Mon, 11 Nov 2024 11:30:20 +0300 Subject: [PATCH 1/3] map camera placement --- docs/api-reference/map/custom-ux.md | 58 +++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/api-reference/map/custom-ux.md diff --git a/docs/api-reference/map/custom-ux.md b/docs/api-reference/map/custom-ux.md new file mode 100644 index 0000000..86790ec --- /dev/null +++ b/docs/api-reference/map/custom-ux.md @@ -0,0 +1,58 @@ +--- +sidebar_position: 3 +--- + +# Custom UX + +Smplr.js provides a few options that help you customize the map experience to your requirements. We're regularly adding new options, so [reach out](https://www.smplrspace.com/support) and share what you'd like to do with it. + +## Adapting the look & feel and experience + +### Render options + +## Viewer controls + +### Get the camera placement + +`map.setCameraPlacement` lets you position the camera. You would typically embed the map viewer and have an interface to retrieve one or more placement(s) to be stored in your database. You can then load any placement object from your database to set the initial value. The camera placement can be retrieved with the following function: + +```ts +map.getCameraPlacement() => ({ + pitch: number + bearing: number + zoom: number + center: { + lng: number + lat: number + } +}) +``` + +The "placement" is a Javascript object that includes the position and direction of the camera. It is defined as an orbit position (pitch, bearing, zoom) around a center point which the camera points towards. It is fully compatible with the [native Mapbox camera values](https://docs.mapbox.com/android/maps/guides/camera-and-animation/camera/). + +- `pitch` is the angle given in degrees of the camera's position in the vertical plane. `0` corresponds to a top down view, while `90` corresponds to a view from the ground. +- `bearing` is the angle given in degrees of the camera's position in the horizontal plane. `0` faces North, `90` faces East, and `-90` or `270` faces West. +- `zoom` represents the distance to the center point. It has a value between `0` and `22`, with `0` showing the whole Earth, and `15` showing buildings. +- `center` contains the GPS coordinates of the center point in `{ lat, lng }` format. + +### Set the camera placement + +You can move the camera to a specific position and have it target a specific point as well by calling the following function: + +```ts +map.setCameraPlacement({ + pitch?: number, + bearing?: number, + zoom?: number, + center?: { + lng: number + lat: number + }, + animate?: boolean, + speed?: number +}) => void +``` + +- placement parameters (see description above) are the new desired value. All parameters are _optional_ and the ones that are not provided will keep their current value. +- `animate` - _optional_ - should be set to false to jump to the new placement and true to animate the camera to the new placement. _Default value: false_ +- `speed` - _optional_ - defines the speed of the camera animation and should be used with animate set to true. _Default value: 1.2_ \ No newline at end of file From ee0043aff1516bc0ff8495f852d96984dfc4617d Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Mon, 11 Nov 2024 11:41:43 +0300 Subject: [PATCH 2/3] map render options --- docs/api-reference/map/custom-ux.md | 30 +++++++++++++++++++++++++++ docs/api-reference/space/custom-ux.md | 10 ++++----- 2 files changed, 35 insertions(+), 5 deletions(-) diff --git a/docs/api-reference/map/custom-ux.md b/docs/api-reference/map/custom-ux.md index 86790ec..57bbb10 100644 --- a/docs/api-reference/map/custom-ux.md +++ b/docs/api-reference/map/custom-ux.md @@ -10,8 +10,38 @@ Smplr.js provides a few options that help you customize the map experience to yo ### Render options +To customize how the map viewer renders the spaces, you can pass in a number of options to the rendering engine. Below are the options currently exposed. Render options can be updated dynamically as described [further](#update-render-options-dynamically). + +```ts +interface MapSpaceRenderOptions { + footprint?: { + render?: boolean + color?: string + } + walls?: { + render?: boolean + } + grounds?: { + render?: boolean + } + windows?: { + render?: boolean + } +} +``` + ## Viewer controls +### Update render options dynamically + +Render options are described in details in [Render options](#render-options). You can update them dynamically with the method below: + +```ts +map.updateRenderOptions(options: MapSpaceRenderOptions) => void +``` + +- `options` is an object of the [`MapSpaceRenderOptions`](#render-options) interface, which is deeply merged with the current options used by the viewer. To "unset" an optional value, you can pass `undefined` explicitely. + ### Get the camera placement `map.setCameraPlacement` lets you position the camera. You would typically embed the map viewer and have an interface to retrieve one or more placement(s) to be stored in your database. You can then load any placement object from your database to set the initial value. The camera placement can be retrieved with the following function: diff --git a/docs/api-reference/space/custom-ux.md b/docs/api-reference/space/custom-ux.md index a728ef1..8571caf 100644 --- a/docs/api-reference/space/custom-ux.md +++ b/docs/api-reference/space/custom-ux.md @@ -10,10 +10,10 @@ Smplr.js provides a few options that help you customize the floor plan experienc ### Render options -To customize how the viewer renders the space, you can pass in a number of options to the rendering engine. Below are the options currently exposed. Render options should be passed through `startViewer` as described [right below](#viewer-options), or updated dynamically as described [further](#update-render-options-dynamically). +To customize how the space viewer renders the space, you can pass in a number of options to the rendering engine. Below are the options currently exposed. Render options should be passed through `startViewer` as described [right below](#viewer-options), or updated dynamically as described [further](#update-render-options-dynamically). ```ts -interface RenderOptions { +interface SpaceRenderOptions { backgroundColor?: string; grounds?: { render?: boolean; @@ -63,7 +63,7 @@ You can set a number of options when starting the viewer. They are listed below ```ts space.startViewer({ // ...basicControls - renderOptions?: RenderOptions, + renderOptions?: SpaceRenderOptions, topShownLevel?: number, includeLevels?: number[], cameraPlacement?: { @@ -104,10 +104,10 @@ space.startViewer({ Render options are described in details in [Render options](#render-options). They can be set when the viewer starts, but if you need to update them dynamically, you should use the method below: ```ts -space.updateRenderOptions(options: RenderOptions) => void +space.updateRenderOptions(options: SpaceRenderOptions) => void ``` -- `options` is an object of the [`RenderOptions`](#render-options) interface, which is deeply merged with the current options used by the viewer. To "unset" an optional value, you can pass `undefined` explicitely. +- `options` is an object of the [`SpaceRenderOptions`](#render-options) interface, which is deeply merged with the current options used by the viewer. To "unset" an optional value, you can pass `undefined` explicitely. ### Switch between 2D and 3D From 87e7e48415f02a6fe1478313f0ed669cf372fdf9 Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Mon, 11 Nov 2024 11:46:09 +0300 Subject: [PATCH 3/3] map level controls --- docs/api-reference/map/custom-ux.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/api-reference/map/custom-ux.md b/docs/api-reference/map/custom-ux.md index 57bbb10..2660496 100644 --- a/docs/api-reference/map/custom-ux.md +++ b/docs/api-reference/map/custom-ux.md @@ -42,6 +42,24 @@ map.updateRenderOptions(options: MapSpaceRenderOptions) => void - `options` is an object of the [`MapSpaceRenderOptions`](#render-options) interface, which is deeply merged with the current options used by the viewer. To "unset" an optional value, you can pass `undefined` explicitely. +### Navigate levels + +To programmatically choose which levels are visible on the map, you may use the following functions: + +```ts +map.showUpToLevel(levelIndex: number) => void +``` + +- `levelIndex` - zero-based index of the top level you want to see. For example, setting `levelIndex` to `2` is equivalent to pressing the `L3` button in the space viewer. + +You can also reset the viewer back to showing all the levels with: + +```ts +map.showAllLevels() => void +``` + +## Camera controls + ### Get the camera placement `map.setCameraPlacement` lets you position the camera. You would typically embed the map viewer and have an interface to retrieve one or more placement(s) to be stored in your database. You can then load any placement object from your database to set the initial value. The camera placement can be retrieved with the following function: