@hatiolab/things-scene 10.0.0-beta.93 → 10.0.0-beta.95

package/dist-types/types/polygon-path-arc.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Polygon path arc-length / sampling.
+ *
+ * Phase L 의 PolygonPathPoint(per-vertex radius + bulge) 를 polyline 으로 평탄화하여
+ * 전체 길이 계산과 임의 위치(s ∈ [0, L)) 의 좌표·접선각 sampling 을 제공한다.
+ *
+ * 평탄화 로직은 `PolygonExtrude.shape` 의 corner round(quadratic Bezier) + bulge arc
+ * 처리와 동일 — 시각(extruded mesh)과 시뮬(carrier 위치)이 어긋나지 않는다.
+ *
+ * 사용자(loop-conveyor 등): path 가 변하지 않는 동안 결과를 캐시하여 매 carrier sample
+ * 마다 재계산을 피한다.
+ */
+import { type PolygonPathPoint } from './polygon-path.js';
+/** Path sampling 옵션. */
+export interface PathArcOptions {
+    /** Closed loop (path[N-1] → path[0] 자동 연결, 모든 vertex 에 corner round 적용 가능). default true. */
+    closed?: boolean;
+    /** per-vertex radius 가 없을 때 fallback (state.round). default 0. */
+    round?: number;
+    /** corner round (quadratic Bezier) / bulge arc 의 segment 당 sub-division 수. default 24. */
+    divisions?: number;
+}
+/** Path 위 한 점의 sample. */
+export interface PathSample {
+    x: number;
+    y: number;
+    /** 진행 방향 접선각(라디안). atan2(dy, dx). */
+    theta: number;
+}
+/**
+ * 평탄화된 polygon path. 길이/sample 의 cache 컨테이너.
+ *
+ * `path` 가 변하면 인스턴스를 다시 만들어야 한다 (mutation 추적 X).
+ */
+export declare class PolygonPathPolyline {
+    /** 평탄화된 점들. closed 면 마지막 점 = 첫 점. */
+    readonly points: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    /** points[i] 까지의 누적 arc length. cumulative[0] = 0. */
+    readonly cumulative: ReadonlyArray<number>;
+    /** 전체 arc length. closed 면 폐루프 한 바퀴 길이. */
+    readonly length: number;
+    /** closed 여부 (sample 시 wraparound 결정). */
+    readonly closed: boolean;
+    constructor(points: {
+        x: number;
+        y: number;
+    }[], closed: boolean);
+    /**
+     * Path 위 거리 `s` 에서의 좌표 + 접선각.
+     * closed 면 s 는 자동 modulo wrap. open 이면 [0, length] 로 clamp.
+     */
+    sample(s: number): PathSample;
+}
+/**
+ * Polygon path 를 polyline 으로 평탄화. PolygonExtrude.shape 와 동일 sampling 로직.
+ *
+ * - corner round: quadratic Bezier (p1, cursor, p2) 를 `divisions` 분할
+ * - bulge arc: computeArcParams 의 (cx, cy, r, startAngle, endAngle, clockwise) 를
+ *   `divisions` 분할 (clockwise 부호에 맞춰 angle 진행)
+ * - closed=true: 마지막 점에서 첫 점까지 segment 로 닫음
+ * - closed=false: path[0] 와 path[N-1] 은 corner round 적용 안 함 (한쪽 변뿐)
+ */
+export declare function flattenPolygonPath(path: PolygonPathPoint[], options?: PathArcOptions): PolygonPathPolyline;
+/**
+ * Polygon path 의 전체 arc length. 짧은 한 줄 helper.
+ * 반복 호출 시 `flattenPolygonPath` 결과를 캐시하라 (이 함수는 매번 평탄화한다).
+ */
+export declare function polygonPathLength(path: PolygonPathPoint[], options?: PathArcOptions): number;
+//# sourceMappingURL=polygon-path-arc.d.ts.map

