Touka404x/cineforge-previz

# CineForge 白模预演 CineForge 是一款面向导演、分镜师、动画师和内容创作者的桌面端 3D 预演工具。它把场景搭建、人物走位、镜头设计、关键帧动画和视频交付集中到一个工作区中，适合在实拍、动画或短视频制作前快速验证构图、调度和镜头节奏。  ## 项目简介 传统分镜擅长表达画面，但不容易直观看出空间关系、镜头运动和时长。CineForge 使用可快速摆放的白模人物、基础几何体和模型库建立三维场景，再通过虚拟相机、时间线和预制运镜生成连续预演结果。 典型工作流程： 1. 在 **布景模式** 中添加人物、建筑、道路、家具、载具和自然物件。 2. 调整物体的位置、旋转、缩放、颜色、名称、分组和可见性。 3. 切换到 **拍摄模式**，设计画幅、焦距、视角和环境光照。 4. 为相机和物体记录关键帧，或直接套用预制运镜。 5. 使用多段落时间线检查镜头衔接、动作和节奏。 6. 保存 JSON 工程，导出 PNG 静帧或 H.264 MP4 视频。 ## 核心功能 | 模块 | 能力 | | --- | --- | | 场景搭建 | 5 类白模人物、基础几何体、群众阵列和 385 个分类模型 | | 物体编辑 | 选择、多选、框选、复制、删除、分组、重命名、显隐和自定义颜色 | | 变换工具 | 三轴移动、旋转环、统一/独立缩放、吸附和快捷旋转 | | 人物系统 | 26 套姿势预设，支持姿势随物体关键帧变化 | | 虚拟相机 | 自由飞行、透视/二点透视/正交视图、焦距和画幅控制 | | 镜头设计 | 48 套预制运镜，覆盖推进、摇镜、变焦、环绕、跟随、高空和叙事镜头 | | 时间线 | 多段落、相机轨道、物体轨道、播放头、循环、逐段连播和时长调整 | | 动画 | 相机关键帧、物体关键帧、自动机位点、手持抖动和插值播放 | | 环境 | 白天、黄昏、夜晚、阴天和太阳方位调整 | | 项目管理 | 新建、打开、保存、另存为和 JSON 版本兼容读取 | | 输出 | 当前画面 PNG、当前段落 MP4，支持 24/25/30/60 FPS | ## 快速开始 ### Windows 运行包 1. 打开仓库的 [Releases](../../releases/latest) 页面。 2. 下载 `CineForge-v0.9.3-Windows.zip`。 3. 完整解压 ZIP，不要直接在压缩包内运行。 4. 双击 `START.bat`。 运行包已经包含应用程序、项目源码和 FFmpeg 编码器。Windows SmartScreen 可能因为程序没有数字签名而显示“未知发布者”。 ### 从源码运行 准备环境： - Godot Engine `4.7.0` - Windows 10/11 x64 - FFmpeg，仅在导出 MP4 时需要 运行步骤： 1. 克隆仓库。 2. 将 `ffmpeg.exe` 放在仓库根目录。 3. 双击 `RUN_SOURCE.bat`，或用 Godot 打开 `source/project.godot`。 4. 在 Godot 中运行主场景。 git clone https://github.com/Touka404x/cineforge-previz.git cd cineforge-previz .\RUN_SOURCE.bat ## 使用方法 ### 1. 搭建场景 进入“布景”，从右侧素材库选择几何体、人物或模型。模型库分为载具、商业建筑、住宅、道路、中世纪、家具和自然七类，并支持关键字搜索。 选中物体后可在属性面板修改名称、位置、旋转、缩放、颜色和人物姿势。`Ctrl` 多选后可以整体分组，适合处理群众、建筑群或成套道具。 ### 2. 设计镜头 进入“拍摄”，先调整相机到需要的构图，再选择以下任一方式： - **预制镜头**：选中主体，点击镜头卡片预览并套用到当前段落。 - **自动轨道**：移动相机后按 `K` 记录机位点，系统按顺序生成运动。 - **手动轨道**：在播放头位置记录相机帧和物体帧，精确控制动画。 段落可以新建、复制、删除、重命名和拖动排序。按空格可从当前段落连续播放到最后。 ### 3. 保存与输出 - 工程文件：JSON，保存场景对象、段落、关键帧、机位点、环境和输出设置。 - 静帧：PNG，不包含编辑器界面。 - 视频：Godot 先逐帧写入临时 AVI，再由 FFmpeg 编码为 H.264 MP4。 - 视频规格：1920x1080、`yuv420p`、CRF 18、Web 快速起播元数据。 ## 常用操作 | 操作 | 快捷方式 | | --- | --- | | 相机移动 | `W/A/S/D`，`Q/E` 升降，`Shift` 加速 | | 转动视角 | 按住鼠标右键拖动 | | 选择/拖动物体 | 鼠标左键 | | 多选/框选 | `Ctrl + 单击` / `Ctrl + 空白处拖动` | | 复制/删除 | `Ctrl+C` / `Delete` | | 分组/解组 | `Ctrl+G` / `Ctrl+Shift+G` | | 撤销 | `Ctrl+Z` | | 相机关键帧 | `K` | | 物体关键帧 | `J` | | 播放/暂停 | `Space` | | 回到段落起点 | `Home` | | 保存工程 | `Ctrl+S` | | 透视/二点透视 | `5` / `2` | | 顶视图/前视图/右视图 | `7` / `1` / `3` | ## 使用的语言与技术 | 语言或技术 | 用途 | | --- | --- | | **GDScript** | 主要业务语言；负责 UI、3D 场景、相机、时间线、关键帧、项目文件和导出流程 | | **Godot Scene / Project Format** | `project.godot` 与 `main.tscn` 描述项目配置和入口场景 | | **Godot Shader Language** | 画面运动模糊等实时视觉效果 | | **JSON** | 模型索引、用户工程和本地设置的数据格式 | | **Python** | 仓库完整性、敏感信息、资源数量和网络原语检查 | | **Windows Batch** | 一键启动运行包、打开源码工程和校验发布文件 | | **FFmpeg CLI** | 将本地渲染结果编码为 H.264 MP4 | 运行时基于 Godot 4.7 Forward+ 渲染器，3D 素材采用 GLB/glTF，图片资源采用 PNG。 ## 项目架构 main.gd |-- SceneManager 场景对象、选择、分组、序列化 |-- FlyCamera 相机输入、投影与镜头姿态 |-- TimelinePanel 时间线、轨道、关键帧和播放头 |-- TranslateGizmo 移动轴、旋转环与命中测试 |-- FigureLib 白模人物、身体类型和姿势库 |-- ExportManager Godot 逐帧渲染与 FFmpeg 编码 |-- UITheme 主题、字体和控件样式 `-- FrameOverlay 画幅边界与安全框 完整模块关系和数据流见 [架构文档](docs/ARCHITECTURE.md)。 ## 目录结构 . |-- source/ | |-- scripts/ GDScript 业务模块 | |-- models/ 385 个 GLB 模型 | |-- thumbs/ 模型缩略图 | |-- previews/ 运镜预览图 | |-- fonts/ UI 字体 | |-- models_index.json 模型分类与索引 | |-- main.tscn 主场景 | `-- project.godot Godot 项目配置 |-- docs/ 架构、网络与安全文档 |-- third_party/ 第三方构建信息和许可证 |-- tools/project_audit.py 项目自动检查 |-- .github/ CI、Issue 与 PR 模板 `-- RUN_SOURCE.bat 源码启动入口 ## 开发与验证 提交代码前运行： python tools/project_audit.py 检查内容包括必需文件、脚本/模型/图片数量、JSON 有效性、敏感信息、绝对路径、网络 API 和不应进入 Git 的二进制发布物。GitHub Actions 会在每次推送和 Pull Request 中执行同一套检查。 贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md)，安全问题请按 [SECURITY.md](SECURITY.md) 私下报告。 ## 许可证 业务代码按 [GNU GPL v3](LICENSE) 提供。Godot Engine、FFmpeg、MiSans、模型和图片使用各自的许可条款；再分发前请阅读 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

标签：3D预演, Godot, Homebrew安装, 关键帧动画, 分镜工具, 场景调度, 影视动画, 虚拟拍摄, 逆向工具