# Rocky-scanner-ts

**Repository Path**: codekpy/rocky-scanner-ts

## Basic Information

- **Project Name**: Rocky-scanner-ts
- **Description**: 一个基于 TypeScript + React 的开源项目，通过边缘检测算法将实时摄像头画面转换为超声波扫描风格效果。灵感来源于安迪·威尔《挽救计划》（Project Hail Mary）中的外星伙伴 Rocky —— 他那标志性的超声波扫描感知方式和科幻仪器美学。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://rocky.cloudroo.top/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-02
- **Last Updated**: 2026-05-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Rocky Scanner 🔬

> 实时摄像头画面 → 超声波扫描风格可视化

一个基于 TypeScript + React 的开源项目，通过边缘检测算法将实时摄像头画面转换为超声波扫描风格效果。灵感来源于安迪·威尔《挽救计划》（Project Hail Mary）中的外星伙伴 Rocky —— 他那标志性的超声波扫描感知方式和科幻仪器美学。

![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)
![React](https://img.shields.io/badge/React-19+-61dafb.svg)
![Vite](https://img.shields.io/badge/Vite-7+-646cff.svg)

## ✨ 特性

- 🎥 **实时视频捕获** — 基于 WebRTC `getUserMedia` API 的摄像头实时流
- 🔍 **Sobel 边缘检测** — 标准 Sobel 算子实现，逐帧梯度计算
- 🎨 **科幻风格渲染** — 深蓝紫背景 + 青色扫描线动画
- 🎛️ **交互控制** — 阈值滑块、模式切换（3D深度/柔深度）
- 📦 **模块化设计** — 清晰的模块分离（camera / edge-detector / renderer）
- 🌍 **国内镜像友好** — 使用国内 npm 镜像源

## 📦 安装与运行

### 前置要求

- Node.js >= 20.19.0（推荐 22.x）
- npm >= 10.x

### 快速开始

```bash
# 1. 克隆仓库
git clone https://github.com/your-username/rocky-scanner-ts.git
cd rocky-scanner-ts

# 2. 安装依赖（已配置淘宝镜像源）
npm install

# 3. 启动开发服务器
npm run dev

# 4. 浏览器访问 http://localhost:5173
```

### 构建生产版本

```bash
npm run build
npm run preview
```

## 🏗️ 项目结构

```
rocky-scanner-ts/
├── src/
│   ├── modules/
│   │   ├── camera.ts          # 摄像头管理（WebRTC 封装）
│   │   ├── edge-detector.ts   # Sobel 边缘检测算法
│   │   └── renderer.ts        # Canvas 渲染与扫描线动画
│   ├── components/
│   │   ├── RockyScanner.tsx    # 主扫描组件
│   │   └── ControlPanel.tsx   # 控制面板组件
│   ├── App.tsx                # 主应用（状态管理）
│   ├── main.tsx               # 入口文件
│   ├── types.ts               # TypeScript 类型定义
│   └── index.css              # 全局科幻主题样式
├── index.html                 # HTML 入口
├── vite.config.ts             # Vite 配置
├── tsconfig.json              # TypeScript 配置
├── package.json               # 项目配置
└── LICENSE                    # Apache 2.0 许可证
```

## 🔬 核心原理

### 边缘检测逻辑

本项目使用 **Sobel 算子** 实现边缘检测，核心步骤如下：

#### 1. 梯度计算

Sobel 算子使用两个 3×3 卷积核分别计算水平和垂直方向的梯度：

**水平梯度核 (Gx)**：
```
[-1  0  1]
[-2  0  2]
[-1  0  1]
```

**垂直梯度核 (Gy)**：
```
[-1 -2 -1]
[ 0  0  0]
[ 1  2  1]
```

对每个像素的 3×3 邻域进行卷积，得到 Gx 和 Gy 值。

#### 2. 梯度幅度

```
G = sqrt(Gx² + Gy²)
```

梯度幅度越大，表示该位置越可能是边缘。

#### 3. 阈值处理

- **强对比模式**：超过阈值的像素以亮青色显示，其余为黑色（二值化）
- **柔和边缘模式**：使用 Sigmoid 函数平滑映射梯度值，产生渐变边缘效果

### 渲染管线

```
摄像头视频流
    ↓
离屏 Canvas 帧捕获 (ImageData)
    ↓
Sobel 边缘检测 (EdgeDetector.detect)
    ↓
Canvas 绘制边缘结果 (putImageData)
    ↓
叠加扫描线动画 (requestAnimationFrame)
    ↓
最终科幻风格画面
```

### 扫描线动画

- 周期：3 秒
- 方向：从底部到顶部
- 效果：渐变透明度 + 中心亮线
- 实现：`CanvasRenderingContext2D.createLinearGradient`

## 🎛️ 自定义配置

### 修改默认参数

编辑 `src/App.tsx` 中的初始状态：

```typescript
const [settings, setSettings] = useState<ScannerSettings>({
  threshold: 128,      // 边缘检测阈值 (0-255)
  mode: 'high-contrast', // 'high-contrast' | 'soft-edge'
});
```

### 调整视觉风格

编辑 `src/index.css` 可以修改：
- 背景颜色（`.app` 中的渐变）
- 轮廓颜色（搜索 `#00ffff` 替换）
- 扫描线颜色（`src/modules/renderer.ts` 中的 `SCANLINE_PERIOD` 和颜色值）
- 网格密度（`renderer.ts` 中的 `gridSize`）

### 修改摄像头参数

编辑 `src/modules/camera.ts` 的 `start()` 方法：

```typescript
this.stream = await navigator.mediaDevices.getUserMedia({
  video: {
    facingMode: 'environment', // 'user' 前置 / 'environment' 后置
    width: { ideal: 640 },     // 分辨率
    height: { ideal: 480 },
  },
  audio: false,
});
```

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

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

### 开发规范

- 使用 TypeScript 严格模式
- 组件使用函数式组件 + Hooks
- 模块职责单一，避免耦合
- 代码注释使用中文

## 📄 许可证

本项目采用 **Apache 2.0** 许可证。详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- 灵感来源：《挽救计划》（Project Hail Mary）Rocky 的超声波感知方式
- UI 组件库：[mdui](https://mdui.org/)
- 构建工具：[Vite](https://vitejs.dev/)