---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "圖片處理架構設計"
date: "2026-04-25"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "圖片處理架構設計"
ai_query_hints:
  - "查詢 圖片處理架構設計 的內容"
  - "圖片處理架構設計 的主要目的是什麼？"
  - "如何操作或實施 圖片處理架構設計？"
---

# 圖片處理架構設計

## 1. 概述

### 1.1 設計理念
將圖片視為**單幀影片**，利用現有的影片處理管道進行統一的元數據提取和內容分析。

### 1.2 核心優勢
1. **技術復用**：重用現有影片處理器（ASR/ASRX、YOLO、OCR、Face、Scene）
2. **統一接口**：圖片和影片使用相同的 API 接口
3. **成本效益**：無需開發專用的圖片處理系統
4. **數據一致性**：圖片和影片使用相同的數據模型

---

## 2. 技術實現

### 2.1 處理流程

```
圖片輸入
    ↓
[圖片預處理]
    ↓
圖片 → 單幀影片轉換 (1秒, 1fps)
    ↓
[現有影片處理管道]
    ↓
    ├──> ASR/ASRX 處理器 (跳過，無音頻)
    ├──> OCR 處理器 (文字識別)
    ├──> YOLO 處理器 (物件檢測)
    ├──> Face 處理器 (人臉識別)
    ├──> Scene 處理器 (場景分類)
    ↓
分片生成
    ↓
向量嵌入
    ↓
檢索服務
```

### 2.2 圖片轉影片策略

| 參數 | 值 | 說明 |
|------|-----|------|
| **幀率** | 1 fps | 單幀影片，1秒長度 |
| **分辨率** | 保持原圖 | 不進行縮放 |
| **編碼格式** | MP4/H.264 | 標準影片格式 |
| **臨時存儲** | 處理後刪除 | 減少存儲占用 |

### 2.3 EXIF 元數據提取

| EXIF 字段 | 用途 | 存儲位置 |
|-----------|------|----------|
| **拍攝時間** | 時間戳 | `chunks.start_time` |
| **GPS 坐標** | 地理位置 | `chunks.metadata.gps` |
| **相機型號** | 設備信息 | `chunks.metadata.camera` |
| **曝光參數** | 技術數據 | `chunks.metadata.exposure` |

---

## 3. 數據模型擴展

### 3.1 媒體類型枚舉

```rust
// src/core/media/types.rs
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum MediaType {
    Video(VideoType),
    Image(ImageType),
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum VideoType {
    Mp4,
    Mov,
    Avi,
    Mkv,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum ImageType {
    Jpeg,
    Png,
    Gif,
    Bmp,
    Webp,
}

// 擴展 VideoRecord 結構
pub struct VideoRecord {
    pub id: i64,
    pub uuid: String,
    pub media_type: MediaType,  // 新增字段
    pub duration: f64,          // 圖片: duration = 1.0
    pub width: u32,
    pub height: u32,
    // ... 其他現有字段
}
```

### 3.2 圖片特定元數據

```rust
pub struct ImageMetadata {
    pub exif_data: Option<serde_json::Value>,
    pub color_profile: Option<String>,
    pub dpi: Option<(u32, u32)>,
    pub format: ImageType,
}

pub struct VideoRecord {
    // ... 現有字段
    pub image_metadata: Option<ImageMetadata>,  // 圖片特有元數據
}
```

---

## 4. 分片策略

### 4.1 圖片特有分片類型

| 分片類型 | 對應影片分片 | 圖片應用 |
|----------|--------------|----------|
| **TimeBased** | `ChunkType::TimeBased` | 單一時間點 (0.0-1.0秒) |
| **Visual** | `ChunkType::Visual` | YOLO 檢測到的視覺物件 |
| **Text** | `ChunkType::Sentence` | OCR 識別的文本內容 |
| **Face** | 新類型 `ChunkType::Face` | 人臉識別結果 |

### 4.2 分片內容結構

```rust
// 圖片視覺分片
pub struct ImageVisualChunk {
    pub objects: Vec<DetectedObject>,  // YOLO 檢測結果
    pub scene_tags: Vec<String>,       // 場景分類標籤
    pub dominant_colors: Vec<Color>,   // 主導顏色
}

// 圖片文本分片  
pub struct ImageTextChunk {
    pub ocr_text: String,              // OCR 識別文本
    pub text_regions: Vec<TextRegion>, // 文本區域位置
    pub language: Option<String>,      // 語言識別
}
```

---

## 5. 處理器適配

### 5.1 現有處理器修改

