From 0a55c8290127900a195dbd0318bf2e9b57c3d1bb Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Fri, 24 Nov 2023 11:33:16 +0800 Subject: [PATCH 1/3] document dotted polylines --- docs/api-reference/space/data-layers.md | 44 +++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/api-reference/space/data-layers.md b/docs/api-reference/space/data-layers.md index f4a9c0c..e4ba4d1 100644 --- a/docs/api-reference/space/data-layers.md +++ b/docs/api-reference/space/data-layers.md @@ -189,6 +189,50 @@ space.addDataLayer({ The [Add data elements](/examples/add-data-elements) example gives a full overview of draggable & reshapable layers, including a polyline layer. +### Dotted polyline layer + +A dotted polyline layer is similar to a polyline layer but has each data element rendered as a line of spheres. Also lines can be animated with a few styles. + +```ts +space.addDataLayer({ + id: string, + type: 'dotted-polyline', + data: [{ + id: string | number, + coordinates: [{ + levelIndex: number, + x: number, + z: number, + elevation: number + }], + ...customData: object + }], + diameter?: number | (dataElement: object) => number, + gap?: number, + anchor?: 'bottom' | 'center' | 'top', + color?: string | (dataElement: object) => string, + alpha?: number, + animation?: false | 'railway' | 'waves', + speed?: number, + amplitude?: number, + waves?: number +}) => DataLayerController +``` + +- `id` is a unique identifier for this layer which is used for updates. +- `data` is an array of objects (refered to as data elements) to be rendered. Each element **must** have an `id` (unique identifier within the data array) and a `coordinates` array. Elements can also contain any additional custom data used for rendering options. +- `diameter` - _optional_ - defines the diameter of the sphere to render in meters. It can be defined as a number for all elements or per element with a function that takes each element as argument and returns the diameter for that element. _Default value: 1m._ +- `gap` - _optional_ - defines the distance between each sphere in the line as a fraction of the diameter. E.g. 0.3 means the gap is 30% of the diameter. _Default value: 0.3._ +- `anchor` - _optional_ - defines if the position provided for each data element corresponds to the bottom, center or top of the sphere. _Default value: center._ +- `color` - _optional_ - defines the color of the sphere to render. It can be defined as a hexadecimal string like "#3a3c3c" for all elements or per element with a function that takes each element as argument and returns the hexadecimal color string for that element. _Default value: "#2393d4"._ +- `alpha` - _optional_ - defines the transparency of the spheres for the whole layer. Element specific alpha value is not supported. The value should be between 0 (invisible) and 1 (opaque). _Default value: 1._ +- `animation` - _optional_ - use `false` to disable animation, `'railway'` to move spheres in a queue like wagons, or `'waves'` to scale spheres like a wave. _Default value: false._ +- `speed` - _optional_ - defines the speed of the animation. In 'railway' mode, speed 1 means each sphere gets to next one in 1 second. In 'waves' mode, speed 1 means it takes 1 second for a wave to go up and down for each sphere. _Default value: 1._ +- `amplitude` - _optional, 'waves' mode only_ - defines the scaling factor of the waves, so 0.4 means each sphere will grow 40% of its diameter. _Default value: 0.4._ +- `waves` - _optional, 'waves' mode only_ - defines the number of waves visible on each line at a single point of time. _Default value: 1._ + +Live example coming soon. + ### Furniture layer A furniture layer has each data element mapped to one or more pieces of furniture from the floor plan. From a1771ceffb557e2910bda0ff0dd826123e00ef60 Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Fri, 24 Nov 2023 11:40:04 +0800 Subject: [PATCH 2/3] document newlines in tooltips --- docs/api-reference/space/data-layers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-reference/space/data-layers.md b/docs/api-reference/space/data-layers.md index e4ba4d1..5f1eac1 100644 --- a/docs/api-reference/space/data-layers.md +++ b/docs/api-reference/space/data-layers.md @@ -21,7 +21,7 @@ space.addDataLayer({ ``` - `...layerDefinition` - refer to the [overview](./overview#data-layers) page. -- `tooltip` - _optional_ - is taking the newly hovered data element as argument and should return the content of the tooltip to render. It is called once when the pointer starts to hover a data element. +- `tooltip` - _optional_ - is taking the newly hovered data element as argument and should return the content of the tooltip to render. It is called once when the pointer starts to hover a data element. Built-in tooltips are text only, newlines are supported by using [multi-line template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#multi-line_strings). If you need HTML/CSS in your tooltips, check the [custom tooltips example](/examples/custom-tooltips/). - `onClick` - _optional_ - is taking the data element that was clicked as argument. It is called each time a click or tap event happens. - `onHover` - _optional_ - is taking the newly hovered data element as argument. It is called once when the pointer starts to hover a data element. - `onHoverOut` - _optional_ - is taking the previously hovered data element as argument. It is called once when the pointer stops hovering a data element. From a47182a0c32b3103b14a6f742e3c8d1a9f0e6dca Mon Sep 17 00:00:00 2001 From: Thibaut Tiberghien Date: Fri, 24 Nov 2023 11:44:55 +0800 Subject: [PATCH 3/3] document onResize --- docs/api-reference/space/space.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/api-reference/space/space.md b/docs/api-reference/space/space.md index ba59d52..8af7942 100644 --- a/docs/api-reference/space/space.md +++ b/docs/api-reference/space/space.md @@ -40,7 +40,8 @@ space.startViewer({ allowModeChange?: boolean, onModeChange?: (mode: '2d' | '3d') => void, onReady?: () => void, - onError?: (error: string | Error) => void, + onError?: (errorMessage: string) => void, + onResize?: (containerRect: DOMRect) => void, ...customUX: object }) => void ``` @@ -52,6 +53,7 @@ space.startViewer({ - `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. +- `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.). - `...customUX` represents additional options that let you customise the user experience as documented in the [custom UX](./custom-ux#viewer-options) page. 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.