Merge pull request #66 from smplrspace/next

v2.18.0

docs/api-reference/color/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Color",
-  "position": 3
+  "position": 4
 }

docs/api-reference/map/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Map",
+  "position": 2
+}

docs/api-reference/map/buildings.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 2
+sidebar_label: Buildings
+---
+
+# Buildings on the map
+
+One of the main added "layer" the Smplrspace map viewer provides, as compared to just Mapbox is the ability to render 3D spaces from your Smplrspace data, and 3D cities based on OpenStreetMap data in a few lines of code. Here are the functions currently available.
+
+## Spaces from Smplrspace
+
+### Add spaces by ID
+
+To fetch spaces from your Smplrspace account and render them on the map, call the following method. Note that the spaces need to be georeferenced within the platform.
+
+```ts
+map.addSpacesById(spaceIds: string[]) => void
+```
+
+- `spaceIds` - unique identifiers of the spaces in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+
+### Remove spaces by ID
+
+To remove specific spaces from the map, call this function:
+
+```ts
+map.removeSpacesById(spaceIds: string[]) => void
+```
+
+- `spaceIds` - unique identifiers of the spaces in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+
+### Remove all spaces
+
+To remove all spaces from the map, call this function:
+
+```ts
+map.removeAllSpaces() => void
+```
+
+## 3D cities
+
+### Control OSM layer
+
+To control whether to render the 3D cities based on OpenStreetMap data or not, use the following methods:
+
+```ts
+map.showOsmBuildings() => void
+map.hideOsmBuildings() => void
+map.toggleOsmBuildings() => void
+```

docs/api-reference/map/map.md

