PartTrellis — part-aware image-to-3D on TRELLIS.2 O-Voxel

PartTrellis packs the parts of an object into two interleaved volumes (contact graph contracted until bipartite), runs a two-stream rectified flow over TRELLIS.2's O-Voxel representation, and decodes each volume with the stock TRELLIS.2 decoder. Every part stays a clean, closed sub-mesh; no segmenter runs after generation.

This repository carries the released checkpoints, the ablation checkpoints from the paper, and the project code (data processing, training, inference, evaluation, figure rendering). Datasets are distributed separately.

Released pipeline (the checkpoints every number in the paper uses)

file	role	steps
ckpts/stage1_layout_sepocc_100k.pt	Stage-1 layout flow — separate weights per stream, per-stream I/O, disjointness loss L_ov (w=5)	100k
ckpts/stage2_slat_orig_100k.pt	Stage-2 SLat flow in the original TRELLIS.2 VAE latent space	100k
ckpts/shape_dec_next_dc_f16c32_fp16.pt	SLat decoder — stock microsoft/TRELLIS.2-4B file converted to .pt; identical weights to ckpts/shape_dec_next_dc_f16c32_fp16.safetensors there	—

Stage-1 sparse-structure decoding uses the stock microsoft/TRELLIS-image-large ss_dec_conv3d_16l8_fp16 (downloaded automatically by from_pretrained). Image conditioning uses gated facebook/dinov3-vitl16-pretrain-lvd1689m — accept the license once, then run with HF_HUB_OFFLINE=1 on cluster nodes.

Ablation checkpoints (self-trained)

file	paper table	note
ablations/stage1_no_Lov_100k.pt	disjointness ablation, w/o L_ov row	separate weights, otherwise identical to release
ablations/stage1_shared_emb_100k.pt	weight-sharing ablation, shared row	one backbone + volume embedding into AdaLN
ablations/volumes_dual_shared_100k.pt	#volumes ablation, dual arm	shared backbone, 2 volumes
ablations/volumes_tri_shared_100k.pt	#volumes ablation, tri arm	shared backbone, 3 volumes (greedy 3-coloring)
ablations/omnipart_port_tr2_44k.pt	OmniPart-representation port onto TRELLIS.2	token cost ×3.05, wall-clock ×3.78 vs ours at equal budget

External components — links only

component	where
TRELLIS.2 (code)	https://github.com/microsoft/TRELLIS.2
TRELLIS.2 weights (incl. shape enc/dec)	https://huggingface.co/microsoft/TRELLIS.2-4B
TRELLIS v1 weights (ss decoder)	https://huggingface.co/microsoft/TRELLIS-image-large
DINOv3 conditioning	https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m (gated)
X-Part / P3-SAM (baseline)	https://github.com/Tencent-Hunyuan/Hunyuan3D-Part
Hunyuan3D-2.1 (baseline generator)	https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1
OmniPart (baseline)	https://github.com/HKU-MMLab/OmniPart
PartPacker (baseline)	https://github.com/NVlabs/PartPacker
AutoPartGen (baseline)	no public code at time of writing; evaluated on author-released outputs

Code

file	contents
code/trellis2_part_code.tar.gz	full project tree: data processing (attraction/data/ — O-Voxel prep, bipartite contraction, latent prep), training configs & trainers, scripts/infer_e2e_dual.py, evaluation (scripts/eval_parts_full.py, scripts/eval_parts_hungarian.py), plus all project docs (OVOXEL_TRUTH.md, DATA_PIPELINE.md, status notes)
code/eval1000_helpers.tar.gz	test-split lists, alignment helpers (48 signed-axis-perm oracle), aggregation and figure-assembly scripts
code/blender_kit.tar.gz	Blender 4.2 Cycles rendering kit used for every figure (warm studio backdrop, part palettes, registered multi-panel framing); also on GitHub: https://github.com/AuroraRyan0301/Blender-Visualization-Skill — the tarball carries the studio-backdrop commit in case it is not pushed there yet

Environment notes

• Python 3.10, PyTorch matching your CUDA driver (cu126 wheels for driver 570).
• pip install 'mpmath<1.4' (sympy/torch import breaks on 1.4).
• O-Voxel is field-free: meshes are voxelized as-is after rigid normalization only — never remesh or watertight-repair inputs.

Inference

python trellis2_part/scripts/infer_e2e_dual.py \
  --obj_list LIST.txt --out_dir OUT \
  --p1_ckpt ckpts/stage1_layout_sepocc_100k.pt --p1_variant separate --p1_per_stream_io \
  --p2_ckpt ckpts/stage2_slat_orig_100k.pt \
  --shape_dec_ckpt ckpts/shape_dec_next_dc_f16c32_fp16.pt \
  --renders_root RENDERS --cond_subdir renders_cond_pbr

Evaluation

scripts/eval_parts_full.py computes CD/F1 at whole-object and part level with the 48 signed-axis-permutation alignment oracle; scripts/eval_parts_hungarian.py adds the one-to-one Hungarian detection metric (cost = ‖Δcentroid‖₂ + CD in the normalized unit cube; a match counts at part CD < τ).