### Install and Setup CompGS

Source: https://context7.com/ucdvision/compact3d/llms.txt

Follow these steps to clone the CompGS repository, install the official 3DGS, and apply the CompGS patch. Ensure your CUDA environment is set up for 3DGS.

```bash
# 1. Clone CompGS
git clone https://github.com/UCDvision/compact3d
cd compact3d

# 2. Clone and install the official 3DGS repo (follow its README for CUDA env)
git clone https://github.com/graphdeco-inria/gaussian-splatting --recursive
cd gaussian-splatting
pip install -e submodules/diff-gaussian-rasterization
pip install -e submodules/simple-knn
cd ..

# 3. Install the bitarray dependency
pip install bitarray

# 4. Move CompGS files into the gaussian-splatting tree
bash move_files_to_gsplat.sh
# Moves: train_kmeans.py, render.py, decompress_to_ply.py, run.sh
#        scene/kmeans_quantize.py, scene/gaussian_model.py, scene/__init__.py
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/ucdvision/compact3d/blob/main/README.md

Clone the Compact3D repository and install the necessary dependencies, including the 'bitarray' package for efficient storage of k-means indices.

```shell
git clone https://github.com/UCDvision/compact3d
cd compact3d
pip install bitarray
```

--------------------------------

### End-to-End CompGS Training

Source: https://context7.com/ucdvision/compact3d/llms.txt

Runs CompGS training with interleaved K-Means quantization. Key parameters control quantization start, codebook size, and opacity regularization.

```bash
# Typical run.sh invocation — CompGS-4k with opacity regularization
cd gaussian-splatting

path_base=/data/nerf_datasets
ncls=4096          # clusters for scale/rot/dc
ncls_sh=512        # clusters for spherical harmonics
kmeans_iters=10    # K-Means iterations per assignment step
st_iter=15000      # start quantization after 15k warmup iters
max_iters=30000
max_prune_iter=20000
lambda_reg=1e-7

CUDA_VISIBLE_DEVICES=0 python train_kmeans.py \
  --port 4060 \
  -s "$path_base/tandt/train" \
  -m output/exp_001/tandt/train \
  --start_checkpoint output/exp_001_noquant/tandt/train/chkpnt15000.pth \
  --kmeans_ncls    $ncls \
  --kmeans_ncls_sh $ncls_sh \
  --kmeans_ncls_dc $ncls \
  --kmeans_st_iter $st_iter \
  --kmeans_iters   $kmeans_iters \
  --total_iterations $max_iters \
  --quant_params sh dc rot scale \
  --kmeans_freq 100 \
  --opacity_reg \
  --lambda_reg $lambda_reg \
  --max_prune_iter $max_prune_iter \
  --eval
# Output: point_cloud.ply + kmeans_inds.bin + kmeans_centers.pth + kmeans_args.npy
```

--------------------------------

### Render Novel Views from Quantized Model

Source: https://context7.com/ucdvision/compact3d/llms.txt

Generates PNG renders from a CompGS checkpoint using the standard gaussian_renderer.render().

```bash
# Generate test-set renders from the quantized model
python render.py \
  -m output/exp_001/tandt/train \
  --skip_train \
  --load_quant
# Renders saved to: output/exp_001/tandt/train/test/ours_30000/renders/*.png
#                   output/exp_001/tandt/train/test/ours_30000/gt/*.png

# Evaluate PSNR / SSIM / LPIPS on the renders
python metrics.py -m output/exp_001/tandt/train
# Prints per-scene metrics; results.json written to the model directory
```

--------------------------------

### Run Training Script

Source: https://github.com/ucdvision/compact3d/blob/main/README.md

Navigate to the gaussian-splatting directory and execute the training script. Modify dataset and output paths in 'run.sh'. For faster training with minor performance impact, adjust 'kmeans_iters' and 'kmeans_freq'.

```shell
cd gaussian-splatting
bash run.sh
```

--------------------------------

### Load Quantized Scene with GaussianModel

Source: https://context7.com/ucdvision/compact3d/llms.txt

Initializes a GaussianModel and loads a scene using quantized weights. Automatically detects the highest saved iteration if load_iteration is -1. Requires a ModelParams-compatible namespace.

```python
from scene import Scene
from scene.gaussian_model import GaussianModel
from arguments import ModelParams
from argparse import Namespace

