Merge pull request #55 from smplrspace/feat/pt-1848/compute-endpoints

[PT-1848] add compute queries
smplrspace · Feb 23, 2024 · 1f0454e · 1f0454e
2 parents e3b4f64 + 63998e4
commit 1f0454e
Show file tree

Hide file tree

Showing 5 changed files with 340 additions and 81 deletions.
diff --git a/docs/api-reference/queryclient/furniture.md b/docs/api-reference/queryclient/furniture.md
@@ -0,0 +1,133 @@
+---
+sidebar_position: 4
+---
+
+# Furniture
+
+## Furniture interface
+
+Multiple queries in this page return objects of the type `Furniture` described below:
+
+```ts
+interface Furniture {
+  catalogId: string;
+  id: string;
+  name: string;
+  levelIndex: number;
+  position: {
+    x: number;
+    z: number;
+    elevation: number;
+  };
+  rotation: Partial<{
+    pitch: number;
+    yaw: number;
+    roll: number;
+  }>;
+  dimensions: Partial<{
+    length: number;
+    height: number;
+    width: number;
+  }>;
+  configuration?: object;
+}
+```
+
+- `catalogId` - unique identifier of the furniture model, internal to Smplrspace. For example, all desks will share their `catalogId`.
+- `id` - unique identifier of this particular piece of furniture, in that space.
+- `name` - name given to the furniture in the editor.
+- `levelIndex` - zero-based index of the level where the furniture is located. For example, `levelIndex` equals to `2` means the furniture is on `L3` if there are no basements.
+- `position` - location of the center of the furniture in the floor plan. Values are given in meter. The absolute value has no meaning since the coordinate `(0,0,0)` is arbitrary. So these values are only relevant relatively to each other.
+- `rotation` - angle of rotation of the furniture in degrees. `yaw` would typically be the only non-null value as it represents the rotation around the vertical axis.
+- `dimensions` - size of the furniture in centimeters. `length` and `width` are the dimensions in the 2D horizontal plane, while `height` is the vertical height in the 3D space.
+- `configuration` - only exists for parametric furniture models, and contains the values of all model options for that piece of furniture. The schema depends on the model.
+
+## getAllFurnitureInSpace
+
+To list all furniture from a space, you can call the following query.
+
+```ts
+smplrClient.getAllFurnitureInSpace(id: string): Promise<Furniture[]>
+```
+
+- `id` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `Furniture` - this main interface is described [here](#furniture-interface).
+
+## getFurnitureOnLevel
+
+To list all furniture from a single level in a space, you can call the following query.
+
+```ts
+smplrClient.getFurnitureOnLevel({
+  spaceId: string,
+  levelIndex: number
+}): Promise<Furniture[]>
+```
+
+- `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](#furniture-interface) to learn more.
+- `Furniture` - this main interface is described [here](#furniture-interface).
+
+## getFurnitureInPolygon
+
+To list all furniture contained within an area defined by a polygon, you can call the following query.
+
+```ts
+smplrClient.getFurnitureInPolygon({
+  spaceId: string,
+  polygon: {
+    levelIndex: number,
+    x: number,
+    z: number
+  }[]
+}): Promise<Furniture[]>
+```
+
+- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `polygon` - the definition of the area used as a mask to extract furniture. It has the same schema as the coordinates from the [polygon data layers](/api-reference/space/data-layers#polygon-layer). It is assumed here that all coordinates have the same `levelIndex` value.
+- `Furniture` - this main interface is described [here](#furniture-interface).
+
+## getFurnitureById
+
+To extract a single piece of furniture from a space, identified by its unique identifier, you can call the following query.
+
+```ts
+smplrClient.getFurnitureById({
+  spaceId: string,
+  furnitureId: string
+}): Promise<Furniture | null>
+```
+
+- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `furnitureId` - unique identifier of the furniture in the space, has a similar format to `spaceId`.
+- `Furniture` - this main interface is described [here](#furniture-interface).
+
+Returns `null` if the furniture is not found in the space.
+
+## isFurnitureInPolygon
+
+To know whether a piece of furniture is contained within an area defined by a polygon, you can call the following query.
+
+```ts
+smplrClient.isFurnitureInPolygon({
+  spaceId: string,
+  furnitureId: string,
+  polygon: {
+    levelIndex: number,
+    x: number,
+    z: number
+  }[]
+}): Promise<boolean | null>
+```
+
+- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `furnitureId` - unique identifier of the furniture in the space, has a similar format to `spaceId`.
+- `polygon` - the definition of the area used as a mask to extract furniture. It has the same schema as the coordinates from the [polygon data layers](/api-reference/space/data-layers#polygon-layer). It is assumed here that all coordinates have the same `levelIndex` value.
+
+Returns `null` if the furniture is not found in the space, `false` if it is found but not in the polygon, `true` if it is found in the polygon.
+
+A similar query is available for points, see [isPointInPolygon](/api-reference/queryclient/geometry#ispointinpolygon).
+
+## Need any other data?
+
+[Get in touch](mailto:[email protected]) with any use-case that would require new queries to be exposed.
diff --git a/docs/api-reference/queryclient/geometry.md b/docs/api-reference/queryclient/geometry.md
@@ -0,0 +1,184 @@
+---
+sidebar_position: 5
+---
+
+# Geometry
+
+## getPolylineLength
+
+To measure the length of a line or polyline, you can call the following query.
+
+```ts
+smplrClient.getPolylineLength({
+  line: {
+    levelIndex: number,
+    x: number,
+    z: number,
+    elevation: number
+  }[],
+  unit?: 'ft' | 'm' | 'cm' | 'mm'
+}): number
+```
+
+- `line` - the polyline you want to compute the length for. It has the same schema as the coordinates from the [polyline data layers](/api-reference/space/data-layers#polyline-layer).
+- `unit` - _optional_ - your unit of choice. _Default value: m_
+
+## getPolygonArea
+
+To measure the area of a polygon, you can call the following query.
+
+```ts
+smplrClient.getPolygonArea({
+  polygon: {
+    levelIndex: number,
+    x: number,
+    z: number
+  }[],
+  unit?: 'sqft' | 'sqm'
+}): number
+```
+
+- `polygon` - the polygon you want to compute the length for. It has the same schema as the coordinates from the [polygon data layers](/api-reference/space/data-layers#polygon-layer).
+- `unit` - _optional_ - your unit of choice. _Default value: sqm_
+
+## getPolygonCenter
+
+To get the center point of a polygon, you can call the following query.
+
+```ts
+smplrClient.getPolygonCenter({
+  polygon: {
+    levelIndex: number,
+    x: number,
+    z: number
+  }[]
+}): {
+  levelIndex: number,
+  x: number,
+  z: number
+}
+```
+
+- `polygon` - the polygon you want to get the center for. It has the same schema as the coordinates from the [polygon data layers](/api-reference/space/data-layers#polygon-layer).
+
+## getPointsBoundingBox
+
+To get the bounding box of a set of points, you can call the following query. The bounding box is defined as a polygon which is always straight with respect to the (x, z) axes.
+
+```ts
+smplrClient.getPointsBoundingBox({
+  points: {
+    levelIndex: number,
+    x: number,
+    z: number
+  }[],
+  padding?: number
+}): {
+  levelIndex: number,
+  x: number,
+  z: number
+}[]
+```
+
+- `points` - the array of points you want to compute the bounding box for.
+- `padding` - _optional_ - minimum space between the points and the bounding box in meters. _Default value: 0_
+
+## getLevelBoundingBox
+
+To get the bounding box of the entire floor plate of a space, you can call the following query. The bounding box is defined as a polygon which is always straight with respect to the (x, z) axes.
+
+```ts
+smplrClient.getLevelBoundingBox({
+  spaceId: string,
+  levelIndex: number,
+  padding?: number
+}): Promise<{
+  levelIndex: number,
+  x: number,
+  z: number
+}[]>
+```
+
+- `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.
+- `padding` - _optional_ - minimum space between the floor plate's grounds/walls and the bounding box in meters. _Default value: 0_
+
+## getPointsConcaveHull
+
+The concave hull of a set of points is the smallest polygon that contains all the points, similar to a contour. To get the concave hull of a set of points, you can call the following query.
+
+Note that concave hulls are not suitable for sparse points, and you should use a convex hull instead – [get in touch](mailto:[email protected]) if you need this.
+
+Similarly, walls (or any data represented by lines or polygons) are typically not suitable for pure concave hulls — we have a dedicated query for such data with [getLinesConcaveHull](#getlinesconcavehull) below.
+
+```ts
+smplrClient.getPointsConcaveHull({
+  points: {
+    levelIndex: number,
+    x: number,
+    z: number
+  }[],
+  simplify?: boolean,
+  simplifyTolerance?: number
+}): {
+  levelIndex: number,
+  x: number,
+  z: number
+}[]
+```
+
+- `points` - the array of points you want to compute the bounding box for.
+- `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_
+
+## getLinesConcaveHull
+
+The concave hull of a set of lines is the smallest polygon that contains all the lines without "breaking" any of them, which makes it more suitable for "continuous" data (like walls) than the pure concave hulls computed in [getPointsConcaveHull](#getpointsconcavehull). It is similar to a contour. To get the concave hull of a set of lines, you can call the following query.
+
+```ts
+smplrClient.getLinesConcaveHull({
+  lines: {
+    levelIndex: number,
+    x: number,
+    z: number
+  }[][],
+  simplify?: boolean,
+  simplifyTolerance?: number
+}): {
+  levelIndex: number,
+  x: number,
+  z: number
+}[]
+```
+
+- `lines` - the array of lines you want to compute the bounding box for.
+- `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_
+
+## isPointInPolygon
+
+To know whether a point is contained within an area defined by a polygon, you can call the following query.
+
+```ts
+smplrClient.isPointInPolygon({
+  point: {
+    levelIndex: number,
+    x: number,
+    z: number
+  },
+  polygon: {
+    levelIndex: number,
+    x: number,
+    z: number
+  }[]
+}): boolean
+```
+
+- `point` - the point coordinates in 2D, with the same schema as `polygon` below.
+- `polygon` - the definition of the area used as a mask to extract furniture. It has the same schema as the coordinates from the [polygon data layers](/api-reference/space/data-layers#polygon-layer). It is assumed here that all coordinates have the same `levelIndex` value.
+
+A similar query is available for furniture pieces, see [isFurnitureInPolygon](/api-reference/queryclient/furniture#isfurnitureinpolygon).
+
+## Need any other data?
+
+[Get in touch](mailto:[email protected]) with any use-case that would require new queries to be exposed.
diff --git a/docs/api-reference/queryclient/queryclient.md b/docs/api-reference/queryclient/queryclient.md
@@ -6,9 +6,16 @@ slug: overview
 
 # Querying your data
 
-Smplr.js makes a `smplr` object available on the global scope. One of the classes provided under this object is `QueryClient`, which exposes selected API endpoints allowing programmatic queries to retrieve or mutate your Smplrspace hosted data.
+Smplr.js provides a `smplr` object. One of the classes provided under this object is `QueryClient`, which exposes capabilities generally related to the extraction of information out of your floor plans and spatial data. Here are a few examples:
 
-All queries are typed end-to-end, reducing runtime errors and improving developer experience with auto-completion.
+- call selected backend API endpoints allowing programmatic queries to retrieve or mutate your Smplrspace hosted data,
+- extract furniture listings or information from the floor plans,
+- compute distances, areas, and the like from mapped data,
+- compute centers, bounding boxes, concave hulls,
+- ask if a point or a piece of furniture is located within a given boundary,
+- and we're adding queries based on demand, so [get in touch](mailto:[email protected]) and share your use-case.
+
+Most queries are typed end-to-end, reducing runtime errors and improving developer experience with auto-completion.
 
 ## Constructor
 
@@ -26,7 +33,7 @@ const smplrClient = new smplr.QueryClient({
 
 ## How to use it
 
-Each query exposed via `QueryClient` return a `Promise` ([MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)) to the resulting data, and throws structured errors if any. You can consume them and handle errors as per your preference using `Promise.then().catch()` or `async/await` with a `try/catch` block.
+Some queries exposed via `QueryClient` are synchronous, while others return a `Promise` ([MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)) to the resulting data, and throw structured errors if any. You can consume such queries and handle errors as per your preference using `Promise.then().catch()` or `async/await` with a `try/catch` block.
 
 ### Using async/await
 
@@ -64,11 +71,11 @@ smplrClient
 
 ## Queries
 
-The query client has just been released and will be expanded on over the coming months based on user requests. For now, we support `utils` queries to check the connection and version of the API, as well as `spaces` queries to retrieve details about spaces.
-
-Get more details in the dedicated page:
+The query client is pretty recent and will fast evolving based on user requests. Below are the type of queries currently supported. Get more details in the dedicated page.
 
-- [Utils queries](./utils)
-- [Spaces queries](./spaces)
+- [Utility queries](./utils): check the connection and version of the API.
+- [Spaces queries](./spaces): retrieve details about your spaces.
+- [Furniture queries](./furniture): extract furniture from your spaces.
+- [Geometry queries](./geometry): compute dimensions and perform geometrical simplifications of your data.
 
-Get in touch with any use-case that would require new queries to be exposed.
+[Get in touch](mailto:[email protected]) with any use-case that would require new queries to be exposed.