Files

LKH 3b053c714c init

all

视频

视频

视频

视频

视频

init

2026-07-29 09:17:00 +08:00

7.6 KiB

Raw Blame History

3D导演台

一个基于 React、Vite、Three.js 和 React Three Fiber 的 3D 分镜导演台。它适用于轻量级预演、镜头规划和场景摆位，支持在浏览器里搭建角色、机位、场景和全景背景，并通过关键帧动画让人物与镜头动起来，还能一键把整段动画导出为视频。

功能概览

导演视角 / 机位视角切换
内置8种不同的人物，20种不同的人物姿势
角色、群演、基础几何体和机位快速添加
本地 FBX / OBJ 模型导入，可自定义模型库
群众阵列，想多少人就可以多少人
全景图导入与背景调节
机位拍摄、截图记录和基础镜头管理
视口比例框、九宫格、平移 / 旋转 / 缩放控制
关键帧动画：物体位移 / 旋转 / 缩放 + 镜头运镜（机位、注视点、视野 FOV）关键帧，旋转使用四元数 slerp 保证平滑过渡
时间轴：播放 / 暂停、指针拖动逐帧预览、时长调整、打帧 / 删除 / 清空
视频导出：上帝视角或机位视角，把整段动画录制成 WebM 视频
本地场景与关键帧状态持久化

界面截图

演示

机位视角下的关键帧运镜与时间轴 scrub 预览：

技术栈

React 18
Vite 6
TypeScript
Three.js
@react-three/fiber
@react-three/drei
Zustand
Vitest

项目结构

src
├─ app/layout          # 顶层壳布局，组织画布、左右侧栏与底部时间轴
├─ editor/canvas       # Three.js / R3F 视口、画幅框、工具条、截图视图、回放覆盖
├─ editor/panels       # 左侧对象树、右侧属性面板、底部时间轴
├─ editor/store        # Zustand 状态管理、撤销、剪贴板、关键帧 actions
├─ editor/io           # 截图导出、视频导出、工程导入导出、宿主通信
├─ editor/loaders      # 本地模型与全景图导入
├─ editor/runtime      # 角色渲染、骨骼、姿势应用、播放状态与回放驱动
├─ editor/schema       # 数据结构、机位、视口、时间轴与插值定义
└─ styles              # 全局样式

时间轴与视频导出相关的核心文件：

editor/schema/timeline.ts — 时间轴数据模型与纯函数（物体 / 相机关键帧的插值、增删改）
editor/runtime/playbackStore.ts — 播放状态（播放中、指针、时长、录制模式）
editor/runtime/PlaybackFrameDriver.tsx — useFrame 推进指针
editor/runtime/ActiveCameraPlaybackSync.tsx — 机位视角下用运镜轨道覆盖渲染相机
editor/canvas/PlaybackTransformSync.tsx — 按指针把物体 / 相机线框的插值结果覆盖到场景对象
editor/panels/TimelinePanel.tsx — 时间轴 UI（播放控制、关键帧编辑、视频导出按钮）
editor/io/videoExport.ts — MediaRecorder 录制 canvas → WebM

本地开发

npm install
npm run dev

默认开发地址通常为：

http://127.0.0.1:5173/

如果本机端口被占用，Vite 会自动顺延到下一个可用端口。

需要局域网访问（手机或其他设备）时：

npm run dev -- --host

Windows 提示：

vite.config 已处理中文路径下 server.fs.allow 的盘符解析问题（避免 403 Restricted）。

若 npm install 报 @rollup/rollup-darwin-arm64 平台不匹配，用 npm install --force 跳过——该包是 macOS 专用，Windows 不需要，rollup 会自动装载对应平台的二进制。

预览生产包：

npm run preview

默认预览地址通常为：

http://127.0.0.1:4173/

常用操作

顶部可切换 导演视角 与 机位视角
左侧用于搜索、选择、分组查看场景对象，并支持可见性 / 锁定 / 删除
中央视口用于摆放场景、切换变换模式、添加角色和机位、导入资源与截图
右侧属性面板会根据当前选中对象自动切换为场景 / 角色 / 模型 / 摄像机编辑面板；选中摄像机时可直接编辑位置 / 注视坐标 / FOV
底部时间轴：
- 选中对象或相机 → 用 gizmo 或右侧面板摆好状态 → 指针移到某时刻 → 点「在指针处打关键帧」
- 拖动指针可逐帧预览所有对象在该时刻的姿态
- 点关键帧方块可选中（变橙）以便更新 / 删除；方块右上角的 × 可直接删除单帧
- 「清空全部」一键清除所有关键帧（可撤销）
- 「导出视频·上帝视角 / 机位视角」录制整段动画为 WebM

快捷键

Ctrl/Cmd + C：复制当前选中对象
Ctrl/Cmd + V：粘贴复制对象
Ctrl/Cmd + Z：撤销最近一次操作
Delete / Backspace：删除当前选中对象

关键帧与视频导出说明

物体关键帧：记录位移 / 旋转 / 缩放，位移与缩放帧间线性插值，旋转使用四元数球面插值（slerp），确保转身等动作沿最短路径平滑过渡。
镜头运镜关键帧：记录机位位置、注视点 target、视野 FOV；仅 manual（手动坐标）相机支持打运镜关键帧，锁定物体的相机（targetMode = object）不支持。
编辑与预览：暂停态下用 gizmo 或右侧属性面板编辑对象（被拖对象不会被回放覆盖）；拖指针 scrub 实时预览各时刻姿态（机位视角下镜头同步跟随）；点播放看连续动画。
视频导出：基于浏览器 MediaRecorder 录制 canvas 画面，优先 MP4（Chrome 120+ / Safari），不支持时回退 WebM（Chrome / Firefox）。导出范围 = 时间轴时长，从 0 播放到末尾自动下载。当前为 MVP：无音频、分辨率随画布尺寸。

数据与嵌入

当前场景、本地模型库与关键帧都会写入浏览器 localStorage
工程数据为 version: 2，含 timeline 字段（物体轨道 tracks + 相机运镜轨道 cameraTracks）；导入旧 v1 工程会自动迁移、补齐空时间轴
支持导出工程 JSON，也支持通过文件重新导入
支持“保存最近工程 / 恢复最近工程”
组件已包含宿主页面通信桥，适合嵌入到更大的创作工作台中

Electron 桌面版打包

项目支持打包为 Windows 桌面应用（Electron + NSIS 安装包）。

一键打包：

build-electron.bat

或手动分步执行：

npm install
npm run build
npx electron-builder --win

打包产物位于 release/ 目录：

故事AI导演工作台 Setup x.x.x.exe — NSIS 安装包（推荐分发）
win-unpacked/ — 免安装版，整个文件夹拷走即可运行

打包脚本已配置 npmmirror 镜像加速 Electron 和 electron-builder 二进制下载。

构建与测试

构建：

npm run build

测试：

npm test

最近一次核对结果：

npm run build 可通过
构建阶段会出现少量 Vite 警告：部分模型库缩略图 URL 会保留到运行时解析，同时主包体积超过默认 chunk 警告阈值
npm test 新增了关键帧动画与视频导出相关用例（时间轴插值、播放状态与录制模式、store 关键帧 actions、时间轴面板交互等）；剩余 8 个既有失败用例（模型库面板、视口画幅/轴向命中区、个别姿势预设、样式断言）保持不变，未引入回归

开源说明

本仓库以源码演示为主，适合继续扩展为更完整的 3D 导演工具。
当前版本保留内置角色能力，并支持通过界面导入本地模型与全景图。
若你基于本项目继续发布，请自行确认新增模型、贴图和场景素材的分发许可。

License

MIT

7.6 KiB Raw Blame History Unescape Escape