Interactive Forest - 儿童画作互动森林 🌲

这是一个创新的互动艺术项目，将儿童的画作转化为生动的森林生态系统。

✨ 核心功能（最新）

🎥 摄像头 / 图片双输入

• 支持本地图片上传或直接使用摄像头拍照作为分割输入
• 自动“强制彩色”纠正部分 USB 摄像头初始化为灰阶的问题（可关闭）
• 拍照后自动释放摄像头并进入 ROI 选择

🎨 SAM 智能抠图工作流（多步骤）

• 上传 / 拍照 → ROI 选择 → 点选分割 → 候选对比 → 画笔润色 → 集成
• 多 ROI 管理：可批量框选、逐个处理、切换时状态记忆
• 点标注（正/负）+ 画笔删补（增/减）
• 候选掩码自动预览（半透明叠加）
• 导出时进行 ROI 裁剪 + 边缘轻柔化（feather）
• 输出命名唯一：seg_<stem>_roi_<index>_<timestamp>_<rand>.png，避免覆盖

🖼️ 舞台元素管理（Control Panel ↔ Projection Screen 双屏）

• 元素“上墙”后变为可见；“下墙”仅隐藏不删除，可再次显示
• 元素删除会同步删除本地 output 目录对应 PNG 文件（安全过滤）
• 启动时自动扫描历史导出文件并恢复为可管理元素（去重）
• 右侧面板新元素置顶显示，支持批量显示/隐藏已上墙元素

🔊 音效与动画

• 音效播放去重防抖：修复双触发/重复播放问题
• 上墙时可配置音效（一次/循环）、音量；隐藏时自动停止音频
• 轨迹动画支持关键帧（位置 / 缩放 / 旋转 / 透明度）

🧠 健壮性与体验优化

• 摄像头灰阶自动检测并增强（亮度/对比/饱和）
• 资源 URL 统一规范，避免缩略图偶发缺失
• Strict Mode 双调用防重恢复
• 清空舞台 / 单元素删除的后端文件同步清理

🌲 沉浸式森林投影舞台

• 后端导出 PNG 通过 /files 静态挂载加载
• 全屏无干扰展示 + 可视化动画 / 音效联动
• 双窗口 IPC（Electron）或 postMessage 回退通信

🎭 动画与交互系统

• 多种动画效果:
  • 🍃 摇摆动画 (sway): 温和的左右摇摆
  • ✈️ 呼吸动画 (breath): 呼吸式尺寸变换
  • 🚶 路径移动 (move): 自定义路径移动
• 拖拽控制: 鼠标自由拖拽元素位置
• 触碰反馈: 点击元素触发音效和动画

🎵 音效系统

• 元素专属音效: 每个元素分配独特的声音
• 触发播放: 点击或选中时播放音效
• 环境音: 可选的背景环境音效

🚀 快速开始（更新）

1. 启动后端服务（SAM + 资产管理 + 删除接口）

cd apps/cv_service

# 设置环境变量
$env:SAM_WEIGHTS="./app/models/sam_vit_h_4b8939.pth"
$env:OUTPUT_DIR="../../output"

# 启动SAM服务
python -m uvicorn app.main:app --reload --port 7001

2. 启动前端桌面应用（ControlPanel + ProjectionScreen）

cd apps/desktop
npm install
npm run dev

3. 准备媒体与权重

请将以下文件放置到指定位置：

视频背景 (必需):

• 📁 apps/desktop/renderer/public/video/forest.mp4
• 推荐规格: 1920x1080, MP4格式, 循环动画

音效文件 (可选):

• 📁 apps/desktop/renderer/public/audio/
  • bird.mp3 - 鸟类音效
  • dog.mp3 - 动物音效
  • wind.mp3 - 风声音效

🎯 使用流程（新工作流）

1. 选择“选择图片”或开启摄像头拍照；拍照后自动进入 ROI 阶段
2. 拖拽框选 ROI（可多个）→ 首 ROI 自动进入“分割”步骤
3. 在 ROI 内点击添加正向/负向点 → 点数≥1 后执行“开始分割”
4. 在候选列表中挑选最佳掩码，可进入“画笔润色”微调
5. 确认后导出为舞台元素（初始未上墙，列表顶部出现）
6. 点击“上墙”元素显示到投影屏幕（可配置音效/轨迹）
7. “下墙”仅隐藏；再次“上墙”可恢复；“删除”会移除并删除本地 PNG
8. 清空舞台会批量移除并清理 output/ 中对应 seg_ 文件

