From 999ad769a2146dc80689e787d8c7a7b9ba94fd31 Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Fri, 22 Mar 2024 13:32:10 +0800 Subject: [PATCH 1/6] auto-rotate --- docs/api-reference/space/custom-ux.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/api-reference/space/custom-ux.md b/docs/api-reference/space/custom-ux.md index 9ef1c73..543874f 100644 --- a/docs/api-reference/space/custom-ux.md +++ b/docs/api-reference/space/custom-ux.md @@ -74,6 +74,7 @@ space.startViewer({ }, disableCameraControls?: boolean, disableCameraRotation?: boolean, + autoRotate?: boolean, hideNavigationButtons?: boolean }) => void ``` @@ -85,6 +86,7 @@ space.startViewer({ - `cameraPlacement` - _optional_ - set the initial position and direction of the camera. See [camera controls](./custom-ux#camera-controls) for more details. - `disableCameraControls` - _optional_ - set this to true so the camera placement cannot be changed by the user. This disables mouse, touch and keyboard inputs as well as removes the zoom control buttons. _Default value: false_ - `disableCameraRotation` - _optional_ - set this to true to force a top view of the scene. It essentially gets the interactivity to match the 2D mode, but in 3D mode. _Default value: false_ +- `autoRotate` - _optional_ - set this to true to have the viewer spin around the space automatically. You can also start, set the rotation speed, and stop the rotation as described [below](#auto-rotate-the-viewer). _Default value: false_ - `hideNavigationButtons` - _optional_ - set this to true if you want the user to control the camera but want to remove the navigation buttons. Mouse, touch and keyboard inputs will work while the buttons are hidden. _Default value: false_ ## Viewer controls @@ -199,6 +201,22 @@ space.zoomIn() => void space.zoomOut() => void ``` +### Auto-rotate the viewer + +You can get the viewer to spin around the building at a certain speed. To start the rotation: + +```ts +space.startAutoRotation(speed?: number) => void +``` + +- `speed` - _optional_ - sets how fast the rotation goes. _Default value: 0.8_. + +To stop the rotation: + +```ts +space.stopAutoRotation() => void +``` + ## Reacting to events from the viewer You can add event listeners on the viewer to react to interactions happenning in it. The list of event types that can be observed is limited at the moment, and we'll be adding more based on users needs and demand. From 2f3fcf646692ec6ce7cd5343c8c28d79a174a3a0 Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Mon, 1 Apr 2024 12:27:14 +0800 Subject: [PATCH 2/6] ctrl+k to search --- docusaurus.config.js | 4 ++++ static/js/hotkey.js | 11 +++++++++++ 2 files changed, 15 insertions(+) create mode 100644 static/js/hotkey.js diff --git a/docusaurus.config.js b/docusaurus.config.js index be045bb..e3b98c0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -97,6 +97,10 @@ const config = { ], scripts: [ + { + src: '/js/hotkey.js', + async: false + }, process.env.NODE_ENV === 'production' ? { src: 'https://deep-positive.smplrspace.com/script.js', diff --git a/static/js/hotkey.js b/static/js/hotkey.js new file mode 100644 index 0000000..a584664 --- /dev/null +++ b/static/js/hotkey.js @@ -0,0 +1,11 @@ +// Ctrl + K should focus the search bar +document.onkeydown = function (e) { + if (e.ctrlKey && e.key === 'k') { + const search = document.getElementsByClassName('navbar__search-input')[0] + if (search) { + search.focus() + } + // By default, using Ctrl + K in Chrome will open the location bar, so disable this + e.preventDefault() + } +} From 25003cd3c03700af9a672a319ad9ef5d069a262b Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Wed, 3 Apr 2024 17:15:02 +0800 Subject: [PATCH 3/6] startViewer promise --- docs/api-reference/space/space.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/api-reference/space/space.md b/docs/api-reference/space/space.md index bd98062..49d1c00 100644 --- a/docs/api-reference/space/space.md +++ b/docs/api-reference/space/space.md @@ -46,7 +46,7 @@ space.startViewer({ onResize?: (containerRect: DOMRect) => void, onVisibleLevelsChanged?: (visibleLevels: number[]) => void ...customUX: object -}) => void +}) => Promise ``` - `preview` - _optional_ - starts by a preview image with a play button similar to YouTube embed. It is advisable to use [our ESM bundle](/#esm-bundle-supports-runtime-tree-shaking) to ensure a quick initial render. _Default value: false_. @@ -54,12 +54,14 @@ space.startViewer({ - `mode` - _optional_ - lets you choose between 2D and 3D rendering. _Default value: 3d_. - `allowModeChange` - _optional_ - set this to true to allow users to switch between 2D and 3D. _Default value: false_. - `onModeChange` - _optional_ - is called whenever the user changes the mode. Requires allowModeChange to be set to true. -- `onReady` - _optional_ - is called once the viewer's initial render is done. -- `onError` - _optional_ - is called if an error occur while starting the viewer. +- `onReady` - _optional_ - is called once the viewer's initial render is done. You may alternatively use the promise returned by startViewer, which resolves when the viewer is ready. +- `onError` - _optional_ - is called if an error occur while starting the viewer. You may alternatively use the promise returned by startViewer to catch errors. - `onResize` - _optional_ - is called whenever the viewer is resized, including after the initial render, when the window is resized, or on mobile when the device is rotated between vertical to horizontal positions. This can be used to reposition custom tooltips (e.g.). - `onVisibleLevelsChanged` - _optional_ - is called whenever there is a change in the visible levels. This could be through the user clicking the level picker, or through an API call of [`showUpToLevel`](/api-reference/space/custom-ux#navigate-levels). It is also called when the space first renders. The handler take a single argument `visibleLevels`, which is the ordered list of zero-based level indices currently visible in the viewer. The last element in that list is always the highest visible level. - `...customUX` represents additional options that let you customise the user experience as documented in the [custom UX](./custom-ux#viewer-options) page. +Calling `startViewer` returns a `Promise` ([MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)) which resolves when the viewer is ready. This lets you use `Promise.then().catch()` or `async/await` with a `try/catch` block to react when the viewer is ready, or to handle errors that may occur. It is an alternative to providing `onReady` and `onError` callback methods. You may choose the option that suits the most your environment or coding style. + Although not a rule not to break, we generally _recommend_ to use `preview: true` as this avoids loading the space if the user do not intend to interact with it. It also helps with reducing the number of views counted on your spaces. ### Stop the viewer From 32d19498b092528df8a38106a2fad383692e4c96 Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Wed, 3 Apr 2024 22:49:14 +0800 Subject: [PATCH 4/6] setMode docs --- docs/api-reference/space/custom-ux.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/api-reference/space/custom-ux.md b/docs/api-reference/space/custom-ux.md index 543874f..31bad6b 100644 --- a/docs/api-reference/space/custom-ux.md +++ b/docs/api-reference/space/custom-ux.md @@ -101,6 +101,16 @@ space.updateRenderOptions(options: RenderOptions) => 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. +### Switch between 2D and 3D + +To programatically switch between 2D and 3D modes without restarting the viewer, you can call: + +```ts +space.setMode(mode: '2d' | '3d') => void +``` + +- `mode` - the desired rendering mode. + ### Navigate levels This is the programmatic equivalent to pressing the level buttons in the bottom-left controls: From e3eb20fda3a9d84038091bc7222952d6322cf920 Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Thu, 4 Apr 2024 19:12:16 +0800 Subject: [PATCH 5/6] renderingMessage --- docs/api-reference/space/space.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/api-reference/space/space.md b/docs/api-reference/space/space.md index 49d1c00..46eb096 100644 --- a/docs/api-reference/space/space.md +++ b/docs/api-reference/space/space.md @@ -38,6 +38,7 @@ To initiate an interactive viewer session, use the following code. space.startViewer({ preview?: boolean, loadingMessage?: string, + renderingMessage?: string, mode?: '2d' | '3d', allowModeChange?: boolean, onModeChange?: (mode: '2d' | '3d') => void, @@ -51,6 +52,7 @@ space.startViewer({ - `preview` - _optional_ - starts by a preview image with a play button similar to YouTube embed. It is advisable to use [our ESM bundle](/#esm-bundle-supports-runtime-tree-shaking) to ensure a quick initial render. _Default value: false_. - `loadingMessage` - _optional_ - lets you override the text displayed while the space is loading. _Default value: "Loading your space"_. +- `renderingMessage` - _optional_ - lets you override the text displayed when the space is loaded but still rendering. _Default value: same as loadingMessage_. - `mode` - _optional_ - lets you choose between 2D and 3D rendering. _Default value: 3d_. - `allowModeChange` - _optional_ - set this to true to allow users to switch between 2D and 3D. _Default value: false_. - `onModeChange` - _optional_ - is called whenever the user changes the mode. Requires allowModeChange to be set to true. From 8c038a18a3f345637d1580d63c8799896997b2eb Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Fri, 12 Apr 2024 13:55:08 +0800 Subject: [PATCH 6/6] removeAllDataLayers --- docs/api-reference/space/space.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/api-reference/space/space.md b/docs/api-reference/space/space.md index 46eb096..51212f4 100644 --- a/docs/api-reference/space/space.md +++ b/docs/api-reference/space/space.md @@ -168,3 +168,11 @@ space.removeDataLayer(id: string) => void - `id` is the identifier of the layer to remove. An equivalent method is `remove` on a [data layer controller](./data-layers#data-layer-controller). + +### Remove all layers + +Removing all data layers at once is done as follow. + +```ts +space.removeAllDataLayers() => void +```