@@ -0,0 +1,116 @@
+---
+sidebar_label: Overview
+slug: overview
+sidebar_position: 1
+---
+
+# Embedding the map viewer
+
+Smplr.js makes a `smplr` object available on the global scope. One of the classes provided under this object is the `Map` class. It provides the API necessary to render the Smplrspace map viewer, a custom pre-configured Mapbox-based map which provide all the feature of Mapbox, plus Smplrspace specific features to render your spaces, add 3D cities based on OpenStreetMap data, add data layers, and more.
+
+## Constructor
+
+To create a Map instance, initialise it as follow.
+
+```ts
+const map = new smplr.Map({
+  clientToken: string,
+  containerId: string,
+  disableErrorReporting?: boolean,
+}) => Map
+```
+
+- `clientToken` is an API token that is used to authenticate client-side requests. It is safe to have it exposed in your client code. You can manage your organisation's tokens in the Smplrspace app, by heading to the Developers page from the main menu. [More info](/guides/embedding#client-tokens).
+- `containerId` is the "id" of the html "div" container where smplr.js should render the viewer, something like "smplr-container" that can be found in your html. Only ids are supported, not classes.
+- `disableErrorReporting` - _optional_ - can be set to "true" to disable the automated reporting of errors to our 3rd party error tracking tool, [Sentry](https://sentry.io/). We have discovered that Sentry's instrumentation could make it seem as if all network requests originated from smplr.js. Unfortunately, there is nothing simple we can do on our side to avoid that. If this is an issue for you, you can disable Sentry altogether. The tradeoff is that we will not automatically detect errors hapenning in your integration, and you may need to be more proactive to report them for us to roll out fixes.
+
+## Interactive map viewer session
+
+### Start the viewer
+
+To initiate an interactive viewer session, use the following code.
+
+```ts
+map.startViewer({
+  spaceIds?: string[]
+  osmBuildings?: boolean
+  hash?: boolean
+  fitNewSpacesInScreen?: boolean
+  loadingMessage?: string
+  forceLoader?: boolean
+  onReady?: () => void
+  onError?: (errorMessage: string) => void
+  onSpaceClick?: ({ space, levelIndex }: { space: object | undefined; levelIndex: number }) => void
+}) => Promise<void>
+```
+
+- `spaceIds` - _optional_ - lets you specify the Smplrspace ID of the spaces to render on the map when initializing the viewer. You can also do that dynamically as described on the [Building page](/api-reference/map/buildings).
+- `osmBuildings` - _optional_ - lets you choose whether to render or not cities in 3D. City buildings data comes from OpenStreetMap and is automatically rendered in 3D. You can also do that dynamically as described in [3D cities](/api-reference/map/buildings#3d-cities). _Default value: true_.
+- `hash` - _optional_ - lets you choose whether to automatically sync the map location to the hash fragment of the page's URL. This makes it for easy to share links to specific map locations. It relies on Mapbox's corresponding [parameter](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters). _Default value: false_.
+- `fitNewSpacesInScreen` - _optional_ - lets you choose whether to automatically recenter the map to fit all the spaces when the spaces rendered on the map change. You can also center the map using [`fitAllSpacesInScreen`](#fit-all-spaces-in-screen). \_Default value: true.
+- `loadingMessage` - _optional_ - lets you override the text displayed while the space is loading. This can be change dynamically as well, see [UI controls](#ui-controls). _Default value: "Loading map"_.
+- `forceLoader` - _optional_ - provides programmatic control to whether the loader should be displayed or not. By default we display it while loading the map and initial spaces provided by `spaceIds`, but you can control this if you load your own data as well. This can be change dynamically as well, see [UI controls](#ui-controls). \_Default value: false.
+- `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.
+- `onSpaceClick` - _optional_ - is called when the user clicks a 3D space, and provide data about which space and which level where clicked.
+
+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.
+
+### Stop the viewer
+
+To stop the viewer, dispose of resources it allocated, and clear the container in which it is rendered back to its original state, call the following function.
+
+```ts
+space.remove() => void
+```
+
+## Render buildings
+
+See the dedicated functions you can call to render buildings [on this page](/api-reference/map/buildings).
+
+## Control the map location
+
+### Focus on a specific space
+
+You can change automatically "fly" the map to a specific space, by providing the space's identifier as follow:
+
+```ts
+map.flyToSpace(spaceId: string) => void
+```
+
+- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+
+### Fit all spaces in screen
+
+You can change automatically "fly" the map to an overview point, showing all rendered spaces, as follow:
+
+```ts
+map.fitAllSpacesInScreen() => void
+```
+
+## UI controls
+
+### Change the loading message
+
+You can change the loading message any time as follow. This doesn't impact whether the loader is displayed or not.
+
+```ts
+map.updateLoadingMessage(message: string) => void
+```
+
+### Control the loader
+
+You can control whether the loader is displayed or not anytime with the following functions.
+
+```ts
+map.showLoader() => void
+map.hideLoader() => void
+```
+
+## Full Mapbox SDK
+
+The Smplrspace map viewer is built on top of [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/guides). We provide a number of features dedicated to Smplrspace use-cases, but you can also build anything you want by accessing the full Mapbox SDK as below:
+
+```ts
+map.mapbox() => mapboxgl.Map | undefined
+```

docs/api-reference/queryclient/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "QueryClient",
-  "position": 2
+  "position": 3
 }

docs/api-reference/queryclient/doors-windows.md

@@ -0,0 +1,137 @@
+---
+sidebar_position: 5
+---
+
+# Doors & windows
+
+## Opening interface
+
+Doors and windows are the same thing under the hood in Smplrspace, we call them wall "openings". Multiple queries in this page return objects of the type `Opening` described below:
+
+```ts
+interface Opening {
+  id: string;
+  name: string;
+  dimensions: {
+    width: number;
+    height: number;
+    baseHeight: number;
+  };
+  options: object;
+  coordinates: {
+    levelIndex: number;
+    x: number;
+    z: number;
+    elevation: number;
+  }[];
+}
+```
+
+- `id` - unique identifier of this particular opening.
+- `name` - name given to the furniture in the editor. It could be an empty string.
+- `dimensions.width` - horizontal width of the opening in centimeters.
+- `dimensions.baseHeight` - distance between the ground and the bottom of the opening. It is usually 0 for doors and positive for windows.
+- `dimensions.height` - distance between the bottom and the top of the opening.
+- `options` - contains all sorts of options selected in the editor and used to render the opening.
+
+## getAllDoorsInSpace
+
+To list all doors from a space, you can call the following query.
+
+```ts
+smplrClient.getAllDoorsInSpace(id: string): Promise<Opening[]>
+```
+
+- `id` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `Opening` - this main interface is described [here](#opening-interface).
+
+## getAllDoorsInSpaceFromCache
+
+This is the synchronous equivalent of the query right above.
+
+```ts
+smplrClient.getAllDoorsInSpaceFromCache(id: string): Opening[]
+```
+
+where `id` and `Opening` are as defined in `getAllDoorsInSpace`.
+
+## getDoorsOnLevel
+
+To list all doors from a single level in a space, you can call the following query.
+
+```ts
+smplrClient.getDoorsOnLevel({
+  spaceId: string,
+  levelIndex: number
+}): Promise<Opening[]>
+```
+
+- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `levelIndex` - zero-based index of the level. Refer to the [Opening interface](#Opening-interface) to learn more.
+- `Opening` - this main interface is described [here](#opening-interface).
+
+## getDoorsOnLevelFromCache
+
+This is the synchronous equivalent of the query right above.
+
+```ts
+smplrClient.getDoorsOnLevelFromCache({
+  spaceId: string,
+  levelIndex: number
+}): Opening[]
+```
+
+where `spaceId`, `levelIndex`, and `Opening` are as defined in `getDoorsOnLevel`.
+
+## getAllWindowsInSpace
+
+To list all windows from a space, you can call the following query.
+
+```ts
+smplrClient.getAllWindowsInSpace(id: string): Promise<Opening[]>
+```
+
+- `id` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `Opening` - this main interface is described [here](#opening-interface).
+
+## getAllWindowsInSpaceFromCache
+
+This is the synchronous equivalent of the query right above.
+
+```ts
+smplrClient.getAllWindowsInSpaceFromCache(id: string): Opening[]
+```
+
+where `id` and `Opening` are as defined in `getAllWindowsInSpace`.
+
+## getWindowsOnLevel
+
+To list all windows from a single level in a space, you can call the following query.
+
+```ts
+smplrClient.getWindowsOnLevel({
+  spaceId: string,
+  levelIndex: number
+}): Promise<Opening[]>
+```
+
+- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `levelIndex` - zero-based index of the level. Refer to the [Opening interface](#Opening-interface) to learn more.
+- `Opening` - this main interface is described [here](#opening-interface).
+
+## getWindowsOnLevelFromCache
+
+This is the synchronous equivalent of the query right above.
+
+```ts
+smplrClient.getWindowsOnLevelFromCache({
+  spaceId: string,
+  levelIndex: number
+}): Opening[]
+```
+
+where `spaceId`, `levelIndex`, and `Opening` are as defined in `getDoorsOnLevel`.
+
+## Need any other data?
+
+[Get in touch](mailto:[email protected]) with any use-case that would require new queries to be exposed.

docs/api-reference/queryclient/geometry.md

@@ -112,10 +112,14 @@ smplrClient.getLevelBoundingBoxFromCache({
   spaceId: string,
   levelIndex: number,
   padding?: number
-}): BoundingBox
+}): {
+  levelIndex: number,
+  x: number,
+  z: number
+}[]
 ```
 
-where `spaceId`, `levelIndex`, `padding`, and `BoundingBox` are as defined in `getLevelBoundingBox`.
+where `spaceId`, `levelIndex`, and `padding` are as defined in `getLevelBoundingBox`.
 
 ## getPointsConcaveHull
 
@@ -169,6 +173,41 @@ smplrClient.getLinesConcaveHull({
 - `simplify` - _optional_ - whether the returned hull should be simplified, which means consecutive points that are aligned will be removed to keep only the first and the last. _Default value: true_
 - `simplifyTolerance` - _optional_ - authorized distance from the alignment used during the simplification process, given in meters. _Default value: 0.005_
 
+## getLevelAutomaticGround
+
+To get the automatic ground of the entire floor plate of a space, you can call the following query. The automatic ground is the [continuous concave hull](#getlinesconcavehull) of all the walls of the level put together. It may be enabled or disabled in the editor, but the value here will return a valid hull if the level exists and has walls.
+
+```ts
+smplrClient.getLevelAutomaticGround({
+  spaceId: string,
+  levelIndex: number,
+}): Promise<{
+  levelIndex: number,
+  x: number,
+  z: number
+}[] | null>
+```
+
+- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `levelIndex` - zero-based index of the level. Refer to the [Furniture interface](/api-reference/queryclient/furniture#furniture-interface) to learn more.
+
+## getLevelAutomaticGroundFromCache
+
+This is the synchronous equivalent of the query right above.
+
+```ts
+smplrClient.getLevelAutomaticGroundFromCache({
+  spaceId: string,
+  levelIndex: number,
+}): {
+  levelIndex: number,
+  x: number,
+  z: number
+}[] | null
+```
+
+where `spaceId`, and `levelIndex` are as defined in `getLevelAutomaticGround`.
+
 ## isPointInPolygon
 
 To know whether a point is contained within an area defined by a polygon, you can call the following query.

docs/api-reference/queryclient/queryclient.md

@@ -29,7 +29,7 @@ const smplrClient = new smplr.QueryClient({
 ```
 
 - `organizationId` is the unique identifier of your organization in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e". Personal accounts are also treated as "personal organization". To get your organization's ID, head to the Developers page from the main menu.
-- `clientToken` is an API token that is used to authenticate client-side requests. It is safe to have it exposed in your client code. You can manage your organisation's tokens in the Smplrspace app, by heading to the Developers page from the main menu.
+- `clientToken` is an API token that is used to authenticate client-side requests. It is safe to have it exposed in your client code. You can manage your organisation's tokens in the Smplrspace app, by heading to the Developers page from the main menu. [More info](/guides/embedding#client-tokens).
 
 ## How to use it