@hatiolab/figure-model 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/CHANGELOG.md +11 -11
  2. package/README.md +9 -9
  3. package/dist/blueprint.d.ts +32 -3
  4. package/dist/blueprint.d.ts.map +1 -1
  5. package/dist/blueprint.js +76 -6
  6. package/dist/blueprint.js.map +1 -1
  7. package/dist/cost-chart.d.ts +1 -1
  8. package/dist/cost-chart.js +2 -2
  9. package/dist/cost.d.ts +4 -4
  10. package/dist/cost.d.ts.map +1 -1
  11. package/dist/cost.js +2 -2
  12. package/dist/cost.js.map +1 -1
  13. package/dist/index.d.ts +1 -1
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +1 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/keys.d.ts +2 -2
  18. package/dist/keys.js +3 -3
  19. package/dist/keys.js.map +1 -1
  20. package/dist/types.d.ts +53 -28
  21. package/dist/types.d.ts.map +1 -1
  22. package/dist/types.js +22 -10
  23. package/dist/types.js.map +1 -1
  24. package/dist/validate.d.ts +1 -1
  25. package/dist/validate.js +7 -7
  26. package/dist/validate.js.map +1 -1
  27. package/docs/design.md +3 -3
  28. package/docs/format-survey.md +3 -3
  29. package/docs/format.md +18 -18
  30. package/docs/validation.md +5 -5
  31. package/package.json +1 -1
package/docs/format.md CHANGED
@@ -1,13 +1,13 @@
1
1
  # 형식 레퍼런스
2
2
 
3
- 정본(`FigureSource`)과 청사진(`FigureBlueprint`)의 모든 필드.
3
+ 원본 데이터(`FigureSource`)와 청사진(`FigureBlueprint`)의 모든 필드.
4
4
 
5
5
  ```
6
6
  FigureSource 저작 결과. 편집 가능한 정본. DB 에 저장된다.
7
7
  FigureBlueprint 보드가 세우는 형태. 정본에서 파생되는 캐시. 저장하지 않는다.
8
8
  ```
9
9
 
10
- 값의 정본은 `src/types.ts` 다. 이 문서와 코드가 어긋나면 `src/docs.test.ts` 가 깨진다.
10
+ 값의 기준이 되는 원본은 `src/types.ts` 다. 이 문서와 코드가 어긋나면 `src/docs.test.ts` 가 실패한다.
11
11
 
12
12
  ## 좌표 규약
13
13
 
@@ -20,7 +20,7 @@ z 앞 (보는 쪽)
20
20
  ```
21
21
 
22
22
  크기도 축 이름으로 부른다. `width` · `height` · `depth` 는 쓰지 않는다 — 어느 축인지
23
- 따로 외워야 하는 낱말이고, 그 외움이 실제로 사고를 냈다.
23
+ 따로 외워야 하는 용어이고, 실제로 그것 때문에 사고가 났다.
24
24
 
25
25
  ```
26
26
  transform.position { x, y, z } 부품 중심의 자리
@@ -36,7 +36,7 @@ transform.rotation { x, y, z } 축별 회전(도), 선택
36
36
 
37
37
  ---
38
38
 
39
- ## `FigureSource` — 정본
39
+ ## `FigureSource` — 원본 데이터
40
40
 
41
41
  | 필드 | 타입 | 필수 | 뜻 |
42
42
  | ------------- | -------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -45,13 +45,13 @@ transform.rotation { x, y, z } 축별 회전(도), 선택
45
45
  | `parts` | `FigurePart[]` | ✓ | 부품. 하나는 있어야 한다 |
46
46
  | `anchor` | `Vec3` | | 배치 기준점 |
47
47
  | `detailLevel` | `'S' \| 'M' \| 'L'` | | 부품 수 상한을 정한다 (3 · 8 · 20) |
48
- | `styleKit` | `string` | | StyleKit 이름 — 팔레트·분할 수·그리드·등급을 한 벌로 받는다 |
48
+ | `styleKit` | `string` | | StyleKit 이름. 팔레트·분할 수·그리드·등급을 한 번에 받는다 |
49
49
 
50
50
  ## `FigurePart` — 부품
51
51
 
52
52
  | 필드 | 타입 | 필수 | 뜻 |
