@deepnoid/canvas 0.1.85 → 0.1.86

package/skills/deepnoid-canvas/references/types.md

@@ -0,0 +1,231 @@
+# 타입 API 레퍼런스
+
+모든 public 타입은 `@deepnoid/canvas`에서 직접 import합니다.
+
+## Import
+
+```tsx
+import { DrawMode } from '@deepnoid/canvas';
+import type {
+  Annotation,
+  Rectangle,
+  Label,
+  ApplyAnnotationStyle,
+  AnnotationCanvasHandle,
+} from '@deepnoid/canvas';
+```
+
+---
+
+## DrawMode (Enum)
+
+어노테이션 그리기 모드를 지정하는 enum.
+
+```typescript
+enum DrawMode {
+  RECTANGLE = 'RECTANGLE',
+  POLYGON = 'POLYGON',
+}
+```
+
+### 사용 예시
+
+```tsx
+import { DrawMode } from '@deepnoid/canvas';
+
+// drawing.mode에 사용
+<AnnotationEditor drawing={{ mode: DrawMode.RECTANGLE, ... }} />
+
+// 어노테이션 타입 판별
+if (annotation.type === DrawMode.RECTANGLE) {
+  // RectangleAnnotation으로 좁혀짐
+  console.log(annotation.x, annotation.y, annotation.width, annotation.height);
+} else if (annotation.type === DrawMode.POLYGON) {
+  // PolygonAnnotation으로 좁혀짐
+  console.log(annotation.points);
+}
+```
+
+---
+
+## Annotation (Union Type)
+
+```typescript
+type Annotation = RectangleAnnotation | PolygonAnnotation;
+```
+
+`type` 필드로 discriminated union 판별.
+
+### RectangleAnnotation
+
+```typescript
+type RectangleAnnotation = {
+  type: DrawMode.RECTANGLE;
+  x: number;            // 좌상단 X (원본 이미지 px)
+  y: number;            // 좌상단 Y (원본 이미지 px)
+  width: number;        // 너비 (원본 이미지 px)
+  height: number;       // 높이 (원본 이미지 px)
+  label?: Label;        // 라벨 정보
+  color?: 'success' | 'warning' | 'danger';  // 상태 색상
+  selected?: boolean;   // 선택 상태 (엔진 내부 관리)
+  showOnlySelected?: boolean;
+};
+```
+
+### PolygonAnnotation
+
+```typescript
+type PolygonAnnotation = {
+  type: DrawMode.POLYGON;
+  points: { x: number; y: number }[];  // 꼭짓점 배열 (원본 이미지 px)
+  label?: Label;
+  color?: 'success' | 'warning' | 'danger';
+  selected?: boolean;
+  showOnlySelected?: boolean;
+};
+```
+
+### 데이터 예시
+
+```typescript
+// RectangleAnnotation
+const rect: Annotation = {
+  type: DrawMode.RECTANGLE,
+  x: 100,
+  y: 50,
+  width: 200,
+  height: 150,
+  label: { id: 1, name: 'defect', type: 'bbox' },
+  color: 'danger',
+};
+
+// PolygonAnnotation
+const polygon: Annotation = {
+  type: DrawMode.POLYGON,
+  points: [
+    { x: 100, y: 100 },
+    { x: 250, y: 80 },
+    { x: 300, y: 200 },
+    { x: 150, y: 250 },
+  ],
+  label: { id: 2, name: 'crack', type: 'polygon' },
+  color: 'warning',
+};
+```
+
+---
+
+## Rectangle (Type)
+
+사각형의 기하 정보만 담는 순수 타입. 어노테이션이 아닌 좌표 계산 등에 활용.
+
+```typescript
+type Rectangle = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+```
+
+---
+
+## Label (Type)
+
+어노테이션에 부여하는 라벨 정보.
+
+```typescript
+type Label = {
+  id: number;     // 라벨 고유 ID
+  name: string;   // 표시 이름 (applyStyle의 drawText에서 사용)
+  type: string;   // 라벨 분류 (자유 문자열, 예: 'bbox', 'polygon', 'seed')
+};
+```
+
+### 사용 예시
+
+```tsx
+const labels: Label[] = [
+  { id: 1, name: '결함', type: 'defect' },
+  { id: 2, name: '균열', type: 'crack' },
+  { id: 3, name: '정상', type: 'normal' },
+];
+
+// drawing.label에 설정하면 새로 그리는 어노테이션에 자동 부여
+<AnnotationEditor
+  drawing={{
+    mode: DrawMode.RECTANGLE,
+    label: labels[0],
+    lineSize: 2,
+    applyStyle,
+  }}
+  ...
+/>
+```
+
+---
+
+## ApplyAnnotationStyle (Type)
+
+어노테이션 렌더링 스타일을 완전 제어하는 콜백 함수 타입.
+
+```typescript
+type ApplyAnnotationStyle = (params: ApplyAnnotationStyleParams) => void;
+
+type ApplyAnnotationStyleParams = {
+  variant: 'drawRect' | 'drawText';       // 현재 렌더링 단계
+  context: CanvasRenderingContext2D;        // Canvas 2D 컨텍스트
+  annotation: Annotation;                  // 렌더링 대상 어노테이션
+  drawLineSize: number;                    // 설정된 선 두께 (현재 2px 고정)
+  zoom: number;                            // 현재 줌 배율
+};
+```
+
+### variant 설명
+
+| variant | 호출 시점 | 설정해야 할 Canvas 속성 |
+|---------|----------|------------------------|
+| `'drawRect'` | 도형 렌더링 | `strokeStyle`, `fillStyle`, `lineWidth`, `setLineDash` + 실제 도형 그리기 (`strokeRect`, `beginPath`/`stroke` 등) |
+| `'drawText'` | 라벨 텍스트 렌더링 | `fillStyle`, `font`, `textBaseline` + 실제 텍스트 그리기 (`fillText`) |
+
+상세 예제는 [apply-style.md](apply-style.md) 참조.
+
+---
+
+## AnnotationCanvasHandle (Interface)
+
+`ref`를 통해 캔버스를 프로그래밍 방식으로 제어.
+
+```typescript
+interface AnnotationCanvasHandle {
+  resetImageSize(): void;   // 캔버스 크기 및 줌을 초기 상태로 리셋
+}
+```
+
+### 사용 예시
+
+```tsx
+import { useRef } from 'react';
+import type { AnnotationCanvasHandle } from '@deepnoid/canvas';
+
+const ref = useRef<AnnotationCanvasHandle>(null);
+
+// 줌 리셋 버튼
+<button onClick={() => ref.current?.resetImageSize()}>초기화</button>
+<AnnotationEditor ref={ref} ... />
+```
+
+---
+
+## 전체 Export 요약
+
+| Export | Kind | import 방식 |
+|--------|------|------------|
+| `AnnotationEditor` | Component | `import { AnnotationEditor } from '@deepnoid/canvas'` |
+| `AnnotationViewer` | Component | `import { AnnotationViewer } from '@deepnoid/canvas'` |
+| `DrawMode` | Enum (value) | `import { DrawMode } from '@deepnoid/canvas'` |
+| `Annotation` | Type | `import type { Annotation } from '@deepnoid/canvas'` |
+| `Rectangle` | Type | `import type { Rectangle } from '@deepnoid/canvas'` |
+| `Label` | Type | `import type { Label } from '@deepnoid/canvas'` |
+| `ApplyAnnotationStyle` | Type | `import type { ApplyAnnotationStyle } from '@deepnoid/canvas'` |
+| `AnnotationCanvasHandle` | Interface | `import type { AnnotationCanvasHandle } from '@deepnoid/canvas'` |