附加：启动时自动恢复历史 seg_*.png（未自动上墙）

🛠️ 技术架构

后端 (FastAPI + SAM)

• 图像分割: Meta SAM模型提供AI抠图能力
• 会话管理: 支持多用户同时使用
• 文件管理: 自动处理上传、处理、导出流程

前端 (Electron + React + PIXI.js)

• 跨平台: Electron提供桌面应用体验
• 现代UI: React构建响应式用户界面
• 高性能渲染: PIXI.js实现流畅的2D图形和动画

核心特性

• 🔄 实时同步: 前后端实时通信
• 🎨 GPU加速: 硬件加速的图形渲染
• 📱 响应式: 适配不同分辨率屏幕
• 🔊 多媒体: 视频、音频、图像综合处理

🎪 应用场景

教育展示

• 儿童美术展: 将静态画作转化为动态展示
• 互动教学: 让孩子看到自己的创作"活"起来
• 艺术治疗: 通过互动增强孩子的创作兴趣

商业应用

• 艺术画廊: 创新的数字艺术展示方式
• 儿童乐园: 沉浸式的娱乐体验
• 教育机构: 现代化的教学工具

🔧 关键配置与命名

项目	说明
OUTPUT_DIR	导出 PNG、恢复扫描、删除接口操作目录
文件命名	seg_<stem>_roi_<index>_<timestamp>_<rand>.png
摄像头滤镜	仅 CSS 预览，不改变底层捕获数据
画笔润色	将 strokes 发送 /sam/brush-refinement，返回新的 refined mask id

动画参数调整

在Stage组件中可以调整动画参数：

animation: {
  type: 'sway',      // 动画类型
  speed: 1.0,        // 速度倍数
  amplitude: 10,     // 摇摆幅度
  phase: 0           // 初始相位
}

音效配置

sound: {
  audio: HTMLAudioElement,
  loop: true,        // 是否循环
  volume: 0.3        // 音量 (0.0-1.0)
}

📋 系统要求

硬件要求

• CPU: 支持AVX指令集 (Intel i5或同等性能)
• 内存: 16GB+ RAM (SAM模型较大)
• 显卡: 支持WebGL 2.0 (集成显卡即可)
• 存储: 5GB+ 可用空间

软件环境

• 操作系统: Windows 10/11, macOS 10.15+, Linux
• Node.js: 16.0+
• Python: 3.8+
• 浏览器: Chrome 80+, Firefox 75+, Safari 13+

🚨 故障排除（新增场景）

问题	说明	解决
摄像头灰阶	某些 USB 摄像头默认单通道	自动强制彩色或手动“🎨 强制彩色”
分割按钮提示缺少文件	摄像头模式 sessionId 未就绪	等待 0.5s 再试；检查 /sam/init 响应
上墙后音频重复	旧版本逻辑超时双触发	已修复（清除回退定时器）
删除元素文件未消失	非 seg_ 前缀或权限不足	确认文件名 & 目录权限
缩略图偶尔空白	URL 不统一	已统一使用 /files 路径

常见问题

1. 黑屏问题

• 确保已安装React类型定义: npm install @types/react @types/react-dom
• 检查视频文件是否存在于正确路径

2. SAM 服务连接失败

• 验证后端服务运行状态: http://localhost:7001/health
• 检查环境变量设置是否正确

3. 音效无法播放

• 确保音频文件格式正确 (MP3, WAV)
• 检查浏览器自动播放策略设置

调试技巧

• 开启DevTools查看控制台错误
• 使用网络面板监控API请求
• 查看终端输出的详细日志

🤝 贡献指南

欢迎贡献代码、报告问题或提出改进建议！

1. Fork 项目仓库
2. 创建特性分支: git checkout -b feature/amazing-feature
3. 提交更改: git commit -m 'Add amazing feature'
4. 推送分支: git push origin feature/amazing-feature
5. 创建Pull Request

📄 开源协议

本项目采用 MIT 协议 - 详见 LICENSE 文件

🎉 致谢

• Meta AI - SAM (Segment Anything Model) 提供强大的图像分割能力
• PIXI.js - 高性能2D渲染引擎
• React & Electron - 现代化的前端技术栈
• FastAPI - 高性能Python Web框架

---

让每一幅儿童画作都在数字森林中绽放生命力！ 🌟 （文档更新：含摄像头与新工作流特性）