@unrdf/spatial-kg 26.4.2

package/src/lod-manager.mjs

@@ -0,0 +1,209 @@
+/**
+ * @file Level-of-Detail Manager
+ * @module @unrdf/spatial-kg/lod-manager
+ * @description Optimize rendering with distance-based LOD
+ */
+
+import { LODLevelSchema, SpatialGraphConfigSchema } from './schemas.mjs';
+import { trace } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('@unrdf/spatial-kg/lod-manager');
+
+/**
+ * LOD Manager
+ */
+export class LODManager {
+  /**
+   * @param {Object} config - LOD configuration
+   */
+  constructor(config = {}) {
+    const validated = SpatialGraphConfigSchema.parse({ lod: config });
+    this.config = validated.lod;
+    this.nodeLevels = new Map();
+    this.cameraPosition = { x: 0, y: 0, z: 0 };
+  }
+
+  /**
+   * Update camera position
+   * @param {Object} position - Camera position {x, y, z}
+   * @returns {void}
+   */
+  updateCamera(position) {
+    this.cameraPosition = { ...position };
+  }
+
+  /**
+   * Calculate LOD level for node
+   * @param {Object} node - Node with position
+   * @returns {number} LOD level (0=high, 1=medium, 2=low)
+   */
+  calculateLevel(node) {
+    if (!this.config.enabled) return 0;
+
+    const dx = node.position.x - this.cameraPosition.x;
+    const dy = node.position.y - this.cameraPosition.y;
+    const dz = node.position.z - this.cameraPosition.z;
+    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    // Find appropriate LOD level
+    for (let i = 0; i < this.config.levels.length; i++) {
+      if (distance < this.config.levels[i].distance) {
+        return i;
+      }
+    }
+
+    return this.config.levels.length - 1;
+  }
+
+  /**
+   * Update all node LOD levels
+   * @param {Map<string, Object>} nodes - All graph nodes
+   * @returns {Array<Object>} Nodes that changed LOD level
+   */
+  updateLevels(nodes) {
+    return tracer.startActiveSpan('lod.update-levels', span => {
+      try {
+        const changes = [];
+
+        for (const [id, node] of nodes) {
+          const newLevel = this.calculateLevel(node);
+          const oldLevel = this.nodeLevels.get(id);
+
+          if (oldLevel !== newLevel) {
+            const dx = node.position.x - this.cameraPosition.x;
+            const dy = node.position.y - this.cameraPosition.y;
+            const dz = node.position.z - this.cameraPosition.z;
+            const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+            const change = LODLevelSchema.parse({
+              nodeId: id,
+              currentLevel: newLevel,
+              distance,
+              shouldUpdate: true,
+            });
+
+            changes.push(change);
+            this.nodeLevels.set(id, newLevel);
+          }
+        }
+
+        span.setAttributes({
+          'lod.changes': changes.length,
+          'lod.total_nodes': nodes.size,
+        });
+
+        return changes;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Get LOD level for node
+   * @param {string} nodeId - Node ID
+   * @returns {number} LOD level
+   */
+  getLevel(nodeId) {
+    return this.nodeLevels.get(nodeId) || 0;
+  }
+
+  /**
+   * Get complexity for LOD level
+   * @param {number} level - LOD level
+   * @returns {string} Complexity ('high', 'medium', 'low')
+   */
+  getComplexity(level) {
+    if (level >= this.config.levels.length) {
+      return this.config.levels[this.config.levels.length - 1].complexity;
+    }
+    return this.config.levels[level].complexity;
+  }
+
+  /**
+   * Get all nodes at LOD level
+   * @param {number} level - LOD level
+   * @returns {Array<string>} Node IDs
+   */
+  getNodesAtLevel(level) {
+    const nodes = [];
+    for (const [id, nodeLevel] of this.nodeLevels) {
+      if (nodeLevel === level) {
+        nodes.push(id);
+      }
+    }
+    return nodes;
+  }
+
+  /**
+   * Get LOD statistics
+   * @returns {Object} Statistics
+   */
+  getStats() {
+    const stats = {
+      enabled: this.config.enabled,
+      levels: {},
+      total: this.nodeLevels.size,
+    };
+
+    for (let i = 0; i < this.config.levels.length; i++) {
+      const count = this.getNodesAtLevel(i).length;
+      stats.levels[i] = {
+        count,
+        complexity: this.getComplexity(i),
+        distance: this.config.levels[i].distance,
+      };
+    }
+
+    return stats;
+  }
+
+  /**
+   * Reset LOD state
+   * @returns {void}
+   */
+  reset() {
+    this.nodeLevels.clear();
+    this.cameraPosition = { x: 0, y: 0, z: 0 };
+  }
+
+  /**
+   * Determine if node should be rendered
+   * @param {string} nodeId - Node ID
+   * @param {Object} _frustum - Camera frustum (optional)
+   * @returns {boolean} Should render
+   */
+  shouldRender(nodeId, _frustum = null) {
+    const level = this.getLevel(nodeId);
+
+    // Always render high detail
+    if (level === 0) return true;
+
+    // Medium detail - render 50%
+    if (level === 1) {
+      const hash = this._hashString(nodeId);
+      return hash % 2 === 0;
+    }
+
+    // Low detail - render 25%
+    if (level === 2) {
+      const hash = this._hashString(nodeId);
+      return hash % 4 === 0;
+    }
+
+    return false;
+  }
+
+  /**
+   * Simple string hash for deterministic culling
+   * @private
+   */
+  _hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      hash = (hash << 5) - hash + str.charCodeAt(i);
+      hash = hash & hash;
+    }
+    return Math.abs(hash);
+  }
+}

package/src/schemas.mjs

@@ -0,0 +1,161 @@
+/**
+ * @file Zod schemas for Spatial Knowledge Graph
+ * @module @unrdf/spatial-kg/schemas
+ */
+
+import { z } from 'zod';
+
+/**
+ * Vector3 schema
+ */
+export const Vector3Schema = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  z: z.number().finite(),
+});
+
+/**
+ * Node3D schema
+ */
+export const Node3DSchema = z.object({
+  id: z.string().min(1),
+  uri: z.string().optional(),
+  label: z.string().optional(),
+  position: Vector3Schema,
+  velocity: Vector3Schema.optional(),
+  mass: z.number().positive().default(1),
+  fixed: z.boolean().default(false),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Edge3D schema
+ */
+export const Edge3DSchema = z.object({
+  id: z.string().min(1),
+  source: z.string().min(1),
+  target: z.string().min(1),
+  predicate: z.string().optional(),
+  strength: z.number().min(0).max(1).default(1),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Spatial graph configuration
+ */
+export const SpatialGraphConfigSchema = z.object({
+  layout: z
+    .object({
+      iterations: z.number().int().positive().default(100),
+      cooldown: z.number().min(0).max(1).default(0.95),
+      repulsionStrength: z.number().positive().default(100),
+      attractionStrength: z.number().positive().default(0.1),
+      gravityStrength: z.number().nonnegative().default(0.01),
+      centerForce: z.boolean().default(true),
+      dimensions: z.literal(3).default(3),
+    })
+    .default({}),
+  rendering: z
+    .object({
+      targetFPS: z.number().int().positive().default(60),
+      enableVR: z.boolean().default(false),
+      enableAR: z.boolean().default(false),
+      nodeSize: z.number().positive().default(1),
+      edgeWidth: z.number().positive().default(0.1),
+      backgroundColor: z.number().int().default(0x000000),
+    })
+    .default({}),
+  lod: z
+    .object({
+      enabled: z.boolean().default(true),
+      levels: z
+        .array(
+          z.object({
+            distance: z.number().positive(),
+            complexity: z.enum(['high', 'medium', 'low']),
+          })
+        )
+        .default([
+          { distance: 10, complexity: 'high' },
+          { distance: 50, complexity: 'medium' },
+          { distance: 100, complexity: 'low' },
+        ]),
+    })
+    .default({}),
+  collaboration: z
+    .object({
+      enabled: z.boolean().default(false),
+      serverUrl: z.string().url().optional(),
+      username: z.string().optional(),
+    })
+    .default({}),
+});
+
+/**
+ * Spatial query options
+ */
+export const SpatialQueryOptionsSchema = z.object({
+  type: z.enum(['proximity', 'ray', 'knn', 'box', 'sphere']),
+  origin: Vector3Schema.optional(),
+  direction: Vector3Schema.optional(),
+  radius: z.number().positive().optional(),
+  k: z.number().int().positive().optional(),
+  bounds: z
+    .object({
+      min: Vector3Schema,
+      max: Vector3Schema,
+    })
+    .optional(),
+});
+
+/**
+ * Gesture event schema
+ */
+export const GestureEventSchema = z.object({
+  type: z.enum(['point', 'grab', 'teleport', 'select', 'pinch']),
+  controller: z.enum(['left', 'right', 'hand-left', 'hand-right']),
+  position: Vector3Schema.optional(),
+  target: z.string().optional(),
+  timestamp: z.number().int().positive(),
+  intensity: z.number().min(0).max(1).optional(),
+});
+
+/**
+ * Collaboration state schema
+ */
+export const CollaborationStateSchema = z.object({
+  userId: z.string().min(1),
+  position: Vector3Schema,
+  rotation: z.object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    z: z.number().finite(),
+    w: z.number().finite(),
+  }),
+  selectedNode: z.string().optional(),
+  timestamp: z.number().int().positive(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * LOD level schema
+ */
+export const LODLevelSchema = z.object({
+  nodeId: z.string().min(1),
+  currentLevel: z.number().int().min(0).max(2),
+  distance: z.number().nonnegative(),
+  shouldUpdate: z.boolean(),
+});
+
+/**
+ * Performance metrics schema
+ */
+export const PerformanceMetricsSchema = z.object({
+  fps: z.number().nonnegative(),
+  frameTime: z.number().nonnegative(),
+  nodeCount: z.number().int().nonnegative(),
+  edgeCount: z.number().int().nonnegative(),
+  renderTime: z.number().nonnegative(),
+  layoutTime: z.number().nonnegative(),
+  timestamp: z.number().int().positive(),
+});

package/src/spatial-kg-engine.mjs

@@ -0,0 +1,264 @@
+/**
+ * @file Spatial Knowledge Graph Engine
+ * @module @unrdf/spatial-kg
+ * @description Main orchestration engine for spatial knowledge graphs
+ */
+
+import { Layout3D } from './layout-3d.mjs';
+import { WebXRRenderer } from './webxr-renderer.mjs';
+import { SpatialQueryEngine } from './spatial-query.mjs';
+import { GestureController } from './gesture-controller.mjs';
+import { LODManager } from './lod-manager.mjs';
+import { CollaborationManager } from './collaboration.mjs';
+import { SpatialGraphConfigSchema } from './schemas.mjs';
+import { trace } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('@unrdf/spatial-kg');
+
+/**
+ * Spatial Knowledge Graph Engine
+ */
+export class SpatialKGEngine {
+  /**
+   * @param {Object} config - Engine configuration
+   */
+  constructor(config = {}) {
+    this.config = SpatialGraphConfigSchema.parse(config);
+
+    // Core components
+    this.layout = new Layout3D(this.config.layout);
+    this.renderer = new WebXRRenderer(this.config.rendering);
+    this.queryEngine = null; // Created after layout
+    this.gestureController = new GestureController();
+    this.lodManager = new LODManager(this.config.lod);
+    this.collaboration = null;
+
+    // State
+    this.running = false;
+    this.animationFrame = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize engine
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    return tracer.startActiveSpan('engine.initialize', async span => {
+      try {
+        await this.renderer.initialize();
+
+        // Setup collaboration if enabled
+        if (this.config.collaboration.enabled) {
+          this.collaboration = new CollaborationManager({
+            userId: this.config.collaboration.username || 'user-' + Date.now(),
+            serverUrl: this.config.collaboration.serverUrl,
+          });
+          await this.collaboration.connect();
+        }
+
+        this.initialized = true;
+
+        span.setAttributes({
+          'engine.initialized': true,
+          'engine.collaboration': this.config.collaboration.enabled,
+        });
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Load graph data
+   * @param {Object} data - Graph data
+   * @param {Array<Object>} data.nodes - Node list
+   * @param {Array<Object>} data.edges - Edge list
+   * @returns {Promise<void>}
+   */
+  async loadGraph(data) {
+    return tracer.startActiveSpan('engine.load-graph', async span => {
+      try {
+        // Add nodes to layout
+        for (const node of data.nodes) {
+          this.layout.addNode(node);
+        }
+
+        // Add edges to layout
+        for (const edge of data.edges) {
+          this.layout.addEdge(edge);
+        }
+
+        // Run initial layout
+        await this.layout.run();
+
+        // Initialize query engine with node positions
+        this.queryEngine = new SpatialQueryEngine(this.layout.nodes);
+
+        // Update renderer
+        this.renderer.updateNodes(this.layout.nodes);
+        this.renderer.updateEdges(this.layout.edges, this.layout.nodes);
+
+        span.setAttributes({
+          'graph.nodes': data.nodes.length,
+          'graph.edges': data.edges.length,
+        });
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Start rendering loop
+   * @returns {void}
+   */
+  start() {
+    if (!this.initialized) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+
+    this.running = true;
+    this._renderLoop();
+  }
+
+  /**
+   * Stop rendering loop
+   * @returns {void}
+   */
+  stop() {
+    this.running = false;
+    if (this.animationFrame && typeof globalThis.cancelAnimationFrame !== 'undefined') {
+      globalThis.cancelAnimationFrame(this.animationFrame);
+      this.animationFrame = null;
+    }
+  }
+
+  /**
+   * Main render loop
+   * @private
+   */
+  _renderLoop() {
+    if (!this.running) return;
+
+    tracer.startActiveSpan('engine.render-loop', span => {
+      try {
+        // Update LOD based on camera
+        const cameraPos = this.renderer.getCameraPosition();
+        this.lodManager.updateCamera(cameraPos);
+        this.lodManager.updateLevels(this.layout.nodes);
+
+        // Update renderer
+        this.renderer.updateNodes(this.layout.nodes);
+
+        // Render frame
+        this.renderer.render();
+
+        // Update collaboration state
+        if (this.collaboration?.isConnected()) {
+          this.collaboration.updateLocalState({
+            position: cameraPos,
+            rotation: { x: 0, y: 0, z: 0, w: 1 }, // Placeholder
+          });
+        }
+
+        const metrics = this.renderer.getMetrics();
+        span.setAttributes({
+          'engine.fps': metrics.fps,
+          'engine.frameTime': metrics.frameTime,
+        });
+      } finally {
+        span.end();
+      }
+    });
+
+    if (typeof globalThis.requestAnimationFrame !== 'undefined') {
+      this.animationFrame = globalThis.requestAnimationFrame(() => this._renderLoop());
+    }
+  }
+
+  /**
+   * Query nodes spatially
+   * @param {Object} options - Query options
+   * @returns {Array<Object>} Query results
+   */
+  query(options) {
+    if (!this.queryEngine) {
+      throw new Error('No graph loaded. Call loadGraph() first.');
+    }
+
+    const { type } = options;
+
+    switch (type) {
+      case 'proximity':
+        return this.queryEngine.proximity(options);
+      case 'ray':
+        return this.queryEngine.rayCast(options);
+      case 'knn':
+        return this.queryEngine.kNearestNeighbors(options);
+      case 'box':
+        return this.queryEngine.box(options);
+      default:
+        throw new Error(`Unknown query type: ${type}`);
+    }
+  }
+
+  /**
+   * Start WebXR session
+   * @param {string} mode - 'immersive-vr' or 'immersive-ar'
+   * @returns {Promise<void>}
+   */
+  async startXR(mode) {
+    await this.renderer.startXRSession(mode);
+  }
+
+  /**
+   * End WebXR session
+   * @returns {Promise<void>}
+   */
+  async endXR() {
+    await this.renderer.endXRSession();
+  }
+
+  /**
+   * Register gesture listener
+   * @param {string} gestureType - Gesture type
+   * @param {Function} callback - Event handler
+   * @returns {Function} Unsubscribe function
+   */
+  onGesture(gestureType, callback) {
+    return this.gestureController.on(gestureType, callback);
+  }
+
+  /**
+   * Get performance metrics
+   * @returns {Object} Metrics
+   */
+  getMetrics() {
+    return {
+      rendering: this.renderer.getMetrics(),
+      lod: this.lodManager.getStats(),
+      layout: {
+        iteration: this.layout.iteration,
+        temperature: this.layout.temperature,
+        nodes: this.layout.nodes.size,
+        edges: this.layout.edges.length,
+      },
+      collaboration: this.collaboration?.getStats() || null,
+    };
+  }
+
+  /**
+   * Dispose engine and cleanup resources
+   * @returns {void}
+   */
+  dispose() {
+    this.stop();
+    this.renderer.dispose();
+    this.gestureController.clear();
+    this.lodManager.reset();
+    if (this.collaboration) {
+      this.collaboration.disconnect();
+    }
+  }
+}