magicCamera 🎩✨ — 魔术师的 AR 卡牌应用

一个创新的 AR 魔术表演应用，能够实时检测卡牌并将其替换为指定的卡牌图像。

github:https://github.com/Anyuer9837/magicCamera

---

📱 普通用户使用指南

🎯 快速开始（3 步操作）

1. 打开应用：启动 magicCamera 应用，授予相机权限
2. 按快门键：进入魔术选牌模式（会看到快门动画和声音）
3. 选择卡牌：依次点击屏幕选择花色和点数
4. 观看效果：摄像头中的卡牌实时替换为你选的卡牌

---

🎮 详细操作说明

按钮操作

🔴 快门按钮（大按钮）

短按快门：

• 播放"咔嚓"快门音效
• 屏幕闪白（模拟拍照效果）
• 进入"选牌模式"

长按快门（按住 1 秒）：

• 打开"参数调节面板"
• 可调整检测参数（见下方参数调节教程）

🔵 切换摄像头按钮（小按钮）

短按：

• 在前置摄像头 ↔ 后置摄像头之间切换
• 自动记住每个摄像头的参数设置

长按（按住 1 秒）：

• 打开/关闭"调试模式"
• 调试模式显示检测轮廓（用于调试，普通用户不需要）

屏幕选牌流程（「门子」阶段）

按下快门后，App 会模拟拍照效果（屏幕闪烁并伴随"咔嚓"声），自动进入「门子」流程，进行两步选牌操作：

✅ 第 1 步：选择花色

点击画面中的对应区域选择花色：

✅ 第 2 步：选择点数

点击画面中的对应区域选择点数：

✨ 选完后的反馈

选定点数后：

• 屏幕瞬间闪一下（黑色闪烁，代表生效）
• 系统自动进行卡牌识别和替换
• 摄像头中的卡牌被替换为你选择的卡牌

---

⚙️ 参数调节教程

如果检测效果不好（卡牌识别不稳定或无法识别），长按快门按钮调整这些参数。

📊 参数面板说明

长按快门按钮打开的参数面板包含 4 个滑块：

参数	范围	作用	调整建议
高斯模糊大小	1~41（奇数）	模糊程度。值越大越模糊	用于去除噪点；太大会丢失细节
Canny 下限	0~255	边界检测的下阈值	越小越容易检测到边界（也容易误检）
Canny 上限	0~255	边界检测的上阈值	越小越容易检测到边界
闭运算补缝大小	1~99	补缝程度。值越大越能填充缝隙	用于连接断裂的边界；太大会融合相邻卡牌

🎯 不同环境下的推荐参数

场景 1：光线充足、背景简单（最佳情况）

默认参数通常就可以用：

• 高斯模糊大小：13
• Canny 下限：0
• Canny 上限：150
• 闭运算补缝大小：30

场景 2：光线较暗、噪点多

增加模糊和补缝，降低 Canny 上限（更容易检测到卡牌）：

• 高斯模糊大小：19~25（增大）
• Canny 下限：0~30（可小幅增加）
• Canny 上限：80~120（降低，更敏感）
• 闭运算补缝大小：40~60（增大）

场景 3：光线很暗、只有手电筒光

激进参数：

• 高斯模糊大小：25~35（很大）
• Canny 下限：0
• Canny 上限：50~100（很低，非常敏感）
• 闭运算补缝大小：50~80（很大）

场景 4：室外强光、反光多、背景复杂

保守参数（避免误检）：

• 高斯模糊大小：9~13（较小）
• Canny 下限：20~50（增加，过滤噪点）
• Canny 上限：180~220（增加，只检测强边界）
• 闭运算补缝大小：15~25（较小）

🔧 调参技巧

1. 检测不到卡牌？

   • ❌ 不要盲目调参，先长按切换摄像头按钮打开调试模式
   • ✅ 在调试模式中，你能看到所有检测到的轮廓（黄线）和边界框（绿线）
   • ✅ 根据轮廓情况来决定怎么调参：
     • 如果没看到黄线，说明检测不到任何卡牌 → 降低 Canny 上限
     • 如果黄线很多很杂乱 → 增加 Canny 下限，降低高斯模糊
     • 如果轮廓断裂不连整 → 增加闭运算补缝大小

2. 实时调参

   • 在参数面板调整任何数值，立即在后台生效
   • 拖动滑块时观察效果，找到最佳值

3. 参数自动保存

   • 调好的参数会自动保存
   • 每个摄像头（前置/后置）独立保存参数
   • 下次使用时自动加载

4. 恢复默认值

   • 卸载重装应用，或清空应用数据

🔍 调试模式

长按切换摄像头按钮启用调试模式后：

• 黄色线条 = 检测到的卡牌轮廓
• 绿色边框 = 轮廓的外接矩形

这帮助你判断参数是否正确调整。

---

🎯 使用示例（完整魔术流程）

📽️ 给观众看的效果

1. 魔术师拿着手机/平板
2. 按下快门键 → 听到快门音，看到屏幕闪白
3. 手机屏幕显示实时摄像头预览
4. 魔术师将摄像头对准观众手中的任意卡牌
5. 魔术发生 🎩✨：摄像头中的卡牌实时变成另一张卡牌（例如红心 A）
6. 卡牌可以旋转、移动，效果始终跟随！

🕵️ 魔术师做的（隐蔽）

1. 短按快门 → 进入选牌模式
2. 点击屏幕左上角 → 选择"黑桃"
3. 点击屏幕左下角 → 选择"K"
4. 屏幕黑闪一下（暗号）→ 已选定黑桃 K
5. 收起手机，让观众看摄像头
6. 摄像头对准任何卡牌 → 全部变成黑桃 K！

---

❓ 常见问题

Q1：应用一直检测不到卡牌怎么办？

A：按照调参技巧部分做以下步骤：

1. 长按切换摄像头按钮打开调试模式
2. 将卡牌放在摄像头前
3. 观察是否有黄线出现（轮廓）
4. 根据轮廓情况调整参数（见"调参技巧"）

Q2：卡牌替换闪烁或不稳定？

A：增加闭运算补缝大小，这会使检测更稳定。

Q3：前置和后置摄像头参数需要一样吗？

A：不一定。两个摄像头独立保存参数，可以分别调优。

Q4：可以替换成自己的卡牌图片吗？

A：需要开发者修改代码和打包。普通用户无法直接修改。

Q5：应用需要联网吗？

A：不需要。完全离线运行，只需要相机权限。

---

📋 系统要求

• Android 版本：5.0 及以上
• 权限：需要相机权限（首次启动时会询问）
• 设备要求：有摄像头的 Android 手机或平板

---

📞 反馈与支持

如遇到问题或有建议，欢迎反馈。

---

祝你魔术表演成功！ 🎩✨

---

👨‍💻 程序员文档

技术细节和开发文档请参考 DEVELOPER.md

程序员相关文档包括：

• 项目技术架构
• 检测算法详解
• 代码结构说明
• 开发环境配置