# Physics-MR-Lab-Development

**Repository Path**: henhenhahi/Physics-MR-Lab-Development

## Basic Information

- **Project Name**: Physics-MR-Lab-Development
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Physics MR Lab —— 混合现实物理光学实验平台

[![React](https://img.shields.io/badge/React-19.0-blue.svg)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
[![Three.js](https://img.shields.io/badge/Three.js-r183-black.svg)](https://threejs.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.128-green.svg)](https://fastapi.tiangolo.com/)
[![OpenCV](https://img.shields.io/badge/OpenCV-4.13-orange.svg)](https://opencv.org/)

**Physics MR Lab** 是一款针对高中物理光学实验设计的混合现实（MR）辅助教学与探究平台。平台结合**计算机视觉（OpenCV）**与**三维场景映射（Three.js）**技术，旨在帮助学生测量玻璃砖的折射率，并直观探索光的折射与全反射规律。

---

## 1. 项目背景与物理教学问题

在高中物理“测量玻璃砖的折射率”及“光的折射定律探究”实验中，传统教学模式通常面临以下挑战：
* **作图与读数误差大**：学生使用量角器手工画线、测量夹角时，主观性大，极易因插针偏差或作图粗细导致折射率测量失准。
* **物理模型抽象**：传统的折射实验完全限定在纸面（二维空间），学生难以建立光波在三维透明介质中传播的空间想象力。
* **教学互动受限**：当学生想要探究临界角（全反射）等临界状态时，物理器材难以迅速响应并给出实时反馈。

---

## 2. 项目目标

本项目的核心目标是构建一个**学术可信、虚实隔离、实时映射**的辅助教学环境：
* 提供计算机视觉算法，自动分析学生实验照片并输出折射率参考数据。
* 实现 SVG 画布与 3D 物理材质沙盒的实时同步映射，增强学生的三维空间认知。
* 作为一个标准的教育实验案例，提供完整的研究可复现性（Replicability）证据，用于 AI 教育场景的实证研究。

---

## 3. 主要功能与状态说明

* **自动图像分析 (Auto CV)**：上传真实激光折射照片，后端自动检测出**矩形玻璃砖**轮廓，提取入射与折射激光轨迹，并自动推导夹角。**注意：自动检测目前仅支持矩形，半圆及任意四边形需通过手动标注进行测量。**
* **2D 手动标注系统 (Manual Markup)**：作为自动分析的补足，支持在底图上直接拖拽编辑矩形、半圆、四边形及“法线-分界面”组合，角度随操作即时刷新。
* **3D 可视化配准空间 (3D View)**：将 2D 轮廓和射线等比例拉伸为 3D 实体模型，提供轨道控制器（OrbitControls）以及 Bloom 辉光光束视觉呈现。
* **教学动态仿真 (Teaching Mode)**：支持入射角滑块与高频连续取样模拟。用户滑动入射角，光路完全遵循折射定律动态计算偏折。当满足光密介质射向光疏介质且入射角大于临界角时，系统会计算并渲染**全反射 (TIR)** 现象。
* **实验历史与导出**：自动记录多次测量结果，支持数据筛选、预览及 JSON 文件导出。

---

## 4. 输入与输出

* **输入 (Input)**：
  * 真实实验静态照片（JPG, PNG）
  * 实验录像视频（MOV, MP4）（**注：当前视频仅支持在 2D 画布作为背景播放，尚未实现视频流的高频逐帧分析**）
  * 实时摄像头视频流（**注：当前仅支持调用摄像头画面做背景显示，不支持摄像头流的连续在线分析**）
  * 交互控制输入：入射角滑块数值、鼠标拖拽画布图元位置、折射率设定值。
* **输出 (Output)**：
  * **2D 渲染**：折射激光线段的 2D 可视化标记、几何角度环、法线标尺。
  * **3D 渲染**：三维玻璃砖材质实体、霓虹光晕效果呈现、**无量纲虚拟网格**与三维轴向导引线。
  * **实验报告**：包含入射角、折射角、测定折射率以及关联图片快照的 JSON 结构数据文件。

---

## 5. 技术架构

系统采用轻量化、松耦合的前后端分离模式：

```
+-------------------------------------------------------------+
|                     浏览器前端 (React Client)                |
|  +-------------------+  +------------------+  +----------+  |
|  | CenterCanvas(SVG) |  | ThreeDCanvas(3D) |  |  Panels  |  |
|  +---------+---------+  +--------^---------+  +----+-----+  |
|            | 2D 坐标              | 3D 空间投射            |     |
|            +----------------> App.tsx <------------+     |
+----------------------------------^--------------------------+
                                   | HTTP /api/analyze
+----------------------------------v--------------------------+
|                     后端算法服务 (FastAPI Server)            |
|  +--------------------+  +------------------+  +----------+  |
|  | OpenCV 轮廓定位算法 |  | HSV 激光提取算法  |  | 物理引擎 |  |
|  +--------------------+  +------------------+  +----------+  |
+-------------------------------------------------------------+
```

---

## 6. 本地安装与运行

### 6.1 环境准备
* Node.js v18.0+
* Python 3.10+

### 6.2 后端服务部署
```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
```

### 6.3 前端客户端运行
```bash
npm install
npm run dev
```
打开浏览器访问 `http://localhost:3000`。

---

## 7. 支持的设备

* **移动教学终端**：iPad Air / Pro (iOS 16+), 安卓平板电脑（推荐使用 Chrome 浏览器以获得最佳 WebGL 支持）。
* **桌面 PC**：Windows 10/11 & macOS，支持 Chrome, Edge, Safari。

---

## 8. 典型实验流程

1. **真实物理采集**：在方格纸上摆放玻璃砖，用红色激光笔射入，使用平板向下拍摄单帧照片。
2. **自动分析/手动标定**：将照片上传至系统，系统提取矩形玻璃轮廓与激光中心，计算入射角与折射角。若拍摄畸变较大或使用非矩形玻璃砖，可手动拖拽辅助工具将虚线与物理光路重合，进行几何标定。
3. **2D/3D 对照探究**：切换至“分屏对照”模式，学生在 3D 空间观察光线的折射立体路径。
4. **历史记录入库**：点击“记录数据”，多次测量后导出 JSON 实验报表。

---

## 9. 数据格式

系统导出的标准实验数据采用 JSON 格式，如下所示：

```json
[
  {
    "id": 1,
    "image": "blob:http://localhost:3000/ad6f-12e3...",
    "incidentAngle": 45.21,
    "refractedAngle": 28.13,
    "refractiveIndex": 1.51
  }
]
```

---

## 10. 物理量定义和单位

* **入射角 $i$ (Incident Angle)**：入射光线与介质分界面法线之间的夹角。单位：度（$^\circ$）。
* **折射角 $r$ (Refracted Angle)**：折射光线与介质分界面法线之间的夹角。单位：度（$^\circ$）。
* **介质折射率 $n$ (Refractive Index)**：光在真空中的传播速度与在介质中传播速度的比值。无量纲物理量。
* **坐标单位**：2D 画布端使用像素（px）和百分比（$0 \sim 1$），3D 空间使用**无量纲虚拟渲染单位**（经方格纸实物尺寸标定后，才可映射转换为实际的厘米或毫米）。

---

## 11. 与其他相关仓库的关系

* **前期的项目基础**：位于 `./前期的项目基础/` 目录下，保留了早期使用单 HTML 页面的原型设计与历史测试代码，用于项目的回溯和版本演变分析。
* **独立前/后端模式**：本项目集成了前端独立构建模块与 FastAPI 单文件路由服务，所有 OpenCV 代码均高度独立，便于将后端移植到更大型的云服务器上。

---

## 12. 已知局限性

* **透视敏感度高**：拍摄倾斜角偏大时，自动矩形识别算法由于直角形变判定失效。
* **视频分析限制**：视频与摄像头在此版本中仅支持背景渲染，无法进行连续逐帧图像分析与追踪。
* 详细技术限制请参阅 **[Known Limitations](docs/KNOWN_LIMITATIONS.md)**。

---

## 13. 当前版本状态与文档导航

当前稳定版本为 **v1.0.0**。

### 📚 学术与开发补档文档指南
* **[REAL_VS_SIMULATED.md](docs/REAL_VS_SIMULATED.md)**：数据来源等级定义（原始数据、检测结果、计算结果、模拟结果、标注结果）及虚实隔离原则。
* **[RESEARCH_DESIGN.md](docs/RESEARCH_DESIGN.md)**：高中物理教学实验的因变量、自变量及学术研究设计。
* **[VALIDATION_PROTOCOL.md](docs/VALIDATION_PROTOCOL.md)**：误差解算、空间可视化标定、对照试验及软硬件规格规范。
* **[DATA_DICTIONARY.md](docs/DATA_DICTIONARY.md)**：所有变量与数据库字段的数据字典映射。
* **[KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md)**：系统已知功能与精度的局限性归纳。
* **[MODULE_MAP.md](docs/MODULE_MAP.md)**：项目模块调用关系与数据流向设计（包含相对路径的源文件引用）。