Polish Arbor model card

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -10,25 +10,34 @@ pipeline_tag: text-to-3d
 
 # Arbor
 
-Arbor is a text-conditioned 3D generation model with geometry constraints. It accepts a prompt plus constraint meshes and generates a 3D mesh through a geometry-conditioned sparse-structure stage followed by TRELLIS SLAT mesh decoding.
+Explicit Geometric Conditioning for Controllable 3D Asset Generation
+
+![Arbor teaser](./assets/arbor_teaser.jpg)
+
+[Project Page](https://arbor.jdihlmann.com/) | [Paper](https://arbor.jdihlmann.com/downloads/arbor_paper.pdf) | [GitHub](https://github.com/Stability-AI/arbor) | [Citation](#citation)
+
+Arbor generates 3D assets from a text prompt and typed geometry constraints. Hull regions mark where geometry should exist, avoidance regions mark space that should stay empty, and touch regions mark surfaces the object should contact or keep reachable.
 
 Please note: For individuals or organizations generating annual revenue of US $1,000,000 (or local currency equivalent) or more, regardless of the source of that revenue, you must obtain an enterprise commercial license directly from Stability AI before commercially using Arbor, derivative works of Arbor, or outputs from Arbor. See https://stability.ai/license and https://stability.ai/enterprise.
 
 ## Model Description
 
-- Developed by: Stability AI
+- Developed by: [Stability AI](https://stability.ai/)
+- Authors: Jan-Niklas Dihlmann, Andreas Engelhardt, Simon Donne, Hendrik Lensch, Mark Boss
 - Model type: Text and geometry constrained 3D generation model
 - Repository: https://github.com/Stability-AI/arbor
-- Checkpoint: `denoiser_ema0.9999_step0053000.pt`
+- Project page: https://arbor.jdihlmann.com/
 - Base stack: TRELLIS text-to-3D and TRELLIS.2 constraint encoding components
 
 ## Files
 
 - `arbor_sparse_structure_config.json`: public inference config for Arbor sparse-structure generation.
-- `slat_flow_txt_dit_B_64l8p2_geo_router_v1_ft_fp16.json`: SLAT mesh generation config used by the public inference pipeline.
-- `denoiser_ema0.9999_step0053000.pt`: released Arbor sparse-structure checkpoint.
+- `slat_flow_txt_dit_B_64l8p2_geo_router_v1_ft_fp16.json`: SLAT mesh generation config used by the release pipeline.
+- `denoiser_ema0.9999_step0053000.pt`: public Arbor sparse-structure checkpoint.
 - Optional parity artifact, if uploaded: `denoiser_step0053000.pt`.
 
+The GitHub code downloads these files automatically when possible. You can also download them explicitly with the helper script shown below.
+
 ## Quickstart
 
 ```bash
@@ -43,10 +52,10 @@ conda install pytorch==2.4.0 torchvision==0.19.0 pytorch-cuda=11.8 -c pytorch -c
 hf auth login
 hf auth whoami
 python scripts/download_model_from_hf.py --repo-id StabilityLabs/arbor --output-dir artifacts/model
-python examples/run_manual_example.py --example bus_013 --output-root outputs/manual_examples --evaluate
+python examples/run_manual_example.py --example chair_080 --output-root outputs/manual_examples --evaluate
 ```
 
-For non-interactive shells, store a read token with:
+For non-interactive shells, pass a token without saving it in shell history:
 
 ```bash
 read -s HF_TOKEN
@@ -55,9 +64,24 @@ unset HF_TOKEN
 hf auth whoami
 ```
 
+## Demo Examples
+
+The GitHub release includes curated constraint meshes and a public evaluator that renders condition-following panels.
+
+![Arbor demo examples](./assets/demo_examples.png)
+
+Run the examples with:
+
+```bash
+python examples/run_manual_example.py --example bus_013 --output-root outputs/manual_examples --evaluate
+python examples/run_manual_example.py --example chair_080 --output-root outputs/manual_examples --evaluate
+python examples/run_manual_example.py --example piano_038 --output-root outputs/manual_examples --evaluate
+python examples/run_manual_example.py --example sink_015 --output-root outputs/manual_examples --evaluate
+```
+
 ## Evaluation Outputs
 
-The GitHub release includes a public `arbor-evaluate` command that computes condition-following metrics and renders inspection panels without training code or the benchmark runner. Static panels render four camera views for each visual column so the object can be inspected from all sides.
+The public `arbor-evaluate` command computes condition metrics and renders inspection panels without training code or benchmark launchers.
 
 ```bash
 arbor-evaluate \
@@ -65,12 +89,18 @@ arbor-evaluate \
   --hull examples/constraints/bus__bus_013__19cbb410/hull_constraint.ply \
   --avoidance examples/constraints/bus__bus_013__19cbb410/avoidance_constraint.ply \
   --touch examples/constraints/bus__bus_013__19cbb410/touchable_constraint.ply \
-  --source-mesh examples/constraints/bus__bus_013__19cbb410/gt_mesh.ply \
+  --reference-mesh examples/constraints/bus__bus_013__19cbb410/gt_mesh.ply \
   --sparse-structure outputs/manual_examples/bus_013/ss_surface.npz \
   --output-dir outputs/manual_examples/bus_013/evaluation
 ```
 
-The evaluator writes `metrics.json`, `metrics_flat.json`, and a four-view `condition_panel.png`; pass `--save-gif` to also write an animated `condition_orbit.gif`. The default orbit speed is 150 ms per frame, configurable with `--gif-duration-ms`.
+`--reference-mesh` is optional. It adds reference metrics such as Chamfer distance and F-score. It is not used for generation.
+
+The evaluator writes `metrics.json`, `metrics_flat.json`, and a four-view `condition_panel.png`. Pass `--save-gif` to also write `condition_orbit.gif`; the default speed is 150 ms per frame.
+
+## Coordinate Note
+
+Arbor follows constraints inside the normalized TRELLIS object box. It does not generate in metric world units. TRELLIS tends to center the asset and make it use the available box, so constraints should describe relative shape inside that box. If one region grows, another part can look smaller because the final asset is still normalized to the same space.
 
 ## Intended Uses
 
@@ -80,10 +110,17 @@ Intended uses include research and creative workflows involving constrained 3D a
 
 Arbor is not intended to generate factual representations of people, events, products, or places. Use must comply with Stability AI's Acceptable Use Policy and license terms.
 
-## Safety
+## Citation
 
-Users should evaluate generated outputs for their own application constraints and apply additional mitigations where needed. Report safety issues to safety@stability.ai and security issues to security@stability.ai.
+```bibtex
+@misc{dihlmann2026arbor,
+  author = {Dihlmann, Jan-Niklas and Engelhardt, Andreas and Donne, Simon and Lensch, Hendrik and Boss, Mark},
+  title = {Arbor: Explicit Geometric Conditioning for Controllable 3D Asset Generation},
+  booktitle = {Preprint},
+  year = {2026}
+}
+```
 
-## Citation
+## Safety
 
-Citation information will be updated with the public Arbor paper record. Until then, cite the Arbor project and upstream TRELLIS work when using this model.
+Users should evaluate generated outputs for their own application constraints and apply additional mitigations where needed. Report safety issues to safety@stability.ai and security issues to security@stability.ai.