{"id":13816211,"url":"https://github.com/francescofugazzi/3dgsconverter","last_synced_at":"2026-01-17T21:32:21.500Z","repository":{"id":204152964,"uuid":"711218525","full_name":"francescofugazzi/3dgsconverter","owner":"francescofugazzi","description":"A Python command-line utility for converting and processing 3D Gaussian Splatting models. Supports N-to-N conversion between 3DGS (.ply), KSplat, SOG, SPZ, Splat, CloudCompare, Parquet, and Compressed PLY. Includes GPU-accelerated filtering (SOR, Density).","archived":false,"fork":false,"pushed_at":"2026-01-13T19:58:08.000Z","size":128,"stargazers_count":480,"open_issues_count":4,"forks_count":32,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-01-13T21:44:59.730Z","etag":null,"topics":["gaussian-splatting"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/francescofugazzi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-28T15:09:50.000Z","updated_at":"2026-01-13T21:33:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"7f7f57e5-85cd-445a-a2a3-957f17310933","html_url":"https://github.com/francescofugazzi/3dgsconverter","commit_stats":null,"previous_names":["francescofugazzi/3dgsconverter"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/francescofugazzi/3dgsconverter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescofugazzi%2F3dgsconverter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescofugazzi%2F3dgsconverter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescofugazzi%2F3dgsconverter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescofugazzi%2F3dgsconverter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/francescofugazzi","download_url":"https://codeload.github.com/francescofugazzi/3dgsconverter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescofugazzi%2F3dgsconverter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28518627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T18:55:29.170Z","status":"ssl_error","status_checked_at":"2026-01-17T18:55:03.375Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gaussian-splatting"],"created_at":"2024-08-04T05:00:37.366Z","updated_at":"2026-01-17T21:32:21.486Z","avatar_url":"https://github.com/francescofugazzi.png","language":"Python","funding_links":["https://github.com/sponsors/francescofugazzi","https://www.buymeacoffee.com/franzipol"],"categories":["Open Source Implementations","Tools, Pipeline \u0026 Utilities"],"sub_categories":["Utilities","Conversion Tools"],"readme":"# 3D Gaussian Splatting Converter\n\n[![GitHub Sponsor](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?style=for-the-badge\u0026logo=github-sponsors)](https://github.com/sponsors/francescofugazzi)\n[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-ffdd00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/franzipol)\n\nA versatile, high-performance tool for converting between various 3D Gaussian Splatting formats. It supports advanced filtering, GPU acceleration, and universal N-to-N conversion between all supported formats.\n\n## Key Features\n\n- **Universal Conversion**: Convert **any** supported format to **any** other format (e.g., `.ply` to `.ksplat`, `.spz` to `.ply`, `.sog` to `.sog`).\n- **Cross-Platform**: Fully compatible with **Windows**, **Linux**, and **macOS** (Apple Silicon \u0026 Intel).\n- **GPU Acceleration**: Built-in GPU support via **Taichi Lang** for extremely fast K-Means clustering (SOG/KSplat compression) and Statistical Outlier Removal (SOR). Supports NVIDIA CUDA, Apple Metal, and Vulkan/Integrated GPUs.\n- **Advanced Filtering**:\n    - **Region of Interest**: Crop using Manual Bounding Box (Runs first for speed).\n    - **Alpha/Opacity**: Remove transparent splats.\n    - **Density Control**: Remove sparse areas while keeping dense clusters (Multi-cluster support).\n    - **Outlier Removal**: Statistical Outlier Removal (SOR) to clean up \"flyers\".\n- **Compression Control**: Balance quality and file size with `--compression_level` (0 = Max Quality).\n- **Format Agnostic**: Filters apply to the intermediate raw data, so they work on ANY input format.\n- **Custom Data Preservation**: Use `--extra_elements` to maintain non-standard PLY properties (like camera parameters) when converting between PLY formats.\n\n## Supported Formats \u0026 Peculiarities\n\n| Format | Extension | Max SH | Features \u0026 Parameters |\n| :--- | :--- | :--- | :--- |\n| **3DGS PLY** | `.ply` | **3** | **Standard Format**. Full float32. \u003cbr\u003e• `--sh_level`: Caps SH degree. |\n| **Cloud Compare** | `.ply` | **3** | **Viewer Compatible**. Forces RGB generation. \u003cbr\u003e• `--rgb`: Auto-converts SH to RGB. |\n| **Compressed PLY** | `.ply` | **3** | **High Compression**. Chunk-based quantization stored in standard PLY container. |\n| **Splat** | `.splat` | **0** | **Legacy Web**. RGB only (No SH). |\n| **KSplat** | `.ksplat` | **2** | **Streaming/Web**. Hierarchical quantization. \u003cbr\u003e• `compression_level` 0 (F32), 1 (F16), ≥2 (Quantized) |\n| **SPZ** | `.spz` | **3** | **Fast Loading**. Gzip compressed. \u003cbr\u003e• `compression_level`: Controls Gzip level (0-9). |\n| **SOG** | `.sog` | **3** | **Web/Mobile Optimized**. GPU texture compression. \u003cbr\u003e• `compression_level`: Codebook size control. |\n| **Parquet** | `.parquet` | **3** | **Data Analysis**. Columnar storage. Pandas compatible. |\n\n## Installation\n\nIt is recommended to use **Conda** to manage dependencies.\n\n1.  **Create and Activate Conda Environment:**\n    ```bash\n    conda create -n gsconv python=3.10\n    conda activate gsconv\n    ```\n    *(Or use a local `.venv` if preferred)*\n\n2.  **Install the Package:**\n\n    *Option A: Quick Install (via pip)*\n    ```bash\n    pip install git+https://github.com/francescofugazzi/3dgsconverter.git\n    ```\n\n    *Option B: Manual Development Install (Clone)*\n    ```bash\n    git clone https://github.com/francescofugazzi/3dgsconverter.git\n    cd 3dgsconverter\n    pip install -r requirements.txt\n    ```\n\n    *Note: To enable GPU acceleration, ensure `taichi` is installed (`pip install taichi`). It is included in `requirements.txt`.*\n\n## Usage\n\nBasic syntax:\n```bash\n3dgsconverter -i \u003cinput_file\u003e -f \u003ctarget_format\u003e [-o \u003coutput_file\u003e] [options]\n```\n*(Aliases: `gsconverter`, `3dgsconv`, `gsconv`)*\n*Note: `-o` is optional. If omitted, the output filename is derived from the input with the correct extension.*\n*Use `--force` to overwrite existing files without confirmation.*\n\n### Common Examples\n\n**1. Basic Conversion (PLY to KSplat)**\n```bash\n3dgsconverter -i input.ply -f ksplat\n# Creates input.ksplat automatically\n```\n\n**2. High-Quality Compression (SOG)**\n```bash\n# Level 1 = High Quality. Level 10 = High Compression.\n3dgsconverter -i input.ply -o output.sog -f sog --compression_level 1\n```\n\n**3. Cleaning a Point Cloud (Filters)**\n```bash\n# Remove invisible points and outliers\n3dgsconverter -i raw.ply -o clean.ply -f 3dgs --min_opacity 5 --sor_intensity 8\n```\n\n**4. Extracting a Region of Interest**\n```bash\n# Crop BEFORE filtering (Attributes: minX minY minZ maxX maxY maxZ)\n3dgsconverter -i scene.spz -o crop.ply -f 3dgs --bbox -2 -2 -2 2 2 2\n```\n\n### Parameter Reference\n\n#### General\n-   `-i, --input`: Path to source file.\n-   `-o, --output`: Path to destination file (Optional).\n-   `-f, --format`: Target format (`3dgs`, `cc`, `ksplat`, `splat`, `sog`, `spz`, `parquet`, `compressed_ply`).\n-   `--force`: Overwrite existing output file without prompting.\n-   `--rgb`: Force RGB generation from SH (for supported formats).\n-   `--extra_elements`: Preserves non-standard PLY elements (like `extrinsic`, `intrinsic`) when converting between 3DGS/CC formats.\n-   `--sh_level`: Target SH degree (0-3). Tool **never** upscales; keeps source degree if lower.\n-   `--compression_level`: 0-10. Controls quality/size ratio for supported formats (SOG, KSplat, SPZ).\n    -   **KSplat**: Set to `2` for quantization (experimental levels \u003e2 map to 2).\n\n#### Advanced Filters\nFilters run in this specific order for efficiency:\n\n1.  **Manual BBox** (`--bbox`): Crops space first.\n2.  **Alpha Filter** (`--min_opacity \u003c0-255\u003e`): Discards points with opacity \u003c threshold.\n3.  **Density Filter**:\n    -   `--density_sensitivity \u003c0.0-1.0\u003e`: Simple slider. 0.0 = Lazy (keeps more), 1.0 = Aggressive (removes sparse halos).\n    -   `--keep_multicluster`: If set, keeps *all* dense clusters. Default: keeps only the largest main cluster.\n4.  **SOR (Flyers)**:\n    -   `--sor_intensity \u003c1-10\u003e`: Simple slider. 1 = Weak (keeps more), 10 = Strong (removes all outliers).\n5.  **Auto BBox** (`--auto_bbox`):\n    -   Calculates the minimal bounding box of the remaining valid points before saving, ensuring tight packing.\n\n## Technical Details\n\nBuilt with **Taichi Lang** for high-performance GPU computing.\n-   **Parallelism**: Voxels and SOR are processed in parallel on the GPU.\n-   **Differentiable Design**: While currently used for conversion, the core is differentiable, allowing for future optimization and training applications.\n-   **No Upscale Rule**: The converter strictly respects the source SH degree. If you convert a File with SH=1 to a format supporting SH=3, the output will remain SH=1 (padded with zeros if necessary, but never \"hallucinated\").\n\n## Credits\n\nThis project builds upon the incredible work of the 3D Gaussian Splatting community. Special thanks to:\n\n-   **[Inria (GraphDeco)](https://github.com/graphdeco-inria/gaussian-splatting)**: The original 3D Gaussian Splatting paper and implementation.\n-   **[Antimatter15](https://github.com/antimatter15/splat)**: For the `.splat` format and the first WebGL viewer.\n-   **[mkkellogg](https://github.com/mkkellogg/GaussianSplats3D)**: For the `.ksplat` format and 3DGS-Three.js integration.\n-   **[Niantic Labs](https://github.com/nianticlabs/spz)**: For the `.spz` format definition.\n-   **[PlayCanvas](https://github.com/playcanvas/supersplat)**: For the `.sog` format, `.ply` chunk-quantization schema, and SuperSplat viewer.\n\n## Refactoring \u0026 Breaking Changes (Type-Check Safe)\n\nThis project has undergone a complete refactoring to modularize the codebase and improve type safety. As a result, some legacy command-line arguments have been deprecated and replaced with more explicit or user-friendly alternatives.\n\n### Replaced Commands\n| Legacy Command | New Equivalent | Description |\n| :--- | :--- | :--- |\n| `--density_filter [v, t]` | `--density_sensitivity` (Slider) | **Effect**: Reduces file size by merging overlapping points.\u003cbr\u003e**Practical**: 0.1 keeps detail, 0.9 aggressively simplifies. |\n| `--remove_flyers [k, s]` | `--sor_intensity` (Slider) | **Effect**: Cleans up floating noise/artifacts.\u003cbr\u003e**Practical**: 1.0 is safe, 10.0 is aggressive. |\n\n### New Features\n*   **Format-Specific Compression**: The `--compression_level` flag adapts to the target format:\n    *   **KSplat**:\n        *   `0`: No compression (Float32 w/ SH). Max quality.\n        *   `1`: Block compression (Uint16 Pos, Float16 Scale/Rot/SH). Good balance.\n        *   `2+`: Aggressive Block compression (Uint16 Pos, Float16 Scale/Rot, Uint8 SH). Smallest size, lossy SH.\n    *   **SPZ**: Controls Gzip compression effort (1-9). This is **lossless** for the data itself, affecting only file size and save time.\n    *   **SOG**: Controls SH Palette Quality (0=Max Quality, 9=Min Quality). Note: Texture compression is always Lossless WebP.\n\n*   **User-Friendly Sliders**: New `--density_sensitivity` (0.0-1.0) and `--sor_intensity` (1.0-10.0) abstract complex parameters away for easier use.\n*   **Modular Architecture**: The monolith code has been split into `formats/`, `processing/`, and `utils/` for better maintainability and extensibility. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrancescofugazzi%2F3dgsconverter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrancescofugazzi%2F3dgsconverter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrancescofugazzi%2F3dgsconverter/lists"}