@things-factory/board-import 10.0.0-beta.108

package/server/service/adapters/image-adapter.ts

@@ -0,0 +1,464 @@
+/**
+ * Image Format Adapter — 이미지 (PNG/JPG/WebP/GIF) → UniversalEntity 목록.
+ *
+ * VLM (Vision LLM) 의존. board-import 의 BoardImportAI.parseFromImage 가 핵심 작업을
+ * 담당하므로 이 어댑터는 그 위에 얇은 wrapper. AI client 가 등록되지 않았거나 vision 미지원
+ * provider 면 parse 시점에 명확한 에러로 실패한다 (detect 는 통과 — 외부 입력 식별만).
+ *
+ * zero-to-twin 메인 트랙 (조감도/사진 업로드 → 보드) 의 첫 어댑터.
+ */
+import { getAIClient } from '../ai/types'
+import type {
+  AdapterCapabilities,
+  AdapterInput,
+  BoundingBox,
+  FormatAdapter,
+  ParseOptions,
+  ParseResult,
+  UniversalEntity
+} from '../types/index'
+
+const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp']
+
+export interface ImageParseOptions extends ParseOptions {
+  /** 자연어 컨텍스트 — VLM 에 함께 전달. 예: "factory floor plan with AGV paths and stockers" */
+  context?: string
+  /** 후보 카테고리 — VLM 이 그 안에서 라벨링하도록 가이드 */
+  categories?: string[]
+  /**
+   * 이미지 dimension — VLM 프롬프트가 픽셀 좌표계를 명시하기 위해 사용. ImageAdapter 가
+   * 헤더에서 읽어 자동 주입한다. 호출자가 직접 부를 때도 명시 가능.
+   */
+  imageWidth?: number
+  imageHeight?: number
+  /**
+   * 사용자 자유서술 hint — 도면 설명, 강조 부분, 카테고리 가이드 등.
+   * VLM 의 view type 분류 + entity 추출 양쪽에 추가 컨텍스트로 합류.
+   */
+  userPrompt?: string
+  /**
+   * View type 명시 (강제). 미지정 시 ImageAdapter 가 1-pass classify 로 자동 결정.
+   * - 'top-down' : orthographic 도면 / 평면도 (픽셀 좌표 그대로)
+   * - 'perspective-3d' : 3D 렌더 / 조감도 / 등각투상 (floor plan 추론)
+   * - 'photo' : 실사진 (floor plan 추론)
+   */
+  viewType?: 'top-down' | 'perspective-3d' | 'photo'
+}
+
+export class ImageAdapter implements FormatAdapter {
+  readonly format = 'image'
+  readonly supportedExtensions = IMAGE_EXTENSIONS
+  readonly capabilities: AdapterCapabilities = {
+    has2D: true,
+    has3D: false,
+    hasSemanticLabels: true, // VLM 이 의미 라벨링
+    hasTextLabels: true, // VLM 이 텍스트 인식
+    hasAttributes: false // CAD 의 명시적 속성 없음
+  }
+
+  async detect(file: AdapterInput, filename?: string): Promise<boolean> {
+    if (filename && IMAGE_EXTENSIONS.some(ext => filename.toLowerCase().endsWith(ext))) return true
+    return detectImageMagic(file)
+  }
+
+  async parse(file: AdapterInput, options: ImageParseOptions = {}): Promise<ParseResult> {
+    const ai = getAIClient()
+    if (!ai) {
+      throw new Error('Image import requires a registered BoardImportAI (call setAIClient first).')
+    }
+    if (!ai.parseFromImage) {
+      throw new Error('Registered BoardImportAI does not implement parseFromImage (no VLM support).')
+    }
+
+    const buffer = toBuffer(file)
+    if (!buffer) {
+      throw new Error('Image input must be a Buffer / ArrayBuffer / Uint8Array.')
+    }
+
+    // 이미지 dimension 을 미리 알아내야 VLM 에 좌표계를 명시적으로 지시할 수 있다.
+    // 미지정 시 LLM 이 0..1 정규화 좌표로 응답해 stage3 가 1px 도형을 그리는 회귀가 발생.
+    const dims = readImageDimensions(buffer)
+
+    const raw = await ai.parseFromImage(buffer, {
+      context: options.context,
+      categories: options.categories as any,
+      imageWidth: dims?.width,
+      imageHeight: dims?.height,
+      userPrompt: options.userPrompt,
+      viewType: options.viewType
+    } as any)
+
+    // 응답 흡수 — 3 가지 형태 다 수용:
+    //   1) { variants: [...] } — 권장 (multi-variant)
+    //   2) { entities: [...], ... } — 구버전 single-variant
+    //   3) [ entity, ... ] — 가장 구버전 (entities only)
+    const viewType: 'top-down' | 'perspective-3d' | 'photo' = options.viewType
+      ? options.viewType
+      : raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? ((raw as any).viewType ?? 'top-down')
+        : 'top-down'
+    const confidence: number =
+      raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? Number((raw as any).confidence ?? 0.5)
+        : 0.5
+    const reasoning: string | undefined =
+      raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? (raw as any).reasoning
+        : undefined
+
+    const rawVariants: any[] = (() => {
+      if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        if (Array.isArray((raw as any).variants) && (raw as any).variants.length > 0) {
+          return (raw as any).variants
+        }
+        if (Array.isArray((raw as any).entities)) {
+          // 구버전 single-variant 응답 — 단일 시안으로 감쌈
+          return [
+            {
+              id: 'default',
+              label: 'default',
+              entities: (raw as any).entities,
+              subjectName: (raw as any).subjectName,
+              subjectDescription: (raw as any).subjectDescription,
+              importStrategy: (raw as any).importStrategy
+            }
+          ]
+        }
+      }
+      if (Array.isArray(raw)) {
+        return [{ id: 'default', label: 'default', entities: raw as any[] }]
+      }
+      return []
+    })()
+
+    // 시안별 entity 정규화 + 좌표 보정 + grid fallback — 시안 무관 동일 적용.
+    const usedGridLayout = viewType === 'perspective-3d' || viewType === 'photo'
+    const denormDim = viewType === 'top-down' ? dims : { width: 1000, height: 1000 }
+
+    const normalizedVariants = rawVariants.map((v: any) => {
+      let entities = (Array.isArray(v.entities) ? v.entities : []).map((e: any, i: number) =>
+        normalizeEntity(e, i)
+      )
+      entities = denormalizeIfFractional(entities, denormDim)
+      if (usedGridLayout) entities = layoutInGrid(entities)
+      const variantBbox = computeOuterBbox(entities)
+      return {
+        id: typeof v.id === 'string' ? v.id : 'variant',
+        label: typeof v.label === 'string' ? v.label : 'variant',
+        description: typeof v.description === 'string' ? v.description : undefined,
+        entities,
+        bbox: variantBbox,
+        subjectName: typeof v.subjectName === 'string' ? v.subjectName : undefined,
+        subjectDescription:
+          typeof v.subjectDescription === 'string' ? v.subjectDescription : undefined,
+        importStrategy: typeof v.importStrategy === 'string' ? v.importStrategy : undefined
+      }
+    })
+
+    // default = 첫 variant. 빈 배열일 때 fallback.
+    const defaultVariant = normalizedVariants[0]
+    const entities = defaultVariant?.entities ?? []
+    const subjectName = defaultVariant?.subjectName
+    const subjectDescription = defaultVariant?.subjectDescription
+    const importStrategy = defaultVariant?.importStrategy
+
+    return {
+      entities,
+      variants: normalizedVariants,
+      metadata: {
+        format: 'image',
+        source: 'vlm',
+        aiClientId: ai.id,
+        imageWidth: dims?.width,
+        imageHeight: dims?.height,
+        viewType,
+        ...(usedGridLayout ? { layoutMethod: 'grid' as const } : {}),
+        viewTypeConfidence: confidence,
+        ...(reasoning ? { viewTypeReasoning: reasoning } : {}),
+        ...(importStrategy ? { importStrategy } : {}),
+        ...(subjectName ? { subjectName } : {}),
+        ...(subjectDescription ? { subjectDescription } : {}),
+        ...(options.userPrompt ? { userPrompt: options.userPrompt } : {})
+      },
+      bbox: computeOuterBbox(entities),
+      units: 'unknown'
+    }
+  }
+}
+
+/**
+ * PNG / JPEG / WebP / GIF / BMP 헤더에서 width/height 추출. dep 없이 inline 처리.
+ * 실패 시 undefined — 호출자가 프롬프트에 dimension 을 포함하지 않게 한다.
+ */
+function readImageDimensions(buf: Buffer): { width: number; height: number } | undefined {
+  if (!buf || buf.length < 26) return undefined
+  // PNG: 8-byte signature + IHDR (length:4, type:4, width:4, height:4)
+  if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+    const width = buf.readUInt32BE(16)
+    const height = buf.readUInt32BE(20)
+    return Number.isFinite(width) && Number.isFinite(height) ? { width, height } : undefined
+  }
+  // JPEG: scan for SOFn (Start Of Frame) markers — 0xFFC0..0xFFCF except DHT/JPG/DAC
+  if (buf[0] === 0xff && buf[1] === 0xd8) {
+    let i = 2
+    while (i + 9 < buf.length) {
+      if (buf[i] !== 0xff) {
+        i++
+        continue
+      }
+      // skip filler 0xFF
+      while (i < buf.length && buf[i] === 0xff) i++
+      const marker = buf[i]
+      i++
+      if (marker === 0xd8 || marker === 0xd9) continue // SOI/EOI
+      if (i + 1 >= buf.length) return undefined
+      const segLen = buf.readUInt16BE(i)
+      // SOFn (baseline=C0, progressive=C2, etc) — exclude DHT(C4), JPG(C8), DAC(CC)
+      if (
+        marker >= 0xc0 &&
+        marker <= 0xcf &&
+        marker !== 0xc4 &&
+        marker !== 0xc8 &&
+        marker !== 0xcc
+      ) {
+        if (i + 7 >= buf.length) return undefined
+        const height = buf.readUInt16BE(i + 3)
+        const width = buf.readUInt16BE(i + 5)
+        return { width, height }
+      }
+      i += segLen
+    }
+    return undefined
+  }
+  // GIF: bytes 6-9 (LE width/height)
+  if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38) {
+    return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) }
+  }
+  // BMP: width@18 (LE), height@22 (LE)
+  if (buf[0] === 0x42 && buf[1] === 0x4d) {
+    return { width: buf.readUInt32LE(18), height: Math.abs(buf.readInt32LE(22)) }
+  }
+  // WebP (VP8/VP8L/VP8X) — 30+ bytes for dimension info
+  if (
+    buf[0] === 0x52 &&
+    buf[1] === 0x49 &&
+    buf[2] === 0x46 &&
+    buf[3] === 0x46 &&
+    buf[8] === 0x57 &&
+    buf[9] === 0x45 &&
+    buf[10] === 0x42 &&
+    buf[11] === 0x50 &&
+    buf.length >= 30
+  ) {
+    // VP8 lossy: chunk header at offset 12, dims at offset 26 (14-bit each)
+    if (buf[12] === 0x56 && buf[13] === 0x50 && buf[14] === 0x38 && buf[15] === 0x20) {
+      const width = buf.readUInt16LE(26) & 0x3fff
+      const height = buf.readUInt16LE(28) & 0x3fff
+      return { width, height }
+    }
+    // VP8L lossless: dims at offset 21 (14-bit packed)
+    if (buf[12] === 0x56 && buf[13] === 0x50 && buf[14] === 0x38 && buf[15] === 0x4c) {
+      const b0 = buf[21]
+      const b1 = buf[22]
+      const b2 = buf[23]
+      const b3 = buf[24]
+      const width = 1 + (((b1 & 0x3f) << 8) | b0)
+      const height = 1 + (((b3 & 0x0f) << 10) | (b2 << 2) | ((b1 & 0xc0) >> 6))
+      return { width, height }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Perspective view 의 entity 들을 격자로 균등 배치한다.
+ *
+ * VLM 은 perspective 좌표 → floor plan 좌표 변환이 불가능에 가깝다 (학습 데이터 부재 +
+ * 명시적 3D 세계 모델 없음). screen 좌표를 그대로 깔면 "perspective 가 평평해진" 결과.
+ * 차라리 좌표를 무시하고 격자로 깔고 사용자가 직접 옮기는 게 정직하다.
+ *
+ * 정책:
+ *   - 각 entity 의 size 는 보존 (VLM 이 추정한 상대 크기는 비교적 신뢰 가능)
+ *   - 격자 col 수 = ceil(sqrt(N)), row 수 = ceil(N/cols)
+ *   - tile 간격 = max(entity 평균 width/height) * 1.4
+ *   - 보드 우상단부터 row-major 로 배치
+ */
+function layoutInGrid(entities: UniversalEntity[]): UniversalEntity[] {
+  if (entities.length === 0) return entities
+  const cols = Math.max(1, Math.ceil(Math.sqrt(entities.length)))
+
+  // tile 크기 결정 — entity 평균 size 의 1.4 배. size 미지정이면 80 plan-unit.
+  const sizes = entities.filter(e => e.size).map(e => e.size!)
+  const avgW = sizes.length ? sizes.reduce((s, v) => s + v.width, 0) / sizes.length : 80
+  const avgH = sizes.length ? sizes.reduce((s, v) => s + v.height, 0) / sizes.length : 80
+  const tileW = Math.max(80, avgW) * 1.4
+  const tileH = Math.max(80, avgH) * 1.4
+
+  return entities.map((e, i) => {
+    const col = i % cols
+    const row = Math.floor(i / cols)
+    const x = col * tileW
+    const y = row * tileH
+    const w = e.size?.width ?? 80
+    const h = e.size?.height ?? 80
+    return {
+      ...e,
+      position: { x, y },
+      size: { width: w, height: h },
+      bbox: { min: { x, y }, max: { x: x + w, y: y + h } }
+    }
+  })
+}
+
+/**
+ * 모든 entity 의 좌표/크기가 [0..2] 범위에 들어가면 normalized 로 간주 (LLM 의 흔한 응답 패턴),
+ * image dimension 으로 곱해 픽셀 좌표로 보정. dim 이 없으면 그대로 반환.
+ */
+function denormalizeIfFractional(
+  entities: UniversalEntity[],
+  dims: { width: number; height: number } | undefined
+): UniversalEntity[] {
+  if (!dims || entities.length === 0) return entities
+  const isAllFractional = entities.every(e => {
+    const xs = [e.position.x, e.bbox.min.x, e.bbox.max.x, (e.size?.width ?? 0)]
+    const ys = [e.position.y, e.bbox.min.y, e.bbox.max.y, (e.size?.height ?? 0)]
+    return [...xs, ...ys].every(v => Number.isFinite(v) && v >= 0 && v <= 2)
+  })
+  if (!isAllFractional) return entities
+  const sx = dims.width
+  const sy = dims.height
+  return entities.map(e => ({
+    ...e,
+    position: { x: e.position.x * sx, y: e.position.y * sy },
+    size: e.size ? { width: e.size.width * sx, height: e.size.height * sy } : undefined,
+    bbox: {
+      min: { x: e.bbox.min.x * sx, y: e.bbox.min.y * sy },
+      max: { x: e.bbox.max.x * sx, y: e.bbox.max.y * sy }
+    }
+  }))
+}
+
+// ── 헬퍼 ─────────────────────────────────────────────────────────────
+
+/**
+ * 매직 바이트로 이미지 형식 감지. filename 이 없거나 확장자가 모호한 경우 fallback.
+ * 외부 reference 가 placeholder 로 응답되는 시나리오 (예: GLB top-view fetch 실패) 도
+ * 같은 binary 검사로 식별 가능.
+ */
+function detectImageMagic(file: AdapterInput): boolean {
+  const buf = toBuffer(file)
+  if (!buf || buf.length < 8) return false
+
+  // PNG: 89 50 4E 47 0D 0A 1A 0A
+  if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return true
+  // JPEG: FF D8 FF
+  if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return true
+  // GIF: 47 49 46 38
+  if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38) return true
+  // BMP: 42 4D
+  if (buf[0] === 0x42 && buf[1] === 0x4d) return true
+  // WebP: RIFF....WEBP
+  if (
+    buf[0] === 0x52 &&
+    buf[1] === 0x49 &&
+    buf[2] === 0x46 &&
+    buf[3] === 0x46 &&
+    buf.length >= 12 &&
+    buf[8] === 0x57 &&
+    buf[9] === 0x45 &&
+    buf[10] === 0x42 &&
+    buf[11] === 0x50
+  ) {
+    return true
+  }
+  return false
+}
+
+/**
+ * VLM 응답 entity 의 결손 필드 복구. uid 누락 → 인덱스 기반, bbox 누락 → position+size 로 합성,
+ * size/position 비숫자 값 → 0 fallback. 후속 stage2 가 안전하게 진행되도록 보호.
+ */
+function normalizeEntity(e: any, index: number): UniversalEntity {
+  const uid = typeof e?.uid === 'string' && e.uid ? e.uid : `img-${index}`
+  const kind = e?.kind ?? 'shape'
+  const position =
+    e?.position && Number.isFinite(e.position.x) && Number.isFinite(e.position.y)
+      ? { x: e.position.x, y: e.position.y }
+      : { x: 0, y: 0 }
+  const size =
+    e?.size && Number.isFinite(e.size.width) && Number.isFinite(e.size.height)
+      ? { width: e.size.width, height: e.size.height }
+      : undefined
+
+  let bbox: BoundingBox
+  if (
+    e?.bbox?.min &&
+    e?.bbox?.max &&
+    Number.isFinite(e.bbox.min.x) &&
+    Number.isFinite(e.bbox.min.y) &&
+    Number.isFinite(e.bbox.max.x) &&
+    Number.isFinite(e.bbox.max.y)
+  ) {
+    bbox = { min: { x: e.bbox.min.x, y: e.bbox.min.y }, max: { x: e.bbox.max.x, y: e.bbox.max.y } }
+  } else {
+    const w = size?.width ?? 0
+    const h = size?.height ?? 0
+    bbox = {
+      min: { x: position.x, y: position.y },
+      max: { x: position.x + w, y: position.y + h }
+    }
+  }
+
+  // bbox 가 position+size 와 일관되지 않으면 (VLM 이 lossy 한 bbox 를 줌) 일관성 보장.
+  // size 가 있을 때 bbox 는 항상 position..(position+size) 를 cover 해야 stage3-board 의
+  // 보드 크기 산정 / flipY 계산이 올바르다. 안 그러면 컴포넌트가 root 외곽으로 spill.
+  if (size) {
+    if (bbox.min.x > position.x) bbox.min.x = position.x
+    if (bbox.min.y > position.y) bbox.min.y = position.y
+    if (bbox.max.x < position.x + size.width) bbox.max.x = position.x + size.width
+    if (bbox.max.y < position.y + size.height) bbox.max.y = position.y + size.height
+  }
+
+  return {
+    uid,
+    kind,
+    position,
+    size,
+    rotation: typeof e?.rotation === 'number' ? e.rotation : undefined,
+    bbox,
+    attribs: e?.attribs && typeof e.attribs === 'object' ? { ...e.attribs } : {}
+  }
+}
+
+/**
+ * 모든 entity 의 bbox 를 합쳐 외부 bbox 산출. 빈 입력 / 무효값은 (0,0)-(0,0) fallback.
+ */
+function computeOuterBbox(entities: UniversalEntity[]): BoundingBox {
+  if (entities.length === 0) return { min: { x: 0, y: 0 }, max: { x: 0, y: 0 } }
+  let minX = Infinity
+  let minY = Infinity
+  let maxX = -Infinity
+  let maxY = -Infinity
+  for (const e of entities) {
+    if (Number.isFinite(e.bbox.min.x) && e.bbox.min.x < minX) minX = e.bbox.min.x
+    if (Number.isFinite(e.bbox.min.y) && e.bbox.min.y < minY) minY = e.bbox.min.y
+    if (Number.isFinite(e.bbox.max.x) && e.bbox.max.x > maxX) maxX = e.bbox.max.x
+    if (Number.isFinite(e.bbox.max.y) && e.bbox.max.y > maxY) maxY = e.bbox.max.y
+  }
+  if (!Number.isFinite(minX)) {
+    return { min: { x: 0, y: 0 }, max: { x: 0, y: 0 } }
+  }
+  return { min: { x: minX, y: minY }, max: { x: maxX, y: maxY } }
+}
+
+function toBuffer(file: AdapterInput): Buffer | undefined {
+  if (Buffer.isBuffer(file)) return file
+  if (file instanceof Uint8Array) return Buffer.from(file)
+  if (file instanceof ArrayBuffer) return Buffer.from(new Uint8Array(file))
+  if (typeof file === 'string') {
+    // 이미지 파싱은 string 입력을 의미 있게 처리할 방법이 없음 (base64 가정은 위험).
+    // 명시적으로 binary 만 수용 — string 은 undefined 로 떨어져 parse 단계에서 명확한 에러.
+    return undefined
+  }
+  return undefined
+}