u-space 0.0.0-alpha.1

package/dist/src/objects/PlaneMesh.d.ts

@@ -0,0 +1,17 @@
+import { MeshStandardNodeMaterial, PlaneGeometry, type MeshStandardNodeMaterialParameters } from 'three/webgpu';
+import type { InteractionEventMap } from '../interactions';
+import { BaseMesh } from './BaseMesh';
+export interface PlaneMeshParameters {
+    geometryParameters?: {
+        width?: number;
+        height?: number;
+        widthSegments?: number;
+        heightSegments?: number;
+    };
+    materialParameters?: MeshStandardNodeMaterialParameters;
+}
+export declare class PlaneMesh extends BaseMesh<PlaneGeometry, MeshStandardNodeMaterial, InteractionEventMap> {
+    readonly isPlaneMesh = true;
+    type: string;
+    constructor({ geometryParameters, materialParameters }?: PlaneMeshParameters);
+}

package/dist/src/objects/Poi.d.ts

@@ -0,0 +1,38 @@
+import type { InteractionEventMap } from '../interactions';
+import { BaseSprite } from './BaseSprite';
+export interface PoiParameters {
+    /** Image URL or HTMLImageElement */
+    img?: string | CanvasImageSource;
+    /** Text content */
+    text?: string;
+    /** Font size in pixels */
+    fontSize?: number;
+    /** Font family */
+    fontFamily?: string;
+    /** Text color */
+    color?: string;
+    /** Icon size in pixels (applied to the image if present) */
+    iconSize?: number;
+    /** Padding between icon and text, and around the container */
+    padding?: number;
+    /** Background color of the POI (optional) */
+    backgroundColor?: string;
+    /** Border radius for the background (optional) */
+    borderRadius?: number;
+    /** Text position relative to the icon */
+    textPosition?: 'top' | 'bottom' | 'left' | 'right';
+}
+export declare class Poi extends BaseSprite<InteractionEventMap> {
+    readonly isPoi = true;
+    type: string;
+    parameters: Required<PoiParameters>;
+    constructor(parameters?: PoiParameters);
+    /**
+     * Update the POI with new parameters
+     * @param parameters Partial POI parameters
+     */
+    updateAsync(parameters?: Partial<PoiParameters>): Promise<void>;
+    private _loadImage;
+    private _drawRoundedRect;
+    dispose(): void;
+}

package/dist/src/objects/ShapeMesh.d.ts

@@ -0,0 +1,17 @@
+import { MeshStandardNodeMaterial, ShapeGeometry, Shape, type MeshStandardNodeMaterialParameters } from 'three/webgpu';
+import type { InteractionEventMap } from '../interactions';
+import type { IPlaneVector2 } from '../interfaces';
+import { BaseMesh } from './BaseMesh';
+export interface ShapeMeshParameters {
+    geometryParameters?: {
+        shape?: Shape | Shape[];
+        curveSegments?: number;
+    };
+    materialParameters?: MeshStandardNodeMaterialParameters;
+}
+export declare class ShapeMesh extends BaseMesh<ShapeGeometry, MeshStandardNodeMaterial, InteractionEventMap> {
+    readonly isShapeMesh = true;
+    type: string;
+    constructor({ geometryParameters, materialParameters }?: ShapeMeshParameters);
+    static createFromPoints(points: IPlaneVector2[], parameters?: ShapeMeshParameters): ShapeMesh;
+}

package/dist/src/objects/SphereMesh.d.ts

@@ -0,0 +1,20 @@
+import { SphereGeometry, MeshStandardNodeMaterial, type MeshStandardNodeMaterialParameters } from 'three/webgpu';
+import type { InteractionEventMap } from '../interactions';
+import { BaseMesh } from './BaseMesh';
+export interface SphereMeshParameters {
+    geometryParameters?: {
+        radius?: number;
+        widthSegments?: number;
+        heightSegments?: number;
+        phiStart?: number;
+        phiLength?: number;
+        thetaStart?: number;
+        thetaLength?: number;
+    };
+    materialParameters?: MeshStandardNodeMaterialParameters;
+}
+export declare class SphereMesh extends BaseMesh<SphereGeometry, MeshStandardNodeMaterial, InteractionEventMap> {
+    readonly isSphereMesh = true;
+    type: string;
+    constructor({ geometryParameters, materialParameters }?: SphereMeshParameters);
+}

