@thatopen/services 0.3.16 → 0.5.0

package/docs/cli/serve.md

@@ -1,43 +1,43 @@
----
-description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
----
-
-## thatopen serve
-
-Builds the app in watch mode and serves the IIFE bundle locally. On every save, esbuild rebuilds and the platform reloads the bundle automatically via SSE.
-
-Does **not** open a browser tab — the app runs inside the platform iframe. Open your project on the platform, then click the debug button to connect it to the local server.
-
-**Usage:**
-```bash
-thatopen serve [flags]
-```
-
-**Flags:**
-
-- `--port <port>` — Port to serve the bundle on. Default: `4000`.
-
-**Endpoints served:**
-
-- `GET /bundle.js` — The compiled IIFE bundle.
-- `GET /bundle.js.map` — Source map.
-- `GET /events` — SSE stream for live reload.
-
-**Example:**
-```bash
-thatopen serve
-thatopen serve --port 4321
-```
-
-**Connecting the platform to your local server:**
-
-1. Go to [https://platform.thatopen.com](https://platform.thatopen.com) and open a project (create one first if needed).
-2. In the top right corner, click the **Local App** icon.
-3. Click **Get Started**.
-
-The platform loads the bundle from port 4000 and renders the app inside the project context, with full access to its models, data, and users. The dev server must be running before opening this URL — if nothing is served on port 4000, the platform will fail to load the app.
-
-The resulting URL follows this pattern:
-```
-https://platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
-```
+---
+description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
+---
+
+## thatopen serve
+
+Builds the app in watch mode and serves the IIFE bundle locally. On every save, esbuild rebuilds and the platform reloads the bundle automatically via SSE.
+
+Does **not** open a browser tab — the app runs inside the platform iframe. Open your project on the platform, then click the debug button to connect it to the local server.
+
+**Usage:**
+```bash
+thatopen serve [flags]
+```
+
+**Flags:**
+
+- `--port <port>` — Port to serve the bundle on. Default: `4000`.
+
+**Endpoints served:**
+
+- `GET /bundle.js` — The compiled IIFE bundle.
+- `GET /bundle.js.map` — Source map.
+- `GET /events` — SSE stream for live reload.
+
+**Example:**
+```bash
+thatopen serve
+thatopen serve --port 4321
+```
+
+**Connecting the platform to your local server:**
+
+1. Go to [https://platform.thatopen.com](https://platform.thatopen.com) and open a project (create one first if needed).
+2. In the top right corner, click the **Local App** icon.
+3. Click **Get Started**.
+
+The platform loads the bundle from port 4000 and renders the app inside the project context, with full access to its models, data, and users. The dev server must be running before opening this URL — if nothing is served on port 4000, the platform will fail to load the app.
+
+The resulting URL follows this pattern:
+```
+https://platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
+```

package/docs/cli/swap.md

@@ -1,30 +1,30 @@
----
-description: "Toggle or explicitly set the engine library mode between stable public packages (@thatopen/*) and private beta packages (@thatopen-platform/*-beta). Updates package.json and .thatopen, then runs npm install. Source code never changes — aliases handle resolution."
----
-
-## thatopen swap
-
-Switches the project between stable and beta engine libraries. Without flags, it toggles from the current state. Updates `package.json` dependencies and sets `beta` in `.thatopen` so `thatopen serve`, `thatopen local-server`, and `vite build` all pick up the change automatically.
-
-Source code stays unchanged — `@thatopen/components` imports resolve to the correct package via esbuild/vite aliases based on the `beta` flag in `.thatopen`.
-
-**Usage:**
-```bash
-thatopen swap           # toggle: stable → beta or beta → stable
-thatopen swap --beta    # force beta
-thatopen swap --stable  # force stable
-```
-
-**Flags:**
-
-- `--beta` — Switch to beta libraries (`@thatopen-platform/*-beta`).
-- `--stable` — Switch back to stable public libraries (`@thatopen/*`).
-
-**Examples:**
-```bash
-thatopen swap
-thatopen swap --beta
-thatopen swap --stable
-```
-
-> Beta packages are private and the access must be explicitly granted by That Open Company.
+---
+description: "Toggle or explicitly set the engine library mode between stable public packages (@thatopen/*) and private beta packages (@thatopen-platform/*-beta). Updates package.json and .thatopen, then runs npm install. Source code never changes — aliases handle resolution."
+---
+
+## thatopen swap
+
+Switches the project between stable and beta engine libraries. Without flags, it toggles from the current state. Updates `package.json` dependencies and sets `beta` in `.thatopen` so `thatopen serve`, `thatopen local-server`, and `vite build` all pick up the change automatically.
+
+Source code stays unchanged — `@thatopen/components` imports resolve to the correct package via esbuild/vite aliases based on the `beta` flag in `.thatopen`.
+
+**Usage:**
+```bash
+thatopen swap           # toggle: stable → beta or beta → stable
+thatopen swap --beta    # force beta
+thatopen swap --stable  # force stable
+```
+
+**Flags:**
+
+- `--beta` — Switch to beta libraries (`@thatopen-platform/*-beta`).
+- `--stable` — Switch back to stable public libraries (`@thatopen/*`).
+
+**Examples:**
+```bash
+thatopen swap
+thatopen swap --beta
+thatopen swap --stable
+```
+
+> Beta packages are private and the access must be explicitly granted by That Open Company.

package/docs/cloud/GaussianSplatConverter.md

@@ -1,43 +1,43 @@
-# GaussianSplatConverter
-
-Convert a 3D Gaussian Splat PLY into a streamable FQ LOD tree.
-
-Reads an uploaded .ply (plain INRIA 3DGS, or a PlayCanvas compressed.ply) and builds an octree of flat-quant (FQ) LOD nodes, published as one visible `.splat` entry whose hidden files hold the streamed nodes. The viewer fetches only the nodes it needs at the LOD it needs.
-
-Pure CPU: no GPU, no WebGPU, no WebP, no k-means — which is what lets it run in a cloud worker at all (the splat-transform toolchain it replaces requires WebGPU). The codec and converter live in @thatopen-platform/components-beta (realityCapture); this component is only the platform I/O around it.
-
-- **Accepts:** `.ply`
-- **Produces:** `.splat`
-- **Result:** the execution's `resultMessage` contains `[splatFileId=<id>]`
-
-## Actions
-
-| action | what it does | params |
-|---|---|---|
-| `default` | Convert the splat in one execution. | `fileId`, `gaussianScale` |
-
-## Params
-
-| id | type | label |
-|---|---|---|
-| `fileId` | string | Gaussian-Splat PLY File ID |
-| `gaussianScale` | string | Gaussian scale (metric calibration, default 1) |
-
-## Notes
-
-- gaussianScale is a METRIC CALIBRATION, not a quality knob: reality-capture splats are non-metric, so this scales them to real-world metres. It is PER-CAPTURE (alcardete calibrates to ~70) — default 1, and recalibrate in the viewer.
-- Spherical harmonics (view-dependent colour) are NOT carried: the FQ codec stores a flat RGBA per splat, and the renderer evaluates no SH. A capture therefore renders matte compared to its source. This is a known fidelity gap, not a bug.
-
-## Usage
-
-```ts
-import { SplatToFq } from "@thatopen/services";
-
-const { executionId } = await client.executeComponent(componentId, {
-  projectId,
-  fileId,
-});
-
-const exec = await client.getExecution(executionId);
-const producedFileId = SplatToFq.parseResult(exec.resultMessage);
-```
+# GaussianSplatConverter
+
+Convert a 3D Gaussian Splat PLY into a streamable FQ LOD tree.
+
+Reads an uploaded .ply (plain INRIA 3DGS, or a PlayCanvas compressed.ply) and builds an octree of flat-quant (FQ) LOD nodes, published as one visible `.splat` entry whose hidden files hold the streamed nodes. The viewer fetches only the nodes it needs at the LOD it needs.
+
+Pure CPU: no GPU, no WebGPU, no WebP, no k-means — which is what lets it run in a cloud worker at all (the splat-transform toolchain it replaces requires WebGPU). The codec and converter live in @thatopen-platform/components-beta (realityCapture); this component is only the platform I/O around it.
+
+- **Accepts:** `.ply`
+- **Produces:** `.splat`
+- **Result:** the execution's `resultMessage` contains `[splatFileId=<id>]`
+
+## Actions
+
+| action | what it does | params |
+|---|---|---|
+| `default` | Convert the splat in one execution. | `fileId`, `gaussianScale` |
+
+## Params
+
+| id | type | label |
+|---|---|---|
+| `fileId` | string | Gaussian-Splat PLY File ID |
+| `gaussianScale` | string | Gaussian scale (metric calibration, default 1) |
+
+## Notes
+
+- gaussianScale is a METRIC CALIBRATION, not a quality knob: reality-capture splats are non-metric, so this scales them to real-world metres. It is PER-CAPTURE (alcardete calibrates to ~70) — default 1, and recalibrate in the viewer.
+- Spherical harmonics (view-dependent colour) are NOT carried: the FQ codec stores a flat RGBA per splat, and the renderer evaluates no SH. A capture therefore renders matte compared to its source. This is a known fidelity gap, not a bug.
+
+## Usage
+
+```ts
+import { SplatToFq } from "@thatopen/services";
+
+const { executionId } = await client.executeComponent(componentId, {
+  projectId,
+  fileId,
+});
+
+const exec = await client.getExecution(executionId);
+const producedFileId = SplatToFq.parseResult(exec.resultMessage);
+```

package/docs/cloud/PointCloudConverter.md

@@ -1,53 +1,53 @@
-# PointCloudConverter
-
-Convert a LAS point cloud into a streamable Potree 2.0 octree.
-
-Reads an uploaded .las and builds a Potree 2.0 octree (metadata.json + hierarchy.bin + chopped octree pieces), published as one visible `.potree` entry whose hidden files hold the streamed chunks. The viewer byte-ranges those chunks, so a cloud opens without downloading it whole.
-
-The conversion itself lives in @thatopen-platform/components-beta (realityCapture); this component is only the platform I/O around it.
-
-- **Accepts:** `.las`
-- **Produces:** `.potree`
-- **Result:** the execution's `resultMessage` contains `[potreeFileId=<id>]`
-
-## Actions
-
-| action | what it does | params |
-|---|---|---|
-| `SIMPLE` | Build the whole cloud in ONE execution. The default, and what you almost always want. | `fileId` |
-| `PLAN` | For clouds too big for SIMPLE: stream the source once and return an adaptive set of tiles that each fit a worker. | `fileId`, `K` |
-| `BUILD` | Build ONE tile of a PLAN as an aligned subtree of the global octree. Fired once per tile. | `grid`, `cell`, `entryId`, `shards` |
-| `MERGE` | Graft the built tiles into one global octree and publish the `.potree` entry. The tiles' bytes are referenced, never copied. | `grid`, `tiles`, `entryId` |
-
-## Params
-
-| id | type | label |
-|---|---|---|
-| `action` | string | Action (SIMPLE|PLAN|BUILD|MERGE) |
-| `fileId` | string | LAS Point Cloud File ID |
-| `K` | number | Split level (PLAN) |
-| `grid` | string | Global grid JSON (BUILD/MERGE) |
-| `cell` | string | Cell name (BUILD) |
-| `tiles` | string | Tile descriptors JSON (MERGE) |
-| `entryId` | string | Shared entry item id (BUILD/MERGE) |
-| `shards` | string | Cell LAS shard hidden-file ids JSON (BUILD cell-file mode) |
-
-## Notes
-
-- PLAN/BUILD/MERGE is a MEMORY workaround, not a speed feature — a billion-point cloud cannot fit in one worker. It needs many chained executions, and the platform's file API is whole-file-only (it ignores HTTP Range) at ~7 MB/s, so a 50GB / 2B-point cloud would spend ~9 hours just moving bytes, most of it network. Convert those OFFLINE and upload the .potree directly.
-- LAZ is not supported (it is compressed; the LASF signature check rejects it).
-
-## Usage
-
-```ts
-import { LasToPotree } from "@thatopen/services";
-
-const { executionId } = await client.executeComponent(componentId, {
-  projectId,
-  fileId,
-  action: "SIMPLE",
-});
-
-const exec = await client.getExecution(executionId);
-const producedFileId = LasToPotree.parseResult(exec.resultMessage);
-```
+# PointCloudConverter
+
+Convert a LAS point cloud into a streamable Potree 2.0 octree.
+
+Reads an uploaded .las and builds a Potree 2.0 octree (metadata.json + hierarchy.bin + chopped octree pieces), published as one visible `.potree` entry whose hidden files hold the streamed chunks. The viewer byte-ranges those chunks, so a cloud opens without downloading it whole.
+
+The conversion itself lives in @thatopen-platform/components-beta (realityCapture); this component is only the platform I/O around it.
+
+- **Accepts:** `.las`
+- **Produces:** `.potree`
+- **Result:** the execution's `resultMessage` contains `[potreeFileId=<id>]`
+
+## Actions
+
+| action | what it does | params |
+|---|---|---|
+| `SIMPLE` | Build the whole cloud in ONE execution. The default, and what you almost always want. | `fileId` |
+| `PLAN` | For clouds too big for SIMPLE: stream the source once and return an adaptive set of tiles that each fit a worker. | `fileId`, `K` |
+| `BUILD` | Build ONE tile of a PLAN as an aligned subtree of the global octree. Fired once per tile. | `grid`, `cell`, `entryId`, `shards` |
+| `MERGE` | Graft the built tiles into one global octree and publish the `.potree` entry. The tiles' bytes are referenced, never copied. | `grid`, `tiles`, `entryId` |
+
+## Params
+
+| id | type | label |
+|---|---|---|
+| `action` | string | Action (SIMPLE|PLAN|BUILD|MERGE) |
+| `fileId` | string | LAS Point Cloud File ID |
+| `K` | number | Split level (PLAN) |
+| `grid` | string | Global grid JSON (BUILD/MERGE) |
+| `cell` | string | Cell name (BUILD) |
+| `tiles` | string | Tile descriptors JSON (MERGE) |
+| `entryId` | string | Shared entry item id (BUILD/MERGE) |
+| `shards` | string | Cell LAS shard hidden-file ids JSON (BUILD cell-file mode) |
+
+## Notes
+
+- PLAN/BUILD/MERGE is a MEMORY workaround, not a speed feature — a billion-point cloud cannot fit in one worker. It needs many chained executions, and the platform's file API is whole-file-only (it ignores HTTP Range) at ~7 MB/s, so a 50GB / 2B-point cloud would spend ~9 hours just moving bytes, most of it network. Convert those OFFLINE and upload the .potree directly.
+- LAZ is not supported (it is compressed; the LASF signature check rejects it).
+
+## Usage
+
+```ts
+import { LasToPotree } from "@thatopen/services";
+
+const { executionId } = await client.executeComponent(componentId, {
+  projectId,
+  fileId,
+  action: "SIMPLE",
+});
+
+const exec = await client.getExecution(executionId);
+const producedFileId = LasToPotree.parseResult(exec.resultMessage);
+```