Skip to content
BranchesTags

Repository files navigation

SplatForge 🎨

Lightweight 3D Gaussian Splat Point Cloud Intelligent Editing Engine

PythonLicenseTestsVersion

简体中文 · 繁體中文 · English

🎉 项目介绍

SplatForge 是一款轻量级的3D高斯泼溅（3D Gaussian Splatting）点云智能编辑引擎，采用纯Python实现，零Node.js依赖。

💡 灵感来源

随着3D高斯泼溅技术在3D重建和NeRF领域的爆发式发展，社区急需一款轻量、易用、无需复杂环境配置的点云编辑工具。现有方案（如supersplat）依赖Node.js/TypeScript技术栈，对Python开发者不够友好。

🔥 自研差异化亮点

  • 纯Python实现 — 仅依赖NumPy，无需安装Node.js或任何JavaScript运行时
  • 双模式操作 — 支持命令行（CLI）和Web浏览器双模式
  • 智能质量分析 — 内置点云质量评分系统，自动检测数据问题并给出修复建议
  • 多格式支持 — 支持PLY、SPLAT、JSON三种格式的读写互转
  • 丰富的编辑操作 — 过滤、裁剪、变换、颜色调整、缩放、分割、合并等
  • 自动修复引擎 — 一键修复NaN值、非归一化四元数、越界值等常见问题

✨ 核心特性

特性描述
📂 多格式I/O支持PLY（ASCII/Binary）、SPLAT、JSON格式读写
🔍 智能过滤按透明度、缩放、空间范围、距离等多维度过滤
✂️ 空间操作裁剪、归一化、仿射变换、统计离群值移除
🎨 属性编辑亮度/对比度/饱和度调整、缩放倍率、统一颜色/缩放
🧩 分割合并网格分割、多点云合并、随机子采样
🩺 质量分析自动评分、问题检测、修复建议
🔧 自动修复NaN/Inf清除、四元数归一化、值域裁剪
🌐 Web界面浏览器内3D可视化与交互式编辑
⚡ 高性能NumPy向量化运算，高效处理大规模点云

🚀 快速开始

环境要求

  • Python 3.8 或更高版本
  • pip 包管理器

安装

# 克隆仓库
git clone https://github.com/gitstq/SplatForge.git
cd SplatForge
# 安装依赖
pip install -r requirements.txt
# （可选）安装Web界面支持
pip install flask
# （可选）安装开发依赖
pip install -r requirements-dev.txt

本地启动

# 命令行模式
python -m splatforge.cli --help
# 生成示例点云
python -m splatforge.cli sample output.ply --shape sphere --count 10000
# 查看点云信息
python -m splatforge.cli info output.ply
# 查看详细统计
python -m splatforge.cli stats output.ply
# 质量分析
python -m splatforge.cli quality output.ply
# 格式转换
python -m splatforge.cli convert input.ply output.splat
# 自动修复
python -m splatforge.cli repair input.ply output.ply
# 过滤操作
python -m splatforge.cli filter input.ply output.ply --min-alpha 0.1 --subsample 50000
# 启动Web界面
python -m splatforge.cli web 8080

📖 详细使用指南

CLI 命令参考

命令说明示例
info显示点云基本信息splatforge info scene.ply
convert格式转换splatforge convert scene.ply scene.json
stats详细统计信息splatforge stats scene.ply
quality质量分析splatforge quality scene.ply
repair自动修复splatforge repair input.ply output.ply
filter过滤操作splatforge filter in.ply out.ply --min-alpha 0.1
sample生成示例splatforge sample out.ply --shape cube --count 5000
webWeb界面splatforge web 5000

Python API 使用

fromsplatforge.coreimportSplatData, SplatIO, SplatEditorfromsplatforge.utilsimportcreate_sample_cloud# 生成示例数据data=create_sample_cloud(10000, shape='sphere')
# 保存为PLYSplatIO.write_ply(data, 'sphere.ply')
# 读取文件loaded=SplatIO.auto_read('sphere.ply')
# 过滤低透明度点云filtered=SplatEditor.filter_by_alpha(loaded, min_alpha=0.5)
# 归一化位置normalized=SplatEditor.normalize_position(filtered, mode='center')
# 调整颜色adjusted=SplatEditor.adjust_colors(normalized, brightness=1.2, saturation=1.5)
# 质量分析quality=SplatEditor.analyze_quality(adjusted)
print(f"质量评分: {quality['score']}/100")
# 自动修复repaired, repairs=SplatEditor.auto_repair(adjusted)
# 保存结果SplatIO.write_ply(repaired, 'output.ply')

Web 界面

