基于 Three.js + FastAPI 的 3D Gaussian Splatting 点云拼接 Web 工具。支持多块点云导入、刚体变换摆位(移动/旋转/缩放)、合并导出 100% 密度 PLY、生成三视图 PNG、导出路径 JSON,以及独立点云裁剪,并可对接 gsplat 渲染出双目立体视觉图像对。
- 多块点云拼接,TransformControls 交互摆位
- 导出 100% 密度合并 PLY(3DGS 62 属性标准 schema)
- 自动生成三视图(俯视/正视/侧视/透视)PNG
- 折线/圆环路径元素 → 导出 JSON
- 独立点云裁剪工具(圆刷/框选,100% 密度导出)
- 双目立体视觉渲染(基于 gsplat,输出左右 RGB + 深度 + 视差)
- msgpack 二进制通信协议
- 零外网依赖:Three.js + msgpack 已 vendor 本地化
| 组件 | 场景 A(只跑后端) | 场景 B(完整渲染) |
|---|---|---|
| Python | 3.10+ | 3.10(conda env) |
| pip | ✓ | ✓(conda env 内) |
| NVIDIA GPU | 不需要 | Ada 架构及以上(RTX 40 系 / sm_89+) |
| CUDA Toolkit | 不需要 | 12.x(/usr/local/cuda) |
| Conda | 可选 | 必需 |
| 磁盘 | ~500 MB | ~10 GB(env + cache) |
5 分钟搞定,适合只想看拼接 / 剪辑 / 资产库功能的人。
git clone <repo-url> joint_web
cd joint_web
pip install -r requirements.txt
cp asset_lib.example.json asset_lib.json
# 编辑 asset_lib.json,把 asset_root 改成你的数据目录
cd ..
python -m joint_web.server --host 0.0.0.0 --port 8930注意:这种模式下点"渲染"按钮会报错(没装 torch/gsplat)。要渲染请走场景 B。
20 分钟搞定(主要时间在下载 torch wheel)。
git clone <repo-url> joint_web
cd joint_web
# 1. 建 conda env(含 torch 2.11.0+cu128 + gsplat + fastapi/uvicorn/numpy/scipy/matplotlib/msgpack/imageio)
# environment.yml 已用 --extra-index-url 直接装 cu128 torch,无需单独装
conda env create -f environment.yml
conda activate joint_web
# 2. 配置数据目录
cp asset_lib.example.json asset_lib.json
# 编辑 asset_lib.json,把 asset_root 改成你的数据目录
# 3. 启动服务
cd ..
conda activate joint_web # 确保激活
python -m joint_web.server --host 0.0.0.0 --port 8930第一次渲染会触发 gsplat JIT 编译 CUDA 算子(5-15 分钟),编译产物缓存在 ~/.cache/torch_extensions/,之后秒级复用。
完整部署细节见 docs/DEPLOYMENT.md。
| 变量 | 默认 | 说明 |
|---|---|---|
JOINT_WEB_SCAN_ROOT |
$(pwd) |
PLY 文件扫描根目录 |
JOINT_WEB_HOST |
0.0.0.0 |
服务监听地址 |
JOINT_WEB_PORT |
8930 |
服务监听端口 |
JOINT_WEB_GPU |
1 |
渲染用 GPU 编号 |
JOINT_WEB_RENDER_PYTHON |
sys.executable |
渲染子进程 python 路径(默认跟主服务同 env) |
JOINT_WEB_STATE_DB |
~/.cache/joint_web/render_state.db |
渲染任务状态库(SQLite);重启 joint_web 后可继续 poll/stop 旧渲染 |
JOINT_WEB_MAX_VISIBLE |
0 |
渲染每帧最多高斯数,0=按 VRAM 自动 cap((free_vram - 1 GiB) / 400 B);N>0 与 auto-cap 取较小者,防 OOM |
render_io 用 SQLite 单行表记录当前渲染任务(PID/output_dir/N 等)。子进程通过 start_new_session=True 脱离父进程会话,joint_web 重启/OOM 不会杀渲染,但重启后仍能:
/jw/scene/render/status继续 poll 进度(数output_dir/sample_*/left_rgb.png)/jw/scene/render/stop给旧 PID 发 SIGTERM/SIGKILL
启动时自动 recover():DB 中 running=1 但 PID 已死 → 标 returncode=-1, error='parent_restart_lost_proc'。跨实例并发防御:任何 joint_web 实例 start_render 都会先 db.is_active() 跨进程检查。
清理:直接 rm $JOINT_WEB_STATE_DB(无 active 任务时安全;有 active 时下次启动会被 recover 清理)。
# 方式 1:命令行参数
python -m joint_web.server --port 8940
# 方式 2:环境变量
JOINT_WEB_PORT=8940 bash run.sh
# 方式 3:run.sh 参数
bash run.sh 8940docker build -t joint-web .
docker run -p 8930:8930 -v /path/to/your/data:/data joint-web注意:Docker 镜像不含渲染(没有 GPU + CUDA + nerfstudio env)。要渲染必须宿主机直接跑 conda env 模式。
Three.js 0.160.0 + @msgpack/msgpack 3 已经 vendor 到 static/vendor/(进 git)。无 CDN 依赖,内网/离线都能跑。
如果要更新版本,跑:
bash scripts/fetch-vendor.sh(更新 scripts/fetch-vendor.sh 里的版本号后)
joint_web/
├── server.py # FastAPI 入口
├── api.py # REST API 路由
├── ply_io.py # 点云 I/O + 多块合并导出
├── ply_utils.py # PLY 底层工具
├── views.py # matplotlib 三视图渲染
├── asset_io.py # 资产库 I/O
├── render_io.py # 渲染子进程管理
├── render_state.py # 渲染状态 SQLite 持久化
├── render_scene.py # gsplat 渲染脚本(subprocess 调用)
├── sample_grass_stereo_gsplat.py # 渲染依赖(已 vendor)
├── render_gaussian_hard_stereo_once.py # 渲染依赖(已 vendor)
├── render_hard_depth_pose_subset.py # 渲染依赖(已 vendor)
├── assets/
│ └── noon_grass_4k.exr # 渲染 skybox(23 MB,已 vendor)
├── static/ # 前端(Three.js SPA)
│ ├── vendor/ # 前端三方库(本地化)
│ │ ├── three/ # three@0.160.0 + addons
│ │ └── msgpack/ # @msgpack/msgpack@3
│ ├── index.html # 首页
│ ├── joint.html # 拼接工具
│ ├── clip.html # 裁剪工具
│ ├── library.html # 资产库
│ ├── common.js # 跨页面共用 helper
│ ├── app.js / clip.js / library.js
│ └── *.css # 样式
├── docs/DEPLOYMENT.md # 完整部署文档
├── environment.yml # conda env 声明(场景 B 用)
├── install_torch.sh # torch cu128 单独装(场景 B 用)
├── scripts/fetch-vendor.sh # 前端 vendor 重新下载(开发用)
├── requirements.txt # 后端 PyPI 依赖(场景 A 用)
├── asset_lib.example.json # 资产库配置模板
├── Dockerfile # Docker(场景 A 用)
├── run.sh # 启动脚本
└── .env.example # 环境变量示例
Q: 导入点云后显示异常?
确保 PLY 文件包含 3DGS 标准属性(x, y, z, f_dc_02, opacity, scale_02, rot_0~3 等 62 个字段)。缺失字段可选择补零继续。
Q: 渲染按钮报错? 没建 conda env,或没装 torch。走场景 B 的步骤建 joint_web env。
Q: 第一次渲染很慢? gsplat JIT 编译 CUDA 算子,5-15 分钟,只发生一次。后续渲染秒级返回。
Q: 端口被占用?
python -m joint_web.server --port <其他空闲端口>。
Q: GPU 编号不对?
export JOINT_WEB_GPU=0(或其他)再启动服务。
Q: 内网无外网能用吗?
能。Three.js + msgpack 已 vendor 到 static/vendor/,零 CDN 依赖。但首次建 conda env 需要外网(下 torch 等)。
Q: 想用 nerfstudio env 而不是 joint_web env?
可以。export JOINT_WEB_RENDER_PYTHON=/opt/miniconda3/envs/nerfstudio/bin/python 后启动服务,主服务跑在任意 env,渲染子进程切到 nerfstudio env。