# Build a minimal ModelParams-compatible namespace
args = Namespace(
    model_path='output/exp_001/tandt/train',
    source_path='/data/nerf_datasets/tandt/train',
    images='images',
    eval=True,
    white_background=False,
    sh_degree=3,
    resolution=-1,
    data_device='cuda',
)
model_params = ModelParams.__new__(ModelParams)
model_params.__dict__.update(vars(args))

gaussians = GaussianModel(sh_degree=3)

# Load scene at the best saved iteration, using quantized weights
scene = Scene(
    args=model_params,
    gaussians=gaussians,
    load_iteration=-1,      # -1 → auto-detect highest iteration
    shuffle=False,
    load_quant=True
)

print('Loaded iteration:', scene.loaded_iter)
print('Test cameras:', len(scene.getTestCameras()))
print('Gaussians loaded:', gaussians._xyz.shape[0])
```

--------------------------------

### Decompress Quantized Model to Standard PLY

Source: https://context7.com/ucdvision/compact3d/llms.txt

Loads a CompGS-quantized checkpoint and writes a standard PLY file compatible with off-the-shelf 3DGS viewers.

```bash
# Decompress to a viewer-compatible PLY file
python decompress_to_ply.py -m output/exp_001/tandt/train
# Finds the highest iteration automatically (--iteration -1 default)
# Writes: output/exp_001/tandt/train/point_cloud/iteration_30000/point_cloud_decompressed.ply

# Decompress a specific iteration
python decompress_to_ply.py -m output/exp_001/tandt/train --iteration 7000
```

--------------------------------

### Move Project Files to Gaussian Splatting Directory

Source: https://github.com/ucdvision/compact3d/blob/main/README.md

Execute the provided script to move the Compact3D project files into the correct locations within the cloned 3D Gaussian Splatting directory.

```shell
bash move_files_to_gsplat.sh
```

--------------------------------

### Verify File Sizes

Source: https://context7.com/ucdvision/compact3d/llms.txt

Checks the size of compressed model files in KB.

```python
import os
print(os.path.getsize(f'{out_dir}/kmeans_inds.bin') / 1024, 'KB')   # << raw float32 size
print(os.path.getsize(f'{out_dir}/kmeans_centers.pth') / 1024, 'KB')
```

--------------------------------

### Render and Evaluate Trained Model

Source: https://github.com/ucdvision/compact3d/blob/main/README.md

Use the provided Python scripts to generate renderings and compute error metrics for the trained model. Use '--skip_train' to avoid rendering from train set viewpoints and '--load_quant' to load the quantized model.

```python
python render.py -m <path to trained model> --skip_train --load_quant # Generate renderings
```

```python
python metrics.py -m <path to trained model> # Compute error metrics on renderings
```

--------------------------------

### Initialize and Use Quantize_kMeans for 3DGS Attributes

Source: https://context7.com/ucdvision/compact3d/llms.txt

Initialize `Quantize_kMeans` for different Gaussian attributes (scale+rotation, SH, DC color) and use its `forward` methods within the training loop. The `assign` flag controls full K-Means reassignment versus efficient center updates.

```python
from scene.kmeans_quantize import Quantize_kMeans

# Quantize the scale+rotation covariance jointly (CompGS-4k variant)
kmeans_scrot = Quantize_kMeans(num_clusters=4096, num_iters=10)

# Inside the training loop (iteration > kmeans_st_iter):
do_assign = (iteration % freq_cls_assn == 1)   # full reassign every 100 iters

