ez-planet-canvas

MLOps 플랫폼을 위한 재사용 가능한 캔버스 라이브러리 모노레포.

Package	Description	Demo
@servantcdh/ez-planet-labeling	Fabric.js 기반 이미지 라벨링 워크스페이스
@servantcdh/ez-planet-cosmos	ReactFlow + Three.js 코스모스 시각화

Quick Start

# 전체 빌드
npm install
npm run build

# 개별 빌드
npm run build:labeling
npm run build:cosmos

---

labeling-canvas

Fabric.js v5 기반의 이미지 라벨링 라이브러리. 호스트 앱이 데이터와 뮤테이션을 Provider로 주입하는 구조.

설치

npm install @servantcdh/ez-planet-labeling

Peer Dependencies

Package	Version
react	^18.0.0
react-dom	^18.0.0
fabric	^5.0.0

External Dependencies (호스트에서 설치 필요)

Package	Version	용도
zustand	^5.0.0	상태 관리
zundo	^2.1.0	undo/redo
@tanstack/react-table	^8.0.0	레코드 테이블
@tanstack/react-virtual	^3.0.0	가상 스크롤
echarts	^5.0.0	차트 시각화
echarts-for-react	^3.0.0	echarts React 래퍼
react-router-dom	^6.0.0	라우팅
@tanstack/react-router	^1.0.0	라우팅

사용법

호스트 앱이 LabelingProviders로 데이터/뮤테이션을 주입하고, LabelingWorkspace가 UI를 렌더링합니다.

import {
  LabelingWorkspace,
  LabelingProviders,
  staticData,
  IDLE_MUTATION,
  type LabelingDataContextValue,
  type LabelingMutationContextValue,
  type LabelingDatasetContextValue,
} from '@servantcdh/ez-planet-labeling'

// 호스트에서 API 데이터를 AsyncData로 래핑
const dataCtx: LabelingDataContextValue = {
  policiesBatch: staticData(policies),
  labelContext: staticData(labelContext),
  labelContextStatus: staticData(status),
  labelSearch: staticData({ list: [], totalCount: 0, filter: {} }),
  // ...
}

const datasetCtx: LabelingDatasetContextValue = {
  datasetDetail: staticData(dataset),
  datasetContents: staticData({ code: 200, message: 'OK', data: { list: records, totalCount: records.length } }),
  datasetContentDetail: staticData(contentDetail),
}

const mutationCtx: LabelingMutationContextValue = {
  batchUpdateLabels: (vars) => api.updateLabels(vars),
  batchUpdateLabelsState: IDLE_MUTATION,
  // ... 10개 mutation + state 쌍
  onMutationSuccess: (hint) => { /* 캐시 무효화 */ },
}

<LabelingProviders data={dataCtx} mutations={mutationCtx} dataset={datasetCtx}>
  <LabelingWorkspace />
</LabelingProviders>

Extension System

호스트별 기능(SAM, AutoLabeling 등)을 플러그인으로 주입:

<LabelingWorkspace extensions={[samExtension, autoLabelingExtension]} />

주요 기능

• 도구: Selection, Bounding Box, Polygon, Brush, Eraser, Magic Brush, Superpixel
• Extension System: LabelingExtension으로 커스텀 기능 등록
• Validation: 검증 결과 생성/수정/삭제 지원
• CSS Modules: lc- prefix 스코핑, CSS 변수 기반 theming, JS에 자동 주입

---

cosmos-canvas

ReactFlow + Three.js 기반의 코스모스(우주) 스타일 플랫폼 시각화 라이브러리.

설치

npm install @servantcdh/ez-planet-cosmos

Peer Dependencies

Package	Version
react	^18.0.0
react-dom	^18.0.0
@xyflow/react	^12.0.0
@react-three/fiber	^8.0.0
@react-three/drei	^9.0.0
three	>=0.160.0
framer-motion	^11.0.0

Bundled Dependencies

Package	용도
zustand	내부 상태 관리

사용법

import { CosmosCanvas } from '@servantcdh/ez-planet-cosmos'
import '@servantcdh/ez-planet-cosmos/dist/style.css'
import '@xyflow/react/dist/style.css'

<CosmosCanvas
  planets={planets}
  orbits={orbits}
  topBar={<MyTopBar />}
  starField={{ starCount: 2000, nebulaCount: 500 }}
  onPlanetClick={(planet) => console.log('Inspect:', planet.id)}
  onPlanetEnter={(planet) => console.log('Enter:', planet.id)}
  onSatelliteClick={({ satellite }) => router.push(satellite?.route ?? '/')}
  renderPlanetInterior={(planet, onExit) => <MyInterior planet={planet} onBack={onExit} />}
/>

주요 기능

• StarField: Three.js 별 + 성운 파티클 배경
• PlanetNode: 상태별 글로우/펄스 효과 (idle, running, error, success)
• OrbitEdge: 베지어 궤도 + 글로우 + 대시 애니메이션
• SidePanel: 행성 클릭 시 위성 목록 슬라이드 패널
• PlanetInterior: 행성 내부 뷰 또는 renderPlanetInterior 커스텀 렌더
• ZoomTransition: 행성 진입 시 줌인 애니메이션
• CosmosTutorial: 온보딩 시스템 (welcome → stepping → complete)
• TopBar Slot: topBar prop으로 호스트 앱 네비게이션 바 주입

---

프로젝트 구조

ez-planet-canvas/
├── packages/
│   ├── labeling-canvas/          # @servantcdh/ez-planet-labeling
│   │   ├── src/
│   │   │   ├── components/       # React 컴포넌트 (Workspace, Navigation, InfoPanel 등)
│   │   │   ├── features/         # 도메인 모듈 (dataset, policy, experiment 등)
│   │   │   ├── hooks/            # 커스텀 React hooks
│   │   │   ├── providers/        # Context Providers (Data, Mutation, Dataset)
│   │   │   ├── store/            # Zustand 스토어
│   │   │   ├── styles/           # CSS (Tailwind + CSS Modules, JS에 주입)
│   │   │   ├── types/            # 도메인 타입 정의
│   │   │   └── utils/            # Fabric.js 도구, SLIC, 유틸리티
│   │   └── vite.config.ts
│   └── cosmos-canvas/            # @servantcdh/ez-planet-cosmos
│       ├── src/
│       │   ├── components/       # CosmosCanvas, PlanetNode, StarField 등
│       │   ├── styles/           # CSS Modules
│       │   └── types/            # Public 타입
│       └── vite.config.ts
├── examples/
│   ├── labeling-demo/            # 라벨링 데모 앱
│   └── cosmos-demo/              # 코스모스 데모 앱
└── package.json                  # npm workspaces root

개발

# 의존성 설치
npm install

# 전체 빌드
npm run build

# 타입 체크
npm run typecheck

# 빌드 산출물 정리
npm run clean

요구사항

• Node.js >= 18.0.0
• TypeScript >= 5.5

License

MIT