@simarena/viewport 0.0.1-alpha.0 → 0.0.1-alpha.1

package/package.json

@@ -1,10 +1,25 @@
 {
   "name": "@simarena/viewport",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.1",
   "description": "SimArena viewport — Three.js rendering, body sync, camera, WebSocket streaming",
+  "keywords": [
+    "robotics",
+    "simarena",
+    "simulation",
+    "three.js",
+    "viewport",
+    "websocket"
+  ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/simarena/viewport"
+  },
+  "files": [
+    "src"
+  ],
   "type": "module",
-  "files": ["src"],
+  "main": "./src/index.ts",
   "exports": {
     ".": {
       "source": "./src/index.ts",
@@ -12,29 +27,20 @@
       "types": "./src/index.ts"
     }
   },
-  "main": "./src/index.ts",
   "scripts": {
-    "check": "tsc --noEmit"
-  },
-  "keywords": ["simarena", "viewport", "three.js", "robotics", "simulation", "websocket"],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/simarena/viewport"
+    "check": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check"
   },
   "dependencies": {
-    "@simarena/format": "0.0.1-alpha.0",
     "three": "^0.183.2"
   },
   "devDependencies": {
     "@types/three": "^0.183.1",
+    "oxfmt": "^0.49.0",
+    "oxlint": "^1.64.0",
     "typescript": "^6.0.2"
-  },
-  "peerDependencies": {
-    "three": "^0.170.0"
-  },
-  "peerDependenciesMeta": {
-    "three": {
-      "optional": true
-    }
   }
 }

package/src/index.ts

@@ -1,13 +1,43 @@
-export { buildScene, createGeomMesh, buildLightComponent } from './compiler/threejs/index.js';
-export type { ViewerScene } from './compiler/threejs/index.js';
+export { createViewport } from "./viewport.js";
+export type { Viewport, ViewportOpts } from "./viewport.js";
 
-export { parseThreeScene } from './parser/threejs/index.js';
-export type { ThreeEntity, ParseOptions, PrimitiveKind } from './parser/threejs/index.js';
+export { buildBodyIdx, applyTransforms, flattenBodies, restoreBodies } from "./sync.js";
+export type { BodySnapshot } from "./sync.js";
+export { loadBodies, connectSim } from "./sync.js";
+export type { BodyInfo, LoadBodiesOpts, LoadBodiesResult, SimOpts, SimHandle } from "./sync.js";
 
-export { createViewport } from './viewport.js';
-export type { Viewport, ViewportOpts } from './viewport.js';
+export type { SimScene, SimFrame, Contact, SimConnection, SimCommand, SimEvent } from "./types.js";
 
-export { buildBodyIdx, applyTransforms, flattenBodies, restoreBodies } from './sync.js';
-export type { BodySnapshot } from './sync.js';
-export { loadBodies, connectSim } from './sync.js';
-export type { BodyInfo, LoadBodiesOpts, LoadBodiesResult, SimOpts, SimHandle } from './sync.js';
+export { LidarViz } from "./sensors/index.js";
+export type { LidarScanConfig, ScanPattern } from "./sensors/index.js";
+export { buildDirs, dirs2D, dirs3D, dirsLivox, dirsFlash } from "./sensors/index.js";
+export { ContactViz } from "./sensors/index.js";
+
+export type {
+  GeomDesc,
+  BodyDesc,
+  RigidBodyDesc,
+  SoftBodyDesc,
+  SkinnedBodyDesc,
+  InstancedBodyDesc,
+  SensorDesc,
+  SimCamera,
+  VisualScene,
+  MaterialDesc,
+  LightDesc,
+  LightType,
+  ParticleDesc,
+  GaussianSplatDesc,
+  EnvironmentDesc,
+} from "./viewer/types.js";
+
+export { SimScene as SimRenderer } from "./viewer/scene.js";
+export type { VizState } from "./viewer/scene.js";
+
+export {
+  buildSceneFromVisual,
+  buildGeomMesh,
+  createPrimitiveMesh,
+  createLightFromDesc,
+} from "./viewer/builder.js";
+export type { BuiltScene } from "./viewer/builder.js";

package/src/sensors/contact.ts