# Joint scale+rotation quantization (shares one codebook of size 4096)
kmeans_scrot.forward_scale_rot(gaussians, assign=do_assign)
# Sets gaussians._scaling_q and gaussians._rotation_q to straight-through
# quantized tensors; gradients flow back to _scaling and _rotation.

# Spherical harmonics (rest coefficients) – separate codebook, 512 clusters
kmeans_sh = Quantize_kMeans(num_clusters=512, num_iters=10)
kmeans_sh.forward_frest(gaussians, assign=do_assign)
# Sets gaussians._features_rest_q

# DC color – separate codebook
kmeans_dc = Quantize_kMeans(num_clusters=4096, num_iters=10)
kmeans_dc.forward_dc(gaussians, assign=do_assign)
# Sets gaussians._features_dc_q

# After training: cluster assignments live in kmeans.cls_ids (torch.Tensor)
# Codebook centers live in kmeans.centers  (num_clusters × vec_dim)
print(kmeans_scrot.centers.shape)   # e.g. torch.Size([4096, 7])  (3 scale + 4 rot)
print(kmeans_scrot.cls_ids.shape)   # torch.Size([N_gaussians])
```

--------------------------------

### Convert Quantized Model to PLY

Source: https://github.com/ucdvision/compact3d/blob/main/README.md

Use this script to convert quantized 3D Gaussian Splatting models to a PLY file for visualization with standard 3D viewers. The output file will be named 'point_cloud_decompressed.ply' in the project's save path.

```shell
python decompress_to_ply.py -m <path to trained model>
```

--------------------------------

### Load Quantized or Standard GaussianModel

Source: https://context7.com/ucdvision/compact3d/llms.txt

Loads a CompGS-quantized or standard PLY model. Set load_quant=True to load compressed checkpoints.

```python
from scene.gaussian_model import GaussianModel

# Load a quantized CompGS checkpoint for inference / rendering
gaussians = GaussianModel(sh_degree=3)
gaussians.load_ply(
    path='output/exp_001/tandt/train/point_cloud/iteration_30000/point_cloud.ply',
    load_quant=True      # reads kmeans_inds.bin + kmeans_centers.pth alongside the ply
)
# gaussians._xyz, _features_dc, _features_rest, _scaling, _rotation, _opacity
# are all populated as CUDA nn.Parameters ready for rendering.

# Load a standard (non-quantized) PLY for comparison
gaussians_full = GaussianModel(sh_degree=3)
gaussians_full.load_ply(
    path='output/exp_001_noquant/tandt/train/point_cloud/iteration_30000/point_cloud.ply',
    load_quant=False
)

print('Quantized  Gaussians:', gaussians._xyz.shape[0])
print('Full model Gaussians:', gaussians_full._xyz.shape[0])
# Both produce the same rendering output via the standard gaussian_renderer.render()
```

--------------------------------

### Save Compressed Model with `save_kmeans`

Source: https://context7.com/ucdvision/compact3d/llms.txt

Use the `save_kmeans` function to serialize the trained quantization artifacts. This includes bit-packed cluster indices in a `.bin` file, codebook tensors in a `.pth` file, and metadata in a `.npy` file.

```python
from train_kmeans import save_kmeans, dec2binary
from bitarray import bitarray
import numpy as np, torch

# Assume training finished; kmeans objects are ready
kmeans_list    = [kmeans_dc, kmeans_sh, kmeans_scrot]
quant_params   = ['dc', 'sh', 'scale_rot']   # matches order in kmeans_list
out_dir        = 'output/exp_001/tandt/train/point_cloud/iteration_30000'

save_kmeans(kmeans_list, quant_params, out_dir)
# Writes:
#   out_dir/kmeans_inds.bin      – bit-packed cluster indices for all params
#   out_dir/kmeans_args.npy      – {'params': [...], 'n_bits': 12, 'total_len': ...}
#   out_dir/kmeans_centers.pth   – {'dc': Tensor, 'sh': Tensor, 'scale_rot': Tensor}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.