gaussforge 0.4.2__tar.gz

gaussforge-0.4.2/.gitignore

@@ -0,0 +1,19 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.whl
+
+# Compiled extensions
+*.so
+*.cpython-*.so
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+
+# IDE
+.vscode/
+.idea/

gaussforge-0.4.2/CMakeLists.txt

@@ -0,0 +1,84 @@
+# Python binding CMakeLists.txt
+# This file is included when building the Python package via scikit-build-core
+
+cmake_minimum_required(VERSION 3.26)
+
+project(gaussforge_python
+    VERSION 0.4.2
+    LANGUAGES CXX C
+)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Find Python and nanobind
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(nanobind CONFIG REQUIRED)
+
+# Include parent project's dependencies
+set(GAUSS_FORGE_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/..")
+
+# Configure version header
+configure_file(
+    ${GAUSS_FORGE_ROOT}/include/gf/core/version.h.in
+    ${CMAKE_CURRENT_BINARY_DIR}/include/gf/core/version.h
+    @ONLY
+)
+
+# Include dependency configurations
+include(FetchContent)
+include(${GAUSS_FORGE_ROOT}/cmakes/zlib.cmake)
+include(${GAUSS_FORGE_ROOT}/cmakes/sog.cmake)
+include(${GAUSS_FORGE_ROOT}/cmakes/spz.cmake)
+
+# Core library source files
+set(GAUSS_FORGE_SOURCES
+    ${GAUSS_FORGE_ROOT}/src/core/model_info.cpp
+    ${GAUSS_FORGE_ROOT}/src/core/validate.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/registry.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/ply_auto.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/ply_compressed_reader.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/ply_compressed_writer.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/ply_reader.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/ply_writer.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/splat_reader.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/splat_writer.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/ksplat_reader.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/ksplat_writer.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/spz_reader.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/spz_writer.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/sog_reader.cpp
+    ${GAUSS_FORGE_ROOT}/src/io/sog_writer.cpp
+)
+
+# Create static library for internal use
+add_library(gauss_forge_py STATIC ${GAUSS_FORGE_SOURCES})
+target_include_directories(gauss_forge_py PUBLIC
+    ${GAUSS_FORGE_ROOT}/include
+    ${CMAKE_CURRENT_BINARY_DIR}/include
+)
+target_link_libraries(gauss_forge_py PUBLIC
+    spz::spz
+    webp
+    nlohmann_json::nlohmann_json
+    ZLIB::ZLIB
+)
+
+# Create Python extension module
+nanobind_add_module(
+    _core
+    STABLE_ABI
+    LTO
+    NB_STATIC
+    src/gaussforge/bindings.cpp
+)
+target_link_libraries(_core PRIVATE gauss_forge_py)
+target_include_directories(_core PRIVATE
+    ${GAUSS_FORGE_ROOT}/include
+    ${CMAKE_CURRENT_BINARY_DIR}/include
+)
+
+# Set output directory for the extension module
+set_target_properties(_core PROPERTIES
+    LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src/gaussforge"
+)

gaussforge-0.4.2/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: gaussforge
+Version: 0.4.2
+Summary: High-performance Gaussian Splatting format conversion library
+Keywords: gaussian-splatting,3d,point-cloud,format-conversion,ply,splat
+Author: tcodestudio
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/3dgscloud/GaussForge
+Project-URL: Repository, https://github.com/3dgscloud/GaussForge.git
+Project-URL: Issues, https://github.com/3dgscloud/GaussForge/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# GaussForge Python Binding
+
+High-performance Gaussian Splatting format conversion library for Python.
+
+## Installation
+
+```bash
+pip install gaussforge
+```
+
+## Quick Start
+
+```python
+import gaussforge
+
+# Create instance
+gf = gaussforge.GaussForge()
+
+# Read a PLY file
+with open("model.ply", "rb") as f:
+    data = f.read()
+
+result = gf.read(data, "ply")
+if "error" not in result:
+    print(f"Loaded {result['data']['numPoints']} points")
+
+# Convert to another format
+converted = gf.convert(data, "ply", "splat")
+if "error" not in converted:
+    with open("output.splat", "wb") as f:
+        f.write(converted["data"])
+```
+
+## Supported Formats
+
+- `ply` - Standard PLY format
+- `compressed.ply` - Compressed PLY format
+- `splat` - Splat format
+- `ksplat` - K-Splat format
+- `spz` - SPZ compressed format
+- `sog` - SOG format
+
+## API Reference
+
+### `GaussForge()`
+
+Create a new GaussForge instance.
+
+### `read(data: bytes, format: str, strict: bool = False) -> dict`
+
+Read Gaussian data from bytes.
+
+- `data`: Raw file data as bytes
+- `format`: Input format name
+- `strict`: Enable strict validation (default: False)
+
+Returns a dict with `data` key containing the parsed Gaussian data, or `error` key on failure.
+
+### `write(ir: dict, format: str, strict: bool = False) -> dict`
+
+Write Gaussian IR to bytes.
+
+- `ir`: Gaussian intermediate representation dict
+- `format`: Output format name
+- `strict`: Enable strict validation (default: False)
+
+Returns a dict with `data` key containing the encoded bytes, or `error` key on failure.
+
+### `convert(data: bytes, in_format: str, out_format: str, strict: bool = False) -> dict`
+
+Convert between formats directly.
+
+- `data`: Input file data as bytes
+- `in_format`: Input format name
+- `out_format`: Output format name
+- `strict`: Enable strict validation (default: False)
+
+Returns a dict with `data` key containing the converted bytes, or `error` key on failure.
+
+### `get_model_info(data: bytes, format: str, file_size: int = 0) -> dict`
+
+Get detailed model information.
+
+- `data`: Raw file data as bytes
+- `format`: Input format name
+- `file_size`: Optional file size for reporting
+
+Returns a dict with `data` key containing model info, or `error` key on failure.
+
+### `get_supported_formats() -> list[str]`
+
+Get list of supported format names.
+
+### `get_version() -> str`
+
+Get library version string.
+
+## Building from Source
+
+```bash
+cd python
+pip install -e .
+```
+
+## License
+
+Apache-2.0

gaussforge-0.4.2/README.md

@@ -0,0 +1,107 @@
+# GaussForge Python Binding
+
+High-performance Gaussian Splatting format conversion library for Python.
+
+## Installation
+
+```bash
+pip install gaussforge
+```
+
+## Quick Start
+
+```python
+import gaussforge
+
+# Create instance
+gf = gaussforge.GaussForge()
+
+# Read a PLY file
+with open("model.ply", "rb") as f:
+    data = f.read()
+
+result = gf.read(data, "ply")
+if "error" not in result:
+    print(f"Loaded {result['data']['numPoints']} points")
+
+# Convert to another format
+converted = gf.convert(data, "ply", "splat")
+if "error" not in converted:
+    with open("output.splat", "wb") as f:
+        f.write(converted["data"])
+```
+
+## Supported Formats
+
+- `ply` - Standard PLY format
+- `compressed.ply` - Compressed PLY format
+- `splat` - Splat format
+- `ksplat` - K-Splat format
+- `spz` - SPZ compressed format
+- `sog` - SOG format
+
+## API Reference
+
+### `GaussForge()`
+
+Create a new GaussForge instance.
+
+### `read(data: bytes, format: str, strict: bool = False) -> dict`
+
+Read Gaussian data from bytes.
+
+- `data`: Raw file data as bytes
+- `format`: Input format name
+- `strict`: Enable strict validation (default: False)
+
+Returns a dict with `data` key containing the parsed Gaussian data, or `error` key on failure.
+
+### `write(ir: dict, format: str, strict: bool = False) -> dict`
+
+Write Gaussian IR to bytes.
+
+- `ir`: Gaussian intermediate representation dict
+- `format`: Output format name
+- `strict`: Enable strict validation (default: False)
+
+Returns a dict with `data` key containing the encoded bytes, or `error` key on failure.
+
+### `convert(data: bytes, in_format: str, out_format: str, strict: bool = False) -> dict`
+
+Convert between formats directly.
+
+- `data`: Input file data as bytes
+- `in_format`: Input format name
+- `out_format`: Output format name
+- `strict`: Enable strict validation (default: False)
+
+Returns a dict with `data` key containing the converted bytes, or `error` key on failure.
+
+### `get_model_info(data: bytes, format: str, file_size: int = 0) -> dict`
+
+Get detailed model information.
+
+- `data`: Raw file data as bytes
+- `format`: Input format name
+- `file_size`: Optional file size for reporting
+
+Returns a dict with `data` key containing model info, or `error` key on failure.
+
+### `get_supported_formats() -> list[str]`
+
+Get list of supported format names.
+
+### `get_version() -> str`
+
+Get library version string.
+
+## Building from Source
+
+```bash
+cd python
+pip install -e .
+```
+
+## License
+
+Apache-2.0

gaussforge-0.4.2/example/.gitignore

@@ -0,0 +1,5 @@
+output.*
+__pycache__/
+*.pyc
+*.so
+*.cpython-*.so

gaussforge-0.4.2/example/test.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+Local test script - Test gaussforge package using tiny_gauss.ply
+
+Usage:
+    1. Build package: pip install -e ..
+    2. Run test: python test.py
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Add parent directory to path for development testing
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from gaussforge import GaussForge, get_version
+
+
+def main():
+    print("=" * 60)
+    print("Testing gaussforge Python package")
+    print("=" * 60)
+
+    test_file = Path(__file__).parent / "tiny_gauss.ply"
+
+    # Check if test file exists
+    if not test_file.exists():
+        print(f"Error: Test file does not exist: {test_file}")
+        sys.exit(1)
+
+    print(f"\nTest file: {test_file}")
+
+    try:
+        # 1. Initialize
+        print("\n1. Initializing GaussForge...")
+        gf = GaussForge()
+        print("   Initialization successful")
+
+        # 2. Print version
+        print("\n2. Getting version...")
+        version = gf.get_version()
+        print(f"   Version: {version}")
+
+        # 3. Get supported formats
+        print("\n3. Getting supported formats...")
+        formats = gf.get_supported_formats()
+        print(f"   Supported formats: {', '.join(formats)}")
+
+        # 4. Read test file
+        print("\n4. Reading test file...")
+        with open(test_file, "rb") as f:
+            input_data = f.read()
+        print(f"   File size: {len(input_data)} bytes")
+
+        read_result = gf.read(input_data, "ply")
+        if "error" in read_result:
+            print(f"   Read failed: {read_result['error']}")
+            sys.exit(1)
+
+        print("   Read successful")
+        data = read_result["data"]
+        print(f"   Number of points: {data['numPoints']}")
+        print(f"   SH degree: {data['meta']['shDegree']}")
+
+        # 5. Test model info
+        print("\n5. Testing model info...")
+        info_result = gf.get_model_info(input_data, "ply", len(input_data))
+        if "error" in info_result:
+            print(f"   Model info failed: {info_result['error']}")
+        else:
+            info = info_result["data"]
+            print("   Model info retrieved")
+            print("   Basic info:")
+            print(f"      - Points: {info['basic']['numPoints']}")
+            if "fileSize" in info["basic"]:
+                print(f"      - File size: {info['basic']['fileSize']} bytes")
+            if "sourceFormat" in info["basic"]:
+                print(f"      - Source format: {info['basic']['sourceFormat']}")
+
+            print("   Rendering:")
+            print(f"      - SH degree: {info['rendering']['shDegree']}")
+            print(f"      - Antialiased: {info['rendering']['antialiased']}")
+
+            if "bounds" in info:
+                print("   Bounds:")
+                print(f"      - X: {info['bounds']['x']}")
+                print(f"      - Y: {info['bounds']['y']}")
+                print(f"      - Z: {info['bounds']['z']}")
+
+            if "scaleStats" in info:
+                print("   Scale stats:")
+                print(f"      - Min: {info['scaleStats']['min']}")
+                print(f"      - Max: {info['scaleStats']['max']}")
+                print(f"      - Avg: {info['scaleStats']['avg']}")
+
+            if "alphaStats" in info:
+                print("   Alpha stats:")
+                print(f"      - Min: {info['alphaStats']['min']}")
+                print(f"      - Max: {info['alphaStats']['max']}")
+                print(f"      - Avg: {info['alphaStats']['avg']}")
+
+            print("   Data sizes:")
+            for key, value in info["sizes"].items():
+                print(f"      - {key}: {value}")
+
+            if "extraAttrs" in info:
+                print("   Extra attributes:")
+                for name, size in info["extraAttrs"].items():
+                    print(f"      - {name}: {size}")
+
+        # 6. Test format conversion
+        print("\n6. Testing format conversion...")
+        output_formats = ["splat", "ksplat", "spz", "ply", "compressed.ply", "sog"]
+
+        for out_format in output_formats:
+            if out_format not in formats:
+                print(f"   Skipping {out_format} (not supported)")
+                continue
+
+            try:
+                convert_result = gf.convert(input_data, "ply", out_format)
+                if "error" in convert_result:
+                    print(f"   ply -> {out_format} failed: {convert_result['error']}")
+                else:
+                    output_size = len(convert_result["data"])
+                    print(f"   ply -> {out_format}: {output_size} bytes")
+
+                    # Save conversion result
+                    output_file = Path(__file__).parent / f"output.{out_format}"
+                    with open(output_file, "wb") as f:
+                        f.write(convert_result["data"])
+                    print(f"      Saved to: {output_file}")
+            except Exception as e:
+                print(f"   ply -> {out_format} failed: {e}")
+
+        print("\n" + "=" * 60)
+        print("All tests completed!")
+        print("=" * 60)
+
+    except Exception as e:
+        print(f"\nTest failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

gaussforge-0.4.2/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["scikit-build-core>=0.10", "nanobind>=2.0.0"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "gaussforge"
+version = "0.4.2"
+description = "High-performance Gaussian Splatting format conversion library"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+authors = [{ name = "tcodestudio" }]
+keywords = [
+    "gaussian-splatting",
+    "3d",
+    "point-cloud",
+    "format-conversion",
+    "ply",
+    "splat",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/3dgscloud/GaussForge"
+Repository = "https://github.com/3dgscloud/GaussForge.git"
+Issues = "https://github.com/3dgscloud/GaussForge/issues"
+
+[tool.scikit-build]
+# Build configuration
+minimum-version = "0.10"
+build-dir = "build/{wheel_tag}"
+
+# Include the C++ source from parent directory
+wheel.packages = ["src/gaussforge"]
+wheel.license-files = ["../LICENSE"]
+sdist.include = ["../src", "../include", "../cmakes"]
+
+# CMake configuration
+cmake.version = ">=3.26"
+
+[tool.scikit-build.cmake.define]
+CMAKE_POSITION_INDEPENDENT_CODE = "ON"

gaussforge-0.4.2/src/gaussforge/__init__.py

@@ -0,0 +1,32 @@
+"""
+GaussForge - High-performance Gaussian Splatting format conversion library.
+
+This library provides efficient conversion between various Gaussian Splatting
+formats including PLY, SPZ, SPLAT, KSPLAT, SOG, and compressed PLY.
+
+Example:
+    import gaussforge
+
+    # Read a PLY file
+    with open("model.ply", "rb") as f:
+        data = f.read()
+
+    gf = gaussforge.GaussForge()
+    result = gf.read(data, "ply")
+
+    if "error" in result:
+        print(f"Error: {result['error']}")
+    else:
+        print(f"Loaded {result['data']['numPoints']} points")
+
+    # Convert to another format
+    converted = gf.convert(data, "ply", "splat")
+    if "error" not in converted:
+        with open("output.splat", "wb") as f:
+            f.write(converted["data"])
+"""
+
+from gaussforge._core import GaussForge, get_version
+
+__version__ = get_version()
+__all__ = ["GaussForge", "get_version", "__version__"]

gaussforge-0.4.2/src/gaussforge/bindings.cpp

@@ -0,0 +1,356 @@
+#include <nanobind/nanobind.h>
+#include <nanobind/stl/string.h>
+#include <nanobind/stl/vector.h>
+#include <nanobind/stl/unordered_map.h>
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "gf/core/gauss_ir.h"
+#include "gf/core/model_info.h"
+#include "gf/core/validate.h"
+#include "gf/core/version.h"
+#include "gf/io/registry.h"
+
+namespace nb = nanobind;
+
+namespace {
+
+/**
+ * Convert GaussianCloudIR to Python dict
+ * Returns bytes for float arrays (zero-copy friendly)
+ */
+nb::dict gaussIRToPy(const gf::GaussianCloudIR &ir) {
+    nb::dict result;
+
+    result["numPoints"] = ir.numPoints;
+
+    // Convert float vectors to bytes for efficient transfer
+    auto floatVecToBytes = [](const std::vector<float> &vec) -> nb::bytes {
+        if (vec.empty())
+            return nb::bytes();
+        return nb::bytes(reinterpret_cast<const char *>(vec.data()),
+                         vec.size() * sizeof(float));
+    };
+
+    result["positions"] = floatVecToBytes(ir.positions);
+    result["scales"] = floatVecToBytes(ir.scales);
+    result["rotations"] = floatVecToBytes(ir.rotations);
+    result["alphas"] = floatVecToBytes(ir.alphas);
+    result["colors"] = floatVecToBytes(ir.colors);
+    result["sh"] = floatVecToBytes(ir.sh);
+
+    // Handle extras
+    nb::dict extras;
+    for (const auto &pair : ir.extras) {
+        extras[pair.first.c_str()] = floatVecToBytes(pair.second);
+    }
+    result["extras"] = extras;
+
+    // Handle metadata
+    nb::dict meta;
+    meta["shDegree"] = ir.meta.shDegree;
+    meta["sourceFormat"] = ir.meta.sourceFormat;
+    result["meta"] = meta;
+
+    return result;
+}
+
+/**
+ * Convert Python dict to GaussianCloudIR
+ */
+gf::GaussianCloudIR pyToGaussIR(nb::dict pyIR) {
+    gf::GaussianCloudIR ir;
+    ir.numPoints = nb::cast<int32_t>(pyIR["numPoints"]);
+
+    auto fill = [&](const char *key, std::vector<float> &dest) {
+        if (pyIR.contains(key)) {
+            nb::bytes data = nb::cast<nb::bytes>(pyIR[key]);
+            if (data.size() > 0) {
+                const float *ptr = reinterpret_cast<const float *>(data.c_str());
+                size_t count = data.size() / sizeof(float);
+                dest.assign(ptr, ptr + count);
+            }
+        }
+    };
+
+    fill("positions", ir.positions);
+    fill("scales", ir.scales);
+    fill("rotations", ir.rotations);
+    fill("alphas", ir.alphas);
+    fill("colors", ir.colors);
+    fill("sh", ir.sh);
+
+    if (pyIR.contains("extras")) {
+        nb::dict ex = nb::cast<nb::dict>(pyIR["extras"]);
+        for (auto item : ex) {
+            std::string key = nb::cast<std::string>(item.first);
+            nb::bytes data = nb::cast<nb::bytes>(item.second);
+            if (data.size() > 0) {
+                const float *ptr = reinterpret_cast<const float *>(data.c_str());
+                size_t count = data.size() / sizeof(float);
+                ir.extras[key].assign(ptr, ptr + count);
+            }
+        }
+    }
+
+    if (pyIR.contains("meta")) {
+        nb::dict m = nb::cast<nb::dict>(pyIR["meta"]);
+        if (m.contains("shDegree")) {
+            ir.meta.shDegree = nb::cast<int32_t>(m["shDegree"]);
+        }
+        if (m.contains("sourceFormat")) {
+            ir.meta.sourceFormat = nb::cast<std::string>(m["sourceFormat"]);
+        }
+    }
+
+    return ir;
+}
+
+/**
+ * Convert ModelInfo to Python dict
+ */
+nb::dict modelInfoToPy(const gf::ModelInfo &info) {
+    nb::dict result;
+
+    // Basic info
+    nb::dict basic;
+    basic["numPoints"] = info.numPoints;
+    if (info.fileSize > 0)
+        basic["fileSize"] = static_cast<double>(info.fileSize);
+    if (!info.sourceFormat.empty())
+        basic["sourceFormat"] = info.sourceFormat;
+    result["basic"] = basic;
+
+    // Rendering properties
+    nb::dict rendering;
+    rendering["shDegree"] = info.shDegree;
+    rendering["antialiased"] = info.antialiased;
+    result["rendering"] = rendering;
+
+    // Metadata
+    nb::dict meta;
+    meta["handedness"] = gf::HandednessToString(info.handedness);
+    meta["upAxis"] = gf::UpAxisToString(info.upAxis);
+    meta["unit"] = gf::LengthUnitToString(info.unit);
+    meta["colorSpace"] = gf::ColorSpaceToString(info.colorSpace);
+    result["meta"] = meta;
+
+    // Geometry statistics
+    if (info.numPoints > 0) {
+        nb::dict bounds;
+        bounds["x"] = nb::make_tuple(info.bounds.minX, info.bounds.maxX);
+        bounds["y"] = nb::make_tuple(info.bounds.minY, info.bounds.maxY);
+        bounds["z"] = nb::make_tuple(info.bounds.minZ, info.bounds.maxZ);
+        result["bounds"] = bounds;
+    }
+
+    // Scale statistics
+    if (info.scaleStats.count > 0) {
+        nb::dict scaleStats;
+        scaleStats["min"] = info.scaleStats.min;
+        scaleStats["max"] = info.scaleStats.max;
+        scaleStats["avg"] = info.scaleStats.avg;
+        result["scaleStats"] = scaleStats;
+    }
+
+    // Alpha statistics
+    if (info.alphaStats.count > 0) {
+        nb::dict alphaStats;
+        alphaStats["min"] = info.alphaStats.min;
+        alphaStats["max"] = info.alphaStats.max;
+        alphaStats["avg"] = info.alphaStats.avg;
+        result["alphaStats"] = alphaStats;
+    }
+
+    // Data size breakdown
+    nb::dict sizes;
+    sizes["positions"] = gf::FormatBytes(info.positionsSize);
+    sizes["scales"] = gf::FormatBytes(info.scalesSize);
+    sizes["rotations"] = gf::FormatBytes(info.rotationsSize);
+    sizes["alphas"] = gf::FormatBytes(info.alphasSize);
+    sizes["colors"] = gf::FormatBytes(info.colorsSize);
+    sizes["sh"] = gf::FormatBytes(info.shSize);
+    sizes["total"] = gf::FormatBytes(info.totalSize);
+    result["sizes"] = sizes;
+
+    // Extra attributes
+    if (!info.extraAttrs.empty()) {
+        nb::dict extras;
+        for (const auto &[name, size] : info.extraAttrs) {
+            extras[name.c_str()] = gf::FormatBytes(size);
+        }
+        result["extraAttrs"] = extras;
+    }
+
+    return result;
+}
+
+} // namespace
+
+/**
+ * GaussForge Python binding class
+ */
+class GaussForgePy {
+public:
+    GaussForgePy() : registry_(std::make_unique<gf::IORegistry>()) {}
+
+    nb::dict read(nb::bytes pyData, const std::string &format,
+                  bool strict = false) {
+        try {
+            const uint8_t *data =
+                reinterpret_cast<const uint8_t *>(pyData.c_str());
+            size_t size = pyData.size();
+
+            auto *reader = registry_->ReaderForExt(format);
+            if (!reader)
+                return err("No reader for " + format);
+
+            auto ir_or = reader->Read(data, size, {strict});
+            if (!ir_or)
+                return err(ir_or.error().message);
+
+            auto validation = gf::ValidateBasic(ir_or.value(), strict);
+            if (!validation.message.empty() && strict)
+                return err(validation.message);
+
+            nb::dict res;
+            res["data"] = gaussIRToPy(ir_or.value());
+            if (!validation.message.empty())
+                res["warning"] = validation.message;
+            return res;
+        } catch (const std::exception &e) {
+            return err(e.what());
+        }
+    }
+
+    nb::dict write(nb::dict pyIR, const std::string &format,
+                   bool strict = false) {
+        try {
+            auto *writer = registry_->WriterForExt(format);
+            if (!writer)
+                return err("No writer for " + format);
+
+            auto data_or = writer->Write(pyToGaussIR(pyIR), {strict});
+            if (!data_or)
+                return err(data_or.error().message);
+
+            nb::dict res;
+            res["data"] = nb::bytes(
+                reinterpret_cast<const char *>(data_or.value().data()),
+                data_or.value().size());
+            return res;
+        } catch (const std::exception &e) {
+            return err(e.what());
+        }
+    }
+
+    nb::dict convert(nb::bytes pyData, const std::string &inFormat,
+                     const std::string &outFormat, bool strict = false) {
+        try {
+            auto *reader = registry_->ReaderForExt(inFormat);
+            auto *writer = registry_->WriterForExt(outFormat);
+            if (!reader || !writer)
+                return err("Format handler not found");
+
+            const uint8_t *data =
+                reinterpret_cast<const uint8_t *>(pyData.c_str());
+            size_t size = pyData.size();
+
+            auto ir_or = reader->Read(data, size, {strict});
+            if (!ir_or)
+                return err(ir_or.error().message);
+
+            auto out_or = writer->Write(ir_or.value(), {strict});
+            if (!out_or)
+                return err(out_or.error().message);
+
+            nb::dict res;
+            res["data"] = nb::bytes(
+                reinterpret_cast<const char *>(out_or.value().data()),
+                out_or.value().size());
+            return res;
+        } catch (const std::exception &e) {
+            return err(e.what());
+        }
+    }
+
+    nb::list getSupportedFormats() {
+        nb::list formats;
+        for (auto &s : {"ply", "compressed.ply", "splat", "ksplat", "spz", "sog"})
+            formats.append(s);
+        return formats;
+    }
+
+    nb::dict getModelInfo(nb::bytes pyData, const std::string &format,
+                          size_t fileSize = 0) {
+        try {
+            const uint8_t *data =
+                reinterpret_cast<const uint8_t *>(pyData.c_str());
+            size_t size = pyData.size();
+
+            auto *reader = registry_->ReaderForExt(format);
+            if (!reader)
+                return err("No reader for " + format);
+
+            auto ir_or = reader->Read(data, size, {/*strict=*/false});
+            if (!ir_or)
+                return err(ir_or.error().message);
+
+            gf::ModelInfo info = gf::GetModelInfo(ir_or.value(), fileSize);
+
+            nb::dict res;
+            res["data"] = modelInfoToPy(info);
+            return res;
+        } catch (const std::exception &e) {
+            return err(e.what());
+        }
+    }
+
+    std::string getVersion() { return GAUSS_FORGE_VERSION_STRING; }
+
+private:
+    std::unique_ptr<gf::IORegistry> registry_;
+
+    nb::dict err(const std::string &m) {
+        nb::dict e;
+        e["error"] = m;
+        return e;
+    }
+};
+
+NB_MODULE(_core, m) {
+    m.doc() = "GaussForge - High-performance Gaussian Splatting format "
+              "conversion library";
+
+    nb::class_<GaussForgePy>(
+        m, "GaussForge",
+        "Main class for Gaussian Splatting format conversion")
+        .def(nb::init<>(), "Create a new GaussForge instance")
+        .def("read", &GaussForgePy::read, nb::arg("data"), nb::arg("format"),
+             nb::arg("strict") = false,
+             "Read Gaussian data from bytes. Returns dict with 'data' or "
+             "'error'.")
+        .def("write", &GaussForgePy::write, nb::arg("ir"), nb::arg("format"),
+             nb::arg("strict") = false,
+             "Write Gaussian IR to bytes. Returns dict with 'data' or 'error'.")
+        .def("convert", &GaussForgePy::convert, nb::arg("data"),
+             nb::arg("in_format"), nb::arg("out_format"),
+             nb::arg("strict") = false,
+             "Convert between formats. Returns dict with 'data' or 'error'.")
+        .def("get_supported_formats", &GaussForgePy::getSupportedFormats,
+             "Get list of supported format names.")
+        .def("get_model_info", &GaussForgePy::getModelInfo, nb::arg("data"),
+             nb::arg("format"), nb::arg("file_size") = 0,
+             "Get detailed model information. Returns dict with 'data' or "
+             "'error'.")
+        .def("get_version", &GaussForgePy::getVersion,
+             "Get library version string.");
+
+    // Module-level convenience function
+    m.def(
+        "get_version", []() { return std::string(GAUSS_FORGE_VERSION_STRING); },
+        "Get library version string.");
+}