53
53
  | ----------- | ----------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- |
54
- | `name` | `string` | ✓ | **저장되는 식별자다.** 바인딩·애니메이션·슬롯이 이 이름을 가리킨다. 바꾸면 인스턴스의 바인딩이 조용히 끊긴다. 한 Figure 안에서 겹칠 수 없다 |
54
+ | `name` | `string` | ✓ | **저장되는 식별자다.** 바인딩·애니메이션·슬롯이 이 이름을 가리킨다. 바꾸면 인스턴스의 바인딩이 오류보고없이 끊긴다. 한 Figure 안에서 겹칠 수 없다 |
55
55
  | `primitive` | `PrimitiveKind` | ✓ | 아래 표 |
56
56
  | `transform` | `PartTransform` | ✓ | 자리와 크기 |
57
57
  | `material` | `PartMaterial` | ✓ | 색과 질감 |
@@ -59,7 +59,7 @@ transform.rotation { x, y, z } 축별 회전(도), 선택
59
59
  | `shape` | `PartShape` | | 단면. `rect` · `polygon` 만 |
60
60
  | `slot` | `'cap' \| 'side'` | | 상태 색이 연동될 재질 슬롯. 없으면 상태를 표현하지 않는다 |
61
61
  | `sizing` | `SizingRule` | | 크기 반응 규칙. 기본 `'scale'` |
62
- | `repeat` | `{ axis, gap }` | | `sizing` 이 `'repeat'` 일 때 필수 |
62
+ | `repeat` | `{ axis, pitch }` | | `sizing` 이 `'repeat'` 일 때 필수 |
63
63
  | `animation` | `AnimationPoint` | | 애니메이션 포인트 |
64
64
  | `label` | `LabelSpec` | | 텍스트. 아래 표 |
65
65
 
@@ -101,7 +101,7 @@ mesh 계열은 치수만으로 선다. extrude 계열은 2D 단면을 위로 민
101
101
 
102
102
  #### 색은 팔레트 토큰 하나뿐이다 — 빠뜨린 것이 아니라 금지한 것이다
103
103
 
104
- 무늬·그라디언트를 담는 자리가 `PartMaterial` 에 없는 것은 아직 안 만들어서가 아니다.
104
+ 무늬·그라디언트를 담을 항목이 `PartMaterial` 에 없는 것은 아직 만들지 않아서가 아니다.
105
105
  두 이유에서 일부러 뺐다.
106
106
 
107
107
  | | 이유 |
@@ -129,7 +129,7 @@ mesh 계열은 치수만으로 선다. extrude 계열은 2D 단면을 위로 민
129
129
  | ------- | ------------------- | ----------------------------------------------------------------------------------- |
130
130
  | `kind` | `AnimationKind` | `fade` · `heartbeat` · `moving` · `outline` · `rotation` · `vibration` · `waypoint` |
131
131
  | `axis` | `'x' \| 'y' \| 'z'` | 회전은 필수 |
132
- | `pivot` | `Vec3` | **회전은 필수.** 없으면 부품 자기 중심으로 돈다 |
132
+ | `pivot` | `Vec3` | **회전은 필수.** 없으면 회전축이 부품 자기 중심이 된다 |
133
133
 
134
134
  ### `LabelSpec`
135
135
 
@@ -157,12 +157,12 @@ mesh 계열은 치수만으로 선다. extrude 계열은 2D 단면을 위로 민
157
157
 
158
158
  ## `FigureBlueprint` — 청사진
159
159
 
160
- `compile(source)` 가 낸다. 저장하지 않는다 — 정본에서 언제든 다시 만든다.
160
+ `compile(source)` 가 만든다. 저장하지 않고 원본 데이터에서 언제든 다시 만든다.
161
161
 
162
162
  | 필드 | 타입 | 뜻 |
163
163
  | -------------------------- | ----------------------- | ----------------------------------------- |
164
164
  | `version` | `number` | `BLUEPRINT_VERSION`. 형식이 바뀌면 오른다 |
165
- | `type` · `base` · `anchor` | | 정본에서 그대로 |
165
+ | `type` · `base` · `anchor` | | 원본 데이터에서 그대로 |
166
166
  | `budget` | `{ triangles, groups }` | 예산. `groups` 가 **재는 값**이다 |
167
167
  | `groups` | `BlueprintGroup[]` | 재질별로 병합된 묶음 |
168
168
  | `points` | `BlueprintPoint[]` | 애니메이션 포인트. 부품 이름으로 가리킨다 |
@@ -174,16 +174,16 @@ mesh 계열은 치수만으로 선다. extrude 계열은 2D 단면을 위로 민
174
174
  | 필드 | 뜻 |
175
175
  | ------------- | --------------------------------------------------- |
176
176
  | `materialKey` | MaterialBank 키 |
177
- | `material` | 정본의 `PartMaterial` 그대로 |
177
+ | `material` | 원본 데이터의 `PartMaterial` 그대로 |
178
178
  | `slot` | 재질 슬롯 |
179
- | `animated` | 애니메이션이 걸린 묶음. **걸리면 부품 하나만 든다** |
179
+ | `animated` | 애니메이션이 연결된 그룹인지. **연결되면 부품을 하나만 갖는다** |
180
180
  | `members` | `BlueprintMember[]` |
181
181
 
182
182
  ### `BlueprintMember` — 묶음 안의 부품
183
183
 
184
184
  | 필드 | 뜻 |
185
185
  | ------------------------------------------------------------------ | ----------------------------------------------------------------- |
186
- | `name` · `primitive` · `transform` · `shape` · `sizing` · `repeat` | 정본에서 |
186
+ | `name` · `primitive` · `transform` · `shape` · `sizing` · `repeat` | 원본 데이터에서 |
187
187
  | `segments` | 곡면 분할 수. **2D 톱뷰를 3D 와 같은 각으로 근사하려면 필요하다** |
188
188
  | `geometryKey` | GeometryBank 키. 실체가 아니라 참조다 |
189
189
  | `triangles` | 이 부품의 삼각형 수 **추정** |
@@ -198,7 +198,7 @@ mesh 계열은 치수만으로 선다. extrude 계열은 2D 단면을 위로 민
198
198
  | `materialKeyOf` | `token\|preset\|f\|t` (`-` 는 없음) |
199
199
  | `groupKeyOf` | `materialKey\|\|slot` |
200
200
 
201
- **geometry 키에 치수가 든다.** 경로에서 오는 형상은 단위로 정규화하면 모서리 반경
201
+ **geometry 키에 치수가 들어간다.** 경로에서 오는 형상은 단위로 정규화하면 모서리 반경
202
202
  비율이 망가지므로 치수를 굽고, 대신 같은 치수끼리만 공유한다. **자리는 키에 들지
203
203
  않는다** — 어디 있든 같은 형상이다.
204
204
 
@@ -249,11 +249,11 @@ material 키를 줄인다.
249
249
  | `transparent` | `LIMITS.transparentMaterials` | 투명은 별도 정렬 경로 |
250
250
  | `parts` | `PART_LIMIT[detailLevel]` | 등급이 정한 상한. 등급이 없으면 이 항목이 빠진다 |
251
251
 
252
- - `score` — **가장 빠듯한 한도에 남은 여유**(0–100). 평균이 아니다. 넷 중 하나만 꽉
252
+ - `score` — **한도에 가장 가까운 항목에 남은 여유**(0–100). 평균이 아니다. 넷 중 하나만 꽉
253
253
  차 있어도 대량 배치에서는 그것이 병목이 되므로, 평균을 내면 병목이 여유에 묻힌다.
254
254
  - `grade` — **A** 여유 절반 이상 · **B** 4분의 1 이상 · **C** 한도 안 · **D** 한도 초과.
255
255
  D 는 곧 위반이 있다는 뜻이고 사유는 `blueprint.violations` 에 있다.
256
- - `tightest` — 어느 한도가 제일 빠듯한가. **여기부터 고치면 된다.**
256
+ - `tightest` — 어느 한도가 가장 가까운가. **여기부터 고치면 된다.**
257
257
  - `reuse` — 형상 되쓰기. **점수에 넣지 않는다.** 되쓰기는 많을수록 좋지만 한도가
258
258
  없다. 점수에 섞으면 「형상을 억지로 같게 만들라」는 신호가 되어 저작을 왜곡한다.
