@unrdf/spatial-kg 26.4.2

package/src/spatial-query.mjs

@@ -0,0 +1,429 @@
+/**
+ * @file Spatial Query Engine
+ * @module @unrdf/spatial-kg/spatial-query
+ * @description Spatial queries for 3D knowledge graphs (proximity, ray casting, k-NN)
+ */
+
+import { SpatialQueryOptionsSchema } from './schemas.mjs';
+import { trace } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('@unrdf/spatial-kg/spatial-query');
+
+/**
+ * Octree node for spatial indexing
+ * @private
+ */
+class OctreeNode {
+  constructor(bounds, capacity = 8) {
+    this.bounds = bounds;
+    this.capacity = capacity;
+    this.nodes = [];
+    this.divided = false;
+    this.children = null;
+  }
+
+  /**
+   * Check if point is in bounds
+   */
+  contains(point) {
+    return (
+      point.x >= this.bounds.min.x &&
+      point.x <= this.bounds.max.x &&
+      point.y >= this.bounds.min.y &&
+      point.y <= this.bounds.max.y &&
+      point.z >= this.bounds.min.z &&
+      point.z <= this.bounds.max.z
+    );
+  }
+
+  /**
+   * Insert node into octree
+   */
+  insert(node) {
+    if (!this.contains(node.position)) return false;
+
+    if (this.nodes.length < this.capacity) {
+      this.nodes.push(node);
+      return true;
+    }
+
+    if (!this.divided) {
+      this._subdivide();
+    }
+
+    for (const child of this.children) {
+      if (child.insert(node)) return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Subdivide into 8 octants
+   * @private
+   */
+  _subdivide() {
+    const { min, max } = this.bounds;
+    const midX = (min.x + max.x) / 2;
+    const midY = (min.y + max.y) / 2;
+    const midZ = (min.z + max.z) / 2;
+
+    this.children = [
+      // Front quadrants
+      new OctreeNode(
+        { min: { x: min.x, y: min.y, z: min.z }, max: { x: midX, y: midY, z: midZ } },
+        this.capacity
+      ),
+      new OctreeNode(
+        { min: { x: midX, y: min.y, z: min.z }, max: { x: max.x, y: midY, z: midZ } },
+        this.capacity
+      ),
+      new OctreeNode(
+        { min: { x: min.x, y: midY, z: min.z }, max: { x: midX, y: max.y, z: midZ } },
+        this.capacity
+      ),
+      new OctreeNode(
+        { min: { x: midX, y: midY, z: min.z }, max: { x: max.x, y: max.y, z: midZ } },
+        this.capacity
+      ),
+      // Back quadrants
+      new OctreeNode(
+        { min: { x: min.x, y: min.y, z: midZ }, max: { x: midX, y: midY, z: max.z } },
+        this.capacity
+      ),
+      new OctreeNode(
+        { min: { x: midX, y: min.y, z: midZ }, max: { x: max.x, y: midY, z: max.z } },
+        this.capacity
+      ),
+      new OctreeNode(
+        { min: { x: min.x, y: midY, z: midZ }, max: { x: midX, y: max.y, z: max.z } },
+        this.capacity
+      ),
+      new OctreeNode(
+        { min: { x: midX, y: midY, z: midZ }, max: { x: max.x, y: max.y, z: max.z } },
+        this.capacity
+      ),
+    ];
+
+    this.divided = true;
+
+    // Redistribute existing nodes
+    for (const existingNode of this.nodes) {
+      for (const child of this.children) {
+        if (child.insert(existingNode)) break;
+      }
+    }
+    this.nodes = [];
+  }
+
+  /**
+   * Query nodes in range
+   */
+  query(bounds, found = []) {
+    if (!this._intersects(bounds)) return found;
+
+    for (const node of this.nodes) {
+      if (this._pointInBounds(node.position, bounds)) {
+        found.push(node);
+      }
+    }
+
+    if (this.divided) {
+      for (const child of this.children) {
+        child.query(bounds, found);
+      }
+    }
+
+    return found;
+  }
+
+  /**
+   * Check if bounds intersect
+   * @private
+   */
+  _intersects(bounds) {
+    return !(
+      bounds.max.x < this.bounds.min.x ||
+      bounds.min.x > this.bounds.max.x ||
+      bounds.max.y < this.bounds.min.y ||
+      bounds.min.y > this.bounds.max.y ||
+      bounds.max.z < this.bounds.min.z ||
+      bounds.min.z > this.bounds.max.z
+    );
+  }
+
+  /**
+   * Check if point in bounds
+   * @private
+   */
+  _pointInBounds(point, bounds) {
+    return (
+      point.x >= bounds.min.x &&
+      point.x <= bounds.max.x &&
+      point.y >= bounds.min.y &&
+      point.y <= bounds.max.y &&
+      point.z >= bounds.min.z &&
+      point.z <= bounds.max.z
+    );
+  }
+}
+
+/**
+ * Spatial Query Engine
+ */
+export class SpatialQueryEngine {
+  /**
+   * @param {Map<string, Object>} nodes - Graph nodes with positions
+   */
+  constructor(nodes = new Map()) {
+    this.nodes = nodes;
+    this.octree = null;
+    this._buildOctree();
+  }
+
+  /**
+   * Build octree spatial index
+   * @private
+   */
+  _buildOctree() {
+    if (this.nodes.size === 0) {
+      this.octree = null;
+      return;
+    }
+
+    // Calculate bounds
+    let minX = Infinity,
+      minY = Infinity,
+      minZ = Infinity;
+    let maxX = -Infinity,
+      maxY = -Infinity,
+      maxZ = -Infinity;
+
+    for (const node of this.nodes.values()) {
+      minX = Math.min(minX, node.position.x);
+      minY = Math.min(minY, node.position.y);
+      minZ = Math.min(minZ, node.position.z);
+      maxX = Math.max(maxX, node.position.x);
+      maxY = Math.max(maxY, node.position.y);
+      maxZ = Math.max(maxZ, node.position.z);
+    }
+
+    // Add padding
+    const padding = 10;
+    const bounds = {
+      min: { x: minX - padding, y: minY - padding, z: minZ - padding },
+      max: { x: maxX + padding, y: maxY + padding, z: maxZ + padding },
+    };
+
+    this.octree = new OctreeNode(bounds);
+
+    // Insert all nodes
+    for (const node of this.nodes.values()) {
+      this.octree.insert(node);
+    }
+  }
+
+  /**
+   * Proximity query - find nodes within radius
+   * @param {Object} options - Query options
+   * @param {Object} options.origin - Center point
+   * @param {number} options.radius - Search radius
+   * @returns {Array<Object>} Nodes within radius
+   */
+  proximity(options) {
+    return tracer.startActiveSpan('spatial-query.proximity', span => {
+      try {
+        const { origin, radius } = SpatialQueryOptionsSchema.parse({
+          type: 'proximity',
+          ...options,
+        });
+
+        if (!this.octree) return [];
+
+        // Query octree with bounding box
+        const bounds = {
+          min: {
+            x: origin.x - radius,
+            y: origin.y - radius,
+            z: origin.z - radius,
+          },
+          max: {
+            x: origin.x + radius,
+            y: origin.y + radius,
+            z: origin.z + radius,
+          },
+        };
+
+        const candidates = this.octree.query(bounds);
+
+        // Filter by actual distance
+        const results = candidates.filter(node => {
+          const dx = node.position.x - origin.x;
+          const dy = node.position.y - origin.y;
+          const dz = node.position.z - origin.z;
+          const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+          return dist <= radius;
+        });
+
+        span.setAttributes({
+          'query.type': 'proximity',
+          'query.candidates': candidates.length,
+          'query.results': results.length,
+          'query.radius': radius,
+        });
+
+        return results;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Ray casting query - find nodes along ray
+   * @param {Object} options - Query options
+   * @param {Object} options.origin - Ray origin
+   * @param {Object} options.direction - Ray direction (normalized)
+   * @param {number} [options.radius=1] - Ray thickness
+   * @returns {Array<Object>} Nodes intersecting ray
+   */
+  rayCast(options) {
+    return tracer.startActiveSpan('spatial-query.raycast', span => {
+      try {
+        const {
+          origin,
+          direction,
+          radius = 1,
+        } = SpatialQueryOptionsSchema.parse({
+          type: 'ray',
+          ...options,
+        });
+
+        const results = [];
+
+        for (const node of this.nodes.values()) {
+          // Vector from origin to node
+          const toNode = {
+            x: node.position.x - origin.x,
+            y: node.position.y - origin.y,
+            z: node.position.z - origin.z,
+          };
+
+          // Project onto ray direction
+          const projection =
+            toNode.x * direction.x + toNode.y * direction.y + toNode.z * direction.z;
+
+          if (projection < 0) continue; // Behind ray
+
+          // Closest point on ray
+          const closest = {
+            x: origin.x + direction.x * projection,
+            y: origin.y + direction.y * projection,
+            z: origin.z + direction.z * projection,
+          };
+
+          // Distance from node to ray
+          const dx = node.position.x - closest.x;
+          const dy = node.position.y - closest.y;
+          const dz = node.position.z - closest.z;
+          const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+          if (dist <= radius) {
+            results.push({ node, distance: projection });
+          }
+        }
+
+        // Sort by distance along ray
+        results.sort((a, b) => a.distance - b.distance);
+
+        span.setAttributes({
+          'query.type': 'raycast',
+          'query.results': results.length,
+        });
+
+        return results.map(r => r.node);
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * K-nearest neighbors query
+   * @param {Object} options - Query options
+   * @param {Object} options.origin - Query point
+   * @param {number} options.k - Number of neighbors
+   * @returns {Array<Object>} K nearest nodes
+   */
+  kNearestNeighbors(options) {
+    return tracer.startActiveSpan('spatial-query.knn', span => {
+      try {
+        const { origin, k } = SpatialQueryOptionsSchema.parse({
+          type: 'knn',
+          ...options,
+        });
+
+        const distances = [];
+
+        for (const node of this.nodes.values()) {
+          const dx = node.position.x - origin.x;
+          const dy = node.position.y - origin.y;
+          const dz = node.position.z - origin.z;
+          const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+          distances.push({ node, distance: dist });
+        }
+
+        distances.sort((a, b) => a.distance - b.distance);
+        const results = distances.slice(0, k).map(d => d.node);
+
+        span.setAttributes({
+          'query.type': 'knn',
+          'query.k': k,
+          'query.results': results.length,
+        });
+
+        return results;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Box query - find nodes in bounding box
+   * @param {Object} options - Query options
+   * @param {Object} options.bounds - Bounding box {min, max}
+   * @returns {Array<Object>} Nodes in box
+   */
+  box(options) {
+    return tracer.startActiveSpan('spatial-query.box', span => {
+      try {
+        const { bounds } = SpatialQueryOptionsSchema.parse({
+          type: 'box',
+          ...options,
+        });
+
+        if (!this.octree) return [];
+
+        const results = this.octree.query(bounds);
+
+        span.setAttributes({
+          'query.type': 'box',
+          'query.results': results.length,
+        });
+
+        return results;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Rebuild spatial index
+   * @returns {void}
+   */
+  rebuild() {
+    this._buildOctree();
+  }
+}

package/src/webxr-renderer.mjs

@@ -0,0 +1,291 @@
+/**
+ * @file WebXR Renderer
+ * @module @unrdf/spatial-kg/webxr-renderer
+ * @description WebXR-enabled 3D rendering for spatial knowledge graphs
+ */
+
+import { SpatialGraphConfigSchema } from './schemas.mjs';
+import { trace } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('@unrdf/spatial-kg/webxr-renderer');
+
+/**
+ * Mock Three.js scene (for testing without actual Three.js)
+ * In production, import from 'three'
+ */
+class MockScene {
+  constructor() {
+    this.children = [];
+  }
+  add(object) {
+    this.children.push(object);
+  }
+  remove(object) {
+    const index = this.children.indexOf(object);
+    if (index > -1) this.children.splice(index, 1);
+  }
+}
+
+class MockMesh {
+  constructor(geometry, material) {
+    this.geometry = geometry;
+    this.material = material;
+    this.position = { x: 0, y: 0, z: 0 };
+    this.userData = {};
+  }
+}
+
+/**
+ * WebXR Renderer
+ */
+export class WebXRRenderer {
+  /**
+   * @param {Object} config - Renderer configuration
+   * @param {HTMLCanvasElement} [config.canvas] - Canvas element
+   */
+  constructor(config = {}) {
+    const validated = SpatialGraphConfigSchema.parse({ rendering: config });
+    this.config = validated.rendering;
+    this.canvas = config.canvas;
+
+    // Scene setup (using mock for testing)
+    this.scene = new MockScene();
+    this.camera = null;
+    this.renderer = null;
+
+    // Node/edge meshes
+    this.nodeMeshes = new Map();
+    this.edgeMeshes = new Map();
+
+    // XR state
+    this.xrSession = null;
+    this.isVR = false;
+    this.isAR = false;
+
+    // Performance
+    this.frameTime = 0;
+    this.lastFrameTime = 0;
+    this.fps = 60;
+  }
+
+  /**
+   * Initialize renderer
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    return tracer.startActiveSpan('renderer.initialize', async span => {
+      try {
+        // In real implementation, create Three.js renderer, camera, etc.
+        // For testing, just simulate initialization
+
+        this.camera = {
+          position: { x: 0, y: 10, z: 50 },
+          rotation: { x: 0, y: 0, z: 0 },
+          fov: 75,
+        };
+
+        span.setAttributes({
+          'renderer.initialized': true,
+          'renderer.targetFPS': this.config.targetFPS,
+        });
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Start WebXR session
+   * @param {string} mode - 'immersive-vr' or 'immersive-ar'
+   * @returns {Promise<void>}
+   */
+  async startXRSession(mode) {
+    return tracer.startActiveSpan('renderer.start-xr', async span => {
+      try {
+        // In real implementation, request XR session from WebXR API
+        // For testing, simulate session start
+
+        this.xrSession = { mode };
+        this.isVR = mode === 'immersive-vr';
+        this.isAR = mode === 'immersive-ar';
+
+        span.setAttributes({
+          'xr.mode': mode,
+          'xr.active': true,
+        });
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * End WebXR session
+   * @returns {Promise<void>}
+   */
+  async endXRSession() {
+    if (this.xrSession) {
+      this.xrSession = null;
+      this.isVR = false;
+      this.isAR = false;
+    }
+  }
+
+  /**
+   * Update node positions
+   * @param {Map<string, Object>} nodes - Nodes with positions
+   * @returns {void}
+   */
+  updateNodes(nodes) {
+    return tracer.startActiveSpan('renderer.update-nodes', span => {
+      try {
+        // Update existing nodes
+        for (const [id, node] of nodes) {
+          let mesh = this.nodeMeshes.get(id);
+
+          if (!mesh) {
+            // Create new mesh
+            mesh = new MockMesh({}, {});
+            mesh.userData.nodeId = id;
+            this.nodeMeshes.set(id, mesh);
+            this.scene.add(mesh);
+          }
+
+          // Update position
+          mesh.position.x = node.position.x;
+          mesh.position.y = node.position.y;
+          mesh.position.z = node.position.z;
+        }
+
+        // Remove deleted nodes
+        for (const [id, mesh] of this.nodeMeshes) {
+          if (!nodes.has(id)) {
+            this.scene.remove(mesh);
+            this.nodeMeshes.delete(id);
+          }
+        }
+
+        span.setAttributes({
+          'renderer.nodes': nodes.size,
+          'renderer.meshes': this.nodeMeshes.size,
+        });
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Update edges
+   * @param {Array<Object>} edges - Edge list
+   * @param {Map<string, Object>} nodes - Node positions
+   * @returns {void}
+   */
+  updateEdges(edges, nodes) {
+    return tracer.startActiveSpan('renderer.update-edges', span => {
+      try {
+        // Clear existing edges (simple approach)
+        for (const mesh of this.edgeMeshes.values()) {
+          this.scene.remove(mesh);
+        }
+        this.edgeMeshes.clear();
+
+        // Create edge meshes
+        for (const edge of edges) {
+          const source = nodes.get(edge.source);
+          const target = nodes.get(edge.target);
+
+          if (source && target) {
+            const mesh = new MockMesh({}, {});
+            mesh.userData.edgeId = edge.id;
+            mesh.userData.source = edge.source;
+            mesh.userData.target = edge.target;
+
+            this.edgeMeshes.set(edge.id, mesh);
+            this.scene.add(mesh);
+          }
+        }
+
+        span.setAttributes({
+          'renderer.edges': edges.length,
+        });
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Render frame
+   * @returns {void}
+   */
+  render() {
+    return tracer.startActiveSpan('renderer.render', span => {
+      try {
+        const now = performance.now();
+        this.frameTime = now - this.lastFrameTime;
+        this.lastFrameTime = now;
+
+        // Calculate FPS
+        if (this.frameTime > 0) {
+          this.fps = 1000 / this.frameTime;
+        }
+
+        // In real implementation, render Three.js scene
+        // For testing, just track metrics
+
+        span.setAttributes({
+          'renderer.fps': Math.round(this.fps),
+          'renderer.frameTime': this.frameTime,
+        });
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Get camera position
+   * @returns {Object} Camera position
+   */
+  getCameraPosition() {
+    return { ...this.camera.position };
+  }
+
+  /**
+   * Set camera position
+   * @param {Object} position - New position
+   * @returns {void}
+   */
+  setCameraPosition(position) {
+    this.camera.position.x = position.x;
+    this.camera.position.y = position.y;
+    this.camera.position.z = position.z;
+  }
+
+  /**
+   * Get performance metrics
+   * @returns {Object} Metrics
+   */
+  getMetrics() {
+    return {
+      fps: Math.round(this.fps),
+      frameTime: this.frameTime,
+      nodeCount: this.nodeMeshes.size,
+      edgeCount: this.edgeMeshes.size,
+      xrActive: this.xrSession !== null,
+    };
+  }
+
+  /**
+   * Dispose renderer
+   * @returns {void}
+   */
+  dispose() {
+    this.nodeMeshes.clear();
+    this.edgeMeshes.clear();
+    if (this.xrSession) {
+      this.endXRSession();
+    }
+  }
+}