package/dist/src/objects/Topology.d.ts

@@ -0,0 +1,64 @@
+import { type Vector3, Group, type ColorRepresentation } from 'three/webgpu';
+import type { InteractionEventMap } from '../interactions';
+import { TubeMesh } from './TubeMesh';
+import { BaseGroup } from './BaseGroup';
+export interface TopologyParameters {
+    nodeColor?: ColorRepresentation;
+    nodeRadius?: number;
+    edgeColor?: ColorRepresentation;
+    edgeRadius?: number;
+    pathColor?: ColorRepresentation;
+    pathRadius?: number;
+}
+export declare class Topology extends BaseGroup<InteractionEventMap> {
+    readonly isTopology = true;
+    type: string;
+    parameters: Required<TopologyParameters>;
+    nodes: Map<string, Vector3>;
+    adjacencyMap: Map<string, Map<string, number>>;
+    graphGroup: Group<InteractionEventMap> | null;
+    pathMeshes: TubeMesh[];
+    constructor(parameters?: TopologyParameters);
+    /**
+     * Add a node to the topology graph.
+     * @param id Unique identifier for the node
+     * @param position 3D position of the node
+     */
+    addNode(id: string, position: Vector3): void;
+    /**
+     * Remove a node from the topology graph.
+     * @param id Unique identifier for the node
+     */
+    removeNode(id: string): void;
+    /**
+     * Add an edge between two nodes.
+     * @param from Node ID
+     * @param to Node ID
+     * @param weight Cost of the edge. Defaults to Euclidean distance.
+     * @param bidirectional If true, adds the reverse edge as well. Default true.
+     */
+    addEdge(from: string, to: string, weight?: number, bidirectional?: boolean): void;
+    /**
+     * Remove an edge between two nodes.
+     * @param from Node ID
+     * @param to Node ID
+     * @param bidirectional If true, removes the reverse edge as well. Default true.
+     */
+    removeEdge(from: string, to: string, bidirectional?: boolean): void;
+    /**
+     * Find the shortest path between start and end nodes using Dijkstra's algorithm.
+     */
+    getShortestPath(startId: string, endId: string): Vector3[];
+    /**
+     * Renders the entire topology graph structure using TubeGeometry and Spheres.
+     */
+    renderGraph(): void;
+    clearGraph(): void;
+    /**
+     * Visualizes a path using TubeGeometry (CatmullRomCurve3).
+     */
+    renderPath(points: Vector3[], color?: ColorRepresentation): TubeMesh | undefined;
+    clearPaths(): void;
+    dispose(): void;
+    getNeighbors(id: string): Map<string, number> | undefined;
+}

package/dist/src/objects/TubeMesh.d.ts

@@ -0,0 +1,18 @@
+import { TubeGeometry, MeshStandardNodeMaterial, type Vector3, type Curve, type MeshStandardNodeMaterialParameters } from 'three/webgpu';
+import type { InteractionEventMap } from '../interactions';
+import { BaseMesh } from './BaseMesh';
+export interface TubeMeshParameters {
+    geometryParameters?: {
+        path?: Curve<Vector3>;
+        tubularSegments?: number;
+        radius?: number;
+        radialSegments?: number;
+        closed?: boolean;
+    };
+    materialParameters?: MeshStandardNodeMaterialParameters;
+}
+export declare class TubeMesh extends BaseMesh<TubeGeometry, MeshStandardNodeMaterial, InteractionEventMap> {
+    readonly isTubeMesh = true;
+    type: string;
+    constructor({ geometryParameters, materialParameters }?: TubeMeshParameters);
+}

package/dist/src/objects/index.d.ts

@@ -0,0 +1,13 @@
+export * from './BaseMesh';
+export * from './BaseGroup';
+export * from './BaseSprite';
+export * from './Model';
+export * from './Topology';
+export * from './Poi';
+export * from './SphereMesh';
+export * from './TubeMesh';
+export * from './ShapeMesh';
+export * from './ExtrudeMesh';
+export * from './PlaneMesh';
+export * from './CircleMesh';
+export * from './ObjectUtils';