package/dist-types/types/polygon-path-arc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon-path-arc.d.ts","sourceRoot":"","sources":["../../src/types/polygon-path-arc.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAA;AAE1B,wBAAwB;AACxB,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,0BAA0B;AAC1B,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAA;CACd;AAQD;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxD,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC1C,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;gBAEZ,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,EAAE,MAAM,EAAE,OAAO;IAa/D;;;OAGG;IACH,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU;CAkC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,gBAAgB,EAAE,EACxB,OAAO,GAAE,cAAmB,GAC3B,mBAAmB,CAiHrB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAE5F"}

package/dist-types/types/polygon-path.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Polygon-style path point.
+ *
+ * 폐루프(폴리곤) 모델링에서 per-vertex 코너 라운드, 호, 3D 높이까지 표현하기 위한 확장 좌표.
+ *
+ * - x, y: 평면 좌표 (2D 캔버스, 동시에 3D 의 x, z 평면)
+ * - z: 3D 에서의 높이 (component base 로부터의 Y 오프셋). 2D 코드는 무시.
+ * - radius: per-vertex 코너 라운드 반지름. 미지정 시 state.round 로 fallback.
+ * - bulge: 다음 세그먼트에 적용할 sagitta(호의 화살 높이).
+ *          부호로 볼록/오목 결정 — 양수=화면 위쪽, 음수=화면 아래쪽.
+ *          항상 작은 호로 그려진다 (큰 호 / sweep flip 없음).
+ *          |bulge| < BULGE_EPSILON 이면 직선으로 자동 취급.
+ *
+ * 모든 필드가 옵셔널이므로 기존 `{ x, y }[]` path 와 100% 호환.
+ */
+export interface PolygonPathPoint {
+    x: number;
+    y: number;
+    z?: number;
+    radius?: number;
+    bulge?: number;
+}
+export type PolygonPath = PolygonPathPoint[];
+/**
+ * 호로 취급하는 최소 sagitta. 부동소수점 노이즈로 의도한 직선이
+ * 미세 호로 잘못 해석되는 것을 막고, 핸들 드래그에서 line ↔ arc 자동 전환의 기준이 된다.
+ */
+export declare const BULGE_EPSILON = 0.5;
+/**
+ * 다음 세그먼트가 호로 그려지는지 여부 — |bulge| >= BULGE_EPSILON 일 때만 true.
+ */
+export declare function hasArc(point: PolygonPathPoint): boolean;
+export interface ArcParams {
+    cx: number;
+    cy: number;
+    radius: number;
+    startAngle: number;
+    endAngle: number;
+    clockwise: boolean;
+}
+/**
+ * 두 점 + sagitta(=bulge) 으로부터 호 파라미터 계산.
+ *   - chord  = |p2 - p1|
+ *   - radius r = (chord² + 4·sagitta²) / (8·|sagitta|)
+ *   - 중심은 chord 중점에서 chord 에 수직 방향으로 (r - |sagitta|) 만큼 이동
+ *   - bulge 부호로 수직 방향(볼록/오목) 이 결정된다 — 항상 작은 호.
+ *
+ * 컨벤션 (캔버스 좌표계, y down): perp = (uy, -ux), 핸들 = mid + perp * bulge.
+ * 호는 핸들과 같은 쪽으로 부풀고, 중심은 그 반대편.
+ *
+ * cw:
+ *   - bulge>0 → 중심이 perp 반대편 → angle 증가가 작은 호 (cw=false)
+ *   - bulge<0 → 중심이 perp 같은 편 → angle 감소가 작은 호 (cw=true)
+ */
+export declare function computeArcParams(p1: {
+    x: number;
+    y: number;
+}, p2: {
+    x: number;
+    y: number;
+}, bulge: number): ArcParams | null;
+/**
+ * Bulge 핸들 ◇ 의 화면 위치.
+ *
+ * mid + perp * (bulge or displayMin). bulge=0 일 때도 핸들이 보이도록 displayMin 으로 보정.
+ */
+export declare function bulgeHandlePosition(p1: {
+    x: number;
+    y: number;
+}, p2: {
+    x: number;
+    y: number;
+}, bulge?: number, displayMin?: number): {
+    x: number;
+    y: number;
+    perpX: number;
+    perpY: number;
+} | null;
+/**
+ * 드래그 좌표 → 새 bulge 값. perp 축 투영. |proj| < BULGE_EPSILON 이면 0 (line).
+ * chord 길이를 초과하지 않도록 클램프.
+ */
+export declare function bulgeFromDrag(p1: {
+    x: number;
+    y: number;
+}, p2: {
+    x: number;
+    y: number;
+}, dragPoint: {
+    x: number;
+    y: number;
+}): number;
+/**
+ * 효과적 코너 반지름 — per-vertex `radius` 가 있으면 사용, 없으면 fallback.
+ * 음수/NaN 방어.
+ */
+export declare function effectiveCornerRadius(point: PolygonPathPoint, fallbackRound: number): number;
+/**
+ * 코너 라운드 핸들의 화면 위치 계산.
+ *
+ * cursor 에서 두 변(prev→cursor, cursor→next) 의 angle bisector(내각 이등분) 방향으로
+ * `dist` 만큼 이동한 점. `dist` 는 현재 라운드 값이거나, 너무 작으면 displayMin 으로 보정
+ * (radius=0 일 때도 핸들이 보이도록).
+ *
+ * 직선(180도) 코너는 bisector 가 0 → null 반환.
+ */
+export declare function cornerHandlePosition(prev: {
+    x: number;
+    y: number;
+}, cursor: {
+    x: number;
+    y: number;
+}, next: {
+    x: number;
+    y: number;
+}, effectiveR: number, displayMin?: number): {
+    x: number;
+    y: number;
+    bisectorX: number;
+    bisectorY: number;
+} | null;
+/**
+ * 드래그 좌표 → 새 corner radius 값 계산.
+ *
+ * 드래그 점을 angle bisector 축에 투영한 거리. 음수(반대편 방향)면 0 으로 클램프.
+ * 인접 변 길이의 절반을 초과하지 않도록 상한 적용.
+ */
+export declare function cornerRadiusFromDrag(prev: {
+    x: number;
+    y: number;
+}, cursor: {
+    x: number;
+    y: number;
+}, next: {
+    x: number;
+    y: number;
+}, dragPoint: {
+    x: number;
+    y: number;
+}): number;
+/**
+ * Path 의 모든 점이 동일한 z 를 갖는지 확인.
+ *
+ * 균일 z 인 경우: 전체 폴리곤이 평면 (수평) 폐루프 — `state.zPos` 만으로 표현 가능.
+ * 비균일 z 인 경우: 램프/뱅킹/엘리베이션 — 별도 BufferGeometry 빌더 필요 (Phase L.2b).
+ *
+ * 반환:
+ *   - 모든 점에 z 가 없으면 0 (기본 평면)
+ *   - 모든 점이 동일 z 를 갖으면 그 z 값
+ *   - 점마다 z 가 다르면 null (variable z, 향후 처리)
+ */
+export declare function uniformZ(path: PolygonPathPoint[]): number | null;
+//# sourceMappingURL=polygon-path.d.ts.map

package/dist-types/types/polygon-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon-path.d.ts","sourceRoot":"","sources":["../../src/types/polygon-path.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatiolab/things-scene",
-  "version": "10.0.0-beta.93",
+  "version": "10.0.0-beta.95",
   "description": "A high-performance 2D/3D scene graph library for building interactive visual editors, combining HTML5 Canvas and Three.js to enable facility visualization, data-driven animations, and real-time monitoring dashboards",
   "main": "things-scene-min.js",
   "module": "things-scene.mjs",