# 3d-director-desk

**Repository Path**: zbgit11/3d-director-desk

## Basic Information

- **Project Name**: 3d-director-desk
- **Description**: 浏览器端 3D 运镜与分镜导演台，支持人物、道具、轨迹点和动作时间轴
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-16
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3D 导演台

一个在浏览器中运行的 3D 运镜与分镜工具。你可以摆放人物、道具和生活模型，为人物或物体制作动作，再像玩第一人称游戏一样用 `WASD` 走镜头、记录轨迹点并预演成片。

- 在线体验：<https://xiaozangao.github.io/3d-director-desk/>
- 源代码：<https://github.com/xiaozangao/3d-director-desk>

![3D 导演台界面示例](docs/assets/readme/06.png)

## 主要功能

- 无需先放置机位，直接进入掌镜模式并用 `Enter` 连续记录轨迹点
- 每个轨迹点可独立跟踪不同的人物或物体，目标运动时镜头会继续跟随
- 轨迹点支持添加、插入、删除、排序、移动和批量调整位置
- 支持平滑/折线轨迹、匀速/柔和速度曲线，整段时长最长 30 秒
- 人物、道具和摄影机共用时间轴，可随时播放、暂停和拖动检查
- 内置电影慢推、人物跟拍、快速追拍、产品环绕等 6 套运镜参数
- 内置 UE4 风格人偶、基础几何体及 18 个生活模型，包括汽车、公交车、自行车、沙发、餐桌、冰箱和路灯等
- 人物支持 20 套静态姿势，以及行走、跑步、蹲起、跨步、跳跃、挥手 6 套可播放动作
- 支持本地导入 FBX、OBJ 模型，支持工程 JSON 导入和导出
- 支持多个独立导演台，数据按导演台保存在当前浏览器中
- 支持 iframe / `postMessage` 嵌入其他网页应用

## 群友贡献

- `AIGC 耀光`，抖音号：`AIJPDM001`：提供群友镜头预设构想与共创反馈。

## v0.3.0 更新（2026-07-18）

- 镜头与人物双轨时间轴支持直接拖动定位，当前时间显示更醒目。
- 人物路线点使用常亮双层圆圈，地面纹理大小可由用户直接输入。
- 每个镜头轨迹点可选择跟踪身体部位，并可单点或全线开启镜头防抖。
- 基础预设 8 个、群友预设 10 个；所有群友预设支持实时调整轨迹范围。
- 外部 FBX / GLB 人物支持骨架体检、动作分离导入和手动骨骼映射。
- 开源版模型库内置 Mixamo 兼容人物、37 个 GUO 绑骨人物与动物，以及配套道具素材。
- 新增自动、流畅、高清性能档位，提供标准性能基准与匿名报告导出。
- 二创接口可读取工程和时间轴，并请求当前帧、首尾帧和参考视频导出。

## 上一轮更新（2026-07-13）

### 人物路线

- 人物路线现在可以像摄影机轨迹一样直接编辑，支持添加、插入、删除和拖动路线点。
- 路线支持平滑曲线；人物会在行走过程中逐渐转向，不再停下来转完方向后再走。
- 人物路线可常亮显示，点击空白处也不会消失；路线点保持可见，方便直接继续编辑。
- 选中人物路线点时不会强制把人物和时间轴跳到该点，需要时可单独定位预览。

### 运镜与监看

- 摄影机轨迹点支持在任意两个点之间插入，也可以多选整段或任意几个轨迹点后整体移动。
- 新增可拖动实时监看小窗：看路线时监看最终成片，看成片时监看导演路线。
- 看成片时底部时间轴保持可用；暂停或拖动时间轴只改变时间，不会退出第一视角成片模式。
- “看成片 FOV”和“小窗 FOV”已经分开，互不影响；参考视频导出使用看成片 FOV。
- 跟踪目标会读取人物运动后的实时位置，每个摄影机轨迹点仍可单独选择跟踪对象。

### 防穿模、导出与编辑体验

- 场景面板新增“路径碰撞”开关。开启后人物会贴地，人物路线和摄影机轨迹会避开场景物体；关闭后允许自由穿过。
- 新增 H.264 MP4 参考视频导出，支持 720p / 1080p 和 24 / 30 / 60 FPS。
- 优化 `Ctrl / Cmd + Z` 撤销逻辑，连续拖动会作为一次操作撤销。
- XYZ 移动控件只保留三轴箭头，去掉容易误操作的三个平面控制块。

## 运行要求