@@ -0,0 +1,124 @@
+import * as THREE from "three";
+import type { Contact } from "../types.js";
+
+const LAYER = 3;
+const SPHERE_R = 0.015;
+const ARROW_LEN = 0.12;
+const FORCE_LOW = 0.5;
+const FORCE_HIGH = 50;
+
+const arrowDir = new THREE.Vector3();
+const arrowOrigin = new THREE.Vector3();
+const _color = new THREE.Color();
+
+function forceColor(force: number): THREE.Color {
+  const t = Math.min(1, Math.max(0, (force - FORCE_LOW) / (FORCE_HIGH - FORCE_LOW)));
+  const hue = 0.6 - t * 0.6;
+  return _color.clone().setHSL(hue, 1, 0.55);
+}
+
+function makeSphere(scene: THREE.Object3D, geo: THREE.SphereGeometry): THREE.Mesh {
+  const mat = new THREE.MeshBasicMaterial({
+    color: 0xffffff,
+    depthTest: false,
+    transparent: true,
+    opacity: 0.85,
+  });
+  const m = new THREE.Mesh(geo, mat);
+  m.layers.set(LAYER);
+  m.renderOrder = 999;
+  m.visible = false;
+  scene.add(m);
+  return m;
+}
+
+function makeArrow(scene: THREE.Object3D): THREE.ArrowHelper {
+  const a = new THREE.ArrowHelper(
+    new THREE.Vector3(0, 0, 1),
+    new THREE.Vector3(0, 0, 0),
+    ARROW_LEN,
+    0xffffff,
+    ARROW_LEN * 0.3,
+    ARROW_LEN * 0.15,
+  );
+  a.layers.set(LAYER);
+  a.line.layers.set(LAYER);
+  a.cone.layers.set(LAYER);
+  a.renderOrder = 999;
+  a.visible = false;
+  scene.add(a);
+  return a;
+}
+
+export class ContactViz {
+  #scene: THREE.Object3D;
+  #geo: THREE.SphereGeometry;
+  #spheres: THREE.Mesh[] = [];
+  #arrows: THREE.ArrowHelper[] = [];
+  visible = true;
+
+  constructor(scene: THREE.Object3D) {
+    this.#scene = scene;
+    this.#geo = new THREE.SphereGeometry(SPHERE_R, 8, 6);
+  }
+
+  update(contacts: Contact[]): void {
+    if (!this.visible) {
+      this.hide();
+      return;
+    }
+
+    while (this.#spheres.length < contacts.length) {
+      this.#spheres.push(makeSphere(this.#scene, this.#geo));
+      this.#arrows.push(makeArrow(this.#scene));
+    }
+
+    for (let i = 0; i < contacts.length; i++) {
+      const c = contacts[i];
+      if (!c) continue;
+      const sphere = this.#spheres[i]!;
+      const arrow = this.#arrows[i]!;
+      const col = forceColor(c.force);
+
+      sphere.position.set(c.pos[0], c.pos[1], c.pos[2]);
+      (sphere.material as THREE.MeshBasicMaterial).color.copy(col);
+      sphere.visible = true;
+
+      if (c.normal) {
+        arrowDir.set(c.normal[0], c.normal[1], c.normal[2]).normalize();
+        arrowOrigin.set(c.pos[0], c.pos[1], c.pos[2]);
+        arrow.position.copy(arrowOrigin);
+        arrow.setDirection(arrowDir);
+        arrow.setColor(col);
+        const len = Math.min(ARROW_LEN * 3, ARROW_LEN + c.force * 0.002);
+        arrow.setLength(len, len * 0.3, len * 0.15);
+        arrow.visible = true;
+      } else {
+        arrow.visible = false;
+      }
+    }
+
+    for (let i = contacts.length; i < this.#spheres.length; i++) {
+      this.#spheres[i]!.visible = false;
+      this.#arrows[i]!.visible = false;
+    }
+  }
+
+  hide(): void {
+    for (const s of this.#spheres) s.visible = false;
+    for (const a of this.#arrows) a.visible = false;
+  }
+
+  dispose(): void {
+    for (const s of this.#spheres) {
+      (s.material as THREE.Material).dispose();
+      this.#scene.remove(s);
+    }
+    for (const a of this.#arrows) {
+      this.#scene.remove(a);
+    }
+    this.#spheres = [];
+    this.#arrows = [];
+    this.#geo.dispose();
+  }
+}

package/src/sensors/directions.ts

@@ -0,0 +1,103 @@
+/** LiDAR ray direction generators — pure math, no dependencies. */
+
+/** Horizontal ring — 2D planar scan (SICK, RPLiDAR, Hokuyo) */
+export function dirs2D(samples = 360, hfov: [number, number] = [-180, 180]): Float64Array {
+  const out = new Float64Array(samples * 3);
+  const start = (hfov[0] * Math.PI) / 180;
+  const span = ((hfov[1] - hfov[0]) * Math.PI) / 180;
+  for (let i = 0; i < samples; i++) {
+    const a = start + (i / samples) * span;
+    out[i * 3] = Math.cos(a);
+    out[i * 3 + 1] = Math.sin(a);
+    out[i * 3 + 2] = 0;
+  }
+  return out;
+}
+
+/** Multi-channel vertical rings — 3D spinning (Velodyne, Ouster) */
+export function dirs3D(
+  channels = 16,
+  azimuth = 120,
+  hfov: [number, number] = [-180, 180],
+  vfov: [number, number] = [-15, 15],
+): Float64Array {
+  const n = channels * azimuth,
+    out = new Float64Array(n * 3);
+  const hStart = (hfov[0] * Math.PI) / 180,
+    hSpan = ((hfov[1] - hfov[0]) * Math.PI) / 180;
+  for (let c = 0; c < channels; c++) {
+    const phi = ((vfov[0] + (c / (channels - 1)) * (vfov[1] - vfov[0])) * Math.PI) / 180;
+    for (let a = 0; a < azimuth; a++) {
+      const th = hStart + (a / azimuth) * hSpan;
+      const i = c * azimuth + a;
+      out[i * 3] = Math.cos(phi) * Math.cos(th);
+      out[i * 3 + 1] = Math.cos(phi) * Math.sin(th);
+      out[i * 3 + 2] = Math.sin(phi);
+    }
+  }
+  return out;
+}
+
+/** Time-varying petal pattern (Livox Mid-360 style) */
+export function dirsLivox(t: number, rays = 600, maxEl = 20): Float64Array {
+  const out = new Float64Array(rays * 3),
+    el = (maxEl * Math.PI) / 180;
+  for (let i = 0; i < rays; i++) {
+    const alpha = (i / rays) * Math.PI * 6 + t * 0.2;
+    const az = alpha,
+      e = Math.sin(alpha * 2.3) * el;
+    out[i * 3] = Math.cos(e) * Math.cos(az);
+    out[i * 3 + 1] = Math.cos(e) * Math.sin(az);
+    out[i * 3 + 2] = Math.sin(e);
+  }
+  return out;
+}
+
+/** Perspective grid — flash / depth camera */
+export function dirsFlash(w = 64, h = 48, fovDeg = 60): Float64Array {
+  const n = w * h,
+    out = new Float64Array(n * 3),
+    fov = (fovDeg * Math.PI) / 180;
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const nx = (x / (w - 1)) * 2 - 1,
+        ny = (y / (h - 1)) * 2 - 1;
+      const ax = Math.atan(nx * Math.tan(fov / 2) * (w / h));
+      const ay = Math.atan(ny * Math.tan(fov / 2));
+      const i = y * w + x;
+      out[i * 3] = Math.cos(ay) * Math.cos(ax);
+      out[i * 3 + 1] = Math.sin(ax);
+      out[i * 3 + 2] = -Math.sin(ay);
+    }
+  }
+  return out;
+}
+
+export type ScanPattern = "2d" | "3d" | "livox" | "flash";
+
+export interface LidarScanConfig {
+  pattern?: ScanPattern;
+  horizontalSamples?: number;
+  horizontalFov?: [number, number];
+  verticalFov?: [number, number];
+  channels?: number;
+  range?: [number, number];
+  sampleRate?: number;
+  height?: number;
+  near?: number;
+}
+
+/** Build directions from a LidarScanConfig */
+export function buildDirs(cfg: LidarScanConfig, t = 0): Float64Array {
+  const pattern = cfg.pattern ?? "2d";
+  if (pattern === "3d")
+    return dirs3D(
+      cfg.channels ?? 16,
+      cfg.horizontalSamples ?? 120,
+      cfg.horizontalFov ?? [-180, 180],
+      cfg.verticalFov ?? [-15, 15],
+    );
+  if (pattern === "livox") return dirsLivox(t, cfg.horizontalSamples ?? 600);
+  if (pattern === "flash") return dirsFlash();
+  return dirs2D(cfg.horizontalSamples ?? 120, cfg.horizontalFov ?? [-180, 180]);
+}

