🔮 Mystic Gestures Tarot

一个使用手势识别和 AI 驱动的交互式塔罗牌 Web 应用

在线演示 | 功能特性 | 快速开始 | 手势控制

✨ 项目简介

Mystic Gestures Tarot 是一个融合了现代 Web 技术与神秘塔罗元素的创新应用。通过 MediaPipe 手势识别技术，用户可以用自然的手势动作与虚拟塔罗牌互动，体验前所未有的沉浸式占卜体验。

🎯 核心亮点

🖐️ 自然手势交互 - 使用 MediaPipe 实时识别手部动作
🎨 流畅动画效果 - Canvas 驱动的 3D 卡牌动画系统
🤖 AI 智能解读 - 集成 Google Gemini AI 生成神秘的塔罗解读
🃏 完整塔罗牌组 - 包含 78 张经典 Rider-Waite-Smith 塔罗牌
🌙 神秘视觉风格 - 深色主题搭配金色点缀，营造神秘氛围
📱 响应式设计 - 支持桌面端和移动端访问

🎮 功能特性

1️⃣ 交互式占卜模式 (Begin Ritual)

通过摄像头捕捉手势，完成完整的塔罗牌抽取流程：

握拳 (Closed Fist) → 卡牌堆叠
张开手掌 (Open Palm) → 卡牌洗牌散开
竖起一根手指 (Pointing Up) → 选中一张牌
摇动手指 (Shake) → 翻转揭示卡牌，触发 AI 解读

2️⃣ 学习模式 (Study the Glyphs)

浏览完整的塔罗牌库，了解每张牌的含义和象征。

3️⃣ 实时视觉反馈

🎥 画中画显示摄像头画面和手部骨骼追踪
✨ 金色粒子特效环绕选中的卡牌
🔄 平滑的卡牌翻转和移动动画
📊 实时显示手势识别状态

🚀 快速开始

前置要求

Node.js >= 18.0.0
npm >= 9.0.0
支持 WebRTC 的现代浏览器（Chrome、Edge、Safari 等）
摄像头权限

1. 克隆项目

git clone https://github.com/Dreammmmix/tarot.git
cd tarot/mystic-gestures-tarot

2. 安装依赖

npm install

3. 配置 API 密钥

创建 .env.local 文件并添加你的 Gemini API 密钥：

API_KEY=your_gemini_api_key_here

💡 获取 API 密钥: 访问 Google AI Studio 免费获取

4. 启动开发服务器

npm run dev

应用将运行在 http://localhost:3000/

5. 构建生产版本

npm run build
npm run preview

🖐️ 手势控制

手势识别状态机

   握拳 (STACKED)
        ↓
   张开手掌 (SHUFFLING)
        ↓
   竖起手指 (SELECTED)
        ↓
   摇动手指 (REVEALED)

详细手势说明

手势	动作	效果	状态
✊ Closed Fist	握紧拳头	卡牌回到堆叠状态	`STACKED`
🖐️ Open Palm	张开五指	卡牌开始洗牌并散开	`SHUFFLING`
☝️ Pointing Up	竖起食指	选中一张牌到中央	`SELECTED`
👆 Shake Finger	快速左右摇动手指	翻转卡牌并触发 AI 解读	`REVEALED`

使用技巧

💡 保持手部在摄像头视野内，距离适中（30-60cm）
💡 确保光线充足，避免强烈背光
💡 手势动作可以夸张一些，识别效果更好
💡 查看右上角的实时反馈确认识别状态

🏗️ 技术架构

核心技术栈

Frontend Framework:  React 19.2 + TypeScript
Build Tool:          Vite 6.4
Gesture Recognition: MediaPipe Hands 0.10.14
AI Service:          Google Gemini 2.5 Flash
Canvas Rendering:    HTML5 Canvas API
Styling:             TailwindCSS (inline)

项目结构

mystic-gestures-tarot/
├── App.tsx                 # 主应用组件
├── index.tsx              # 应用入口
├── types.ts               # TypeScript 类型定义
├── constants.ts           # 塔罗牌数据和常量
├── components/
│   ├── IntroScreen.tsx    # 欢迎页面
│   ├── LearnScreen.tsx    # 学习模式
│   └── TarotCanvas.tsx    # 核心交互画布
├── services/
│   └── geminiService.ts   # Gemini AI 集成
├── public/
│   └── cards/             # 78 张塔罗牌图片
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md

关键模块说明

1. `TarotCanvas.tsx` - 核心渲染引擎

使用 requestAnimationFrame 实现 60fps 动画循环
基于 Canvas 2D Context 实现伪 3D 卡牌渲染
粒子系统模拟魔法特效
MediaPipe 手势识别集成

2. `geminiService.ts` - AI 解读服务

封装 Google Gemini API 调用
生成基于 "Penderecki's Garden" 风格的神秘解读
错误处理和降级策略

3. `constants.ts` - 数据层