package/skills/deepnoid-canvas/rules/annotations.md

@@ -0,0 +1,152 @@
+# 어노테이션 데이터 규칙
+
+## 규칙 1: 모든 어노테이션에 type 필드가 필수다
+
+`Annotation` 타입은 discriminated union이므로, `type` 필드가 없으면 타입 추론이 동작하지 않습니다.
+
+```tsx
+// ✅ 올바른 사용 — type 필드 포함
+const rect: Annotation = {
+  type: DrawMode.RECTANGLE,
+  x: 100,
+  y: 50,
+  width: 200,
+  height: 150,
+};
+
+const polygon: Annotation = {
+  type: DrawMode.POLYGON,
+  points: [
+    { x: 100, y: 100 },
+    { x: 200, y: 100 },
+    { x: 150, y: 200 },
+  ],
+};
+
+// ❌ 잘못된 사용 — type 누락
+const rect = { x: 100, y: 50, width: 200, height: 150 };
+```
+
+## 규칙 2: DrawMode enum을 사용해야 한다
+
+문자열 리터럴 대신 반드시 `DrawMode` enum을 사용합니다.
+
+```tsx
+import { DrawMode } from '@deepnoid/canvas';
+
+// ✅ 올바른 사용
+{ type: DrawMode.RECTANGLE, ... }
+{ type: DrawMode.POLYGON, ... }
+
+// ❌ 잘못된 사용 — 문자열 직접 사용 (타입 에러)
+{ type: 'RECTANGLE', ... }
+{ type: 'rectangle', ... }
+```
+
+## 규칙 3: 좌표는 원본 이미지 기준 픽셀 좌표다
+
+캔버스에 표시된 좌표가 아니라, 원본 이미지의 픽셀 좌표를 사용합니다. 줌/팬 변환은 엔진이 자동 처리합니다.
+
+```tsx
+// ✅ 올바른 사용 — 원본 이미지 좌표
+// 원본 이미지가 1920x1080일 때:
+{ type: DrawMode.RECTANGLE, x: 500, y: 300, width: 200, height: 150 }
+
+// ❌ 잘못된 사용 — 화면 표시 좌표를 그대로 사용
+// 캔버스가 50%로 축소되어 있어도 원본 좌표를 사용해야 함
+```
+
+## 규칙 4: RectangleAnnotation의 width/height는 양수여야 한다
+
+사용자가 역방향으로 드래그하면 엔진이 자동 정규화하지만, 외부에서 직접 생성 시 양수 값이어야 합니다.
+
+```tsx
+// ✅ 올바른 사용
+{ type: DrawMode.RECTANGLE, x: 100, y: 100, width: 200, height: 150 }
+
+// ❌ 잘못된 사용 — 음수 크기
+{ type: DrawMode.RECTANGLE, x: 300, y: 250, width: -200, height: -150 }
+```
+
+## 규칙 5: PolygonAnnotation의 points는 최소 3개여야 한다
+
+유효한 폴리곤을 형성하려면 최소 3개의 점이 필요합니다.
+
+```tsx
+// ✅ 올바른 사용 — 3개 이상의 점
+{
+  type: DrawMode.POLYGON,
+  points: [
+    { x: 100, y: 100 },
+    { x: 200, y: 100 },
+    { x: 150, y: 200 },
+  ],
+}
+
+// ❌ 잘못된 사용 — 2개 이하의 점
+{
+  type: DrawMode.POLYGON,
+  points: [
+    { x: 100, y: 100 },
+    { x: 200, y: 100 },
+  ],
+}
+```
+
+## 규칙 6: annotations 상태 관리는 React state로 한다
+
+`setAnnotations` 콜백으로 어노테이션이 변경될 때 외부 상태와 동기화됩니다.
+
+```tsx
+// ✅ 올바른 사용 — React state 관리
+const [annotations, setAnnotations] = useState<Annotation[]>([]);
+
+<AnnotationEditor
+  annotations={annotations}
+  setAnnotations={setAnnotations}
+  ...
+/>
+
+// ❌ 잘못된 사용 — ref나 외부 변수로 관리
+const annotationsRef = useRef<Annotation[]>([]);
+<AnnotationEditor
+  annotations={annotationsRef.current}
+  setAnnotations={(a) => { annotationsRef.current = a; }}
+  ...
+/>
+// → 리렌더링이 발생하지 않아 UI가 동기화되지 않음
+```
+
+## 규칙 7: selected 필드를 외부에서 직접 조작하지 않는다
+
+어노테이션 선택 상태는 엔진이 내부적으로 관리합니다. 외부에서 `selected: true`를 설정해도 동작하지만, 엔진과 충돌할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — 선택은 캔버스 내 클릭으로
+// 사용자가 캔버스에서 어노테이션을 클릭하면 자동으로 selected 처리됨
+
+// ⚠️ 주의 — 외부에서 selected 설정
+setAnnotations(prev => prev.map(a =>
+  a === target ? { ...a, selected: true } : { ...a, selected: false }
+));
+// 가능하지만, setAnnotations가 다시 엔진에 전달되면서 불필요한 리렌더링 발생 가능
+```
+
+## 규칙 8: label은 선택적이지만, 텍스트 표시에 필요하다
+
+`label` 필드가 없으면 `drawText` variant에서 표시할 텍스트가 없습니다.
+
+```tsx
+// ✅ 텍스트 라벨이 필요한 경우
+{
+  type: DrawMode.RECTANGLE,
+  x: 100, y: 100, width: 200, height: 150,
+  label: { id: 1, name: 'defect', type: 'bbox' },
+}
+
+// ✅ 텍스트 라벨이 불필요한 경우 — label 생략 가능
+{
+  type: DrawMode.RECTANGLE,
+  x: 100, y: 100, width: 200, height: 150,
+}
+```

package/skills/deepnoid-canvas/rules/events.md

@@ -0,0 +1,124 @@
+# 이벤트 및 단축키 규칙
+
+## 규칙 1: annotationSelected 이벤트로 DrawMode 동기화
+
+캔버스에서 어노테이션을 클릭하면 `window`에 `annotationSelected` CustomEvent가 발생합니다.
+이를 통해 외부 UI의 그리기 모드를 자동 전환할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — annotationSelected 이벤트 리스닝
+useEffect(() => {
+  const handler = (e: CustomEvent) => {
+    if (e.detail?.type) {
+      setDrawMode(e.detail.type); // DrawMode.RECTANGLE 또는 DrawMode.POLYGON
+    }
+  };
+  window.addEventListener('annotationSelected', handler);
+  return () => window.removeEventListener('annotationSelected', handler);
+}, []);
+
+// ❌ 잘못된 사용 — 이벤트 클린업 누락
+useEffect(() => {
+  window.addEventListener('annotationSelected', handler);
+  // return 없음 → 메모리 누수
+}, []);
+```
+
+## 규칙 2: enableHotkeys를 명시적으로 설정한다
+
+단축키는 기본적으로 비활성화되어 있습니다 (`enableHotkeys` 기본값: `true` in Editor, 단 명시적 설정 권장).
+
+```tsx
+// ✅ 올바른 사용 — 명시적 설정
+<AnnotationEditor enableHotkeys {...otherProps} />
+
+// ✅ 단축키 충돌이 있는 경우 비활성화
+<AnnotationEditor enableHotkeys={false} {...otherProps} />
+```
+
+### 지원 단축키
+
+| 키 | 기능 | 조건 |
+|---|---|---|
+| `Delete` | 선택된 어노테이션 삭제 | 어노테이션 선택 상태일 때 |
+| `Ctrl+Z` (Mac: `Cmd+Z`) | Undo | 히스토리가 있을 때 |
+| `Ctrl+Shift+Z` (Mac: `Cmd+Shift+Z`) | Redo | undo 후 히스토리가 있을 때 |
+| `X` | 선택 어노테이션만 보기 토글 | 언제든 |
+| `Escape` | 진행 중인 그리기 취소 | 폴리곤 점 찍기 중 등 |
+
+## 규칙 3: 이미지 로드 이벤트를 활용한다
+
+`events` prop으로 이미지 로드 성공/실패를 감지할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — 로드 상태 관리
+const [imageLoaded, setImageLoaded] = useState(false);
+
+<AnnotationEditor
+  image={imageUrl}
+  events={{
+    onImageLoadSuccess: () => setImageLoaded(true),
+    onImageLoadError: (error) => {
+      console.error('이미지 로드 실패:', error);
+      setImageLoaded(false);
+    },
+  }}
+  ...
+/>
+
+// ❌ 잘못된 사용 — events를 undefined로 전달
+<AnnotationEditor
+  events={undefined}  // 타입 에러: events는 필수 prop
+  ...
+/>
+
+// ✅ 이벤트가 필요 없으면 빈 객체 전달
+<AnnotationEditor events={{}} ... />
+```
+
+## 규칙 4: 단축키와 외부 키 이벤트의 충돌에 주의한다
+
+`enableHotkeys`가 켜져 있으면 `window` 레벨에서 키 이벤트를 감지합니다.
+외부에서 같은 키(Delete, X, Ctrl+Z)를 사용하는 경우 충돌이 발생할 수 있습니다.
+
+```tsx
+// ✅ 충돌 방지 — 캔버스 영역에서만 단축키 활성화
+// enableHotkeys를 조건부로 제어
+const [canvasFocused, setCanvasFocused] = useState(false);
+
+<div
+  onFocus={() => setCanvasFocused(true)}
+  onBlur={() => setCanvasFocused(false)}
+>
+  <AnnotationEditor
+    enableHotkeys={canvasFocused}
+    ...
+  />
+</div>
+
+// ❌ 잘못된 사용 — 폼 입력이 있는 페이지에서 항상 enableHotkeys
+// → Delete 키로 텍스트 삭제 시 어노테이션도 삭제됨
+```
+
+## 규칙 5: setAnnotations 콜백은 비동기적으로 호출된다
+
+엔진 내부에서 어노테이션이 변경되면 `setAnnotations` 콜백이 호출됩니다.
+이 콜백 내에서 무거운 로직을 실행하면 성능에 영향을 줄 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — 가벼운 상태 업데이트만
+<AnnotationEditor
+  setAnnotations={setAnnotations}
+  ...
+/>
+
+// ⚠️ 주의 — 콜백 내 무거운 로직
+<AnnotationEditor
+  setAnnotations={(annotations) => {
+    setAnnotations(annotations);
+    // 매 마우스 이동마다 호출될 수 있어 성능 이슈
+    saveToServer(annotations); // ← debounce 권장
+  }}
+  ...
+/>
+```

