@things-factory/figure-ui 10.1.3

package/client/modeller/figure-source.test.ts

@@ -0,0 +1,336 @@
+import { existsSync, readFileSync } from 'fs'
+import { dirname, join } from 'path'
+
+import { toFigureSource, fromFigureSource } from './figure-source'
+import type { BoardModel, PartModel } from './figure-source'
+import type { FigureSource } from '@hatiolab/figure-model'
+
+/**
+ * 씬 모델 ↔ `FigureSource`.
+ *
+ * 저작 중의 정본은 씬 모델이고, 형식은 저장하거나 판정할 때 접어서 만든다. 두 어휘가
+ * 다르므로 **옮기는 일이 한 곳에만** 있어야 하고, 그 한 곳이 맞는지를 여기서 못 박는다.
+ *
+ * 가장 중요한 것은 왕복이다. 접었다 펴면 같아야 하고 펴서 접어도 같아야 한다 —
+ * 어느 한쪽에서만 맞으면 AI 가 제안해 온 정본을 편집하는 순간 값이 샌다.
+ */
+
+/** 판 3000 x 2000 x 800 — 세 축이 다 달라야 축을 바꿔 써도 시험이 잡는다. */
+const BOARD: BoardModel = {
+  width: 3000,
+  height: 2000,
+  depth: 800,
+  figureType: 'AGV',
+  detailLevel: 'L'
+}
+
+const PART: PartModel = {
+  type: 'figure-part',
+  name: 'deck',
+  primitive: 'cube',
+  left: 1100,
+  top: 700,
+  width: 800,
+  height: 600,
+  zPos: 300,
+  depth: 200,
+  token: 'palette.primary'
+}
+
+describe('접기 — 씬 모델을 형식으로', () => {
+  it('판이 기준 상자가 된다 — 높이는 판의 depth 다', () => {
+    const { base } = toFigureSource(BOARD, [])
+    expect(base).toEqual({ x: 3000, y: 800, z: 2000 })
+  })
+
+  it('부품 자리가 판 중심 기준이 된다', () => {
+    const [part] = toFigureSource(BOARD, [PART]).parts
+
+    // 평면 중심 (1100+400, 700+300) = (1500, 1000), 판 중심 (1500, 1000) → 원점
+    expect(part.transform.position.x).toBe(0)
+    expect(part.transform.position.z).toBe(0)
+  })
+
+  it('zPos 는 밑면이다 — 중심으로 올려 적는다', () => {
+    const [part] = toFigureSource(BOARD, [PART]).parts
+
+    // 밑면 300 + 두께 200/2 = 중심 400. 판 높이 800 의 절반을 빼면 0
+    expect(part.transform.position.y).toBe(0)
+  })
+
+  it('가운데를 벗어난 부품이 그만큼 어긋나 적힌다', () => {
+    const moved = { ...PART, left: 1200, top: 900, zPos: 500 }
+    const [part] = toFigureSource(BOARD, [moved]).parts
+
+    expect(part.transform.position).toEqual({ x: 100, y: 200, z: 200 })
+  })
+
+  it('크기가 축 이름으로 바뀐다 — 두께가 y 다', () => {
+    const [part] = toFigureSource(BOARD, [PART]).parts
+    expect(part.transform.size).toEqual({ x: 800, y: 200, z: 600 })
+  })
+
+  /*
+    씬은 라디안을 쓰고 이름이 뒤섞여 있다 — rotationY 가 three 의 z 로 간다.
+    형식은 도를 쓰고 축 이름이 그대로다.
+  */
+  it('회전이 도로 바뀌고 축이 제자리를 찾는다', () => {
+    const turned = { ...PART, rotationX: Math.PI / 6, rotation: Math.PI / 2, rotationY: Math.PI }
+    const [part] = toFigureSource(BOARD, [turned]).parts
+
+    expect(part.transform.rotation).toEqual({ x: 30, y: -90, z: 180 })
+  })
+
+  it('회전이 없으면 필드를 두지 않는다', () => {
+    const [part] = toFigureSource(BOARD, [PART]).parts
+    expect(part.transform.rotation).toBeUndefined()
+  })
+
+  it('재질이 한 덩어리로 모인다', () => {
+    const [part] = toFigureSource(BOARD, [{ ...PART, preset: 'metal', flatShading: false }]).parts
+    expect(part.material).toEqual({ token: 'palette.primary', preset: 'metal', flatShading: false })
+  })
+
+  it('단면 값이 shape 으로 모인다', () => {
+    const [part] = toFigureSource(BOARD, [{ ...PART, primitive: 'rect', round: 40 }]).parts
+    expect(part.shape).toEqual({ round: 40 })
+  })
+
+  it('단면 값이 없으면 shape 을 두지 않는다', () => {
+    expect(toFigureSource(BOARD, [PART]).parts[0].shape).toBeUndefined()
+  })
+})
+
+describe('펴기 — 형식을 씬 모델로', () => {
+  const SOURCE: FigureSource = {
+    type: 'AGV',
+    base: { x: 3000, y: 800, z: 2000 },
+    detailLevel: 'L',
+    parts: [
+      {
+        name: 'deck',
+        primitive: 'cube',
+        transform: { position: { x: 100, y: 200, z: 200 }, size: { x: 800, y: 200, z: 600 } },
+        material: { token: 'palette.primary' }
+      }
+    ]
+  }
+
+  it('기준 상자가 판이 된다', () => {
+    const { board } = fromFigureSource(SOURCE)
+    expect(board).toMatchObject({ width: 3000, height: 2000, depth: 800 })
+  })
+
+  it('중심 기준 자리가 씬의 모서리·밑면으로 바뀐다', () => {
+    const [part] = fromFigureSource(SOURCE).parts
+    expect(part).toMatchObject({ left: 1200, top: 900, zPos: 500 })
+  })
+
+  it('부품이 씬 타입을 갖는다 — 판에 그대로 놓을 수 있어야 한다', () => {
+    expect(fromFigureSource(SOURCE).parts[0].type).toBe('figure-part')
+  })
+})
+
+/*
+  왕복.
+
+  이것이 이 모듈의 존재 이유다. 한쪽에서만 맞으면 AI 가 제안해 온 정본을 펴서
+  편집하고 다시 접는 순간 값이 샌다 — 그것도 조용히.
+*/
+/**
+ * 형식이 가진 것을 되도록 다 담은 정본. 안 쓰이는 필드도 넣는다.
+ *
+ * describe 밖에 둔다 — 아래 「픽스처가 형식을 다 담는다」가 이것을 형식의 필드 목록과
+ * 맞대어 본다.
+ */
+/** 형식이 가진 것을 되도록 다 담은 정본. 안 쓰이는 필드도 넣는다. */
+const FULL: FigureSource = {
+  type: 'AGV',
+  base: { x: 3000, y: 800, z: 2000 },
+  detailLevel: 'L',
+  styleKit: 'factory',
+  anchor: { x: 0, y: -400, z: 0 },
+  parts: [
+    {
+      name: 'deck',
+      primitive: 'cube',
+      transform: { position: { x: 100, y: 200, z: 200 }, size: { x: 800, y: 200, z: 600 } },
+      material: { token: 'palette.primary', preset: 'metal', flatShading: true }
+    },
+    {
+      name: 'wheel',
+      primitive: 'cylinder',
+      segments: 24,
+      transform: {
+        position: { x: -700, y: -260, z: 420 },
+        size: { x: 180, y: 70, z: 180 },
+        rotation: { z: 90 }
+      },
+      material: { token: 'palette.dark', preset: 'rubber' }
+    },
+    {
+      name: 'panel',
+      primitive: 'rect',
+      // 속을 판 단면. 한 겹 안이라 처음 판 시험이 못 봤던 자리다.
+      shape: { round: 40, hollow: { wall: 8, floor: 4 } },
+      transform: {
+        position: { x: 0, y: 260, z: -500 },
+        size: { x: 400, y: 30, z: 200 },
+        rotation: { x: 15, y: -30, z: 45 }
+      },
+      material: { token: 'palette.accent', transparent: true },
+      // 아직 아무 일도 안 하는 필드들. 잃어버리면 안 된다.
+      materialSlot: 'cap',
+      keepRound: false,
+      sizing: 'fixed',
+      anchor: { x: 'span', y: 'max', z: 'center' },
+      label: { name: 'rpm', source: 'speed', when: 'zoomed' }
+    },
+    {
+      name: 'foot',
+      primitive: 'polygon',
+      shape: {
+        path: [
+          { x: -60, y: -40 },
+          { x: 60, y: -40 },
+          { x: 0, y: 40 }
+        ]
+      },
+      transform: { position: { x: 900, y: -340, z: -600 }, size: { x: 120, y: 80, z: 80 } },
+      material: { token: 'palette.neutral' },
+      sizing: 'repeat',
+      repeat: { axis: 'x', pitch: 200 }
+    }
+  ],
+  /*
+    움직임. 편집면이 아직 안 만지는 자리이며, **바로 그래서 여기 있다.**
+
+    이 픽스처가 「형식이 가진 것을 되도록 다 담은 정본」인데 clip 이 빠져 있었고, 그
+    사이 `toFigureSource` 가 clip 을 안 실었다. 시험은 초록이었다 — 픽스처에 없는 것은
+    시험이 못 본다. 표본 롤러에 clip 을 적고 미리보기에서 아무것도 안 돌고 나서야 알았다.
+  */
+  animations: [
+    {
+      name: 'spin',
+      drive: 'loop',
+      channels: [
+        {
+          target: 'wheel',
+          path: 'rotation',
+          pivot: { x: 0, y: 0, z: 0 },
+          keys: [
+            { at: 0, value: { x: 0, y: 0, z: 0 } },
+            { at: 1, value: { x: 0, y: 360, z: 0 } }
+          ]
+        }
+      ]
+    }
+  ]
+}
+
+describe('왕복해도 같다', () => {
+
+  it('펴서 접으면 그대로다', () => {
+    const { board, parts } = fromFigureSource(FULL)
+    expect(toFigureSource(board, parts)).toEqual(FULL)
+  })
+
+  it('접어서 펴면 그대로다', () => {
+    const { board, parts } = fromFigureSource(FULL)
+    const again = fromFigureSource(toFigureSource(board, parts))
+
+    expect(again.board).toEqual(board)
+    expect(again.parts).toEqual(parts)
+  })
+
+  it('두 번 왕복해도 값이 밀리지 않는다 — 라디안·도를 오가도', () => {
+    let source = FULL
+    for (let i = 0; i < 5; i++) {
+      const { board, parts } = fromFigureSource(source)
+      source = toFigureSource(board, parts)
+    }
+    expect(source).toEqual(FULL)
+  })
+
+  it('움직임도 살아남는다 — 열었다 저장하는 것만으로 지워지던 자리다', () => {
+    const { board, parts } = fromFigureSource(FULL)
+
+    expect(toFigureSource(board, parts).animations).toEqual(FULL.animations)
+  })
+
+  it('안 쓰이는 필드도 살아남는다 — 조용히 사라지면 저작자가 알 길이 없다', () => {
+    const { board, parts } = fromFigureSource(FULL)
+    const panel = toFigureSource(board, parts).parts.find(part => part.name === 'panel')!
+
+    expect(panel.materialSlot).toBe('cap')
+    expect(panel.sizing).toBe('fixed')
+    expect(panel.label).toEqual({ name: 'rpm', source: 'speed', when: 'zoomed' })
+  })
+})
+
+/*
+  픽스처가 형식을 따라가는지.
+
+  **이 파일에서 필드가 네 번 샜다** — `ports` · `animations` · `anchor` · `shape.hollow`.
+  네 번 다 왕복 시험은 초록이었다. 위의 `FULL` 이 「형식이 가진 것을 되도록 다 담은
+  정본」이라고 적혀 있었지만 실제로는 그때그때 손으로 채운 것이라, 형식에 필드가 늘면
+  픽스처는 그대로 있고 시험은 늘어난 자리를 보지 못했다.
+
+  네 번째 것은 **한 겹 안**이라 최상위만 세던 첫 판이 놓쳤다. 그래서 픽스처의 키를
+  깊이 상관없이 다 모아 놓고 맞댄다.
+
+  그래서 픽스처를 믿지 않고 **형식이 스스로 밝힌 필드 목록**을 읽는다. 형식이 붙은
+  타입 선언(`dist/types.d.ts`)이 정본이고, 거기 적힌 이름이 픽스처에 없으면 여기서
+  깨진다. 다음 번 필드는 화면이 아니라 이 시험이 먼저 잡는다.
+*/
+describe('픽스처가 형식을 다 담는다', () => {
+  /**
+   * 형식이 붙여 보낸 타입 선언 파일.
+   *
+   * `require.resolve` 로는 못 잡는다 — jest 의 resolver 가 `.d.ts` 를 모듈로 보지
+   * 않는다. 올라가면서 찾고, 못 찾으면 조용히 건너뛰지 않고 여기서 깨진다.
+   */
+  function declarationPath(): string {
+    for (let at = __dirname; at !== dirname(at); at = dirname(at)) {
+      const candidate = join(at, 'node_modules/@hatiolab/figure-model/dist/types.d.ts')
+      if (existsSync(candidate)) return candidate
+    }
+    throw new Error('figure-model 의 타입 선언을 못 찾았다 — 이 시험은 그것이 정본이다')
+  }
+
+  /** 붙은 타입 선언에서 한 인터페이스의 필드 이름을 뽑는다. */
+  function fieldsOf(name: string): string[] {
+    const declared = readFileSync(declarationPath(), 'utf-8')
+    const start = declared.indexOf(`export interface ${name} {`)
+    expect(start).toBeGreaterThan(-1)
+
+    // 중첩이 없는 평평한 인터페이스다. 다음 닫는 중괄호가 끝이다.
+    const body = declared.slice(start, declared.indexOf('\n}', start))
+    return [...body.matchAll(/^\s{4}(\w+)\??:/gm)].map(m => m[1])
+  }
+
+  /** 픽스처가 쓴 키를 깊이 상관없이 모은다 — 흘린 필드가 한 겹 안에 있었다. */
+  function keysDeep(value: unknown, into = new Set<string>()): Set<string> {
+    if (Array.isArray(value)) value.forEach(one => keysDeep(one, into))
+    else if (value && typeof value === 'object') {
+      for (const [key, one] of Object.entries(value)) {
+        into.add(key)
+        keysDeep(one, into)
+      }
+    }
+    return into
+  }
+
+  const WRITTEN = keysDeep(FULL)
+
+  /*
+    `fold` 가 실제로 낱개로 푸는 것들이다. 통째로 나르는 구조(`transform` 처럼)는 필드가
+    늘어도 안 새므로 여기 없다.
+  */
+  it.each(['FigureSource', 'FigurePart', 'PartShape', 'HollowSpec'])(
+    '%s 가 가진 모든 필드가 왕복 픽스처에 있다',
+    name => {
+      expect(fieldsOf(name).filter(field => !WRITTEN.has(field))).toEqual([])
+    }
+  )
+})

package/client/modeller/figure-source.ts

@@ -0,0 +1,338 @@
+import type { DetailLevel, FigurePart, FigureSource, 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 board. `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 board is the base box; its centre is the format's origin.
+ *
+ *     format            scene
+ *     ────────────────  ──────────────────────────────
+ *     base.x            board width
+ *     base.y            board depth      <- height
+ *     base.z            board height
+ *
+ *     size.x            width
+ *     size.y            depth
+ *     size.z            height
+ *
+ *     position.x        left + width/2  - board width/2
+ *     position.y        zPos + depth/2  - board depth/2      <- zPos is the underside
+ *     position.z        top  + height/2 - board height/2
+ *
+ *     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 BoardModel {
+  /** 기준 상자. 씬의 용어 그대로다. */
+  width: number
+  height: number
+  depth: number
+  /** 컴포넌트 타입 이름. **저장되는 식별자다.** */
+  figureType?: string
+  detailLevel?: DetailLevel
+  styleKit?: string
+  /**
+   * 형상 전체의 기준점.
+   *
+   * **부품의 `anchor` 와 다른 것이다.** 이쪽은 점(`Vec3`)이고 저쪽은 축별로 어느 면을
+   * 붙잡느냐다. 한 형식 안에 같은 낱말이 둘인 것은 좋지 않으나, 이름을 바꾸면 저장된
+   * 원본이 따라와야 하므로 여기서 정하지 않는다.
+   */
+  anchor?: Vec3
+  /**
+   * 움직임. **부품 바깥에 있다** — clip 하나가 부품 여럿을 함께 움직이기 때문이다.
+   *
+   * 편집면이 아직 이것을 만지지 않는다. 그래도 여기 실어 두는 것은, 안 실으면 열었다
+   * 저장하는 것만으로 **조용히 지워지기** 때문이다.
+   */
+  animations?: FigureSource['animations']
+}
+
+/** 부품 컴포넌트의 상태. 씬의 용어 그대로다. */
+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
+
+  token?: string
+  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']
+}
+
+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
+}
+
+/** 소수점 넷째 자리까지. 라디안↔도를 오가며 생기는 꼬리를 자른다. */
+function round4(value: number): number {
+  return Math.round(value * 1e4) / 1e4
+}
+
+/**
+ * 판의 절반. 형식의 원점이 판 중심이라 이 값이 늘 함께 다닌다.
+ *
+ * 축 이름은 **형식의 것**이다 — x 가로 · y 높이 · z 세로.
+ */
+export function halfOf(board: BoardModel): Vec3 {
+  return { x: board.width / 2, y: board.depth / 2, z: board.height / 2 }
+}
+
+/**
+ * 저작자가 보는 축이 씬의 어느 용어인가.
+ *
+ * 씬은 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 boardExtent(board: BoardModel, axis: PlaneAxis): number {
+  return axis === 'x' ? board.width : axis === 'y' ? board.depth : board.height
+}
+
+/** 부품 하나를 저장 형식으로 변환한다. 저작 화면이 저작자의 어휘로 보일 때 쓴다. */
+export function partToFigure(part: PartModel, board: BoardModel): FigurePart {
+  return partTo(part, halfOf(board))
+}
+
+/** 부품 하나를 씬 용어로 되돌린다. */
+export function partFromFigure(part: FigurePart, board: BoardModel): PartModel {
+  return partFrom(part, halfOf(board))
+}
+
+/** 씬 모델을 저장 형식으로 변환한다. */
+export function toFigureSource(board: BoardModel, parts: PartModel[]): FigureSource {
+  const half = halfOf(board)
+
+  return withoutEmpty({
+    type: board.figureType ?? '',
+    base: { x: board.width, y: board.depth, z: board.height },
+    anchor: board.anchor,
+    detailLevel: board.detailLevel,
+    styleKit: board.styleKit,
+    parts: parts.map(part => partTo(part, half)),
+    animations: board.animations
+  }) 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 })
+  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 - half.y),
+        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,
+    materialSlot: part.materialSlot,
+    keepRound: part.keepRound,
+    sizing: part.sizing,
+    anchor: part.anchor,
+    repeat: part.repeat,
+    label: part.label
+  }) as FigurePart
+}
+
+/** 형식을 씬 모델로 편다. */
+export function fromFigureSource(source: FigureSource): { board: BoardModel; parts: PartModel[] } {
+  const half: Vec3 = { x: source.base.x / 2, y: source.base.y / 2, z: source.base.z / 2 }
+
+  const board = withoutEmpty({
+    width: source.base.x,
+    height: source.base.z,
+    depth: source.base.y,
+    figureType: source.type,
+    detailLevel: source.detailLevel,
+    styleKit: source.styleKit,
+    anchor: source.anchor,
+    animations: source.animations
+  }) as BoardModel
+
+  return { board, 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(half.y + 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
+  }) as PartModel
+}