启动Web界面后，在浏览器中打开 http://localhost:8080，支持：

  • 📁 拖拽上传PLY/SPLAT文件
  • 🎲 一键生成示例点云（球体/立方体/平面/随机）
  • 📊 实时点云信息与质量评分
  • 🎨 交互式3D可视化（鼠标拖拽旋转、滚轮缩放）
  • 🔧 透明度过滤、子采样、归一化、颜色/缩放调整
  • 📤 导出为PLY/SPLAT/JSON格式

💡 设计思路与迭代规划

设计理念

  • 轻量化优先 — 核心功能仅依赖NumPy，保持最小依赖
  • 双模式设计 — CLI适合自动化脚本，Web适合交互式探索
  • 数据安全 — 所有操作默认返回新对象，不修改原始数据

技术选型

组件选型原因
核心语言Python数据科学生态成熟，NumPy性能优异
数据存储NumPy数组向量化运算，内存高效
CLI框架argparsePython标准库，零额外依赖
Web框架Flask轻量灵活，API开发便捷

后续迭代计划

  • 🎥 Web界面集成Three.js实现GPU加速渲染
  • 📐 支持SH系数（球谐函数）的完整读写
  • 🔄 支持COLLADA/OBJ等更多3D格式
  • 📊 点云密度分析与可视化
  • 🔗 支持作为MCP Server供AI Agent调用
  • 📦 PyPI发布，支持pip install splatforge

📦 打包与部署

作为库使用

pip install -e .

运行测试

pip install pytest
pytest tests/ -v

Web部署

# 安装Flask
pip install flask
# 启动服务（默认端口5000）
python -m splatforge.cli web
# 指定端口
python -m splatforge.cli web 8080

兼容环境

环境支持状态
Linux (x86_64)✅ 完全支持
macOS (x86_64/ARM64)✅ 完全支持
Windows (x86_64)✅ 完全支持
Python 3.8+✅ 完全支持

🤝 贡献指南

欢迎社区贡献！请遵循以下规范：

  1. Fork 本仓库
  2. 创建特性分支：git checkout -b feature/your-feature
  3. 编写代码和测试
  4. 提交：git commit -m "feat: add your feature"
  5. 推送：git push origin feature/your-feature
  6. 创建 Pull Request

详细指南请参阅 CONTRIBUTING.md

📄 开源协议

本项目基于 MIT License 开源。

繁體中文

🎉 專案介紹

SplatForge 是一款輕量級的3D高斯潑濺（3D Gaussian Splatting）點雲智慧編輯引擎，採用純Python實現，零Node.js依賴。

💡 靈感來源

隨著3D高斯潑濺技術在3D重建和NeRF領域的爆發式發展，社區急需一款輕量、易用、無需複雜環境配置的點雲編輯工具。現有方案依賴Node.js/TypeScript技術棧，對Python開發者不夠友好。

🔥 自研差異化亮點

  • 純Python實現 — 僅依賴NumPy，無需安裝Node.js或任何JavaScript運行時
  • 雙模式操作 — 支援命令列（CLI）和Web瀏覽器雙模式
  • 智慧品質分析 — 內建點雲品質評分系統，自動檢測資料問題並給出修復建議
  • 多格式支援 — 支援PLY、SPLAT、JSON三種格式的讀寫互轉
  • 豐富的編輯操作 — 過濾、裁剪、變換、顏色調整、縮放、分割、合併等
  • 自動修復引擎 — 一鍵修復NaN值、非歸一化四元數、越界值等常見問題

✨ 核心特性

特性描述
📂 多格式I/O支援PLY（ASCII/Binary）、SPLAT、JSON格式讀寫
🔍 智慧過濾按透明度、縮放、空間範圍、距離等多維度過濾
✂️ 空間操作裁剪、歸一化、仿射變換、統計離群值移除
🎨 屬性編輯亮度/對比度/飽和度調整、縮放倍率、統一顏色/縮放
🧩 分割合併網格分割、多點雲合併、隨機子採樣
🩺 品質分析自動評分、問題檢測、修復建議
🔧 自動修復NaN/Inf清除、四元數歸一化、值域裁剪
🌐 Web介面瀏覽器內3D視覺化與互動式編輯
⚡ 高效能NumPy向量化運算，高效處理大規模點雲

🚀 快速開始

# 安裝依賴
pip install -r requirements.txt
# 生成範例點雲
python -m splatforge.cli sample output.ply --shape sphere --count 10000
# 查看點雲資訊
python -m splatforge.cli info output.ply
# 品質分析
python -m splatforge.cli quality output.ply
# 格式轉換
python -m splatforge.cli convert input.ply output.splat
# 啟動Web介面
python -m splatforge.cli web 8080

📖 詳細使用指南

