@operato/scene-storage 10.0.0-beta.32 → 10.0.0-beta.34

package/src/stock.ts

@@ -0,0 +1,426 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+
+import { Component, Model, RealObject } from '@hatiolab/things-scene'
+import * as THREE from 'three'
+
+const STOCK_COLOR = '#ccaa76'
+const _color = new THREE.Color()
+const _matrix = new THREE.Matrix4()
+const _position = new THREE.Vector3()
+const _quaternion = new THREE.Quaternion()
+const _scale = new THREE.Vector3()
+
+function createStockMaterial(color: string | number, opts?: { opacity?: number; transparent?: boolean }): THREE.MeshStandardMaterial {
+  const mat = new THREE.MeshStandardMaterial({
+    color,
+    side: THREE.FrontSide,
+    metalness: 0,
+    roughness: 1,
+    envMapIntensity: 0
+  })
+  if (opts?.opacity !== undefined) {
+    mat.opacity = opts.opacity
+    mat.transparent = opts.transparent ?? true
+  }
+  return mat
+}
+
+/**
+ * Stock material/legend 정보를 제공하는 컴포넌트 인터페이스.
+ * Visualizer와 RackTable 모두 이를 구현한다.
+ */
+export interface StockMaterialProvider {
+  _stock_materials: THREE.Material[]
+  _default_material?: THREE.Material
+  _empty_material?: THREE.Material
+  legendTarget?: Component
+  hideEmptyStock?: boolean
+}
+
+export class Stock extends RealObject<THREE.Mesh> {
+  static defaultMaterial = createStockMaterial(STOCK_COLOR) as THREE.MeshStandardMaterial
+  static defaultEmptyMaterial = createStockMaterial(STOCK_COLOR, { opacity: 0.33, transparent: true })
+  static stockGeometry = new THREE.BoxGeometry(1, 1, 1)
+
+  _hideEmptyStock: boolean = false
+  _focused: boolean = false
+  declare _focusedAt?: number
+
+  // InstancedMesh 모드
+  _instancedMesh?: THREE.InstancedMesh
+  _instanceIndex: number = -1
+  _basePosition?: { x: number; y: number; z: number }
+  _baseScale?: { x: number; y: number; z: number }
+
+  model: any
+  _data?: any
+
+  constructor(component: Component, model: any) {
+    super(component)
+    this.model = model
+  }
+
+  get isInstanced(): boolean {
+    return !!this._instancedMesh && this._instanceIndex >= 0
+  }
+
+  protected getObject3dInstance() {
+    return new THREE.Mesh()
+  }
+
+  /**
+   * 가장 가까운 StockMaterialProvider 조상을 찾는다 (RackTable 또는 Visualizer).
+   */
+  get provider(): StockMaterialProvider | undefined {
+    let component = this.component
+
+    while (component) {
+      if ('_stock_materials' in component) {
+        return component as unknown as StockMaterialProvider
+      }
+      component = component.parent
+    }
+  }
+
+  private get _legendStatus(): any | undefined {
+    return this.provider?.legendTarget?.getState('status') || undefined
+  }
+
+  /**
+   * InstancedMesh의 해당 인스턴스 색상을 설정한다.
+   */
+  private _setInstanceColor(color: string | number) {
+    if (!this._instancedMesh) return
+    _color.set(color)
+    this._instancedMesh.setColorAt(this._instanceIndex, _color)
+    this._instancedMesh.instanceColor!.needsUpdate = true
+  }
+
+  /**
+   * 색상을 결정하고 InstancedMesh에 반영한다.
+   */
+  private _applyMaterialColor(index: number) {
+    const status = this._legendStatus
+    if (!status) {
+      this._setInstanceColor(this._getDefaultColor())
+      return
+    }
+
+    const range = status.ranges?.[index]
+    if (!(range && range.color)) {
+      this._setInstanceColor(this._getDefaultColor())
+      return
+    }
+
+    this._setInstanceColor(range.color)
+  }
+
+  private _getDefaultColor(): string | number {
+    const status = this._legendStatus
+    return status?.defaultColor || STOCK_COLOR
+  }
+
+  // 하위 호환: 개별 mesh 모드 material 접근
+  getMaterial(index: number) {
+    const status = this._legendStatus
+    if (!status) return this.userDefineDefaultMaterial
+
+    const range = status.ranges?.[index]
+    if (!(range && range.color)) {
+      this.stockMaterials[index] = this.userDefineDefaultMaterial
+    }
+
+    if (!this.stockMaterials[index]) {
+      this.stockMaterials[index] = createStockMaterial(range.color)
+    }
+
+    var alpha = range.color.replace(/^.*,(.+)\)/, '$1')
+    if (alpha > 0 && alpha < 1) {
+      this.stockMaterials[index].opacity = alpha
+      this.stockMaterials[index].transparent = true
+    }
+
+    return this.stockMaterials[index]
+  }
+
+  get stockMaterials(): THREE.Material[] {
+    return this.provider?._stock_materials ?? []
+  }
+
+  get userDefineDefaultMaterial(): THREE.Material {
+    const p = this.provider
+
+    if (p) {
+      if (!p._default_material) {
+        const status = this._legendStatus
+        const defaultColor = status?.defaultColor
+        if (!defaultColor) return Stock.defaultMaterial
+
+        var alpha = Number(defaultColor.replace(/^.*,(.+)\)/, '$1'))
+        var hasAlpha = alpha > 0 && alpha < 1
+        p._default_material = createStockMaterial(defaultColor, hasAlpha ? { opacity: alpha, transparent: true } : undefined)
+      }
+      return p._default_material
+    }
+
+    return Stock.defaultMaterial
+  }
+
+  get emptyMaterial(): THREE.Material {
+    const p = this.provider
+
+    if (p) {
+      if (!p._empty_material) {
+        const status = this._legendStatus
+        const defaultColor = status?.defaultColor || STOCK_COLOR
+
+        var alpha = Number(defaultColor.replace(/^.*,(.+)\)/, '$1'))
+        var opacity = (alpha > 0 && alpha < 1) ? alpha : 0.33
+        p._empty_material = createStockMaterial(defaultColor, { opacity, transparent: true })
+      }
+      return p._empty_material
+    }
+
+    return Stock.defaultEmptyMaterial
+  }
+
+  build() {
+    super.build()
+
+    // InstancedMesh 모드에서는 개별 mesh를 생성하지 않음
+    if (this.isInstanced) return
+
+    var { width, height, depth } = this.model
+
+    this._hideEmptyStock = !!this.provider?.hideEmptyStock
+
+    this.createStock(width, height, depth)
+  }
+
+  createStock(w: number, h: number, d: number) {
+    this.object3d.geometry = Stock.stockGeometry
+    this.object3d.material = this._hideEmptyStock ? this.emptyMaterial : this.userDefineDefaultMaterial
+
+    this.object3d.scale.set(w, d, h)
+
+    this.object3d.receiveShadow = true
+
+    this.object3d.castShadow = true
+    this.object3d.onBeforeRender = () => {
+      this.onBeforeRender()
+    }
+  }
+
+  onchangeStockData(data: any) {
+    this._data = data
+
+    if (this.isInstanced) {
+      this._onchangeStockDataInstanced(data)
+      return
+    }
+
+    // 개별 mesh 모드 (하위 호환)
+    this.object3d.userData = {
+      ...this.object3d.userData,
+      data
+    }
+
+    const stockStatus = this._legendStatus as
+      | { field: string; aggregation?: string; ranges: { min?: string | number; max?: string | number; color?: string }[] }
+      | undefined
+    if (!stockStatus) return
+
+    var statusField = stockStatus.field
+    var aggregation = stockStatus.aggregation || 'sum'
+    var ranges = stockStatus.ranges
+
+    if (!(statusField && ranges)) return
+
+    var items = data.items
+
+    if (!items) {
+      this.object3d.material = this._hideEmptyStock ? this.emptyMaterial : this.userDefineDefaultMaterial
+      return
+    }
+
+    var statusValues: any[] = items
+      .map((item: any) => item && item[statusField])
+      .filter((value: any) => value !== undefined && value !== null)
+
+    if (statusValues.length === 0) {
+      this.object3d.material = this._hideEmptyStock ? this.emptyMaterial : this.userDefineDefaultMaterial
+      return
+    }
+
+    var status = this._aggregate(statusValues, aggregation)
+
+    var isInRanges = ranges.some((range, index) => {
+      let { min: minValue, max: maxValue } = range
+
+      var min: number | undefined =
+        minValue !== undefined && minValue !== null && minValue !== '' ? Number(minValue) : undefined
+      var max: number | undefined =
+        maxValue !== undefined && maxValue !== null && maxValue !== '' ? Number(maxValue) : undefined
+
+      var maxCheck = max === undefined ? true : max > status
+      var minCheck = min === undefined ? true : min <= status
+
+      if (maxCheck && minCheck) {
+        this.object3d.material = this.getMaterial(index)
+        return true
+      } else {
+        this.object3d.material = this._hideEmptyStock ? this.emptyMaterial : this.userDefineDefaultMaterial
+        return false
+      }
+    })
+    if (!isInRanges) {
+      this.object3d.material = this.userDefineDefaultMaterial
+    }
+  }
+
+  /**
+   * InstancedMesh 모드에서의 데이터 변경 처리.
+   * 개별 mesh의 material 대신 instanceColor를 변경한다.
+   */
+  private _onchangeStockDataInstanced(data: any) {
+    const stockStatus = this._legendStatus as
+      | { field: string; aggregation?: string; ranges: { min?: string | number; max?: string | number; color?: string }[] }
+      | undefined
+    if (!stockStatus) return
+
+    var statusField = stockStatus.field
+    var aggregation = stockStatus.aggregation || 'sum'
+    var ranges = stockStatus.ranges
+
+    if (!(statusField && ranges)) return
+
+    var items = data.items
+
+    if (!items) {
+      this._setInstanceColor(this._getDefaultColor())
+      return
+    }
+
+    var statusValues: any[] = items
+      .map((item: any) => item && item[statusField])
+      .filter((value: any) => value !== undefined && value !== null)
+
+    if (statusValues.length === 0) {
+      this._setInstanceColor(this._getDefaultColor())
+      return
+    }
+
+    var status = this._aggregate(statusValues, aggregation)
+
+    var matched = false
+    for (let index = 0; index < ranges.length; index++) {
+      const range = ranges[index]
+      let { min: minValue, max: maxValue } = range
+
+      var min: number | undefined =
+        minValue !== undefined && minValue !== null && minValue !== '' ? Number(minValue) : undefined
+      var max: number | undefined =
+        maxValue !== undefined && maxValue !== null && maxValue !== '' ? Number(maxValue) : undefined
+
+      var maxCheck = max === undefined ? true : max > status
+      var minCheck = min === undefined ? true : min <= status
+
+      if (maxCheck && minCheck) {
+        this._applyMaterialColor(index)
+        matched = true
+        break
+      }
+    }
+
+    if (!matched) {
+      this._setInstanceColor(this._getDefaultColor())
+    }
+  }
+
+  private _aggregate(values: any[], aggregation: string): number {
+    switch (aggregation) {
+      case 'sum':
+        return values.reduce((sum: number, val: any) => sum + Number(val), 0)
+      case 'avg':
+        return values.reduce((sum: number, val: any) => sum + Number(val), 0) / values.length
+      case 'min':
+        return Math.min(...values.map((val: any) => Number(val)))
+      case 'max':
+        return Math.max(...values.map((val: any) => Number(val)))
+      default:
+        return values.reduce((sum: number, val: any) => sum + Number(val), 0)
+    }
+  }
+
+  onBeforeRender = () => {
+    if (!this.isInstanced) {
+      // 개별 mesh 모드
+      if (this._focused) {
+        var lastTime = performance.now() - this._focusedAt!
+        var progress = lastTime / 2000
+        this.object3d.rotation.y = 2 * Math.PI * progress
+        this.component.invalidate()
+      } else if (this._focusedAt) {
+        delete this._focusedAt
+        this.object3d.rotation.y = 0
+        this.component.invalidate()
+      }
+      return
+    }
+
+    // InstancedMesh 모드: 해당 인스턴스의 matrix만 갱신
+    if (this._focused && this._instancedMesh && this._basePosition && this._baseScale) {
+      var lastTime = performance.now() - this._focusedAt!
+      var progress = lastTime / 2000
+      _quaternion.setFromAxisAngle(new THREE.Vector3(0, 1, 0), 2 * Math.PI * progress)
+      _matrix.compose(
+        _position.set(this._basePosition.x, this._basePosition.y, this._basePosition.z),
+        _quaternion,
+        _scale.set(this._baseScale.x, this._baseScale.y, this._baseScale.z)
+      )
+      this._instancedMesh.setMatrixAt(this._instanceIndex, _matrix)
+      this._instancedMesh.instanceMatrix.needsUpdate = true
+      this.component.invalidate()
+    } else if (this._focusedAt && this._instancedMesh && this._basePosition && this._baseScale) {
+      delete this._focusedAt
+      _matrix.compose(
+        _position.set(this._basePosition.x, this._basePosition.y, this._basePosition.z),
+        _quaternion.identity(),
+        _scale.set(this._baseScale.x, this._baseScale.y, this._baseScale.z)
+      )
+      this._instancedMesh.setMatrixAt(this._instanceIndex, _matrix)
+      this._instancedMesh.instanceMatrix.needsUpdate = true
+      this.component.invalidate()
+    }
+  }
+
+  onmouseup(e: MouseEvent, _context: unknown, callback: (arg: { data: any; location: string }) => void) {
+    const data = this._data || this.object3d?.userData?.data
+
+    if (callback && typeof callback == 'function') {
+      callback({
+        ...data,
+        color: this._getCurrentColorHex()
+      })
+    }
+  }
+
+  private _getCurrentColorHex(): string {
+    if (this.isInstanced && this._instancedMesh) {
+      this._instancedMesh.getColorAt(this._instanceIndex, _color)
+      return '#' + _color.getHexString()
+    }
+    return '#' + ((this.object3d.material as any).color?.getHexString() || 'ccaa76')
+  }
+
+  // all update functions should be intentionally empty. important!
+  updateTransform() {}
+  updateDimension() {}
+  updateAlpha() {}
+  updateFillStyle() {}
+  updateStrokeStyle() {}
+  updateHidden() {}
+  updateText() {}
+}

package/src/{rack-cell-3d.ts → storage-cell-3d.ts}

@@ -7,7 +7,7 @@
  * RackCell has no geometry of its own. Its sole 3D purpose is to provide
  * an Object3D that carriers can be attached to (via Three.js `.attach()`),
  * placed at the exact cell position within the rack. The position is derived
- * from the parent AsrsRack's CellMap (by cellId), not from 2D state fields —
+ * from the parent Rack's CellMap (by cellId), not from 2D state fields —
  * rack cells occupy 3D levels that have no 2D analogue.
  *
  * updateTransform() override: things-scene's standard updateTransform
@@ -19,7 +19,7 @@
 import * as THREE from 'three'
 import { RealObjectGroup } from '@hatiolab/things-scene'
 
-export class RackCell3D extends RealObjectGroup {
+export class StorageCell3D extends RealObjectGroup {
   build() {
     super.build()
     this._repositionFromCellMap()

package/src/{rack-cell.ts → storage-cell.ts}

@@ -1,13 +1,13 @@
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  *
- * RackCell — a single storage slot within an AsrsRack.
+ * RackCell — a single storage slot within an Rack.
  *
  * A RackCell is a virtual component: it occupies a specific (bay, row, level)
  * coordinate within the parent rack and acts as a CarrierHolder for one carrier
  * (or several, depending on `cellType`).
  *
- * The crane (AsrsCrane) navigates toward a RackCell as its `place()` destination —
+ * The crane (or any picker) navigates toward a RackCell as its `place()` destination —
  * because the rack cell is a discrete component, Mover.moveTo() can target it
  * directly and arrive at exactly the right bay × level position.
  *
@@ -16,7 +16,7 @@
  * positioned within the rack's coordinate space (RackCell3D handles
  * this via updateTransform override).
  *
- * Lifecycle: AsrsRack._buildCells() instantiates RackCell children.
+ * Lifecycle: Rack._buildCells() instantiates RackCell children.
  * Do not create RackCell components manually — they are managed by the rack.
  *
  * Domain aliases:
@@ -35,7 +35,7 @@ import {
 import type { State, Material3D } from '@hatiolab/things-scene'
 import { CarrierHolder, type AttachFrame } from '@operato/scene-base'
 
-import { RackCell3D } from './rack-cell-3d.js'
+import { StorageCell3D } from './storage-cell-3d.js'
 
 /**
  * How many carriers a cell can hold simultaneously.
@@ -43,13 +43,19 @@ import { RackCell3D } from './rack-cell-3d.js'
  * - multi:  small stack (up to 4, e.g. a multi-deep tray)
  * - bulk:   unlimited (e.g. a floor area measured in slots)
  */
-export type RackCellType = 'single' | 'multi' | 'bulk'
+export type StorageCellType = 'single' | 'multi' | 'bulk'
 
 /** RackCell 컴포넌트 state */
-export interface RackCellState extends State {
+export interface StorageCellState extends State {
   // ── 식별 ──
   cellId?: string
-  cellType?: RackCellType
+  cellType?: StorageCellType
+  /**
+   * 자동 할당된 location ID — RackTable.assignLocations() 가 set. 외부 시스템
+   * (WMS, picker 명령 등) 이 cell 을 지칭하는 사람-친화 ID. RackTable 없이
+   * 단독으로 Rack 을 사용할 땐 unset.
+   */
+  locationId?: string
 
   // ── 3D 재질 ──
   material3d?: Material3D
@@ -79,11 +85,11 @@ const NATURE: ComponentNature = {
       }
     }
   ],
-  help: 'scene/component/rack-cell'
+  help: 'scene/component/storage-cell'
 }
 
 /**
- * RackCell — single-slot storage cell inside an AsrsRack.
+ * RackCell — single-slot storage cell inside an Rack.
  *
  * Mixin chain: CarrierHolder(ContainerAbstract)
  *   - CarrierHolder: publishes attachPointFor(), gates containable() to Carriables
@@ -93,9 +99,9 @@ const NATURE: ComponentNature = {
  * CellMap (via updateTransform override), bypassing things-scene's standard
  * 2D→3D coordinate mapping which cannot express 3D levels.
  */
-@sceneComponent('rack-cell')
+@sceneComponent('storage-cell')
 export default class RackCell extends CarrierHolder(ContainerAbstract) {
-  declare state: RackCellState
+  declare state: StorageCellState
 
   // ── Identification ────────────────────────────────────────────────────────
 
@@ -103,7 +109,7 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
     return this.state.cellId ?? ''
   }
 
-  get cellType(): RackCellType {
+  get cellType(): StorageCellType {
     return this.state.cellType ?? 'single'
   }
 
@@ -226,7 +232,7 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
   // ── 3D ───────────────────────────────────────────────────────────────────
 
   buildRealObject(): RealObject | undefined {
-    return new RackCell3D(this)
+    return new StorageCell3D(this)
   }
 }
 

package/src/{asrs-rack-3d.ts → storage-rack-3d.ts}

@@ -1,7 +1,7 @@
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  *
- * AsrsRack 3D — multi-level high-bay storage rack.
+ * Rack 3D — multi-level storage shelf system.
  *
  * LO-POLY but visually unambiguous as a rack. The signature parts:
  *
@@ -13,7 +13,7 @@
  *     this is a load-bearing storage rack, not just a generic frame)
  *
  * No floor / ceiling panels — the rack is open by design (cells are accessed
- * by the stacker crane from the front/aisle side).
+ * by a picker from the front side).
  *
  * Cargo (pallets, boxes) added as children render at their own z position.
  * The rack itself is purely structural geometry.
@@ -27,7 +27,7 @@ const POST_COLOR = 0x6a7080
 const BEAM_COLOR = 0x556070
 const BRACE_COLOR = 0x556070
 
-export class AsrsRack3D extends RealObjectGroup {
+export class StorageRack3D extends RealObjectGroup {
   build() {
     super.build()