完整的 78 张塔罗牌名称映射
大阿卡纳（22 张）+ 小阿卡纳（56 张）
卡牌图片路径解析

🎨 设计理念

视觉风格

配色方案:
- 主色: #d4af37 (古铜金)
- 背景: #000000 - #0a0a0a (深黑)
- 文字: #ffffff / #9ca3af (白/灰)
字体:
- 标题: 衬线体 + 大字间距 (tracking-widest)
- 正文: 衬线体 + 斜体营造神秘感

动画设计

缓动函数: 使用线性插值（LERP）实现平滑过渡
粒子系统: 金色粒子沿卡牌边缘生成
翻转效果: 基于 cos() 函数的 3D 翻转模拟

用户体验

全屏模式支持
实时手势状态提示
AI 生成等待动画
响应式布局适配

📦 依赖说明

运行时依赖

{
  "react": "^19.2.0",
  "react-dom": "^19.2.0",
  "@google/genai": "^1.30.0"
}

开发依赖

{
  "typescript": "~5.8.2",
  "vite": "^6.2.0",
  "@vitejs/plugin-react": "^5.0.0",
  "@types/node": "^22.14.0"
}

CDN 依赖

@mediapipe/tasks-vision@0.10.14 - 手势识别
MediaPipe WASM 运行时

🌐 浏览器兼容性

浏览器	支持版本	备注
Chrome	>= 90	✅ 完全支持
Edge	>= 90	✅ 完全支持
Safari	>= 14	✅ 需允许摄像头权限
Firefox	>= 88	⚠️ 部分设备手势识别可能不稳定
Mobile Safari	>= 14	✅ 支持，建议横屏使用

🔧 开发说明

环境变量

变量名	说明	必需
`API_KEY`	Gemini API 密钥	✅ 是

脚本命令

npm run dev      # 启动开发服务器
npm run build    # 构建生产版本
npm run preview  # 预览生产构建

调试技巧

手势识别问题: 查看右上角摄像头窗口的骨骼追踪是否正常
卡牌不加载: 检查 public/cards/ 目录和网络请求
AI 无响应: 确认 .env.local 中的 API_KEY 是否正确

🎯 路线图

支持多张牌抽取（三牌阵、凯尔特十字等）
添加语音朗读功能
保存占卜历史记录
支持自定义塔罗牌牌组
WebGL 渲染升级
多语言支持（英文、中文）
PWA 离线支持

📄 许可证

本项目采用 MIT License 开源。

资源归属

塔罗牌图片: Rider-Waite-Smith 塔罗牌 (公有领域)
图片来源: terminal-tarot by Michelle Stermitz (MIT License)
手势识别: Google MediaPipe (Apache 2.0 License)

🙏 致谢

Google MediaPipe - 强大的手势识别框架
Google Gemini AI - AI 解读服务
terminal-tarot - 塔罗牌图片资源
Vite - 快速的构建工具
React - UI 框架

📮 联系方式

如有问题或建议，欢迎通过以下方式联系：

🐛 提交 Issue: GitHub Issues
💬 讨论交流: GitHub Discussions
📧 邮件: [你的邮箱]

✨ 让命运之轮通过你的双手转动 ✨

Made with 🔮 by Dreammmmix

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
assets		assets
components		components
public/cards		public/cards
services		services
.gitignore		.gitignore
App.tsx		App.tsx
README.md		README.md
constants.ts		constants.ts
index.html		index.html
index.tsx		index.tsx
metadata.json		metadata.json
package-lock.json		package-lock.json
package.json		package.json
tarotMeanings.ts		tarotMeanings.ts
tsconfig.json		tsconfig.json
types.ts		types.ts
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

🔮 Mystic Gestures Tarot

✨ 项目简介

🎯 核心亮点

🎮 功能特性

1️⃣ 交互式占卜模式 (Begin Ritual)

2️⃣ 学习模式 (Study the Glyphs)

3️⃣ 实时视觉反馈

🚀 快速开始

前置要求

1. 克隆项目

2. 安装依赖

3. 配置 API 密钥

4. 启动开发服务器

5. 构建生产版本

🖐️ 手势控制

手势识别状态机

详细手势说明

使用技巧

🏗️ 技术架构

核心技术栈

项目结构

关键模块说明

1. TarotCanvas.tsx - 核心渲染引擎

2. geminiService.ts - AI 解读服务

3. constants.ts - 数据层

🎨 设计理念

视觉风格

动画设计

用户体验

📦 依赖说明

运行时依赖

开发依赖

CDN 依赖

🌐 浏览器兼容性

🔧 开发说明

环境变量

脚本命令

调试技巧

🎯 路线图

📄 许可证

资源归属

🙏 致谢

📮 联系方式

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. `TarotCanvas.tsx` - 核心渲染引擎

2. `geminiService.ts` - AI 解读服务

3. `constants.ts` - 数据层

Packages