@wemap/viewer 0.0.0-stage → 14.8.0-beta.4

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026 Wemap SAS. All rights reserved.
+
+This software and its associated source code, documentation, and other
+materials (the "Software") are the proprietary and confidential property of
+Wemap SAS. The Software is licensed, not sold.
+
+No part of the Software may be used, copied, reproduced, modified, merged,
+published, distributed, sublicensed, or sold, in whole or in part, in any form
+or by any means, without the prior written permission of Wemap SAS, except as
+expressly permitted under a separate written license or subscription agreement
+with Wemap SAS. Use of the Software is governed by, and subject to the terms
+of, that agreement.
+
+Unauthorized use, reproduction, or distribution of the Software, or any portion
+of it, may result in severe civil and criminal penalties, and will be
+prosecuted to the maximum extent possible under the law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL WEMAP
+SAS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# @wemap/viewer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic **360° panorama viewer** for Wemap maps. It loads the
+map's image graph (the 360° photos captured on site) and lets users look
+around and walk from photo to photo. Built on three.js, with no UI framework.
+
+Pair it with [`@wemap/viewer-map`](../viewer-map) to show the graph and the look
+direction on a [`@wemap/map`](../map).
+
+## Installation
+
+```bash
+npm install @wemap/core @wemap/geo @wemap/viewer
+```
+
+`three` and `@tweenjs/tween.js` are regular dependencies — nothing else to install.
+
+### No build step (`<script>` tag)
+
+Load the UMD bundle `dist/cdn/wemap-viewer.umd.js` after the `@wemap/core` and
+`@wemap/geo` bundles. It inlines three.js and exposes
+`window.Wemap.Viewer`.
+
+## Requirements
+
+- **`core.init()` first.** Identity (emmid), auth and the VPS endpoint all come
+  from `@wemap/core`; the viewer takes none of them.
+- **A map with a VPS provider.** Without it, `open()` rejects.
+- **A sized container.** The canvas fills its container and follows its size
+  (a `ResizeObserver` handles resizes), so give the container a height.
+
+## Quick start
+
+```ts
+import { core } from '@wemap/core';
+import { WemapViewer } from '@wemap/viewer';
+import '@wemap/viewer/style.css';
+
+await core.init({ emmid: '31668', token: '<token>' });
+
+const viewer = new WemapViewer(document.getElementById('viewer')!, {
+  onNavigate: (nodeId) => console.log('now at', nodeId),
+});
+
+// Open on a node, looking east. Resolves once its image is on screen.
+await viewer.open(1059484, { heading: 90 });
+```
+
+`open()` takes a node id (a deep link, a click on the map graph) or a position,
+in which case it opens on the nearest node, on the position's level when it has
+one:
+
+```ts
+import { Coordinates } from '@wemap/geo';
+
+// Latitude, longitude, altitude (none), level 1.
+await viewer.open(new Coordinates(43.60907, 3.91719, null, 1));
+```
+
+The first call fetches the image graph. Later calls move there like
+`navigateTo`, and `heading` turns the view with an animation. Without `heading`
+the look direction is kept. Awaiting is optional: `ready` and `onError` report
+the same outcome.
+
+## Moving around
+
+- **Look around** by dragging (with inertia), or with the arrow keys once the
+  viewer has focus (press on it, or Tab to it). Zoom with the mouse wheel
+  (`zoom: false` disables it).
+- **Walk** by clicking the floor: hovering shows a disc under the pointer and a
+  cross on the nearest node; clicking walks there. Disable with
+  `navigation: false`. Paused while the view moves to the next node.
+- **Programmatically:** `viewer.open(target, { heading })` (awaitable), or
+  `viewer.navigateTo(nodeId)` (fire and forget), and
+  `viewer.nearestNode(coordinates, level?)` to find the node closest to a place
+  (after `viewer.loadGraph()`, which fetches the graph without opening a photo).
+  `viewer.lookAt(heading, pitch = 0)` turns the camera the short way round;
+  dragging the panorama cancels it.
+
+The look direction is a real compass heading, so it is kept when you change
+node: you keep facing the same way.
+
+`navigateTo` updates `currentNode` and fires `navigate` right away, while the
+new image loads and fades in. If that image fails to load, the viewer goes back
+to the node still on screen (`navigate` fires again with it) and calls
+`onError`.
+
+## Locating a point
+
+In `locate` click mode, a click on the panorama gives the geo position of what
+is under it (from the VPS depth estimate) instead of walking: to place a POI
+where the user points, for example.
+
+```ts
+viewer.setClickMode('locate');
+viewer.on('locate', ({ coordinates, node }) => {
+  console.log(coordinates.lat, coordinates.lng, coordinates.alt, coordinates.level);
+});
+
+viewer.setClickMode('navigate'); // back to walking
+```
+
+The cursor becomes a crosshair, and clicks during a transition are ignored. The
+level is the clicked node's when the VPS gives none. Failures go to `onError`.
+
+## Measuring
+
+In `measure` click mode, two clicks on the panorama give the distance between
+the two points (from the VPS depth estimate). The viewer draws a dot on each
+point and a line between them; a third click clears them, as do changing mode
+and moving to another node.
+
+```ts
+viewer.setClickMode('measure');
+viewer.on('measure', ({ distance }) => showLabel(`${distance.toFixed(2)} m`));
+```
+
+## Drawing over the panorama
+
+`setPolygons` draws polygons anchored in the real world: a shelf front, an area
+on the floor, a door. Each vertex needs an altitude, in the same reference as
+the graph nodes'. The polygons follow the user from node to node; a new call
+replaces them, an empty list clears them. The panorama has no depth: a polygon
+behind a wall still shows.
+
+```ts
+viewer.setPolygons([{
+  coordinates: [
+    new Coordinates(48.99068, 2.20736, -1.41),
+    new Coordinates(48.99067, 2.20742, -1.41),
+    new Coordinates(48.99067, 2.20742, 1.24),
+    new Coordinates(48.99068, 2.20736, 1.24),
+  ],
+  color: '#3860BE',
+}]);
+```
+
+## Events
+
+Each constructor callback (`onNavigate`, `onHeadingChange`, `onReady`,
+`onError`) takes one listener. For more, subscribe with `viewer.on()`, which
+returns an unsubscribe function:
+
+```ts
+const off = viewer.on('heading', (heading) => compass.rotate(heading));
+off();
+```
+
+| Event      | Payload               | When                                         |
+| ---------- | --------------------- | -------------------------------------------- |
+| `ready`    | —                     | The first image is on screen (once)          |
+| `navigate` | `ViewerNode`          | A move to a node starts (click or code)      |
+| `heading`  | `number` (degrees)    | The look heading changes                     |
+| `locate`   | `LocatedPoint`        | A click in `locate` mode was located         |
+| `measure`  | `Measurement`         | Two clicks in `measure` mode were measured   |
+| `click`    | `ViewerClick`         | A click in `navigate` mode walked nowhere (above the horizon, or no node there): its heading, pitch and node, to pick your own geometry |
+
+## Options
+
+| Option               | Type                        | Default | Description                                   |
+| -------------------- | --------------------------- | ------- | --------------------------------------------- |
+| `zoom`               | `boolean`                   | `true`  | Mouse-wheel zoom                              |
+| `maxFov`             | `number`                    | `80`    | Widest vertical field of view, in degrees     |
+| `navigation`         | `boolean`                   | `true`  | Click the floor to walk to the nearest node   |
+| `onNavigate`         | `(nodeId: number) => void`  |         | A move to a node starts                       |
+| `onHeadingChange`    | `(heading: number) => void` |         | The look heading changes                      |
+| `onReady`            | `() => void`                |         | The first image is on screen (once)           |
+| `onLocate`           | `(point: LocatedPoint) => void` |     | A click in `locate` mode was located          |
+| `onMeasure`          | `(measurement: Measurement) => void` | | Two clicks in `measure` mode were measured  |
+| `onError`            | `(error: Error) => void`    |         | Graph, image, located point or measurement failed |
+
+## API
+
+| Member                              | Description                                                 |
+| ----------------------------------- | ----------------------------------------------------------- |
+| `open(target, { heading?, pitch? })` | Open on a node id or the nearest node to a position; resolves once its image is on screen, rejects if the node is unknown or the graph or image fails |
+| `loadGraph(): Promise<ViewerNode[]>` | Fetch the image graph without opening a photo (once; shared with `open()`) |
+| `getNodes(): ViewerNode[]`          | All nodes (id, coordinates, level, image, capture heading); empty until the graph is loaded |
+| `currentNode: ViewerNode \| null`   | The node the viewer is at (set as soon as a move starts)    |
+| `navigateTo(nodeId)`                | Move to a node; no-op if unknown or already there           |
+| `nearestNode(coordinates, level?)`  | Closest node to a place, on `level` when given; null before the graph is loaded |
+| `getHeading(): number`              | Current look heading, degrees (0 = north, clockwise)        |
+| `lookAt(heading, pitch?)`           | Turn to a heading/pitch, animated                           |
+| `setClickMode(mode)` / `clickMode`  | What a click does: `'navigate'` (walk, default), `'locate'` or `'measure'` |
+| `getGraphGeojson()`                 | The graph as GeoJSON (used by `@wemap/viewer-map`)          |
+| `on(event, callback)`               | Subscribe to an event; returns an unsubscribe function      |
+| `resize()`                          | Re-measure the container (automatic on resize)              |
+| `destroy()`                         | Release the renderer, images, listeners and canvas          |
+
+`ViewerDataClient` (graph and image URLs) is exported for standalone use too.

package/dist/cdn/wemap-viewer.css

@@ -0,0 +1,2 @@
+.wemap-viewer__canvas{touch-action:none;-webkit-user-select:none;user-select:none;cursor:grab;width:100%;height:100%;display:block}.wemap-viewer__canvas:active{cursor:grabbing}.wemap-viewer__canvas:focus:not(:focus-visible){outline:none}
+/*$vite$:1*/