Skip to content

imvanda/3D-IOT-Face-Recognition-Room

BranchesTags

Repository files navigation

3D智能虚拟房间

高仿真3D智能家居环境

支持第一人称漫游 · IoT设备控制 · AI语音指令 · 人脸识别认证

React TypeScript Three.js Django Node-RED ThingsBoard License

📖 项目简介

image
PixPin_2026-01-04_17-11-15.mp4

3D智能虚拟房间是一个基于Web的智能家居物联网管理系统，采用第一人称视角3D漫游技术，结合AI语音控制和生物识别技术，提供沉浸式的智能家居体验。

核心特性

  • 🏠 3D沉浸式漫游 - 第一人称视角，WASD移动 + 鼠标转向
  • 🎛️ 14种IoT设备 - 智能灯光、空调、窗帘、投影仪等设备控制
  • 🤖 AI语音控制 - 基于Google Gemini的自然语言指令解析
  • 👤 人脸识别认证 - DeepFace实现的安全用户身份验证
  • 🖐️ 手势识别控制 - MediaPipe实现的数字手势识别 (0-5)
  • � MQTT实时通信 - 设备状态实时同步
  • 🎨 个性化装修 - 自定义地板、墙面、投影画面贴图
  • 👀 视线交互 - 聚焦虚拟摄像头触发物理摄像头连接

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────────┐
│                         前端层 (React)                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  3D渲染引擎   │  │   UI组件     │  │  状态管理    │          │
│  │ Three.js     │  │ Interface    │  │ Zustand      │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                           ↓ ↓ ↓
┌─────────────────────────────────────────────────────────────────┐
│                        通信层                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  MQTT Broker │  │   REST API   │  │  WebSocket   │          │
│  │  Mosquitto   │  │ Django/Node-RED│  │  (可选)      │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                           ↓ ↓ ↓
┌─────────────────────────────────────────────────────────────────┐
│                        后端层                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Django API  │  │  IoT平台     │  │  AI服务      │          │
│  │ (人脸+手势)   │  │ ThingsBoard  │  │ Gemini AI    │          │
│  │  DeepFace/   │  │              │  │              │          │
│  │  MediaPipe   │  │              │  │              │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘

🛠️ 技术栈

前端技术

技术 版本 用途
React 19.2.3 UI框架
TypeScript 5.8.2 类型安全开发
Vite 6.2.0 现代化构建工具
Three.js 0.182.0 3D图形渲染引擎
@react-three/fiber 9.4.2 React的Three.js封装
@react-three/drei 10.7.7 3D辅助组件库
Zustand 5.0.9 轻量级状态管理
mqtt 5.14.1 MQTT通信客户端
lucide-react 0.562.0 图标库
axios 1.13.2 HTTP请求库
@google/genai 1.34.0 Google Gemini AI SDK

后端技术

服务 端口 用途
Django Backend 8000 AI识别服务 (DeepFace + MediaPipe)
Node-RED 1880 可视化流程编排 + 设备控制API
ThingsBoard 8080 企业级IoT平台
Mosquitto MQTT 1884/9001 消息队列 (TCP/WebSocket)
MySQL 3307 业务数据存储 (用户、预设)

AI & 机器学习

技术 用途
Google Gemini AI 自然语言解析智能家居指令
DeepFace 人脸检测、特征提取、用户验证
MediaPipe 手势识别 (21手部关键点)

📦 IoT设备清单

设备类型 数量 控制参数 位置
智能吸顶灯 1 亮度 (0-100%) 房间中央顶部
空调 1 温度 (16-30°C) 左墙
智能窗帘 1 开合程度 (0-100%) 右墙
升降桌 1 高度 (70-120cm) 房间中央
投影仪 1 开关状态 前墙顶部
空气净化器 1 开关 + 模式 左前角
加湿器 1 开关状态 左后角
扫地机器人 1 开关 + 路径模拟 随机移动
温湿度传感器 1 环境监测 左墙中部
摄像头 4 开关 + 实时画面 四角

🚀 快速开始

前置要求

  • Node.js >= 18.0.0
  • Docker & Docker Compose
  • Git

安装步骤

1. 克隆项目

git clone <repository-url>
cd 3dRoomV2

2. 启动Docker服务

# 启动所有后端服务 (Django, MySQL, Node-RED, ThingsBoard, Mosquitto)
docker-compose up -d

# 查看服务状态
docker-compose ps

3. 安装前端依赖

npm install

4. 配置环境变量

创建 .env 文件：

# Google Gemini API Key (从 https://aistudio.google.com/app/apikey 获取)
GEMINI_API_KEY=your_api_key_here

# MQTT配置
MQTT_BROKER_URL=ws://localhost:9001/mqtt
MQTT_USERNAME=
MQTT_PASSWORD=

# Node-RED API地址
NODE_RED_API_URL=http://localhost:1880

5. 启动开发服务器

npm run dev

访问: http://localhost:3000

📁 项目结构

3dRoomV2/
├── components/              # React组件
│   ├── Room.tsx            # 3D房间场景渲染
│   ├── Interface.tsx       # UI界面 (设备列表、聊天、装修)
│   ├── Controls.tsx        # 第一人称相机控制
│   └── AuthOverlay.tsx     # 用户认证覆盖层
├── services/               # 服务层
│   ├── api.ts             # REST API调用封装
│   ├── mqtt.ts            # MQTT客户端服务
│   └── geminiService.ts   # AI语音指令解析
├── django-backend/         # Django后端服务
│   ├── config/            # Django配置
│   ├── smartroom/         # 核心应用
│   │   ├── models.py      # 数据模型
│   │   ├── views.py       # API视图
│   │   └── services/      # AI服务封装
│   ├── Dockerfile         # Docker配置
│   └── requirements.txt    # Python依赖
├── docker-compose.yml     # Docker服务编排
├── mosquitto/             # MQTT Broker配置
│   └── config/
│       └── mosquitto.conf # MQTT配置文件
├── mysql/                 # 数据库初始化脚本
│   └── init.sql
├── nodered-data/          # Node-RED流程数据
│   ├── flows.json         # Node-RED流程定义
│   └── ...
├── App.tsx                # 应用入口
├── index.tsx              # React DOM挂载
├── store.ts               # Zustand全局状态
├── types.ts               # TypeScript类型定义
├── package.json           # 项目依赖
├── tsconfig.json          # TypeScript配置
├── vite.config.ts         # Vite构建配置
├── metadata.json          # 项目元数据
└── README.md              # 项目文档

🎯 功能使用指南

3D漫游控制

  • W/A/S/D - 前后左右移动
  • 鼠标移动 - 转向
  • ESC - 退出锁定模式

IoT设备控制

  1. 点击设备面板中的开关按钮控制设备启停
  2. 滑动滑块调节设备参数 (亮度、温度等)
  3. 使用AI语音指令批量控制设备

AI语音控制

点击麦克风图标，说出自然语言指令：

  • "打开灯光"
  • "把空调调到24度"
  • "打开所有设备"
  • "关闭窗帘和投影仪"

系统会自动解析指令并批量更新设备状态。

人脸识别认证

  1. 首次使用时点击"注册用户"
  2. 允许摄像头权限
  3. 输入用户名并拍照注册
  4. 之后可通过人脸识别快速登录

预设功能

通过人脸+手势组合创建和识别预设：

  1. 创建预设:

    • 点击"创建预设"按钮
    • 设置好设备状态后，输入预设名称
    • 拍摄人脸和手势照片
    • 保存预设配置

  2. 识别预设:

    • 点击"识别预设"按钮
    • 同时拍摄人脸和手势
    • 系统自动识别并应用对应的设备配置

手势识别

系统通过 MediaPipe 识别手部关键点，并计算伸展的手指数量，将其映射为数字 0-5。用户可以将特定的手势数字与设备状态预设绑定，通过手势快速切换场景。

  • 0 (握拳)
  • 1 (伸出 1 根手指)
  • 2 (伸出 2 根手指)
  • 3 (伸出 3 根手指)
  • 4 (伸出 4 根手指)
  • 5 (张开手掌)

个性化装修

  1. 点击"装修模式"按钮
  2. 选择要自定义的区域 (地板、墙面、桌面、投影画面)
  3. 上传自定义图片作为纹理贴图

🔌 API文档

设备管理

获取设备列表

GET http://localhost:1880/api/v1/devices

响应:

{
  "devices": [
    {
      "id": "light-main",
      "name": "智能吸顶灯",
      "type": "LIGHT",
      "status": true,
      "value": 80,
      "position": [0, 2.9, 0]
    }
  ]
}

切换设备状态

POST http://localhost:1880/api/v1/devices/{id}/toggle
Content-Type: application/json

{
  "status": true
}

更新设备参数

POST http://localhost:1880/api/v1/devices/{id}/value
Content-Type: application/json

{
  "value": 24
}

批量更新设备

POST http://localhost:1880/api/v1/devices/batch
Content-Type: application/json

{
  "updates": [
    { "id": "light-main", "status": true },
    { "id": "ac", "value": 24 }
  ]
}

用户认证 (Django API)

用户注册

POST http://localhost:8000/api/v1/auth/register
Content-Type: application/json

{
  "name": "张三",
  "face_image": "data:image/jpeg;base64,..."
}

响应:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "张三",
  "avatar_url": "data:image/jpeg;base64,...",
  "registered_at": "2026-01-05T10:00:00Z"
}

用户登录 (人脸识别)

POST http://localhost:8000/api/v1/auth/login
Content-Type: application/json

{
  "face_image": "data:image/jpeg;base64,..."
}

响应:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "张三",
  "avatar_url": "data:image/jpeg;base64,...",
  "confidence": 0.95
}

预设管理 (Django API)

创建预设

POST http://localhost:8000/api/v1/presets/create/
Content-Type: application/json

{
  "name": "工作模式",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "face_image": "data:image/jpeg;base64,...",
  "gesture_image": "data:image/jpeg;base64,...",
  "device_states": [
    {"device_id": "light-main", "status": true, "value": 80},
    {"device_id": "ac", "status": true, "value": 24}
  ],
  "gesture_digit": 0
}