259
259
 
@@ -272,7 +272,7 @@ material 키를 줄인다.
272
272
  ## 구현 상태 — 선언됐으나 아직 동작하지 않는 것
273
273
 
274
274
  **이 절이 이 문서에서 가장 중요하다.** 형식에 자리가 있다고 해서 그 자리가 동작하는
275
- 것은 아니다. 아래는 정본·청사진에 실려 나가지만 **읽어서 무언가 하는 코드가 아직
275
+ 것은 아니다. 아래는 원본 데이터와 청사진에 함께 나가지만 **읽어서 무언가 하는 코드가 아직
276
276
  없는** 것들이다.
277
277
 
278
278
  | 선언 | 검증 | 청사진에 실림 | 읽는 곳 |
package/docs/validation.md CHANGED
@@ -19,7 +19,7 @@ const { errors, violations } = validate(source)
19
19
 
20
20
  ## 코드는 목록으로 잠겨 있다
21
21
 
22
- `ERROR_CODES` · `VIOLATION_CODES` 가 정본이고 `FigureError.code` · `Violation.code` 가
22
+ `ERROR_CODES` · `VIOLATION_CODES` 가 기준이 되는 원본이고 `FigureError.code` · `Violation.code` 가
23
23
  그 값으로 좁혀져 있다. **목록에 없는 코드는 타입 검사가 막는다.** 이 문서와 목록이
24
24
  어긋나면 `src/docs.test.ts` 가 깨진다.
25
25
 
@@ -36,14 +36,14 @@ const { errors, violations } = validate(source)
36
36
 
37
37
  | 코드 | 언제 |
38
38
  | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
39
- | `not-object` | 객체여야 할 자리에 객체가 아닌 것이 왔다 (정본 자체, 부품, `transform.rotation`, `material`, `animation`, `label`, `Vec3`) |
39
+ | `not-object` | 객체여야 할 자리에 객체가 아닌 것이 왔다 (원본 데이터 자체, 부품, `transform.rotation`, `material`, `animation`, `label`, `Vec3`) |
40
40
  | `not-finite` | 수여야 할 자리가 수가 아니거나 `NaN`·`Infinity` 다 |
41
41
  | `not-positive` | 0 보다 커야 하는데 아니다 (`base` 의 세 변) |
42
42
  | `not-integer` | `segments` 가 정수가 아니다 |
43
43
  | `not-boolean` | `material.flatShading` · `material.transparent` 가 참·거짓이 아니다 |
44
44
  | `not-allowed` | 열거 값이 목록 밖이다 (`primitive` · `preset` · `slot` · `sizing` · `axis` · `detailLevel` · `animation.kind` · `label.when`) |
45
45
 
46
- ### 정본 뼈대
46
+ ### 원본의 필수 항목
47
47
 
48
48
  | 코드 | 언제 | 왜 |
49
49
  | --------------- | ----------------------------------------- | --------------------------------------------------------- |
@@ -87,8 +87,8 @@ const { errors, violations } = validate(source)
87
87
 
88
88
  | 코드 | 언제 | 왜 |
89
89
  | --------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
90
- | `missing-axis` | 회전인데 `axis` 가 없다 | 어느 축으로 도는지 모른다 |
91
- | `missing-pivot` | 회전인데 `pivot` 이 없다 | 없으면 부품 **자기 중심**으로 돈다. 교반 축이 몸체 가운데를 돌아야 하면 결과가 완전히 달라진다 |
90
+ | `missing-axis` | 회전인데 `axis` 가 없다 | 어느 축으로 회전하는지 모른다 |
91
+ | `missing-pivot` | 회전인데 `pivot` 이 없다 | 없으면 회전축이 부품 **자기 중심**이 된다. 교반 축이 몸체 가운데를 돌아야 하면 결과가 완전히 달라진다 |
92
92
 
93
93
  ### 예외 표면
94
94
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hatiolab/figure-model",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "description": "Figure 저작 결과의 정본 형식과 검증 — 재질별로 병합되고 이름이 붙은 부품 그래프. 3D 로 저작한 형상 하나가 씬 컴포넌트로 서는 데 필요한 것을 담는다.",
5
5
  "keywords": [
6
6
  "figure",