fromsplatforge.coreimportSplatData, SplatIO, SplatEditorfromsplatforge.utilsimportcreate_sample_cloud# 生成範例資料data=create_sample_cloud(10000, shape='sphere')
# 讀取檔案loaded=SplatIO.auto_read('scene.ply')
# 過濾低透明度點雲filtered=SplatEditor.filter_by_alpha(loaded, min_alpha=0.5)
# 歸一化位置normalized=SplatEditor.normalize_position(filtered, mode='center')
# 品質分析quality=SplatEditor.analyze_quality(normalized)
print(f"品質評分: {quality['score']}/100")
# 自動修復repaired, repairs=SplatEditor.auto_repair(normalized)
# 儲存結果SplatIO.write_ply(repaired, 'output.ply')

📦 打包與部署

# 安裝為庫
pip install -e .# 執行測試
pytest tests/ -v
# 啟動Web服務
python -m splatforge.cli web 8080

🤝 貢獻指南

歡迎社區貢獻！請參閱 CONTRIBUTING.md

📄 開源協議

本專案基於 MIT License 開源。

English

🎉 About

SplatForge is a lightweight 3D Gaussian Splat point cloud intelligent editing engine built with pure Python and zero Node.js dependency.

💡 Inspiration

With the explosive growth of 3D Gaussian Splatting in 3D reconstruction and NeRF fields, the community urgently needs a lightweight, easy-to-use point cloud editing tool that doesn't require complex environment setup. Existing solutions (like supersplat) depend on Node.js/TypeScript, which isn't ideal for Python developers.

🔥 Differentiation Highlights

  • Pure Python — Only depends on NumPy, no Node.js or JavaScript runtime needed
  • Dual Mode — Full CLI and Web browser interface support
  • Smart Quality Analysis — Built-in scoring system with automatic issue detection and repair suggestions
  • Multi-Format Support — Read/write PLY, SPLAT, and JSON formats
  • Rich Editing Operations — Filtering, cropping, transformation, color adjustment, splitting, merging, and more
  • Auto-Repair Engine — One-click fix for NaN values, unnormalized quaternions, out-of-range values

✨ Core Features

FeatureDescription
📂 Multi-Format I/OPLY (ASCII/Binary), SPLAT, JSON read/write
🔍 Smart FilteringFilter by alpha, scale, bounding box, distance
✂️ Spatial OpsCrop, normalize, affine transform, outlier removal
🎨 Attribute EditBrightness/contrast/saturation, scale, uniform color
🧩 Split & MergeGrid splitting, multi-cloud merging, random subsampling
🩺 Quality AnalysisAuto scoring, issue detection, repair suggestions
🔧 Auto RepairNaN/Inf removal, quaternion normalization, value clamping
🌐 Web InterfaceIn-browser 3D visualization and interactive editing
⚡ High PerformanceNumPy vectorized operations for large-scale point clouds

🚀 Quick Start

# Install dependencies
pip install -r requirements.txt
# Generate sample point cloud
python -m splatforge.cli sample output.ply --shape sphere --count 10000
# View point cloud info
python -m splatforge.cli info output.ply
# Quality analysis
python -m splatforge.cli quality output.ply
# Format conversion
python -m splatforge.cli convert input.ply output.splat
# Start web interface
python -m splatforge.cli web 8080

📖 Usage Guide

fromsplatforge.coreimportSplatData, SplatIO, SplatEditorfromsplatforge.utilsimportcreate_sample_cloud# Generate sample datadata=create_sample_cloud(10000, shape='sphere')
# Load fileloaded=SplatIO.auto_read('scene.ply')
# Filter by alphafiltered=SplatEditor.filter_by_alpha(loaded, min_alpha=0.5)
# Normalize positionsnormalized=SplatEditor.normalize_position(filtered, mode='center')
# Quality analysisquality=SplatEditor.analyze_quality(normalized)
print(f"Quality Score: {quality['score']}/100")
# Auto repairrepaired, repairs=SplatEditor.auto_repair(normalized)
# Save resultSplatIO.write_ply(repaired, 'output.ply')

CLI Reference

CommandDescriptionExample
infoShow point cloud infosplatforge info scene.ply
convertFormat conversionsplatforge convert scene.ply scene.json
statsDetailed statisticssplatforge stats scene.ply
qualityQuality analysissplatforge quality scene.ply
repairAuto repairsplatforge repair input.ply output.ply
filterFilter operationssplatforge filter in.ply out.ply --min-alpha 0.1
sampleGenerate samplesplatforge sample out.ply --shape cube --count 5000
webWeb interfacesplatforge web 5000

📦 Packaging & Deployment

# Install as library
pip install -e .# Run tests
pytest tests/ -v
# Start web server
python -m splatforge.cli web 8080

Compatible Environments

EnvironmentStatus
Linux (x86_64)✅ Supported
macOS (x86_64/ARM64)✅ Supported
Windows (x86_64)✅ Supported
Python 3.8+✅ Supported

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License.

About

Lightweight 3D Gaussian Splat Point Cloud Intelligent Editing Engine - Pure Python, Zero Node.js Dependency

github.com/gitstq/SplatForge

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages