Skip to content

About

一个用于处理点云裁剪和拼接的项目,可用于各种仿真场景。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

3DGS 点云拼接工具 / 3DGS Point Cloud Stitching Tool

基于 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)

场景 A:只跑后端 + 前端 UI(不渲染)

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

访问 http://localhost:8930/

注意:这种模式下点"渲染"按钮会报错(没装 torch/gsplat)。要渲染请走场景 B。


场景 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 8940

Docker 部署(只含后端)

docker 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。

About

一个用于处理点云裁剪和拼接的项目,可用于各种仿真场景。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages