@things-factory/figure-ui 10.1.65 → 10.1.67

package/client/modeller/figure-source.ts

@@ -1,437 +0,0 @@
-import {
-  FIGURE_SOURCE_VERSION,
-  type DetailLevel,
-  type FigurePart,
-  type FigurePlacement,
-  type FigureSource,
-  type Vec3
-} from '@hatiolab/figure-model'
-
-/**
- * Scene model <-> `FigureSource`.
- *
- * ## Why this is the only place that converts
- *
- * While authoring, the source of truth is the **scene model** -- part
- * components sitting on a draft. `FigureSource` is produced from it when the
- * asset is saved or scored.
- *
- * The two use different vocabularies. The scene inherited 2D canvas terms
- * (`width`/`height` in plan, `depth` for height, `left`/`top`/`zPos` for
- * position); the format uses the axes 3D tools use (`x` right, `y` up, `z`
- * front, position at the part's **centre**).
- *
- * **Convert in one place.** Two places drift, and this format has already had
- * one incident caused by axes disagreeing.
- *
- * ## It was called `fold`, and that was wrong
- *
- * `fold` is an established term -- it reduces a structure to a summary, and
- * this repo already uses it correctly (`foldKpi`, `foldProbeResults`). Nothing
- * is reduced here: the same information comes out in a different shape, and it
- * goes back unchanged. A reader who learned `fold` from `foldKpi` reads this
- * one as reducing something, and the user did exactly that.
- *
- * ## The mapping
- *
- * The draft is the base box; its centre is the format's origin.
- *
- *     format            scene
- *     ────────────────  ──────────────────────────────
- *     base.x            draft width
- *     base.y            draft depth      <- height
- *     base.z            draft height
- *
- *     size.x            width
- *     size.y            depth
- *     size.z            height
- *
- *     position.x        left + width/2  - draft width/2
- *     position.y        zPos + depth/2                       <- both measured from the box bottom
- *     position.z        top  + height/2 - draft height/2
- *
- *     (Source edition 2 measures y from the bottom face of the base box, as the scene's zPos does, so
- *     that row needs no half-box shift. x and z are still measured from the box centre. ADR-0065.)
- *
- *     rotation.x        rotationX       (scene radians, format degrees)
- *     rotation.y        -rotation
- *     rotation.z        rotationY
- *
- * The rotation names are crossed because of the scene: `rotationY` becomes
- * three's z (`real-object.ts`, `get rotation()`). That stays inside this table.
- *
- * ## Fields nothing reads yet still travel
- *
- * `materialSlot`, `keepRound`, `sizing`, `anchor`, `repeat` and `label` exist in the format
- * and the editor ignores them. They still have to survive a round trip. When a
- * source proposed by AI is opened, edited and written back, a field that
- * disappears **without an error** is one the author cannot know about.
- *
- * **Five have gone that way here**: `ports`, `animations`, `anchor`,
- * `shape.hollow` and `keepRound`. The last one the test caught first, which
- * is the guard below actually earning its keep. The third showed up as a conveyor motor that stayed on the
- * floor no matter what the sample said; the fourth as a hollowed tray that
- * came out a solid block.
- *
- * All four passed the round-trip test, because the fixture it uses did not
- * carry the field. So the test now reads the **field list the format declares**
- * rather than trusting the fixture.
- *
- * `shape` is unpacked into `round`, `path` and `hollow` rather than carried
- * whole, because the editor holds those as separate state. Every field added
- * under `shape` costs a line here, and forgetting that line was the fourth
- * of the four.
- */
-/** 판 컴포넌트의 상태. 씬의 용어 그대로다. */
-export interface FigureDraft {
-  /** 형식 버전. */
-  version?: number
-  /*
-    The three sizes keep the scene component's names, and the scene assigns its axes differently
-    from the format: here `depth` is the vertical one. Naming the axis alone ("the y axis") does
-    not say which of the two conventions is meant, and this interface sits on the boundary between
-    them — so each field names the `FigureSource` field it becomes. `toFigureSource` and
-    `fromFigureSource` below are the only places that may disagree with these three lines.
-  */
-  /** 가로 너비 (mm) → `base.x`. */
-  width: number
-  /** 앞뒤 깊이 (mm) → `base.z`. 저작자가 위에서 내려다볼 때의 세로다. */
-  height: number
-  /** 높이 (mm) → `base.y`. 서 있는 방향이다. */
-  depth: number
-  /** 컴포넌트 타입 이름. **저장되는 식별자다.** */
-  figureType?: string
-  /** 3D 배치 기준면 ('floor' | 'ceiling' | 'center'). */
-  placement?: FigurePlacement
-  detailLevel?: DetailLevel
-  styleKit?: string
-  /**
-   * 움직임. **부품 바깥에 있다** — clip 하나가 부품 여럿을 함께 움직이기 때문이다.
-   *
-   * 편집면이 아직 이것을 만지지 않는다. 그래도 여기 실어 두는 것은, 안 실으면 열었다
-   * 저장하는 것만으로 **조용히 지워지기** 때문이다.
-   */
-  animations?: FigureSource['animations']
-  /**
-   * 값이 만드는 자세 — **애니메이션과 다른 칸이다.**
-   *
-   * 저것은 시각이 흘러 움직이는 것(도는 롤러)이고 이것은 인스턴스가 준 값이 그대로 자세가
-   * 되는 것(1200mm 내려온 호이스트)이다. 한동안 애니메이션 안에 `drive: 'hold'` 로 숨어
-   * 있었고, 그래서 「길이값을 변수로 노출하라」는 요청에 아무도 이것을 못 찾았다(ADR-0051).
-   */
-  parameters?: FigureSource['parameters']
-  /**
-   * 이 도형이 지는 능력. 씬의 capability mixin 이름이다.
-   *
-   * **부품이 아니라 도형 전체의 것이다** — 「이 컨베이어는 흐름의 마디다」는 부품 하나가
-   * 아니라 도형이 지는 성질이다. 부품 쪽 `capability` 는 그 능력을 **어느 부품이 받쳐
-   * 주나**를 말하는 다른 칸이다.
-   */
-  capabilities?: FigureSource['capabilities']
-  /**
-   * How parts move relative to their parents (ADR-0066). Kept in figure coordinates as stored, the same
-   * terms the inspector shows. Carried even when nothing edits them, so opening and saving never drops
-   * them.
-   */
-  joints?: FigureSource['joints']
-}
-
-/** 부품 컴포넌트의 상태. 씬의 용어 그대로다. */
-export interface PartModel {
-  type: 'figure-part'
-  /** 부품 이름. **저장되는 식별자다.** 씬은 이 값을 검색에도 쓴다. */
-  name: string
-  primitive: FigurePart['primitive']
-
-  left: number
-  top: number
-  width: number
-  height: number
-  /** 부피의 **밑면** 높이. 씬의 'floor' 배치에서 그렇게 정해져 있다. */
-  zPos: number
-  depth: number
-
-  /** 라디안. 씬이 그렇게 쓴다. */
-  rotationX?: number
-  rotation?: number
-  rotationY?: number
-
-  segments?: number
-  round?: number
-  path?: { x: number; y: number }[]
-  /** 속을 판 단면. 편집면이 아직 안 만지지만 잃어버리면 통이 통짜 상자가 된다. */
-  hollow?: NonNullable<FigurePart['shape']>['hollow']
-
-  /**
-   * 편집 중에만 쓰는 상태 — **저장 형식으로 넘어가지 않는다.**
-   *
-   * 씬이 이미 갖고 있는 속성이다. 편집 모드에서는 `faint`(반투명 + 색을 버리고 회색으로
-   * 수렴)로 보이고, 뷰 모드에서는 아예 안 그려진다. 판단은 씬의 `modeling-faint` 한 곳에
-   * 있고 2D 캔버스·3D 재질·DOM 세 채널이 같이 쓴다.
-   *
-   * 숨김은 "지금 이 뒤를 만지려고" 하는 것이지 그 부품의 성질이 아니다. 그래서
-   * `toFigureSource` 가 싣지 않고, 다시 열면 전부 보이는 상태로 돌아온다.
-   */
-  hidden?: boolean
-
-  /**
-   * 씬이 이것을 **집지 않는다** — 클릭·마퀴·기즈모 어디에도 안 걸린다.
-   *
-   * 저작면에만 서는 것(관절 부채꼴)이 쓴다. 저장 형식에는 없는 칸이라 `toFigureSource` 가
-   * 싣지 않는다.
-   */
-  locked?: boolean
-
-  /** 색 토큰 이름 (`palette.primary` 등). */
-  token?: string
-  /*
-    `FigurePart['material']` is required in the format, so these index into it directly. The
-    `NonNullable` on `shape` above is not the same case — `shape` is optional there.
-  */
-  preset?: FigurePart['material']['preset']
-  flatShading?: boolean
-  transparent?: boolean
-  /**
-   * 자체발광. 없으면 안 빛난다.
-   *
-   * 바깥의 `token` 이 **꺼진 모습**이고 이 안의 `token` 이 **켜진 모습**이다 — 꺼진
-   * 전구는 빨갛지 않고 어두운 플라스틱이다.
-   */
-  emissive?: FigurePart['material']['emissive']
-  surface?: FigurePart['material']['surface']
-
-  /* 아직 아무 일도 안 하지만 잃어버리지 않는다. */
-  materialSlot?: FigurePart['materialSlot']
-  /** 단면을 원으로 지킬까. 곡면만 뜻이 있고 기본은 지키는 것이다. */
-  keepRound?: FigurePart['keepRound']
-  sizing?: FigurePart['sizing']
-  /** 축마다 어느 면을 붙잡나. `sizing` 이 정한 것을 덮어쓴다. */
-  anchor?: FigurePart['anchor']
-  repeat?: FigurePart['repeat']
-  label?: FigurePart['label']
-  /**
-   * 이 부품이 능력의 어느 자리인가 — 물건이 앉는 자리(slot)이거나 드나드는 문(port)이다.
-   *
-   * 이 칸이 있는 부품은 **그려지지 않는다.** 저작면에서는 어디인지 보여야 하니 그리지만,
-   * 청사진에서는 `groups` 가 아니라 `anchors` 로 간다.
-   */
-  capability?: FigurePart['capability']
-  /** The part this one is attached to (ADR-0066). The one place a parent is written. */
-  parent?: FigurePart['parent']
-}
-
-const RAD_TO_DEG = 180 / Math.PI
-const DEG_TO_RAD = Math.PI / 180
-
-/** 값이 있는 것만 남긴다. 없는 필드를 `undefined` 로 두면 접었다 편 것이 원본과 달라진다. */
-function withoutEmpty<T extends object>(value: T): T {
-  const out = {} as Record<string, unknown>
-  for (const [key, item] of Object.entries(value)) {
-    if (item !== undefined) out[key] = item
-  }
-  return out as T
-}
-
-/** 소수점 넷째 자리까지. 라디안↔도를 오가며 생기는 꼬리를 자른다. */
-export function round4(value: number): number {
-  return Math.round(value * 1e4) / 1e4
-}
-
-/**
- * 판의 절반. 형식의 원점이 판 중심이라 이 값이 늘 함께 다닌다.
- *
- * 축 이름은 **형식의 것**이다 — x 가로 · y 높이 · z 세로.
- */
-export function halfOf(draft: FigureDraft): Vec3 {
-  return { x: draft.width / 2, y: draft.depth / 2, z: draft.height / 2 }
-}
-
-/*
- * ── The placement is not in these numbers ────────────────────────────────────
- *
- * `placement` says which reference surface a figure of this kind attaches to — a conveyor stands
- * on the floor, an OHT hangs from the ceiling. That is a fact about the figure *type*, and the
- * scene acts on it when an instance is placed: `floor` puts the box on the ground, `ceiling` at
- * the ceiling height less the figure's own height. Nothing about the authored shape changes.
- *
- * So the conversion below does not read it, and the editing canvas does not either. The box is
- * always `0 … base.y` there and `zPos` is always the part's underside. Two figures with identical
- * parts and different placements have identical `parts` arrays, which is what the format says.
- *
- * This used to be wired the other way: the canvas fed the figure's placement to the model layer's
- * `state.placement`, which is a scene-wide coordinate mode ('floor' | 'space' | 'inverted') that
- * flips what `zPos` names for everything in that layer. It stood in for the archetype because the
- * modeller holds exactly one figure — and it cost a whole day of defects, because every number the
- * author typed then meant a different face depending on a dropdown. That coordinate mode is now
- * where it belongs: a workbench setting in `figure-view.ts`, applied to the preview alone.
- */
-
-/**
- * 저작자가 보는 축이 씬의 어느 용어인가.
- *
- * 씬은 2D 캔버스에서 온 용어를 쓰므로 축 이름이 그대로 없다. 이 표가 **유일한** 대응이다 —
- * 편집 규칙이 저마다 자기 표를 들면 한 곳을 고칠 때 다른 곳이 남는다.
- */
-export const AXIS_KEYS = {
-  x: { at: 'left', size: 'width' },
-  y: { at: 'zPos', size: 'depth' },
-  z: { at: 'top', size: 'height' }
-} as const
-
-export type PlaneAxis = keyof typeof AXIS_KEYS
-
-/** 판이 그 축으로 얼마나 넓은가. */
-export function draftExtent(draft: FigureDraft, axis: PlaneAxis): number {
-  return axis === 'x' ? draft.width : axis === 'y' ? draft.depth : draft.height
-}
-
-/** 부품 하나를 저장 형식으로 변환한다. 저작 화면이 저작자의 어휘로 보일 때 쓴다. */
-export function partToFigure(part: PartModel, draft: FigureDraft): FigurePart {
-  return partTo(part, halfOf(draft))
-}
-
-/** 부품 하나를 씬 용어로 되돌린다. */
-export function partFromFigure(part: FigurePart, draft: FigureDraft): PartModel {
-  return partFrom(part, halfOf(draft))
-}
-
-/** 씬 모델을 저장 형식으로 변환한다. */
-export function toFigureSource(draft: FigureDraft, parts: PartModel[]): FigureSource {
-  const half = halfOf(draft)
-
-  return withoutEmpty({
-    version: draft.version ?? FIGURE_SOURCE_VERSION,
-    type: draft.figureType ?? '',
-    base: { x: draft.width, y: draft.depth, z: draft.height },
-    placement: draft.placement,
-    detailLevel: draft.detailLevel,
-    styleKit: draft.styleKit,
-    parts: parts.map(part => partTo(part, half)),
-    animations: draft.animations,
-    parameters: draft.parameters,
-    capabilities: draft.capabilities,
-    joints: draft.joints?.length ? draft.joints : undefined
-  }) as FigureSource
-}
-
-function partTo(part: PartModel, half: Vec3): FigurePart {
-  const rotation = withoutEmpty({
-    x: part.rotationX ? round4(part.rotationX * RAD_TO_DEG) : undefined,
-    y: part.rotation ? round4(-part.rotation * RAD_TO_DEG) : undefined,
-    z: part.rotationY ? round4(part.rotationY * RAD_TO_DEG) : undefined
-  })
-
-  const shape = withoutEmpty({ round: part.round, path: part.path, hollow: part.hollow })
-  /*
-    재질이 하나도 없으면 **칸 자체를 안 적는다.**
-
-    빈 객체를 적으면 형식이 「재질은 있는데 무엇으로 칠할지 모른다」로 읽어
-    `material-unresolvable` 을 낸다. 그리지 않는 자리(`capability`)에는 재질이 없는 것이
-    정상이고, 그 부품이 조용히 오류를 달고 다니게 된다.
-  */
-  const material = withoutEmpty({
-    token: part.token,
-    preset: part.preset,
-    flatShading: part.flatShading,
-    transparent: part.transparent,
-    emissive: part.emissive,
-    surface: part.surface
-  })
-
-  return withoutEmpty({
-    name: part.name,
-    primitive: part.primitive,
-    transform: withoutEmpty({
-      position: {
-        x: round4(part.left + part.width / 2 - half.x),
-        y: round4(part.zPos + part.depth / 2),
-        z: round4(part.top + part.height / 2 - half.z)
-      },
-      size: { x: part.width, y: part.depth, z: part.height },
-      rotation: Object.keys(rotation).length > 0 ? rotation : undefined
-    }),
-    segments: part.segments,
-    shape: Object.keys(shape).length > 0 ? shape : undefined,
-    material: Object.keys(material).length > 0 ? material : undefined,
-    materialSlot: part.materialSlot,
-    keepRound: part.keepRound,
-    sizing: part.sizing,
-    anchor: part.anchor,
-    repeat: part.repeat,
-    label: part.label,
-    capability: part.capability,
-    parent: part.parent
-  }) as FigurePart
-}
-
-/** 형식을 씬 모델로 편다. */
-export function fromFigureSource(source: FigureSource): { draft: FigureDraft; parts: PartModel[] } {
-  const half: Vec3 = { x: source.base.x / 2, y: source.base.y / 2, z: source.base.z / 2 }
-
-  const draft = withoutEmpty({
-    version: source.version,
-    width: source.base.x,
-    height: source.base.z,
-    depth: source.base.y,
-    figureType: source.type,
-    placement: source.placement,
-    detailLevel: source.detailLevel,
-    styleKit: source.styleKit,
-    /* Opened as stored. A legacy `drive: 'hold'` clip is refused by the format now; stored ones were migrated. */
-    animations: source.animations?.length ? source.animations : undefined,
-    parameters: source.parameters?.length ? source.parameters : undefined,
-    capabilities: source.capabilities,
-    joints: source.joints?.length ? source.joints : undefined
-  }) as FigureDraft
-
-  return { draft, parts: source.parts.map(part => partFrom(part, half)) }
-}
-
-function partFrom(part: FigurePart, half: Vec3): PartModel {
-  const { position, size, rotation } = part.transform
-  const material = part.material ?? {}
-
-  return withoutEmpty({
-    type: 'figure-part',
-    name: part.name,
-    primitive: part.primitive,
-
-    left: round4(half.x + position.x - size.x / 2),
-    top: round4(half.z + position.z - size.z / 2),
-    width: size.x,
-    height: size.z,
-    zPos: round4(position.y - size.y / 2),
-    depth: size.y,
-
-    /*
-      라디안은 자르지 않는다.
-
-      소수 넷째에서 잘랐더니 도로 되돌릴 때 57 배로 커져 45 도가 45.0001 이 됐다.
-      자르는 것은 **사람이 읽는 쪽**(도)에서만 한다.
-    */
-    rotationX: rotation?.x ? rotation.x * DEG_TO_RAD : undefined,
-    rotation: rotation?.y ? -rotation.y * DEG_TO_RAD : undefined,
-    rotationY: rotation?.z ? rotation.z * DEG_TO_RAD : undefined,
-
-    segments: part.segments,
-    round: part.shape?.round,
-    path: part.shape?.path,
-    hollow: part.shape?.hollow,
-
-    token: material.token,
-    preset: material.preset,
-    flatShading: material.flatShading,
-    transparent: material.transparent,
-    emissive: material.emissive,
-    surface: material.surface,
-
-    materialSlot: part.materialSlot,
-    keepRound: part.keepRound,
-    sizing: part.sizing,
-    anchor: part.anchor,
-    repeat: part.repeat,
-    label: part.label,
-    capability: part.capability,
-    parent: part.parent
-  }) as PartModel
-}