Upload README.md

README.md

@@ -0,0 +1,99 @@
+---
+license: mit
+pipeline_tag: image-to-3d
+base_model: stabilityai/TripoSR
+tags:
+- lux3d
+- rust
+- candle
+- safetensors
+- canonical-weights
+- 3d
+- image-to-3d
+- mesh-generation
+- triposr
+---
+
+# Lux3D TripoSR Canonical Weights
+
+This repository contains the canonicalized `safetensors` export of the TripoSR checkpoint used by the Lux3D `3d-rs` runtime.
+
+The package converts the original TripoSR checkpoint/config pair into a stable runtime layout with explicit provenance and integrity metadata.
+
+## Model Details
+
+- Model family: `triposr`
+- Canonical file: `model.safetensors`
+- Tensor count: `549`
+- Primary runtime target: Lux3D `3d-rs`
+- Typical output: mesh export (`.obj`)
+
+## Included Files
+
+- `model.safetensors`: canonical model weights for runtime loading
+- `resolved_config.json`: normalized JSON snapshot of the effective TripoSR config
+- `manifest.json`: provenance metadata for the canonical package
+- `checksums.json`: integrity data for the files in this package
+
+## Usage With Lux3D
+
+This folder is designed to be uploaded as a standalone Hugging Face model repository and then restored into:
+
+```text
+<repo-root>/3d/canonical-weights/triposr/
+```
+
+The Lux3D CLI will validate and use the package. The example below assumes you run it from the `3d-rs/` directory:
+
+```powershell
+cargo run -p lux3d-cli -- inspect --repo-root .. triposr
+cargo run -p lux3d-cli -- run --repo-root .. triposr --source ../tp/3d/TripoSR/examples/horse.png --mc-resolution 256 --mc-threshold 25.0 --output ../3d/_generated/triposr.obj
+```
+
+## Provenance
+
+- Upstream source model: [`stabilityai/TripoSR`](https://huggingface.co/stabilityai/TripoSR)
+- Canonicalization flow: `3d-rs/tools/python_baseline/normalize_weights.py`
+- Raw source files expected by Lux3D before normalization:
+  - `3d/models/stabilityai-TripoSR/model.ckpt`
+  - `3d/models/stabilityai-TripoSR/config.yaml`
+
+The exact source checksum set is recorded in `manifest.json`. The integrity of the uploaded package is recorded in `checksums.json`.
+
+## Intended Use
+
+This package is intended for:
+
+- single-image 3D reconstruction in Lux3D
+- mesh generation workflows using TripoSR canonical weights
+- reproducible local/runtime validation
+
+This package is not meant to replace the full upstream TripoSR repository. It is the runtime-focused canonical weight package for Lux3D.
+
+## Limitations
+
+- Verified Lux3D inference currently assumes CUDA.
+- This package includes canonical runtime artifacts only.
+- Texture baking and other extended upstream utilities are outside the scope of this package.
+
+## License
+
+The upstream TripoSR model and code are distributed under MIT.
+
+- Upstream model page: [`stabilityai/TripoSR`](https://huggingface.co/stabilityai/TripoSR)
+- Local package notice: [LICENSE](LICENSE)
+
+Retain upstream attribution when redistributing the package.
+
+## Citation
+
+If you use TripoSR in research, cite the upstream work:
+
+```bibtex
+@article{tripoSR2024,
+  title={TripoSR: Fast 3D Object Reconstruction from a Single Image},
+  author={Tochilkin, Dmitry and Pankratz, David and Liu, Zexiang and Huang, Zixuan and Letts, Adam and Li, Yangguang and Liang, Ding and Laforte, Christian and Jampani, Varun and Cao, Yan-Pei},
+  journal={arXiv preprint arXiv:2403.02151},
+  year={2024}
+}
+```