package/dist/src/types.d.ts

@@ -0,0 +1 @@
+export declare function reinterpretType<T>(_value: unknown): asserts _value is T;

package/dist/src/viewers/CameraControls.d.ts

@@ -0,0 +1,19 @@
+import CameraControlsBase from 'camera-controls';
+import { Box3, type Object3D } from 'three/webgpu';
+export interface FlyToBoxOptions {
+    viewpoint?: 'current' | 'top' | 'bottom' | 'front' | 'back' | 'left' | 'right' | 'frontTop' | 'backTop' | 'leftTop' | 'rightTop' | 'leftFrontTop' | 'rightFrontTop' | 'leftBackTop' | 'rightBackTop';
+    enableTransition?: boolean;
+    padding?: number;
+    cover?: boolean;
+}
+export interface FlyToObjectOptions extends FlyToBoxOptions {
+}
+export declare class CameraControls extends CameraControlsBase {
+    constructor(...args: ConstructorParameters<typeof CameraControlsBase>);
+    /**
+     * Set absolute angle for azimuth to avoid spinning
+     */
+    absoluteRotations(): void;
+    flyToBox(box: Box3, options?: FlyToBoxOptions): Promise<boolean>;
+    flyToObject(object: Object3D, options?: FlyToObjectOptions): Promise<boolean>;
+}

package/dist/src/viewers/Info.d.ts

@@ -0,0 +1,18 @@
+import { type WebGPURenderer } from 'three/webgpu';
+export declare class Info {
+    el: HTMLElement;
+    renderer: WebGPURenderer;
+    container: HTMLElement;
+    drawCallsText: HTMLElement;
+    frameCallsText: HTMLElement;
+    trianglesText: HTMLElement;
+    pointsText: HTMLElement;
+    linesText: HTMLElement;
+    timestampText: HTMLElement;
+    _enabled: boolean;
+    constructor(el: HTMLElement, renderer: WebGPURenderer);
+    update(): void;
+    enable(): void;
+    disable(): void;
+    dispose(): void;
+}

package/dist/src/viewers/RenderPipeline.d.ts

@@ -0,0 +1,17 @@
+import { type Scene, type Camera, RenderPipeline as RenderPipelineBase, type Node } from 'three/webgpu';
+type Args = [ConstructorParameters<typeof RenderPipelineBase>[0], Scene, Camera];
+export declare class RenderPipeline extends RenderPipelineBase {
+    #private;
+    scene: Scene;
+    camera: Camera;
+    currentOutputNode: Node;
+    needsUpdateOutputNode: boolean;
+    constructor(...args: Args);
+    addOverlayPass(pass: Node): void;
+    removeOverlayPass(pass: Node): void;
+    setCamera(camera: Camera): void;
+    setCurrentOutputNode(node: Node): void;
+    resetCurrentOutputNode(): void;
+    render(): void;
+}
+export {};

package/dist/src/viewers/RoomEnvironment.d.ts

@@ -0,0 +1,11 @@
+import { PMREMGenerator, type Texture, type WebGPURenderer } from 'three/webgpu';
+import { RoomEnvironment as RoomEnvironmentClass } from 'three/addons/environments/RoomEnvironment.js';
+export declare class RoomEnvironment {
+    environment: RoomEnvironmentClass;
+    renderer: WebGPURenderer;
+    pmremGenerator: PMREMGenerator;
+    envMap: Texture | null;
+    constructor(renderer: WebGPURenderer);
+    update(): void;
+    dispose(): void;
+}

package/dist/src/viewers/Viewer.d.ts