package/src/sensors/index.ts

@@ -0,0 +1,4 @@
+export { LidarViz } from "./lidar.js";
+export type { LidarScanConfig, ScanPattern } from "./lidar.js";
+export { ContactViz } from "./contact.js";
+export { buildDirs, dirs2D, dirs3D, dirsLivox, dirsFlash } from "./directions.js";

package/src/sensors/lidar.ts

@@ -0,0 +1,120 @@
+/**
+ * LidarViz — Three.js visualization of LiDAR scan data.
+ * Reads pre-computed distances from sim.sensordata and draws lines or points.
+ * No raycasting — pure display component.
+ */
+import * as THREE from "three";
+import type { LidarScanConfig, ScanPattern } from "./directions.js";
+import { buildDirs } from "./directions.js";
+
+export type { LidarScanConfig, ScanPattern };
+
+const LINE_COLOR = 0x00ff88;
+const COLOR_LOW = new THREE.Color().setHSL(0, 1, 0.6);
+const COLOR_HIGH = new THREE.Color().setHSL(0.55, 1, 0.6);
+
+export class LidarViz {
+  readonly group: THREE.Group;
+  readonly name: string;
+
+  private dirs: Float64Array;
+  private n: number;
+  private range: number;
+  private height: number;
+  private pattern: ScanPattern;
+  private channels: number;
+  private azimuth: number;
+  private body: THREE.Object3D;
+  private lines: THREE.LineSegments | null = null;
+  private points: THREE.Points | null = null;
+  private lineMat: THREE.LineBasicMaterial;
+  private ptsMat: THREE.PointsMaterial;
+
+  constructor(name: string, body: THREE.Object3D, cfg: LidarScanConfig) {
+    this.name = name;
+    this.body = body;
+    this.pattern = cfg.pattern ?? "2d";
+    this.range = cfg.range?.[1] ?? 10;
+    this.height = cfg.height ?? 0.3;
+    this.channels = cfg.channels ?? 16;
+    this.azimuth = cfg.horizontalSamples ?? 120;
+    this.dirs = buildDirs(cfg);
+    this.n = this.dirs.length / 3;
+
+    this.lineMat = new THREE.LineBasicMaterial({ color: LINE_COLOR });
+    this.ptsMat = new THREE.PointsMaterial({
+      size: 0.05,
+      vertexColors: true,
+      sizeAttenuation: true,
+    });
+
+    this.group = new THREE.Group();
+    this.group.frustumCulled = false;
+  }
+
+  update(dists: number[] | null): void {
+    if (this.lines) {
+      this.group.remove(this.lines);
+      this.lines.geometry.dispose();
+      this.lines = null;
+    }
+    if (this.points) {
+      this.group.remove(this.points);
+      this.points.geometry.dispose();
+      this.points = null;
+    }
+    if (!dists || dists.length === 0) return;
+
+    const origin = new THREE.Vector3();
+    this.body.getWorldPosition(origin);
+    origin.z += this.height;
+
+    const pts: number[] = [],
+      cols: number[] = [],
+      linePts: number[] = [];
+
+    for (let i = 0; i < Math.min(this.n, dists.length); i++) {
+      const d = dists[i] ?? this.range;
+      const dx = this.dirs[i * 3] ?? 0,
+        dy = this.dirs[i * 3 + 1] ?? 0,
+        dz = this.dirs[i * 3 + 2] ?? 0;
+      const hx = origin.x + dx * d,
+        hy = origin.y + dy * d,
+        hz = origin.z + dz * d;
+
+      if (this.pattern === "2d") {
+        linePts.push(origin.x, origin.y, origin.z, hx, hy, hz);
+      } else if (d < this.range) {
+        pts.push(hx, hy, hz);
+        const t =
+          this.pattern === "3d"
+            ? Math.floor(i / this.azimuth) / Math.max(1, this.channels - 1)
+            : d / this.range;
+        const c = new THREE.Color().lerpColors(COLOR_LOW, COLOR_HIGH, t);
+        cols.push(c.r, c.g, c.b);
+      }
+    }
+
+    if (linePts.length > 0) {
+      const geo = new THREE.BufferGeometry();
+      geo.setAttribute("position", new THREE.Float32BufferAttribute(linePts, 3));
+      this.lines = new THREE.LineSegments(geo, this.lineMat);
+      this.lines.frustumCulled = false;
+      this.group.add(this.lines);
+    }
+    if (pts.length > 0) {
+      const geo = new THREE.BufferGeometry();
+      geo.setAttribute("position", new THREE.Float32BufferAttribute(pts, 3));
+      geo.setAttribute("color", new THREE.Float32BufferAttribute(cols, 3));
+      this.points = new THREE.Points(geo, this.ptsMat);
+      this.group.add(this.points);
+    }
+  }
+
+  dispose(): void {
+    this.lines?.geometry.dispose();
+    this.points?.geometry.dispose();
+    this.lineMat.dispose();
+    this.ptsMat.dispose();
+  }
+}