v3p 0.1.0
Vuer 3DGS Processing - Tools for Gaussian Splatting workflows.
License: MIT
Requires Python: >=3.8

# v3p - Vuer 3DGS Processing

Tools for Gaussian Splatting (3DGS) processing workflows. Built with [params-proto](https://github.com/geyang/params-proto) for configuration management.

[![PyPI version](https://badge.fury.io/py/v3p.svg)](https://badge.fury.io/py/v3p)
[![Documentation](https://readthedocs.org/projects/v3p/badge/?version=latest)](https://v3p.readthedocs.io/en/latest/)

## Installation

```bash
pip install v3p
```

For development:

```bash
git clone https://github.com/vuer-ai/vuer-3dgs-processing.git
cd vuer-3dgs-processing
pip install -e ".[dev]"
```

## Quick Start

### CLI Usage

The `v3p` command provides several subcommands for processing 3DGS point clouds:

```bash
# Show available commands
v3p

# Process a point cloud
v3p process --input-path input.ply --output-path output.ply

# Convert between formats
v3p convert --input-path input.ply --output-path output.pcd
```

### Python API

```python
import v3p
print(v3p.__version__)
```

Using the configuration classes directly:

```python
from v3p.scripts.process import ProcessConfig, main

# Configure via class attributes
ProcessConfig.input_path = "input.ply"
ProcessConfig.output_path = "output.ply"
ProcessConfig.voxel_size = 0.01
ProcessConfig.verbose = True

# Run processing
main()
```

## Commands

### v3p process

Process 3DGS point clouds with filtering and downsampling.

```bash
v3p process --input-path <path> [options]
```

Options:
- `--input-path`: Path to input PLY or point cloud file (required)
- `--output-path`: Path to output file (default: output.ply)
- `--voxel-size`: Voxel size for downsampling (default: 0.01)
- `--remove-outliers`: Remove statistical outliers (default: True)
- `--num-neighbors`: Number of neighbors for outlier detection (default: 20)
- `--std-ratio`: Standard deviation ratio for outlier removal (default: 2.0)
- `--verbose`: Enable verbose output

### v3p convert

Convert between point cloud formats.

```bash
v3p convert --input-path <path> --output-path <path> [options]
```

Options:
- `--input-path`: Path to input file (required)
- `--output-path`: Path to output file (required)
- `--input-format`: Input format - auto, ply, pcd, xyz (default: auto)
- `--output-format`: Output format - ply, pcd, xyz (default: ply)
- `--binary`: Write binary format when supported (default: True)
- `--verbose`: Enable verbose output

## Configuration with params-proto

v3p uses [params-proto](https://github.com/geyang/params-proto) for configuration management. This allows you to:

1. **Set parameters via CLI**: All config class attributes become CLI flags
2. **Set parameters programmatically**: Modify class attributes directly
3. **Use sweep files**: Generate parameter sweeps for batch processing

Example sweep file:

```python
from params_proto import Sweep
from v3p.scripts.process import ProcessConfig

with Sweep(ProcessConfig) as sweep:
    ProcessConfig.input_path = "input.ply"
    with sweep.product:
        ProcessConfig.voxel_size = [0.01, 0.02, 0.05]

sweep.save("process_sweep.jsonl")
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
make test

# Build and preview documentation
make preview

# Build wheel
make wheel

# Publish to PyPI
make publish
```

## Documentation

Full documentation: https://v3p.readthedocs.io/en/latest/

## License

MIT