响应:

{
  "id": "987fcdeb-51a2-43ed-a89c-1eb2e8c7c9f2",
  "name": "工作模式",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_name": "张三",
  "created_at": "2026-01-05T10:00:00Z",
  "gesture_digit": 5
}

识别预设

POST http://localhost:8000/api/v1/presets/recognize/
Content-Type: application/json

{
  "face_image": "data:image/jpeg;base64,...",
  "gesture_image": "data:image/jpeg;base64,..."
}

响应:

{
  "id": "987fcdeb-51a2-43ed-a89c-1eb2e8c7c9f2",
  "name": "工作模式",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_name": "张三",
  "device_states": [
    {"device_id": "light-main", "status": true, "value": 80},
    {"device_id": "ac", "status": true, "value": 24}
  ],
  "confidence": 0.92
}

Node-RED 设备管理

批量更新设备

POST http://localhost:1880/api/v1/devices/batch
Content-Type: application/json

{
  "updates": [
    { "id": "light-main", "status": true },
    { "id": "ac", "value": 24 }
  ]
}

MQTT Topics

Topic 用途
iot/room/devices 全局设备状态广播
iot/room/devices/{device_id} 单设备状态更新

Django API Health Check

GET http://localhost:8000/api/v1/health/

响应:

{
  "status": "healthy",
  "service": "SmartRoom Django Backend",
  "version": "1.0.0"
}

🔧 配置说明

Node-RED配置

访问 http://localhost:1880 导入流程配置：

# 导入文件
nodered-data/flows_final.json

ThingsBoard配置

访问 http://localhost:8080

默认账号:

  • 用户名: sysadmin@thingsboard.org
  • 密码: sysadmin

MQTT配置

配置文件: mosquitto/config/mosquitto.conf

listener 1883
listener 9001
protocol websockets
allow_anonymous true
persistence true
persistence_location /mosquitto/data/

🐳 Docker服务说明

ThingsBoard

企业级IoT平台，提供设备管理、数据存储和可视化功能。

# 查看日志
docker logs my-tb-platform

# 重启服务
docker-compose restart thingsboard

Node-RED

可视化流程编排工具，提供REST API和设备管理接口。

# 查看日志
docker logs my-node-red

# 备份流程
docker cp my-node-red:/data/flows.json ./backup/

Mosquitto

MQTT消息代理，负责设备状态实时通信。

# 查看日志
docker logs my-mqtt-broker

# 测试连接
mosquitto_sub -h localhost -p 1884 -t "iot/room/#"

📝 开发指南

添加新设备

  1. 在 store.ts 中的 devices 数组添加设备定义
  2. 在 components/Room.tsx 中添加设备3D模型
  3. 更新 types.ts 中的 DeviceType 枚举
  4. 在 Node-RED 中创建对应的设备控制流程

扩展AI指令

编辑 services/geminiService.ts:

const systemPrompt = `
你是一个智能家居助手。解析用户指令，返回JSON格式的设备更新数组。
支持的操作：开启、关闭、调节、设置等。
`;

自定义3D模型

在 components/Room.tsx 中使用 Three.js 创建自定义几何体：

<mesh position={[x, y, z]}>
  <boxGeometry args={[width, height, depth]} />
  <meshStandardMaterial color={color} />
</mesh>

🐛 故障排除

前端无法连接MQTT

问题: 设备状态无法实时同步

解决方案:

# 检查Mosquitto服务状态
docker logs my-mqtt-broker

# 确认WebSocket端口9001开放
netstat -an | grep 9001

# 检查浏览器控制台MQTT连接错误

Node-RED API返回404

问题: 设备控制请求失败

解决方案:

# 确认Node-RED流程已导入
docker exec my-node-red cat /data/flows.json

# 检查API端点配置
# 访问 http://localhost:1880 查看流程图

人脸识别失败

问题: 注册/识别返回错误

解决方案:

# 确认Django服务已启动
docker ps | grep django-backend

# 检查服务日志
docker logs smartroom-django-backend

# 检查DeepFace依赖
docker exec smartroom-django-backend pip list | grep deepface

# 健康检查
curl http://localhost:8000/api/v1/health/

3D场景黑屏

问题: 3D渲染区域显示黑色

解决方案:

  • 检查浏览器WebGL支持
  • 确认Three.js资源加载完成
  • 查看浏览器控制台错误信息

🤝 贡献指南

欢迎提交Issue和Pull Request！

开发流程

  1. Fork本仓库
  2. 创建特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启Pull Request

代码规范

  • 使用TypeScript类型注解
  • 遵循ESLint规则
  • 编写清晰的注释
  • 提交前运行 npm run build 确保无错误

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

👥 联系方式

  • 项目主页: [GitHub Repository]
  • 问题反馈: [GitHub Issues]
  • 技术讨论: [Discussions]

🙏 致谢

感谢以下开源项目的支持：

如果这个项目对你有帮助，请给一个 ⭐️ Star！

Made with ❤️ by VanDa

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages