@operato/scene-transport 10.0.0-beta.22

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@operato/scene-transport",
+  "description": "Transport-domain components for things-scene (smart factory / logistics) — forklift, worker, AGV.",
+  "author": "heartyoh",
+  "version": "10.0.0-beta.22",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "license": "MIT",
+  "things-scene": true,
+  "publishConfig": {
+    "access": "public",
+    "@operato:registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/things-scene/operato-scene.git",
+    "directory": "packages/transport"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "lint": "eslint src/ && prettier \"src/**/*.ts\" --check",
+    "format": "eslint src/ --fix && prettier \"src/**/*.ts\" --write"
+  },
+  "dependencies": {
+    "@hatiolab/things-scene": "^10.0.0-beta.1",
+    "@operato/scene-base": "^10.0.0-beta.22",
+    "three": "^0.183.0"
+  },
+  "devDependencies": {
+    "@hatiolab/prettier-config": "^1.0.0",
+    "@types/three": "^0.183.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "prettier": "^3.2.5",
+    "tslib": "^2.3.1",
+    "typescript": "^5.0.4"
+  },
+  "prettier": "@hatiolab/prettier-config",
+  "gitHead": "f48e52f4f5fdc30ec06af9da7cf253f6e29cfb0e"
+}

package/src/agv-3d.ts

@@ -0,0 +1,283 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * Agv 3D — payload (Kiva-style) automated guided vehicle.
+ *
+ * LO-POLY but with **rounded volume** — the Kiva AGV's signature is a
+ * pill-shaped, low-slung chassis with rounded corners, not a flat box.
+ *
+ * Structure:
+ *   - rounded-box chassis (volumetric, with bevels — the visual identity)
+ *   - top deck with raised lift pad at center (Kiva-style under-shelf lift)
+ *   - LED strip running around the perimeter
+ *   - safety bumpers (front + rear, hi-vis with black corners)
+ *   - LiDAR sensor: cylindrical body + transparent dome top
+ *   - 4 wheel covers (fender bumps integrated into chassis sides)
+ *   - charging contacts at rear
+ *   - corner indicator lamps on deck
+ */
+
+import * as THREE from 'three'
+import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+import { RoundedBoxGeometry } from 'three/examples/jsm/geometries/RoundedBoxGeometry.js'
+import { RealObjectGroup } from '@hatiolab/things-scene'
+
+const CHASSIS_COLOR_DARK = 0x444444
+const DECK_COLOR = 0x666677
+const LIFT_PAD_COLOR = 0x4a4a55
+const TIRE_COLOR = 0x202020
+const WHEEL_COVER_COLOR = 0x3a3a3a
+const LIDAR_BODY = 0x222233
+const LIDAR_DOME = 0x445566
+const BUMPER_COLOR = 0xeeaa00
+const BUMPER_BLACK = 0x111111
+const CHARGE_COPPER = 0xc77a00
+
+export class Agv3D extends RealObjectGroup {
+  build() {
+    super.build()
+
+    const { width, height, depth = 0 } = this.component.state
+    const bodyColor = (this.component.state.bodyColor as string) || '#999'
+    const emissiveColor = (this.component.state.lampEmissive as string) || '#222222'
+    const status = this.component.state.status
+    const lampIntensity = status && status !== 'idle' ? 1.5 : 0.2
+
+    const chassisH = depth * 0.85
+    const deckH = depth * 0.05
+    const wheelR = chassisH * 0.30
+    const baseY = -depth / 2
+
+    // ── Rounded chassis (volumetric — the Kiva AGV signature) ────────
+    const chassisRadius = Math.min(width, height) * 0.10
+    const chassisGeo = new RoundedBoxGeometry(width * 0.95, chassisH, height * 0.95, 4, chassisRadius)
+    const chassisMesh = new THREE.Mesh(
+      chassisGeo,
+      new THREE.MeshStandardMaterial({
+        color: CHASSIS_COLOR_DARK,
+        metalness: 0.4,
+        roughness: 0.5
+      })
+    )
+    chassisMesh.position.set(0, baseY + chassisH / 2, 0)
+    chassisMesh.castShadow = true
+    chassisMesh.receiveShadow = true
+    this.object3d.add(chassisMesh)
+
+    // ── Top deck (rounded slab) ───────────────────────────────────────
+    const deckGeo = new RoundedBoxGeometry(width * 0.95, deckH, height * 0.95, 2, chassisRadius * 0.5)
+    const deckMesh = new THREE.Mesh(
+      deckGeo,
+      new THREE.MeshStandardMaterial({ color: DECK_COLOR, metalness: 0.5, roughness: 0.4 })
+    )
+    deckMesh.position.set(0, baseY + chassisH + deckH / 2, 0)
+    deckMesh.castShadow = true
+    deckMesh.receiveShadow = true
+    this.object3d.add(deckMesh)
+
+    // ── Lift mechanism (round pad — Kiva-style under-shelf lift) ─────
+    const liftR = Math.min(width, height) * 0.30
+    const liftH = deckH * 1.5
+    const liftGeo = new THREE.CylinderGeometry(liftR, liftR * 1.05, liftH, 24)
+    const liftMesh = new THREE.Mesh(
+      liftGeo,
+      new THREE.MeshStandardMaterial({ color: LIFT_PAD_COLOR, metalness: 0.6, roughness: 0.35 })
+    )
+    liftMesh.position.set(0, baseY + chassisH + deckH + liftH / 2, 0)
+    liftMesh.castShadow = true
+    this.object3d.add(liftMesh)
+
+    // Body color band on lift rim (status hint)
+    const tintH = liftH * 0.3
+    const tintGeo = new THREE.CylinderGeometry(liftR * 1.03, liftR * 1.03, tintH, 24, 1, true)
+    const tintMesh = new THREE.Mesh(
+      tintGeo,
+      new THREE.MeshStandardMaterial({
+        color: bodyColor,
+        side: THREE.DoubleSide,
+        transparent: true,
+        opacity: 0.7,
+        metalness: 0.1,
+        roughness: 0.6
+      })
+    )
+    tintMesh.position.set(0, baseY + chassisH + deckH + tintH / 2, 0)
+    this.object3d.add(tintMesh)
+
+    // ── LED strip (4 sides, rounded corners follow chassis bevel) ────
+    const stripH = chassisH * 0.10
+    const stripT = Math.min(width, height) * 0.015
+    const stripY = baseY + chassisH * 0.55
+    const stripMaterial = new THREE.MeshStandardMaterial({
+      color: emissiveColor,
+      emissive: emissiveColor,
+      emissiveIntensity: lampIntensity,
+      metalness: 0.1,
+      roughness: 0.4
+    })
+    for (const zSign of [-1, 1]) {
+      const stripGeo = new THREE.BoxGeometry(width * 0.85, stripH, stripT)
+      const stripMesh = new THREE.Mesh(stripGeo, stripMaterial)
+      stripMesh.position.set(0, stripY, zSign * (height * 0.475 - stripT / 2))
+      this.object3d.add(stripMesh)
+    }
+    for (const xSign of [-1, 1]) {
+      const stripGeo = new THREE.BoxGeometry(stripT, stripH, height * 0.85)
+      const stripMesh = new THREE.Mesh(stripGeo, stripMaterial)
+      stripMesh.position.set(xSign * (width * 0.475 - stripT / 2), stripY, 0)
+      this.object3d.add(stripMesh)
+    }
+
+    // ── Safety bumpers (front + rear) ────────────────────────────────
+    const bumperH = chassisH * 0.18
+    const bumperT = Math.min(width, height) * 0.025
+    const bumperY = baseY + bumperH / 2 + wheelR * 0.5
+    const bumperMaterial = new THREE.MeshStandardMaterial({
+      color: BUMPER_COLOR,
+      metalness: 0.1,
+      roughness: 0.6
+    })
+    const bumperBlackMaterial = new THREE.MeshStandardMaterial({
+      color: BUMPER_BLACK,
+      metalness: 0.2,
+      roughness: 0.7
+    })
+    for (const zSign of [-1, 1]) {
+      const yellow = new RoundedBoxGeometry(width * 0.7, bumperH, bumperT, 2, bumperT * 0.4)
+      const yMesh = new THREE.Mesh(yellow, bumperMaterial)
+      yMesh.position.set(0, bumperY, zSign * (height * 0.475 + bumperT / 2))
+      this.object3d.add(yMesh)
+      for (const xSign of [-1, 1]) {
+        const black = new RoundedBoxGeometry(width * 0.13, bumperH, bumperT, 2, bumperT * 0.4)
+        const bMesh = new THREE.Mesh(black, bumperBlackMaterial)
+        bMesh.position.set(xSign * (width * 0.7 / 2 + width * 0.065), bumperY, zSign * (height * 0.475 + bumperT / 2))
+        this.object3d.add(bMesh)
+      }
+    }
+
+    // ── LiDAR sensor (cylinder body + transparent dome) ──────────────
+    const lidarR = Math.min(width, height) * 0.10
+    const lidarBodyH = lidarR * 0.7
+    const lidarBodyGeo = new THREE.CylinderGeometry(lidarR, lidarR * 1.1, lidarBodyH, 16)
+    const lidarBodyMesh = new THREE.Mesh(
+      lidarBodyGeo,
+      new THREE.MeshStandardMaterial({ color: LIDAR_BODY, metalness: 0.6, roughness: 0.4 })
+    )
+    lidarBodyMesh.position.set(0, baseY + chassisH + lidarBodyH / 2, height * 0.35)
+    lidarBodyMesh.castShadow = true
+    this.object3d.add(lidarBodyMesh)
+
+    const domeGeo = new THREE.SphereGeometry(lidarR * 0.95, 24, 16, 0, Math.PI * 2, 0, Math.PI / 2)
+    const domeMesh = new THREE.Mesh(
+      domeGeo,
+      new THREE.MeshStandardMaterial({
+        color: LIDAR_DOME,
+        metalness: 0.3,
+        roughness: 0.2,
+        transparent: true,
+        opacity: 0.8
+      })
+    )
+    domeMesh.position.set(0, baseY + chassisH + lidarBodyH, height * 0.35)
+    this.object3d.add(domeMesh)
+
+    // Status hint on LiDAR top
+    const hintR = lidarR * 0.25
+    const hintMesh = new THREE.Mesh(
+      new THREE.SphereGeometry(hintR, 24, 8),
+      new THREE.MeshStandardMaterial({
+        color: emissiveColor,
+        emissive: emissiveColor,
+        emissiveIntensity: lampIntensity,
+        roughness: 0.3
+      })
+    )
+    hintMesh.position.set(0, baseY + chassisH + lidarBodyH + lidarR * 0.85, height * 0.35)
+    this.object3d.add(hintMesh)
+
+    // ── Wheels with covers ───────────────────────────────────────────
+    const wheelW = width * 0.07
+    const tireMaterial = new THREE.MeshStandardMaterial({ color: TIRE_COLOR, roughness: 0.95 })
+    const coverMaterial = new THREE.MeshStandardMaterial({
+      color: WHEEL_COVER_COLOR,
+      metalness: 0.5,
+      roughness: 0.6
+    })
+
+    const tireGeos: THREE.BufferGeometry[] = []
+    for (const xSign of [-1, 1]) {
+      for (const zSign of [-1, 1]) {
+        const tire = new THREE.CylinderGeometry(wheelR, wheelR, wheelW, 24)
+        tire.rotateZ(Math.PI / 2)
+        tire.translate(xSign * width * 0.42, baseY + wheelR, zSign * height * 0.32)
+        tireGeos.push(tire)
+        // Rounded fender cover
+        const cover = new RoundedBoxGeometry(wheelW * 1.5, wheelR * 1.4, wheelR * 1.6, 2, wheelR * 0.25)
+        cover.translate(xSign * (width * 0.42 + wheelW * 0.4), baseY + wheelR * 1.2, zSign * height * 0.32)
+        const coverMesh = new THREE.Mesh(cover, coverMaterial)
+        coverMesh.castShadow = true
+        this.object3d.add(coverMesh)
+      }
+    }
+    const tireMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(tireGeos), tireMaterial)
+    tireMesh.castShadow = true
+    this.object3d.add(tireMesh)
+
+    // ── Charging contacts (rear) ─────────────────────────────────────
+    const chargeMaterial = new THREE.MeshStandardMaterial({
+      color: CHARGE_COPPER,
+      metalness: 0.9,
+      roughness: 0.2
+    })
+    const chargeT = wheelR * 0.15
+    const chargeH = wheelR * 0.6
+    const chargeW = width * 0.08
+    for (const xSign of [-1, 1]) {
+      const chargeGeo = new RoundedBoxGeometry(chargeW, chargeH, chargeT, 1, chargeT * 0.3)
+      const chargeMesh = new THREE.Mesh(chargeGeo, chargeMaterial)
+      chargeMesh.position.set(xSign * width * 0.10, baseY + chargeH / 2 + wheelR * 0.2, -height * 0.475 - chargeT / 2)
+      this.object3d.add(chargeMesh)
+    }
+
+    // ── Corner indicator lamps ───────────────────────────────────────
+    const cornerR = Math.min(width, height) * 0.022
+    for (const xSign of [-1, 1]) {
+      for (const zSign of [-1, 1]) {
+        const cornerMesh = new THREE.Mesh(
+          new THREE.SphereGeometry(cornerR, 24, 6),
+          new THREE.MeshStandardMaterial({
+            color: emissiveColor,
+            emissive: emissiveColor,
+            emissiveIntensity: lampIntensity * 0.6,
+            roughness: 0.3
+          })
+        )
+        cornerMesh.position.set(
+          xSign * (width * 0.42),
+          baseY + chassisH + deckH + cornerR * 0.6,
+          zSign * (height * 0.42)
+        )
+        this.object3d.add(cornerMesh)
+      }
+    }
+  }
+
+  updateDimension() {}
+
+  onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
+    if (
+      'status' in after ||
+      'bodyColor' in after ||
+      'lampEmissive' in after ||
+      'width' in after ||
+      'height' in after ||
+      'depth' in after
+    ) {
+      this.update()
+      return
+    }
+    super.onchange(after, before)
+  }
+
+  updateAlpha() {}
+}

package/src/agv.ts

@@ -0,0 +1,207 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+import { Component, ComponentNature, Container, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import {
+  Legendable,
+  Placeable,
+  type Alignment,
+  type Heights,
+  type LegendBinding,
+  type PlacementArchetype
+} from '@operato/scene-base'
+
+import { Agv3D } from './agv-3d.js'
+
+/**
+ * Agv status — common to both payload and towing AGVs (kept narrow on purpose).
+ *
+ * - `idle`     — parked, awaiting task
+ * - `moving`   — driving along a path / executing transport
+ * - `charging` — at a charging dock / battery station
+ * - `error`    — fault / blocked / e-stop
+ *
+ * Loaded-vs-empty distinction is *not* in the status enum because for a
+ * Kiva-style payload AGV it's already obvious from the children (cargo
+ * components) parented to it — duplicating that as a status flag would
+ * invite drift.
+ */
+export type AgvStatus = 'idle' | 'moving' | 'charging' | 'error'
+
+/**
+ * Body color — neutral industrial gray base, slightly modulated by status.
+ * AGVs typically have status-color LED strips rather than full body color
+ * change; the body legend stays subtle so the LED strip + lamp do the
+ * communicating.
+ */
+const BODY_LEGEND = {
+  idle: '#999',
+  moving: '#aaa',
+  charging: '#aaa',
+  error: '#c66',
+  default: '#999'
+}
+
+/**
+ * LED strip emissive — the dominant status indicator for AGVs (typically a
+ * color-band running around the chassis perimeter).
+ */
+const LAMP_EMISSIVE_LEGEND = {
+  idle: '#222222',
+  moving: '#44ff44',  // green (operating)
+  charging: '#ffaa00', // amber (charging)
+  error: '#ff3333',   // red
+  default: '#222222'
+}
+
+const NATURE: ComponentNature = {
+  mutable: false,
+  resizable: true,
+  rotatable: true,
+  properties: [
+    {
+      type: 'select',
+      label: 'status',
+      name: 'status',
+      property: {
+        options: [
+          { display: 'Idle', value: 'idle' },
+          { display: 'Moving', value: 'moving' },
+          { display: 'Charging', value: 'charging' },
+          { display: 'Error', value: 'error' }
+        ]
+      }
+    },
+    {
+      type: 'number',
+      label: 'battery',
+      name: 'battery',
+      placeholder: '0..1'
+    }
+  ],
+  help: 'scene/component/agv'
+}
+
+const Base = Legendable(Placeable(Container)) as unknown as typeof Component
+
+/**
+ * Agv — payload (unit-load) automated guided vehicle. The Kiva-style flat-deck
+ * AGV that drives under or carries cargo to/from operation surfaces.
+ *
+ * **Container-based for cargo containment.** A payload Agv has a flat top
+ * deck whose surface is at the scene's operation height. Boxes, parcels,
+ * loaded pallets (anything with `placement: 'operation'`) can be added as
+ * children — when they are, their natural archetype-derived zPos puts them
+ * exactly on the AGV's deck (since AGV depth = operation - floor).
+ *
+ * For the towing variant (no cargo deck, pulls trailers behind), see Tugger.
+ */
+@sceneComponent('agv')
+export default class Agv extends Base {
+  static legends: Record<string, LegendBinding> = {
+    bodyColor: { from: 'status', legend: BODY_LEGEND },
+    lampEmissive: { from: 'status', legend: LAMP_EMISSIVE_LEGEND }
+  }
+
+  /**
+   * AGV sits on its wheels — `floor` archetype. Default depth = operation,
+   * so the top deck lands at the scene's operation height. This is the
+   * design point of payload AGVs: the deck height matches conveyor belt
+   * height, equipment ports, and forklift fork height — cargo transfers
+   * across all of them at the same level.
+   */
+  static placement: PlacementArchetype = 'floor'
+  static align: Alignment = 'bottom'
+  static defaultDepth = (h: Heights) => h.operation - h.floor
+
+  get nature() {
+    return NATURE
+  }
+
+  get anchors() {
+    return []
+  }
+
+  /** Accept logistics packages (placement='operation') as deck cargo. */
+  containable(component: Component) {
+    const archetype = (component.constructor as any).placement
+    if (archetype === 'operation') return true
+    return component.isDescendible(this as any)
+  }
+
+  /**
+   * 2D — render() sets up the rounded chassis path; the framework fills it
+   * with `fillStyle` (= bodyColor from Legendable) and strokes with
+   * `strokeStyle`. Additional top-down details (bumpers, LiDAR, lift pad,
+   * direction triangle) are drawn in `postrender()`.
+   */
+  render(ctx: CanvasRenderingContext2D) {
+    const { width, height, left, top } = this.state
+    const radius = Math.min(width, height) * 0.12
+    ctx.beginPath()
+    ctx.roundRect(left, top, width, height, radius)
+  }
+
+  /** Top-view accent details — bumpers, lift pad, LiDAR, direction triangle. */
+  postrender(ctx: CanvasRenderingContext2D) {
+    super.postrender?.(ctx)
+
+    const { width, height, left, top } = this.state
+    const cx = left + width / 2
+    const cy = top + height / 2
+    const accentColor = (this.state.lampEmissive as string) || '#44ff44'
+
+    ctx.save()
+
+    // Hi-vis bumper strips (front + rear)
+    const bumperT = Math.min(width, height) * 0.06
+    ctx.fillStyle = '#eeaa00'
+    ctx.fillRect(left + width * 0.15, top, width * 0.7, bumperT)
+    ctx.fillRect(left + width * 0.15, top + height - bumperT, width * 0.7, bumperT)
+    ctx.fillStyle = '#111'
+    ctx.fillRect(left + width * 0.02, top, width * 0.13, bumperT)
+    ctx.fillRect(left + width * 0.85, top, width * 0.13, bumperT)
+    ctx.fillRect(left + width * 0.02, top + height - bumperT, width * 0.13, bumperT)
+    ctx.fillRect(left + width * 0.85, top + height - bumperT, width * 0.13, bumperT)
+
+    // Lift pad (center circle — Kiva-style under-shelf lift)
+    const padR = Math.min(width, height) * 0.22
+    ctx.fillStyle = '#4a4a55'
+    ctx.strokeStyle = '#222'
+    ctx.lineWidth = 1
+    ctx.beginPath()
+    ctx.ellipse(cx, cy, padR, padR, 0, 0, Math.PI * 2)
+    ctx.fill()
+    ctx.stroke()
+
+    // LiDAR sensor (small filled circle near front)
+    const lidarR = Math.min(width, height) * 0.07
+    ctx.fillStyle = '#222233'
+    ctx.beginPath()
+    ctx.ellipse(cx, top + height * 0.20, lidarR, lidarR, 0, 0, Math.PI * 2)
+    ctx.fill()
+    ctx.stroke()
+    // Status hint on LiDAR
+    ctx.fillStyle = accentColor
+    ctx.beginPath()
+    ctx.ellipse(cx, top + height * 0.20, lidarR * 0.4, lidarR * 0.4, 0, 0, Math.PI * 2)
+    ctx.fill()
+
+    // Direction-of-travel triangle
+    ctx.fillStyle = accentColor
+    ctx.strokeStyle = '#111'
+    ctx.beginPath()
+    ctx.moveTo(cx, top + height * 0.06)
+    ctx.lineTo(cx - width * 0.06, top + height * 0.13)
+    ctx.lineTo(cx + width * 0.06, top + height * 0.13)
+    ctx.closePath()
+    ctx.fill()
+    ctx.stroke()
+
+    ctx.restore()
+  }
+
+  buildRealObject(): RealObject | undefined {
+    return new Agv3D(this as any)
+  }
+}