| 處理器 | 圖片處理策略 | 修改需求 |
|--------|--------------|----------|
| **ASR/ASRX** | 跳過處理 | 檢測媒體類型，圖片時跳過 |
| **OCR** | 增強處理 | 支持圖片 OCR，可選用更高精度模型 |
| **YOLO** | 正常處理 | 無需修改 |
| **Face** | 正常處理 | 無需修改 |
| **Scene** | 正常處理 | 無需修改 |
| **CUT** | 跳過處理 | 單幀無需場景切換檢測 |

### 5.2 新增處理器

```rust
// EXIF 提取處理器
pub struct ExifExtractor;

impl Processor for ExifExtractor {
    fn process(&self, context: &ProcessorContext) -> Result<ProcessorOutput> {
        // 僅對圖片執行
        if context.media_type == MediaType::Image {
            // 提取 EXIF 數據
            let exif_data = extract_exif(&context.input_path)?;
            Ok(ProcessorOutput::Exif(exif_data))
        } else {
            Ok(ProcessorOutput::Skipped)
        }
    }
}

// 圖片質量評估處理器
pub struct ImageQualityAssessor;

impl Processor for ImageQualityAssessor {
    fn process(&self, context: &ProcessorContext) -> Result<ProcessorOutput> {
        // 評估圖片質量
        let quality_score = assess_image_quality(&context.input_path)?;
        Ok(ProcessorOutput::ImageQuality(quality_score))
    }
}
```

---

## 6. API 擴展

### 6.1 新增端點

```rust
// 圖片上傳端點
POST /api/v1/images/upload
Content-Type: multipart/form-data

// 圖片搜索端點
GET /api/v1/images/search
Query: {
    "text": "沙灘日落",
    "objects": ["person", "umbrella"],
    "colors": ["#FF6B35", "#004E89"],
    "time_range": {"start": "2024-01-01", "end": "2024-12-31"}
}

// 圖片元數據端點
GET /api/v1/images/{uuid}/metadata
```

### 6.2 搜索功能擴展

1. **視覺搜索**：
   - 基於 YOLO 物件檢測
   - 顏色直方圖匹配
   - 紋理特徵相似度

2. **文本搜索**：
   - OCR 文本全文搜索
   - EXIF 元數據過濾

3. **混合搜索**：
   - 視覺 + 文本組合搜索
   - 地理 + 時間範圍搜索

---

## 7. 部署與性能

### 7.1 資源需求

| 資源 | 圖片處理需求 | 影片處理需求 |
|------|--------------|--------------|
| **CPU** | 較低 | 較高 |
| **GPU** | 可選（加速）| 必需 |
| **內存** | 較低 | 較高 |
| **存儲** | 較低 | 較高 |

### 7.2 性能優化

1. **批量處理**：
   ```rust
   // 支持批量圖片處理
   pub async fn process_images_batch(
       image_paths: Vec<PathBuf>,
       concurrency: usize,
   ) -> Result<Vec<ProcessResult>> {
       // 並行處理多張圖片
   }
   ```

2. **緩存策略**：
   - 圖片轉影片結果緩存
   - EXIF 元數據緩存
   - 縮略圖預生成

3. **異步處理**：
   - 非阻塞上傳
   - 後台處理隊列
   - 處理狀態查詢

---

## 8. 實施路線圖

### 8.1 Phase 1: 基礎支持 (1個月)
- [ ] 圖片轉影片工具
- [ ] EXIF 元數據提取
- [ ] 現有處理器適配

### 8.2 Phase 2: 功能增強 (2個月)
- [ ] 圖片專用搜索功能
- [ ] 質量評估處理器
- [ ] 批量處理支持

### 8.3 Phase 3: 高級功能 (3個月)
- [ ] 視覺相似度搜索
- [ ] 圖片去重功能
- [ ] AI 圖片標註增強

---

## 9. 成功指標

### 9.1 功能指標
| 指標 | 目標值 |
|------|--------|
| 圖片處理成功率 | ≥99% |
| OCR 識別準確率 | ≥95% |
| 物件檢測準確率 | ≥90% |
| 處理延遲 | ≤5秒/圖片 |

### 9.2 業務指標
| 指標 | 目標值 |
|------|--------|
| 圖片檢索準確率 | ≥85% |
| 用戶滿意度 | ≥4.5/5.0 |
| 系統吞吐量 | ≥100圖片/分鐘 |

---

**最後更新**: 2026-04-22  
**版本**: V1.0  
**狀態**: 設計階段  
**優先級**: 中