package/skills/deepnoid-canvas/rules/layout.md

@@ -0,0 +1,171 @@
+# 레이아웃, 줌/팬 규칙
+
+## 규칙 1: 컨테이너에 반드시 고정 크기를 설정한다
+
+`AnnotationEditor`/`AnnotationViewer`는 부모 컨테이너의 100% 크기를 차지합니다.
+부모에 크기가 없으면 캔버스가 0px로 렌더링됩니다.
+
+```tsx
+// ✅ 올바른 사용 — 고정 크기
+<div style={{ width: 800, height: 600 }}>
+  <AnnotationEditor ... />
+</div>
+
+// ✅ flex 레이아웃
+<div style={{ display: 'flex', height: '100vh' }}>
+  <aside style={{ width: 200 }}>사이드바</aside>
+  <div style={{ flex: 1 }}>
+    <AnnotationEditor ... />
+  </div>
+</div>
+
+// ❌ 잘못된 사용 — 크기 없는 컨테이너
+<div>
+  <AnnotationEditor ... />
+</div>
+// → 캔버스 크기가 0이 되어 아무것도 보이지 않음
+```
+
+## 규칙 2: panZoomEnabled로 줌/팬을 제어한다
+
+줌(마우스 휠)과 팬(우클릭 드래그)은 `options.panZoomEnabled`로 제어합니다.
+
+```tsx
+// ✅ 줌/팬 활성화
+<AnnotationEditor
+  options={{ panZoomEnabled: true }}
+  ...
+/>
+
+// ✅ 줌/팬 비활성화 (고정 뷰)
+<AnnotationEditor
+  options={{ panZoomEnabled: false }}
+  ...
+/>
+
+// ✅ 기본값: panZoomEnabled를 생략하면 옵션 객체 자체가 없어야 함
+<AnnotationEditor options={undefined} ... />
+```
+
+## 규칙 3: zoom 옵션으로 줌 범위를 제한한다
+
+줌 배율의 최소/최대/단계를 설정할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — 줌 범위 설정
+<AnnotationEditor
+  options={{
+    panZoomEnabled: true,
+    zoom: {
+      min: 0.5,    // 최소 50% (기본: 0.1)
+      max: 4,      // 최대 400% (기본: Infinity)
+      step: 0.9,   // 한 스텝당 배율 변화 (기본: 0.9)
+    },
+  }}
+  ...
+/>
+
+// ✅ 일부만 설정 가능
+<AnnotationEditor
+  options={{
+    panZoomEnabled: true,
+    zoom: { max: 10 }, // min, step은 기본값 사용
+  }}
+  ...
+/>
+```
+
+## 규칙 4: ZoomButton으로 줌 비율 표시 및 리셋
+
+커스텀 줌 버튼 컴포넌트를 주입하여 현재 줌 비율 표시 및 클릭 시 줌 리셋이 가능합니다.
+
+```tsx
+// ✅ 올바른 사용 — 커스텀 ZoomButton
+const ZoomButton = ({ onClick, children }: { onClick: () => void; children: ReactNode }) => (
+  <button
+    onClick={onClick}
+    style={{ position: 'absolute', top: 10, left: 10, zIndex: 10 }}
+  >
+    {children}  {/* "125%" 같은 줌 비율 문자열 */}
+  </button>
+);
+
+<AnnotationEditor
+  options={{
+    panZoomEnabled: true,
+    ZoomButton,
+  }}
+  ...
+/>
+
+// ❌ 잘못된 사용 — ZoomButton에 잘못된 시그니처
+const ZoomButton = ({ zoom }) => <span>{zoom}</span>; // onClick과 children이 필요
+```
+
+## 규칙 5: resetOnImageChange로 이미지 전환 시 줌 상태를 제어한다
+
+이미지가 바뀔 때 줌/팬 상태를 초기화할지 유지할지 선택할 수 있습니다.
+
+```tsx
+// ✅ 이미지 전환 시 줌 리셋
+<AnnotationEditor
+  options={{ resetOnImageChange: true }}
+  ...
+/>
+
+// ✅ 이미지 전환 시 줌 유지 (기본값: false)
+<AnnotationEditor
+  options={{ resetOnImageChange: false }}
+  ...
+/>
+```
+
+## 규칙 6: ref로 캔버스 크기를 수동 리셋할 수 있다
+
+`AnnotationCanvasHandle` ref를 통해 프로그래밍 방식으로 캔버스를 리셋합니다.
+
+```tsx
+import { useRef } from 'react';
+import type { AnnotationCanvasHandle } from '@deepnoid/canvas';
+
+// ✅ 올바른 사용
+const canvasRef = useRef<AnnotationCanvasHandle>(null);
+
+<button onClick={() => canvasRef.current?.resetImageSize()}>
+  크기 초기화
+</button>
+<AnnotationEditor ref={canvasRef} ... />
+
+// ❌ 잘못된 사용 — 잘못된 타입
+const canvasRef = useRef<HTMLCanvasElement>(null); // AnnotationCanvasHandle이어야 함
+```
+
+## 규칙 7: keepCrossOnImageChange로 가이드 십자선 유지
+
+이미지가 변경될 때 마우스 위치의 가이드 십자선(crosshair)을 유지할 수 있습니다.
+`AnnotationEditor`에서만 사용 가능합니다.
+
+```tsx
+// ✅ 이미지 전환 시 십자선 유지 (연속 작업 시 편리)
+<AnnotationEditor keepCrossOnImageChange ... />
+
+// ✅ 기본 동작 — 이미지 전환 시 십자선 제거
+<AnnotationEditor keepCrossOnImageChange={false} ... />
+```
+
+## 규칙 8: 리사이즈 대응은 자동으로 처리된다
+
+컨테이너 크기가 변하면 내부 `ResizeObserver`가 자동으로 캔버스를 재설정합니다 (150ms debounce).
+별도의 리사이즈 처리가 필요 없습니다.
+
+```tsx
+// ✅ 리사이즈 대응 — 별도 처리 불필요
+<div style={{ width: '100%', height: '100%' }}>
+  <AnnotationEditor ... />
+</div>
+
+// ❌ 불필요한 사용 — 수동 리사이즈 핸들러
+window.addEventListener('resize', () => {
+  canvasRef.current?.resetImageSize(); // 불필요, 자동 처리됨
+});
+```