@@ -0,0 +1,59 @@
+import { EventDispatcher, WebGPURenderer, Scene, PerspectiveCamera, Timer, OrthographicCamera } from 'three/webgpu';
+import { InteractionManager } from '../interactions';
+import { ObjectManager } from '../managers';
+import { RenderPipeline } from './RenderPipeline';
+import { CameraControls } from './CameraControls';
+import { RoomEnvironment } from './RoomEnvironment';
+import { ViewerHelper } from './ViewerHelper';
+import { Info } from './Info';
+type ViewerRendererOptions = ConstructorParameters<typeof WebGPURenderer>['0'];
+export interface ViewerOptions {
+    el: HTMLElement;
+    rendererOptions?: ViewerRendererOptions;
+}
+export interface ViewerEventMap {
+    beforeControlsUpdate: {
+        time: number;
+    };
+    afterControlsUpdate: {
+        time: number;
+    };
+    beforeRender: {
+        time: number;
+    };
+    afterRender: {
+        time: number;
+    };
+    cameraChange: {
+        camera: PerspectiveCamera | OrthographicCamera;
+    };
+}
+declare class Viewer extends EventDispatcher<ViewerEventMap> {
+    el: HTMLElement;
+    renderer: WebGPURenderer;
+    scene: Scene;
+    camera: PerspectiveCamera | OrthographicCamera;
+    info: Info;
+    controls: CameraControls;
+    renderPipeline: RenderPipeline;
+    timer: Timer;
+    roomEnvironment: RoomEnvironment;
+    interactionManager: InteractionManager;
+    objectManager: ObjectManager;
+    viewerHelper: ViewerHelper;
+    frameCount: number;
+    frameloop: 'always' | 'demand';
+    constructor({ el, rendererOptions }: ViewerOptions);
+    onWindowResize: () => void;
+    init(): Promise<void>;
+    setCamera(camera: PerspectiveCamera | OrthographicCamera): void;
+    setCameraByType(type: 'perspective' | 'orthographic'): void;
+    render(frame?: number): Promise<void>;
+    private animate;
+    private _initRenderer;
+    createScene(): Scene;
+    createPerspectiveCamera(): PerspectiveCamera;
+    createOrthographicCamera(): OrthographicCamera;
+    dispose(): void;
+}
+export { Viewer };

package/dist/src/viewers/ViewerHelper.d.ts

@@ -0,0 +1,12 @@
+import { type PassNode } from 'three/webgpu';
+import { ViewHelper as ViewHelperBase } from 'three/addons/helpers/ViewHelper.js';
+import type { Viewer } from './Viewer';
+declare class ViewerHelper extends ViewHelperBase {
+    viewer: Viewer;
+    overlayPass: PassNode;
+    constructor(viewer: Viewer);
+    _update: () => void;
+    enable(): this;
+    disable(): this;
+}
+export { ViewerHelper };

package/dist/src/viewers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './Viewer';
+export * from './RoomEnvironment';
+export * from './CameraControls';

package/docs/api-interactions.md

@@ -0,0 +1,64 @@
+# Interactions API
+
+The `InteractionManager` provides a unified way to handle user input (mouse, touch, pointer) over 3D scenes. It resolves the raycasting from screen space to world space and dispatches corresponding events directly directly to the intersected 3D objects.
+
+The `InteractionManager` is automatically instantiated within the `Viewer` at `viewer.interactionManager`.
+
+## Enabling Interaction Events
+
+By default, pointer move events might be disabled for performance reasons. You need to enable them if you want hover and drag effects. This should be explicitly set for interactive applications.
+
+```typescript
+// Enable events on mouse move (like pointerenter and pointerleave)
+viewer.interactionManager.pointerMoveEventsEnabled = true;
+```
+
+### Targeting Objects
+
+You can limit which objects the raycaster checks.
+
+```typescript
+// Default behavior: checks the entire scene
+viewer.interactionManager.targetObjects = [];
+
+// Check only specific objects
+// viewer.interactionManager.targetObjects = [myBox, myModel];
+```
+
+## Adding Event Listeners
+
+Because `u-space` objects (and `BaseMesh`, `BaseGroup` by extension) support custom events, you can attach listeners natively just like a DOM element.
+
+```typescript
+const myBox = new Mesh(geometry, material);
+viewer.scene.add(myBox);
+
+// Example listener attached directly to the 'Mesh' or 'Model'
+myBox.addEventListener('click', (eventData) => {
+  // The underlying pointer event and raycast intersection information
+  const intersect = eventData.event.intersect;
+
+  console.log('Clicked at position:', intersect.point);
+});
+```
+
+## Supported Events
+
+The following event types can be listened to on interactive objects:
+
+- `click`: Fired when the pointer clicks on an object.
+- `dblclick`: Fired when the object is double-clicked rapidly.
+- `pointerdown`: Fired when a pointer button is depressed over an object.
+- `pointerup`: Fired when a pointer button is released, generally following a `pointerdown`.
+- `pointerenter`: Fired when the cursor or pointer enters the boundaries of an object.
+- `pointerleave`: Fired when the cursor or pointer leaves the boundaries of an object.
+
+### Event Propagation
+
+To stop an event from continuing to pass through the intersection hierarchy (e.g., clicking on a model inside a larger bounding box), you can stop its propagation using the event payload:
+
+```typescript
+myObject.addEventListener('click', (e) => {
+  e.event.stopPropagation();
+});
+```

package/docs/api-managers.md

@@ -0,0 +1,54 @@
+# Managers API
+
+`u-space` utilizes specialized managers for handling specific domain logic, such as `ObjectManager` for caching and registering 3D objects.
+
+## ObjectManager
+
+The `ObjectManager` provides a centralized dictionary/map layer to easily retrieve complex models or specific meshes by string IDs or string names without having to recursively traverse the Three.js scene graph.
+
+The default instance is available via `viewer.objectManager`.
+
+### Adding Objects
+
+When you add an object to the manager, you must provide a unique identifier.
+
+```typescript
+const myModel = new Model();
+// ... load logic
+
+// Add with a specific unique ID
+viewer.objectManager.add('my-unique-car-id', myModel);
+
+// An object can be registered under multiple IDs
+viewer.objectManager.add('player-vehicle', myModel);
+```
+
+### Retrieving Objects
+
+The manager gives you fast access to your objects.
+
+#### `getById(id: string)`
+
+Retrieves exactly one object (or `undefined`) matching the specific ID.
+
+```typescript
+const car = viewer.objectManager.getById('my-unique-car-id');
+```
+
+#### `getByName(name: string)`
+
+Because Three.js objects can share the same `.name` property, this method returns a `Set<Object3D>` encompassing all registered objects that match the requested name.
+
+```typescript
+// Assuming myModel.name = 'sedan'
+const sedans = viewer.objectManager.getByName('sedan');
+
+sedans.forEach((vehicle) => {
+  vehicle.position.y += 10;
+});
+```
+
+### Utility Methods
+
+- `getAll()`: Returns all tracked objects.
+- `size`: Returns the total number of objects currently tracked by the manager.

package/docs/api-objects.md

@@ -0,0 +1,65 @@
+# Objects API
+
+`u-space` provides several object wrappers that make manipulating and loading 3D assets easier, primarily extending Three.js's basic nodes.
+
+## Models
+
+The `Model` class extends `BaseGroup` (which in turn extends `THREE.Group`) and simplifies the process of asynchronously loading external 3D models like `glb` and `gltf` files. It features built-in support for different caching layers.
+
+```typescript
+import { Model } from 'u-space';
+
+const myModel = new Model();
+```
+
+### Loading Assets
+
+The `loadAsync` method handles loading the asset from a URL and adding it to the group.
+
+```typescript
+await myModel.loadAsync(options: ModelLoadOptions)
+```
+
+#### `ModelLoadOptions`
+
+| Property     | Type      | Description                                                                                                                      |
+| :----------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------- |
+| `url`        | `string`  | The URL of the `.gltf` or `.glb` file.                                                                                           |
+| `cache`      | `boolean` | (Optional) Enables in-memory caching. If a model has been loaded before, it retrieves it instantly from memory. Default `false`. |
+| `persistent` | `boolean` | (Optional) Enables persistent disk-level caching using the browser's Cache API. Good for larger models. Default `false`.         |
+
+#### Caching Example
+
+```javascript
+// Load a model from network and persist it
+const model1 = new Model();
+model1.loadAsync({ url: 'model.glb', persistent: true });
+
+// Sometime later, this will load from Cache API
+const model2 = new Model();
+model2.loadAsync({ url: 'model.glb', persistent: true });
+
+// This will load from fast Memory Cache
+const model3 = new Model();
+model3.loadAsync({ url: 'model.glb', cache: true, persistent: true });
+```
+
+### Clearing Caches
+
+You can manually clear the internal caches using static methods on the `Model` class:
+
+- `Model.clearMemoryCache()`: Clears the transient runtime memory cache.
+- `await Model.clearPersistentCache()`: Completely clears the browser's persistent cache for `u-space` models.
+
+## Meshes
+
+`u-space` offers a variety of streamlined Mesh classes extending `BaseMesh`. These can be used to quickly construct common 3D shapes without needing to supply geometries or materials right away. They also include built-in interaction event dispatching.
+
+- `CircleMesh`
+- `ExtrudeMesh`
+- `PlaneMesh`
+- `ShapeMesh`
+- `SphereMesh`
+- `TubeMesh`
+
+These are often initialized directly depending on their specific properties (usually extending `THREE.Mesh` parameters and geometries).

package/docs/api-plugins.md

@@ -0,0 +1,103 @@
+# Plugins API
+
+`u-space` architecture includes a rich set of plugins for advanced features, ranging from GIS tile loading to keyboard controls and scene management. These are imported from the `u-space/plugins/*` namespace.
+
+## Available Plugins
+
+### `keyboard-controls`
+
+Provides WASD or directional arrow-key translation and rotation for the active camera.
+
+```typescript
+import { KeyboardControls, ACTION } from 'u-space/plugins/keyboard-controls';
+
+const keyboardControls = new KeyboardControls(viewer);
+
+// Optional: Customize movement speeds
+// keyboardControls.moveDistanceDelta = 2;
+// keyboardControls.rotateAngleDelta = (Math.PI / 180) * 2;
+
+// Activate the listeners
+keyboardControls.enable();
+```
+
+### `minimap`
+
+Generates a customizable 2D minimap tracking a specific target object within the 3D scene.
+
+```typescript
+import { Minimap } from 'u-space/plugins/minimap';
+
+const minimap = new Minimap(viewer);
+minimap.target = myCharacterModel;
+minimap.setSize(600, 200);
+
+// Style the underlying minimap scene
+minimap.scene.background = new THREE.Color(0xffffff);
+
+minimap.enable();
+```
+
+### `tiles`
+
+Provides integration with `3d-tiles-renderer` and geospatial data (like ArcGIS).
+
+```typescript
+import { ArcgisTilesRenderer } from 'u-space/plugins/tiles';
+
+const arcgisTilesRenderer = new ArcgisTilesRenderer(viewer);
+
+// Pass longitude, latitude, and zoom level
+arcgisTilesRenderer.invalidate(120.002269, 30.284849, 4);
+arcgisTilesRenderer.enable();
+```
+
+### `u-manager`
+
+`u-manager` is a comprehensive suite of tools for loading, parsing, and managing complex scene scenarios, properties, visons (camera viewpoints), and animations.
+
+#### Loaders
+
+`u-manager` provides loaders to stream various structured data from a defined base path.
+
+```typescript
+import { SceneLoader, TopologiesLoader } from 'u-space/plugins/u-manager';
+
+// Topology loader for multiple models
+const topologiesLoader = new TopologiesLoader();
+topologiesLoader.setPath('./scenes/my-scene');
+const topologies = await topologiesLoader.loadAsync();
+viewer.scene.add(...topologies);
+
+// Comprehensive Scene loader
+const sceneLoader = new SceneLoader(viewer);
+sceneLoader.setPath('./scenes/my-scene');
+const group = await sceneLoader.loadAsync();
+viewer.scene.add(group);
+```
+
+#### Parsers
+
+Parsers take the data retrieved by Loaders and execute specific logic in the viewport.
+
+```typescript
+import { VisionsLoader, VisionsParser } from 'u-space/plugins/u-manager';
+
+// Load viewpoints
+const visionsLoader = new VisionsLoader(viewer);
+visionsLoader.setPath('./scenes/my-scene');
+const visions = await visionsLoader.loadAsync();
+
+// Parse and execute camera movement
+const visionsParser = new VisionsParser(viewer);
+// Assuming the loader returned an array of states for key 'HOME'
+await visionsParser.flyTo(visions['HOME'][0]);
+```
+
+### Other Plugins
+
+The plugins directory also includes:
+
+- `atmosphere`: For sky rendering.
+- `curve-movement`: For animating objects along predefined paths or splines.
+- `tracking-controls`: Specialized controls for observing moving targets.