GaussTrace

This repository is the implementation of the paper GaussTrace: Provenance Analysis of 3D Gaussian Splatting Models with Evidence-based LLM Reasoning [ICML 2026].

Installation

git clone https://github.com/haolianghan/GaussTrace-code.git

cd GaussTrace-code

Python 3.8+ recommended.

pip install -r requirements.txt

LLM API Configuration

Configure the LLM credentials through environment variables (or a .env file) or a JSON config file. No keys are hard-coded in the code.

export LLM_API_KEY="your-key"
export LLM_BASE_URL="your-endpoint"
export LLM_MODEL="your-model"

or copy config.example.json to config.json, fill in api_key, and pass it with --config.

By default the pipeline targets the HKBU GenAI Platform and authenticates with an api-key request header. If you use another LLM platform (e.g. OpenAI), adjust GSProvenance/llm.py's submit() accordingly (URL path, auth header, and request body).

Data

Our dataset is available at https://huggingface.co/datasets/Haoliang123/3DGS_Provenance.

The input 3DGS .ply files are organized as scenes. Download the dataset and put each scene under a subdirectory of data/ (e.g. data/face/, data/counter/). Paths are relative to the data/ directory (where scenes.json lives):

{
  "face": [
    "face/face.ply",
    "face/skin_tone.ply",
    "face/hulk.ply"
  ]
}

Repository Layout

.
├── GSProvenance/          # shared package
│   ├── __init__.py
│   ├── io.py              # load_ply
│   ├── stats.py           # statistics, simulations
│   └── llm.py             # configurable LLM client
├── reasoning.py           # main entry point (--scene)
├── data/
│   └── scenes.json        # scene name -> model paths (relative)
├── config.example.json    # LLM configuration template
├── requirements.txt
└── .gitignore

Usage

python reasoning.py \
  --scene face \
  --output output/provenance_graph.json \
  --adjacency output/adjacency_matrix.npy \
  --config config.json

• --scene selects a scene defined in data/scenes.json (use --scenes <path> to point at a different scenes file).

Outputs:

• provenance_graph.json — nodes, edges with LLM-given reasons, and the ModelID -> file mapping.
• adjacency_matrix.npy — 0/1 adjacency matrix of the inferred graph.

the provenance graph is produced by an LLM, so re-running on identical inputs may yield slightly different edges (this is inherent to LLM sampling). Each run writes the inferred graph and adjacency matrix to the specified output files.

Citation

If you find our paper useful for your work please cite:

@inproceedings{han2026gausstrace,
  author    = {Haoliang Han and Ziyuan Luo and Renjie Wan},
  title     = {GaussTrace: Provenance Analysis of 3D Gaussian Splatting Models with Evidence-based LLM Reasoning},
  booktitle = {International Conference on Machine Learning},
  year      = {2026}
}