- Windows 10/11 或 macOS
- [Node.js 20 或更高版本](https://nodejs.org/)
- Chrome、Edge 或其他现代桌面浏览器

安装 Node.js 后，在终端运行 `node -v` 和 `npm -v`，能显示版本号就说明环境已准备好。

## 命令行启动

Windows 和 macOS 使用同一套命令。先下载项目：

```bash
git clone https://github.com/xiaozangao/3d-director-desk.git
cd 3d-director-desk
```

第一次运行需要安装依赖：

```bash
npm install
```

以后每次启动只需要：

```bash
npm run dev -- --host 127.0.0.1 --port 5173
```

浏览器打开：

```text
http://127.0.0.1:5173/
```

终端需要保持开启。停止导演台时，在终端按 `Ctrl + C`。

### 不输入命令直接启动

- macOS：双击 `启动导演台.command`
- Windows：双击 `启动导演台.bat`

脚本会在首次运行时自动安装依赖，然后启动服务并打开浏览器。macOS 首次双击如果被系统拦截，请在访达中右键文件，选择“打开”。

## 3 分钟上手

### 1. 建立场景

1. 从左侧场景树选择已有角色，或从工具栏添加人物、道具和生活模型。
2. 选中物体后，用三轴操纵器移动、旋转或缩放。
3. 普通导演视角也支持 `WASD` 移动画面，鼠标拖动观察场景。

### 2. 记录运镜轨迹

1. 点击顶部“运镜”，再点击“开始掌镜”。
2. 鼠标会被锁定，移动鼠标控制视角；按 `Esc` 可释放鼠标并退出掌镜。
3. 调整到第一个想要的画面，按 `Enter` 保存轨迹点 1。
4. 继续移动和转向，每到一个画面按一次 `Enter`，即可保存轨迹点 2、3、4……
5. 退出后点击“看路线”从导演视角检查运动方向，或点击“看成片”查看最终镜头。

掌镜模式快捷键：

| 操作 | 按键 |
| --- | --- |
| 前进 / 后退 | `W` / `S` |
| 左移 / 右移 | `A` / `D` |
| 上升 / 下降 | `E` / `Q` |
| 播放 / 暂停人物动作 | `Space` |
| 锁定 / 取消跟踪准星目标 | `F` |
| 保存或更新轨迹点 | `Enter` |
| 退出掌镜 | `Esc` |
| 调整镜头远近（FOV） | 鼠标滚轮 |

准星对准人物或道具后按 `F`，镜头会锁定目标。锁定后用 `A` / `D` 环绕目标，用 `W` / `S` 靠近或远离目标。

### 3. 编辑轨迹点

- 点击编号选择轨迹点，再进入该点调整位置和朝向。
- 使用“插入轨迹点”可在两个点中间补一个镜头。
- 可删除或调整轨迹点顺序；播放时当前编号会高亮。
- 多选轨迹点后可整体移动，适合把整段 `1-6` 或任意几个点一起挪到新位置。
- 每个轨迹点都能单独选择跟踪目标，因此同一条路线可以先拍角色 1，再切换跟踪角色 2。
- “运镜预设”可快速套用常见时长、轨迹形状和速度曲线，也可自行修改。
- 在“看成片”模式中可直接暂停或拖动底部时间轴，调整完成后继续播放，不会退出当前视角。
- 监看小窗底部有两条独立 FOV：`看成片`控制主画面和导出，`小窗`只控制监看窗口。

### 4. 让人物和物体运动

1. 选中一个人物或道具。
2. 把底部时间轴拖到起始时刻，摆好位置，点击“记录此刻位置”。
3. 把时间轴拖到另一个时刻，移动或旋转物体，再次记录位置。
4. 点击底部播放按钮，人物、物体和镜头会沿同一条时间轴运动。
5. 在掌镜模式中按空格可随时播放或暂停人物动作，方便一边跟拍一边定镜头。

人物路线的推荐操作：选中人物后打开右侧“路线”页，添加或插入路线点，再直接拖动 XYZ 三轴箭头调整。打开工具栏中的“显示人物路线”后，切换到其他对象时路线也会保持显示。

## 路径防穿模

在右侧“3D 场景 → 开关项”中打开“路径碰撞”：

- 人物会自动站在设置的地面高度上。
- 人物移动路线和实际播放会避开场景中的道具或场景物体。
- 摄影机路线、第一视角预演和参考视频导出会使用同一套防穿模结果。
- 需要穿墙、穿门或制作特殊镜头时，关闭开关即可恢复原始路线。

当前版本使用轻量包围盒进行实时防穿模，适合导演台预演；形状特别复杂的导入模型可能会保留少量安全间距。

## 导出参考视频

1. 至少记录两个摄影机轨迹点。
2. 点击“运镜 → 导出”。
3. 选择 720p / 1080p 和 24 / 30 / 60 FPS。
4. 点击“导出 MP4”，等待浏览器完成录制并下载。

导出内容是干净的第一视角画面，不包含操作界面、轨迹线和轨迹点。导出画幅跟随当前画幅设置，FOV 使用“看成片 FOV”。

## 灵敏度设置

打开视口中的设置按钮，可以分别调整：

- 鼠标或触控板转动视角的灵敏度
- 滚轮或触控板缩放的灵敏度
- `WASD` 移动速度

设置会保存在当前浏览器，下次打开仍会使用上次的数值。

## 数据保存和备份

导演台工程默认保存在浏览器的 `localStorage` 中，不会上传到服务器。请注意：

- 换电脑、换浏览器、使用无痕模式或清理网站数据后，原工程不会自动出现。
- 本地地址和 GitHub Pages 在线地址属于两个独立站点，数据不会自动同步。
- 重要工程请使用“导出工程 JSON”定期备份，再通过“导入工程 JSON”恢复。
- 本地导入的模型仅在当前浏览器会话中使用，公开仓库不会包含你的私人模型文件。
- 开发者本机可安装额外人物和道具素材包；素材目录为 `public/local-assets/`，已被 Git 忽略。未安装时，在线版会自动隐藏对应分类，不影响内置模型与动作系统。

## 测试和生产构建

运行全部自动化测试：

```bash
npm test
```

生成生产文件：

```bash
npm run build
```

在本机预览生产版本：

```bash
npm run preview
```

## 部署在线体验

本项目是纯前端应用，不需要购买服务器，可以免费部署到 GitHub Pages。仓库已经包含 `.github/workflows/pages.yml`，推送到 `main` 分支后会自动测试、构建和发布。

1. 在 GitHub 新建一个公开仓库，不要勾选自动创建 README。
2. 在项目目录中初始化并推送代码：

```bash
git init
git add .
git commit -m "首次开源发布"
git branch -M main
git remote add origin https://github.com/YOUR_GITHUB_NAME/3d-director-desk.git
git push -u origin main
```

3. 打开 GitHub 仓库的 `Settings > Pages`。
4. 在 `Build and deployment` 的 `Source` 中选择 `GitHub Actions`。
5. 打开仓库的 `Actions` 页面，等待“测试并部署 GitHub Pages”显示绿色成功标记。
6. 回到 `Settings > Pages` 查看在线地址，通常格式为：

```text
https://YOUR_GITHUB_NAME.github.io/3d-director-desk/
```

以后只需把修改推送到 `main`，在线体验会自动更新。由于 GitHub Pages 必须使用 HTTPS，建议只从正式 Pages 地址分享，不要分享 Actions 中的临时构建链接。

## iframe 嵌入

项目可作为独立页面嵌入其他网页。通过 `instanceId` 隔离工程，通过 `hostOrigin` 指定宿主来源：

```html
<iframe
  src="https://xiaozangao.github.io/3d-director-desk/?instanceId=node_123&theme=dark&hostOrigin=https%3A%2F%2Fexample.com"
></iframe>
```

二创接口支持读取能力、工程 JSON 和当前时间轴，不需要绑定 ComfyUI 或某一种 LLM。完整消息格式、版本迁移规则和本地素材边界见 [`docs/embed-contract.md`](docs/embed-contract.md)。

消息格式和 React 示例见 `docs/embed-contract.md` 与 `examples/infinite-canvas-embed.tsx`。

## 参与开发

1. 从 `main` 创建功能分支。
2. 修改后运行 `npm test` 和 `npm run build`。
3. 提交 Pull Request，并说明改动内容、验证方式和界面变化。
4. 不要提交 `node_modules`、`dist`、浏览器本地工程、私人模型、密钥或令牌。

发现安全问题时，请通过仓库维护者提供的私密联系方式报告，不要在公开 Issue 中附带可直接利用的敏感数据。

## 开源许可证与来源

本项目使用 [MIT License](LICENSE)。项目基于以下 MIT 开源项目继续开发：

- 上游仓库：<https://github.com/jiguang132/storyai-3d-director-desk>
- 初始同步提交：`8c8bd36`
- 详细改造说明：[UPSTREAM.md](docs/UPSTREAM.md)

运行时依赖 React、Three.js、React Three Fiber、Drei、Zustand、Lucide 等开源软件，各依赖的具体版本与许可证以 `package-lock.json` 及对应上游项目为准。生活模型由代码中的基础几何体生成。UE 人偶模型来源及许可证见 `public/models/ue-mannequin-retopology.license.txt`，发布或再分发时请同时保留该说明文件。