{"id":37064442,"url":"https://github.com/404background/3dgs-edit-tools","last_synced_at":"2026-01-14T07:31:48.647Z","repository":{"id":290707102,"uuid":"975236645","full_name":"404background/3dgs-edit-tools","owner":"404background","description":"Tools for editing data of 3D Gaussian Splatting format","archived":false,"fork":false,"pushed_at":"2025-05-22T07:33:45.000Z","size":3849,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-21T22:10:24.071Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/404background.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,"zenodo":null}},"created_at":"2025-04-30T02:08:20.000Z","updated_at":"2025-10-11T09:25:06.000Z","dependencies_parsed_at":"2025-04-30T06:31:33.419Z","dependency_job_id":"b567be1a-2b88-4255-9939-886e36b4d919","html_url":"https://github.com/404background/3dgs-edit-tools","commit_stats":null,"previous_names":["404background/3dgs-edit-tools"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/404background/3dgs-edit-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/404background%2F3dgs-edit-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/404background%2F3dgs-edit-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/404background%2F3dgs-edit-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/404background%2F3dgs-edit-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/404background","download_url":"https://codeload.github.com/404background/3dgs-edit-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/404background%2F3dgs-edit-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413370,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":[],"created_at":"2026-01-14T07:31:47.831Z","updated_at":"2026-01-14T07:31:48.634Z","avatar_url":"https://github.com/404background.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 3DGS Edit Tools\n\nA Python library to convert 3D Gaussian Splatting (3DGS) format data to CSV format, edit it, and convert it back to 3DGS format.\n\n[![GitHub](https://img.shields.io/badge/GitHub-3DGS%20Edit%20Tools-blue?style=flat-square\u0026logo=github)](https://github.com/404background/3dgs-edit-tools)\n[![PyPI](https://img.shields.io/badge/PyPI-3dgs--edit--tools-blue?style=flat-square\u0026logo=pypi)](https://pypi.org/project/3dgs-edit-tools/)\n\n## Features\n\n- Convert 3DGS format (PLY) data to CSV format\n- Convert CSV format data to 3DGS format (PLY)\n- Convert 3DGS format to standard point cloud format\n- Convert point cloud data to/from CSV format for easy editing\n- Tools for comparing 3DGS files and analyzing differences\n- Merge multiple 3DGS files into a single scene\n- Apply transformations (translation, scaling) to 3DGS files\n- Verified compatibility with SuperSplat for visualization\n- Point cloud data verified with CloudCompare\n\n![Haniwa model in 3D Gaussian Splatting format](https://raw.githubusercontent.com/404background/3dgs-edit-tools/main/images/haniwa.png)\n![Haniwa model converted to point cloud format in CloudCompare](https://raw.githubusercontent.com/404background/3dgs-edit-tools/main/images/haniwa_pointcloud.png)\n\n## Project Structure\n\n- **src/**: Core functionality for converting between formats\n- **tools/**: Additional utilities for analyzing and comparing 3DGS files\n- **examples/**: Sample code demonstrating usage of the library\n- **images/**: Sample images and visualizations\n\n## Dependencies\n\n### Core Library (src/)\n\nThe core library in the `src/` folder requires **numpy** for numerical operations. This dependency is automatically installed when you install the package.\n\n### Tools (tools/)\n\nThe tools in the `tools/` folder require additional dependencies:\n\n```bash\npip install pandas matplotlib\n```\n\nThese are automatically installed if you install the package with the `[tools]` extra.\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\n# Basic installation with core functionality\npip install 3dgs-edit-tools\n\n# Complete installation with tools for analysis and comparison\npip install 3dgs-edit-tools[tools]\n```\n\n### From Source\n\nClone this repository:\n\n```bash\ngit clone https://github.com/404background/3dgs-edit-tools.git\ncd 3dgs-edit-tools\npip install -e .  # Install in development mode\n```\n\n## Why CSV Format?\n\nThis library uses CSV format as an intermediate step for editing 3D Gaussian Splatting data because:\n\n- **Human-Readable**: CSV files can be easily viewed and edited with spreadsheet software or text editors\n- **Ease of Editing**: Unlike binary formats, CSV files allow direct modification of values without specialized tools\n- **Compatibility**: CSV is widely supported by data processing tools and programming languages\n- **Transparency**: The structure and values are visible, making it easier to understand the data\n\nPoint cloud data is also converted to CSV format before editing to maintain the same benefits.\n\n## Usage\n\n### As a Library\n\n```python\nfrom src import convert_3dgs_to_csv, convert_csv_to_3dgs\n\n# Convert PLY file to CSV\ncsv_path, _ = convert_3dgs_to_csv('model.ply')\n\n# Write your code to edit the CSV file here\n# ...\n\n# Convert edited CSV back to PLY\nrestored_ply = convert_csv_to_3dgs(csv_path, None)\n```\n\n### Merging and Transforming 3DGS Files\n\n```python\nfrom src import merge_3dgs_files, create_transformed_copy\n\n# Create a transformed copy with 10cm translation on X-axis\ntransformed_ply = create_transformed_copy('model.ply', 'model_moved.ply', \n                                         {'translate': [0.1, 0, 0]})\n\n# Merge original and transformed models\nmerged_ply = merge_3dgs_files('model.ply', transformed_ply, 'merged_scene.ply')\n```\n\n### Point Cloud Workflows\n\n```python\nfrom src import (\n    convert_3dgs_to_pointcloud, \n    convert_pointcloud_to_3dgs,\n    convert_pointcloud_to_csv,\n    convert_csv_to_pointcloud\n)\n\n# 3DGS to point cloud\npointcloud_path = convert_3dgs_to_pointcloud('model.ply')\n\n# Point cloud to CSV for easy editing\ncsv_path = convert_pointcloud_to_csv(pointcloud_path)\n\n# Edit CSV file here...\n\n# CSV back to point cloud\nedited_pointcloud = convert_csv_to_pointcloud(csv_path)\n\n# Point cloud back to 3DGS\nrestored_model = convert_pointcloud_to_3dgs(edited_pointcloud, 'model.ply')\n```\n\n### Using Tools\n\nTo use the comparison tool for analyzing differences between 3DGS files:\n\n```bash\n# First install required dependencies\npip install pandas matplotlib\n\n# Run the comparison tool\npython -m tools.compare_gs path/to/original.ply path/to/modified.ply --output-dir comparison_results\n```\n\nFor more information about available tools, see the [tools/README.md](tools/README.md) file.\n\n### From Command Line\n\nAfter installation, the package provides several command-line executables for easy use:\n\nConvert PLY to CSV:\n\n```bash\n3dgs-to-csv input.ply --output_csv output.csv\n```\n\nConvert CSV to PLY:\n\n```bash\ncsv-to-3dgs input.csv --output_ply output.ply\n```\n\nConvert 3DGS to point cloud:\n\n```bash\n3dgs-to-pointcloud input.ply --output_ply output_pointcloud.ply\n```\n\nConvert point cloud to 3DGS:\n\n```bash\npointcloud-to-3dgs input_pointcloud.ply original.ply --output_ply restored.ply\n```\n\nMerge two 3DGS files:\n\n```bash\nmerge-gs file1.ply file2.ply --output merged.ply --translate-x 0.1\n```\n\nConvert 3DGS to mesh:\n\n```bash\n3dgs-to-mesh input.ply --output output_mesh.obj --method hybrid --quality high\n```\n\nConvert point cloud to CSV:\n\n```bash\npointcloud-to-csv ply2csv input_pointcloud.ply --output_csv output.csv\n```\n\nConvert CSV to point cloud:\n\n```bash\ncsv-to-pointcloud input.csv --output_ply output.ply --color_type uchar\n```\n\nCompare two 3DGS files:\n\n```bash\ncompare-gs original.ply modified.ply --output-dir comparison_results\n```\n\n### Sample Code\n\nSample code is available in the `examples` folder. See `examples/README.md` for details.\n\n### Visualization Tools\n\nThis project has been tested with the following visualization tools:\n\n- **SuperSplat**: For 3D Gaussian Splatting format files (.ply)\n- **CloudCompare**: For point cloud format files (.ply)\n- **Blender**: For mesh format files (.obj, .ply, .stl)\n\nAll point cloud data conversions have been extensively tested using CloudCompare to ensure proper structure, color representation, and export compatibility. Mesh outputs have been verified with Blender to confirm proper mesh topology and compatibility.\n\n## API Reference\n\n### Core Conversion Functions\n\n#### convert_3dgs_to_csv(ply_filename, csv_filename=None)\n\nConverts 3DGS format (PLY) data to CSV format.\n\n**Arguments**:\n- `ply_filename` (str): Path to the input PLY file\n- `csv_filename` (str, optional): Path to the output CSV file. If not specified, it's automatically generated from the input filename\n\n**Returns**:\n- tuple: (csv_filename, None) - Paths of the generated files\n\n#### convert_csv_to_3dgs(csv_filename, footer_filename=None, output_ply_filename=None)\n\nConverts CSV format data to 3DGS format (PLY).\n\n**Arguments**:\n- `csv_filename` (str): Path to the input CSV file\n- `footer_filename` (str, optional): Path to the file containing footer data. If not specified, it's automatically generated from the input filename\n- `output_ply_filename` (str, optional): Path to the output PLY file. If not specified, it's automatically generated from the input filename\n\n**Returns**:\n- str: Path of the generated PLY file\n\n### Merge and Transform Functions\n\n#### merge_3dgs_files(file1, file2, output_file=None, transform=None)\n\nMerges two 3D Gaussian Splatting files into a single file.\n\n**Arguments**:\n- `file1` (str): Path to the first 3DGS file\n- `file2` (str): Path to the second 3DGS file\n- `output_file` (str, optional): Path to the output merged 3DGS file\n- `transform` (dict, optional): Transformation to apply to the second file (e.g. `{'translate': [0.1, 0, 0]}`)\n\n**Returns**:\n- str: Path of the generated merged 3DGS file\n\n#### create_transformed_copy(input_ply, output_ply, transformation)\n\nCreates a transformed copy of a 3DGS file with specified transformations.\n\n**Arguments**:\n- `input_ply` (str): Path to input PLY file\n- `output_ply` (str): Path to output transformed PLY file\n- `transformation` (dict): Dictionary with transformation parameters (e.g. `{'translate': [0.1, 0, 0], 'scale': [1.5, 1, 1]}`)\n\n**Returns**:\n- str: Path to transformed PLY file\n\n### Point Cloud Conversion Functions\n\n#### convert_3dgs_to_pointcloud(ply_filename, output_ply_filename=None)\n\nConverts 3D Gaussian Splatting format to standard point cloud PLY format.\n\n**Arguments**:\n- `ply_filename` (str): Path to the input 3DGS PLY file\n- `output_ply_filename` (str, optional): Path to the output point cloud PLY file\n\n**Returns**:\n- str: Path of the generated point cloud file\n\n#### convert_pointcloud_to_3dgs(pointcloud_ply, original_3dgs_ply, output_ply=None)\n\nConverts a point cloud file back to 3D Gaussian Splatting format using an original 3DGS file as reference.\n\n**Arguments**:\n- `pointcloud_ply` (str): Path to the input point cloud PLY file\n- `original_3dgs_ply` (str): Path to the original 3DGS file to use as reference\n- `output_ply` (str, optional): Path to the output 3DGS file\n\n**Returns**:\n- str: Path of the generated 3DGS file\n\n#### convert_pointcloud_to_csv(ply_filename, csv_filename=None)\n\nConverts point cloud PLY file to CSV format for easier editing.\n\n**Arguments**:\n- `ply_filename` (str): Path to the input point cloud PLY file\n- `csv_filename` (str, optional): Path to the output CSV file\n\n**Returns**:\n- str: Path of the generated CSV file\n\n#### convert_csv_to_pointcloud(csv_filename, output_ply_filename=None, color_type=\"uchar\")\n\nConverts CSV file to point cloud PLY format.\n\n**Arguments**:\n- `csv_filename` (str): Path to the input CSV file\n- `output_ply_filename` (str, optional): Path to the output point cloud PLY file\n- `color_type` (str): Type of color data to use in PLY file ('float' or 'uchar')\n\n**Returns**:\n- str: Path of the generated PLY file\n\n## License\n\nThis project is released under the MIT License. See LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F404background%2F3dgs-edit-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F404background%2F3dgs-edit-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F404background%2F3dgs-edit-tools/lists"}