Add comprehensive README for LiveCompose

[Copilot]

The repository had a near-empty README.md (# .github only). This PR replaces it with full project documentation derived from the mid-term presentation material.

Structure

• Motivation & advantages — pain points addressed, target users, comparison table vs. traditional camera apps
• System architecture — four-layer diagram (hardware → inference → coordination → SwiftUI UI) with per-layer responsibilities
• Model (AdacropModel) — ResNet50 backbone + Actor/Critic/BBox Head modules table; two-phase training (supervised pretraining → RL with NIMA reward); dataset construction pipeline (BLIP captioning + SD v2 Inpaint outpainting + three-step QA)
• Real-time video pipeline — AVFoundation frame pipeline diagram, CoreML student-model distillation rationale
• Tracking & UI guidance — gyroscope-based physics tracker with magnetic snap, haptic feedback event table, GuidanceBar phase→text mapping table
• Metrics & roadmap — evaluation approach (NIMA re-scoring, A/B test), LiDAR depth integration, cloud/community learning plans

Original prompt

构妙 LiveCompose 中期答辩 PPT 方案

一、设计动机与优势

1.1 项目的动机是什么？解决了现有拍照方案的哪些痛点？

我们观察到，虽然现在的智能手机拍照功能很强大，但很多普通用户并不了解专业的摄影构图知识，比如“三分法”或者如何突出主体。他们拍出的照片常常构图平庸，或者抓不住重点。现有的相机应用大多只提供静态的辅助线，比如九宫格，但这并不能主动告诉用户“应该怎么移动手机才能构图更好”。用户仍然需要自己判断和调整，这既费时又容易错过精彩瞬间。我们的项目动机就是解决这个痛点，我们希望通过 AI 技术，实时分析画面内容，并主动引导用户移动手机，轻松获得构图更优良的照片，甚至在对齐时自动完成拍摄，让好照片的诞生更加“智能”和“轻松”。

1.2 产品的目标用户与核心目标是什么？用户通过产品能获得哪些提升？

我们的目标用户主要是那些希望提高手机摄影水平，但又缺乏专业摄影知识的广大普通用户，比如喜欢在社交媒体分享生活的年轻人，或者希望为家人拍出更好照片的父母。产品的核心目标是成为一个“智能构图助手”，通过实时反馈和引导，帮助用户在拍摄当下就完成出色的构图。用户通过使用我们的产品，最直接的提升就是照片的构图质量会显著改善，画面主体更突出，视觉效果更专业。同时，由于引导是实时的，用户可以在拍摄过程中潜移默化地学习到一些构图技巧。对于开启了自动拍照功能的用户，他们还能更专注于捕捉对象的表情和动作，将按下快门的时机交给应用判断，从而可能捕捉到更自然的瞬间。

1.3 对比同类 APP，项目的主要创新点和优势？

目前市场上的相机应用，要么是专注于滤镜和后期处理美颜相机，要么是提供静态的构图辅助线的系统相机。我们的主要创新点在于“实时动态引导”和“智能追踪”。我们不仅通过 AI 模型分析画面，确定一个理想的构图区域，更关键的是，我们结合了设备的陀螺仪数据实现了一个物理上更准确、体验更流畅的追踪系统，实时在屏幕上显示目标点，引导用户移动手机去对齐。这种“检测-追踪-引导-拍摄”的闭环是我们的核心优势。相比于简单的网格线，我们的引导是动态的、交互式的，这让获得一张构图良好的照片不再需要复杂的思考和调整，操作门槛大大降低，实现摄影的普惠化与大众化

二、技术实现

2.1 项目的整体系统架构图？说明各个模块的功能与交互方式

系统架构图：


我们在 ios 平台上设计应用，并将 LiveCompose 构图模型内置于应用中，系统采用了四层设计

我们的架构基础是第一层，也就是数据采集层。这一层直接和硬件打交道。它主要包含两个模块：一个是 CameraManager，它利用苹果的 AVFoundation 框架来管理相机，负责捕捉实时的视频帧数据流 和拍摄最终的照片；另一个是 MotionStabilityMonitor，它通过 CoreMotion 框架持续获取设备的陀螺仪和加速度数据。这一层的工作就是为上层提供原始图像和运动数据。

拿到原始数据后，就进入了第二层，智能决策与追踪层。这一层是实现智能化的关键。它包括了我们的核心 AdacropModel，这是一个通过 CoreML 运行的强化学习模型，它负责分析视频帧，计算出最佳的构图建议。同时，这一层还有 BoxCenterManager，它获取第一层的陀螺仪数据，实现一个基于物理的追踪模型。这个追踪器不仅能计算目标位置，还带有一个“磁性吸附”功能，当用户接近中心点时能自动吸附，帮助稳定对齐。

第三层是核心协调层，它是整个应用的大脑。这一层只有一个关键模块，CaptureViewModel。它负责管理一个复杂的状态机，比如“等待稳定”、“正在检测”、“准备拍照”等。它从第一层拿到数据，指挥第二层在设备稳定时才启动 AdacropModel 进行分析。当模型给出结果后，它把目标点交给 BoxCenterManager 去追踪。它还持续监控追踪状态，一旦发现“已对齐”，就会触发自动拍照逻辑，并根据当前状态生成引导文字给用户看。所有来自界面的操作，比如变焦或切换镜头，也都由它来响应和调度。

最上面是第四层，视图与交互层，也就是用户直接看到和操作的界面。这一层完全由 SwiftUI 构建。它包含了 ContentView 作为主视图，一个 CameraPreview 视图来显示底层的相机预览，以及 UserGuidanceView 和其他 UI 组件，如按钮和变焦环。这一层的所有视图都订阅 CaptureViewModel 的状态。当 ViewModel 更新数据时，例如追踪点位置或引导文字变化时，界面会自动刷新，同时，用户的点击操作也会被传递回 ViewModel 去执行。

2.2 选取了什么模型，如何进行训练，数据集如何搭建，模型的参数等等

1. 模型架构

• 主干网络 （Backbone）：torchvision ResNet50（使用ImageNet 预训练），去掉 fc（self.backbone.fc = Identity），特征维度 2048。用于提取图片的高层语义特征，供后续分支使用。
  • 输入：[B, 3, 224, 224] 图像张量为 3×224×224，将最长边缩放到224，另一边空白部分用黑色填充，保持原始比例
  • 输出：特征向量 [B, 2048]
• Actor 分支
  • 结构：MLP（2048+4 → 1024 → 512 → n_actions）。
  • 输入：图片特征 [B, 2048] + 当前裁剪框状态 [B, 4]（归一化的 (cx, cy, w, h)，分别是裁剪框左上角坐标和宽高，均除以原图尺寸，范围在 0~1）。
  • 输出：动作概率分布 [B, n_actions]。
  • 作用：决定 agent 在当前状态下选择哪个动作（比如移动、缩放、停止等）
• Critic 分支
  • 结构：MLP（2048+4 → 1024 → 512 → 1）。
  • 输入：同 Actor。
  • 输出：当前状态的价值估计 [B, 1]。
  • 作用：用于强化学习中的优势估计和基线，即当前状态有多好
• BBox Head 分支
  • 结构：MLP（2048 → 512 → 4）。
  • 输入：仅图片特征 [B, 2048]。
  • 输出：预测裁剪框参数 [B, 4]。
  • 作用：只在监督预训练阶段用，回归真实裁剪框。

训练数据与环境

• 数据来源：config.data.train_json / val_json（每条记录含 rec['img'] 路径）。
• 环境（CropEnv）：
  • 状态：裁剪后的图像张量 + 归一化几何向量。
  • 奖励：基于 NIMA 美学模型的分数变化（tanh 形状）+ 访问/重复/无效动作惩罚；stop 动作有额外设计。
  • NIMA 评分器：A800SharedNIMAScorer（PyTorch）
    • 架构按权重路径自动选 Inception v3 或 ResNet50，末层输出 10 桶评分分布，期望值为得分（1~10）。
    • 实际评分每 real_score_interval=5 步计算一次，其余用几何启发估计；含缓存与限幅。
    • 权重路径：nima.weights_path（示例 ./NIMA/weights/nima_inception_pytorch.pth）。若缺失则不会加载自定义权重，仅用 ImageNet/随机权重，效果会差。

2. 训练流程

2.1 监督预训练

• 训练部分：只训练 backbone 和 bbox_head

• 流程 ：

  1. 输入图片，backbone 提取特征。
  2. bbox_head 回归裁剪框参数。
  3. 用 MSELoss 和真实框做监督训练。
  4. 训练结束后，把 backbone 和 bbox_head 的权重迁移到完整 ActorCritic 模型。

• 目的：让 backbone 学会裁剪相关特征，bbox_head学会预测合理裁剪框，为后续 RL 提供更好的初始化。

2.2 强化学习

• 训练部分：用完整的 ActorCritic（backbone + actor + critic）。

• 环境 CropEnv

  • 状态组成：

    • 图像裁剪张量 img_tensor: [3, img_size, img_size]，由当前 box 裁剪 + resize 得到
    • 几何状态 state_tensor: [x/iw, y/ih, w/iw, h/ih]

  • 动作集合 self.actions（共 11 个）：

    left, right, up, down, zoom_in, zoom_out, wider, narrower, taller, shorter, stop

  • 步进逻辑：

    1. 根据动作修改 box（平移 / 缩放 / 改变宽高）。

    2. 边界裁剪 并 判断最小尺寸约束

    3. 评分：new_score = _get_score(new_box)

       • 若当前步数满足间隔: real（调用 NIMA）
       • 否则：几何估计 _estimate_score_safe

    4. 奖励：

       • 分数差 score_diff = new_score - prev_score
       • base_reward = tanh(score_diff * 2.0)
       • 惩罚 penalty：
         • 重复访问同一裁剪：visit_penalty
         • 连续完全未改变（no-op）：no_op_penalty
         • 过度重复到 max_repeat：repeat_penalty
       • stop 动作特殊：奖励 = (final_score - prev_score)*2.0 +（早停惩罚或适时停奖励）

    5. 更新 prev_score, best_score, step_count；返回 (img_tensor, state_tensor), reward, done, info

  • 重置 reset()

    • 随机初始化一个可行 box

    • 初始裁剪评分（真实 NIMA 调用）

    • 清理缓存过大时的 score_cache

    • 返回初始状态


• 真实 NIMA 评分比较耗时，为保证训练进度做了以下处理：

  • reset() 会调用 NIMA 得到初始分（init_score）。

  • 每次需要评分时，env._get_score 会先查缓存 score_cache；若命中即不调用 NIMA。

  • 否则按间隔决定是否真实调用：当 self.step_count % self.real_score_interval == 0 时调用 _safe_nima...

[JettyCoffee]

OK