🧭 hermit-trellis2

Training-free Hermite-cached acceleration for TRELLIS.2-4B image-to-3D — ~1.9× fewer network evaluations, lossless, one line of code.

TRELLIS.2-4B · 1024_cascade (mesh + texture) · training-free · single RTX 5090 · MIT

HiCache++ variant: an exponential (DMD/Prony) forecast variant of this repo lives in hermit-trellis2-plus-plus — same carved-hybrid, with the sparse-structure velocity forecast on a Dynamic-Mode-Decomposition basis instead of the Hermite polynomial.

When to use this repo

These repos are complementary accelerators, not competing solutions — each speeds up a different base generator, and the + / ++ suffix is a method choice, not a rival product. Pick by (1) which base model you run, then (2) which forecast basis you want:

• + (HiCache / scaled-Hermite): the published polynomial velocity-forecast basis — conservative, reproduces the HiCache paper. Use it to deploy the established method.
• ++ (HiCache++ / DMD exponential): our Dynamic-Mode-Decomposition basis — the same near-lossless quality at wider skip intervals, where the polynomial diverges. Use it when you push the cache interval for more speed.
• standalone / model-agnostic: hicache-plus-plus — the forecaster itself, to add DMD caching to your own diffusion/flow model.
• fast-trellis2 = the TaylorSeer baseline fork (the upstream "Fast" accel) — the v2 reference point, not a HiCache variant.

This repo: hermit-trellis2 — TRELLIS.2-4B × HiCache (Hermite) — carved-hybrid on the 4B v2 model.

hermit-trellis2 is TRELLIS.2-4B image-to-3D with a training-free Hermite carved-hybrid built into the flow-matching sampler. It forecasts the model's final CFG-combined velocity with a dual-scaled Hermite basis on the sparse-structure stage and carves the structured-latent tokens — so the sampler spends far fewer network evaluations per asset, with the weights, decoders, and the full 1024_cascade mesh + texture left untouched. (The name is a nod to the Hermite forecast at its core — and yes, it's happy running on its own.)

pipe.enable_faster()        # the Hermite carved-hybrid — one line, lossless vs the base model
pipe.enable_faster("base")  # stock TRELLIS.2 sampler (kill-switch)

What it does. Two accelerations act on the velocity the samplers emit, one per stage class:

• Hermite (HiCache) on the sparse-structure stage — a dual-scaled physicist's-Hermite forecast of the velocity that skips network calls fixing the coarse occupancy volume, while always computing the early steps where topology is decided.
• Token-carved SLaT on the structured-latent stages — a learned-cadence temporal skip plus spatial token carving that recomputes only the high-frequency voxels each step.

Where it sits. hermit-trellis2 is the v2 instance of the Hermite carved-hybrid — the same method that on TRELLIS v1 beats Fast-TRELLIS on both speed and quality (sibling repo faster-trellis). On TRELLIS.2 it is a ~1.9× lossless accelerator of the base model; the alternative TaylorSeer port, fast-trellis2, reaches comparable speed and is a touch ahead on the v2 mesh F-score below — TRELLIS.2's fast baseline is already strong, leaving the two on par on v2. The Hermite forecast's distinction is that it stays accurate at long skip horizons where the monomial TaylorSeer basis diverges. It ships as a single, lossless-target configuration — no mode menu.

See Results. GF_CARVE_RATIO / GF_HICACHE_SS_INTERVAL / GF_HICACHE_FIRST_ENHANCE override the defaults for tuning.

Quickstart

git clone https://github.com/Archerkattri/hermit-trellis2
cd hermit-trellis2
# TRELLIS.2 runtime deps (torch, flash-attn, spconv/flex_gemm, o-voxel, cumesh,
# nvdiffrast) per microsoft/TRELLIS.2. Place / symlink weights at ckpts/TRELLIS.2-4B.

from trellis2.pipelines import Trellis2ImageTo3DPipeline
from PIL import Image

pipe = Trellis2ImageTo3DPipeline.from_pretrained("ckpts/TRELLIS.2-4B").to("cuda")
pipe.enable_faster()                                  # ← the only added line

out  = pipe.run(Image.open("input_rgba.png"), pipeline_type="1024_cascade")
mesh = out[0]

example_faster.py is the runnable end-to-end script; example.py is the stock TRELLIS.2 demo.

SPARSE_CONV_BACKEND=spconv SPCONV_ALGO=native ATTN_BACKEND=flash_attn \
PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True CUDA_VISIBLE_DEVICES=0 \
  python example_faster.py --image input_rgba.png

Results

40 Toys4K objects, RTX 5090, TRELLIS.2-4B, full 1024_cascade (mesh + texture), seed 42. Geometry is scored on the o-voxel mesh decoder with area-weighted surface sampling, after a globally-optimal (Go-ICP) similarity alignment to the ground-truth mesh — the same harness across rows, over the 35 objects all three completed. Latency is end-to-end generation, weights resident.

_{CD ↓ lower is better; F1 ↑ higher is better. hermit-trellis2 accelerates the base model ~1.9× at near-lossless quality (F1 mean 0.869 vs 0.860; CD within run-to-run noise). On this v2 mesh F-score the TaylorSeer sibling fast-trellis2 is a touch ahead — TRELLIS.2's strong fast baseline leaves little headroom — so the two are best read as on par on v2. The Hermite forecast's decisive advantage shows on v1 (faster-trellis: 1.35× faster and higher F-score than Fast-TRELLIS) and in its long-horizon stability, where TaylorSeer's monomials diverge.}

Sign-convention update (2026-06-10)

The vendored Hermite forecast evaluated the basis at x = -k; the corrected convention from hicache-plus-plus 1.2.0 is x = +k (the upstream TaylorSeer distance convention; -k flips every odd-order term, extrapolating backwards). This fork now ships the corrected forecast. The published numbers above were measured with the as-released code and remain valid as-measured; re-validation on this model is pending. On the two family models re-validated so far on their published protocols (Hunyuan3D-2 mini and the SAM 3D Objects slat stage; see hunyuan2-plus and sam3d-plus), the corrected forecast matched the as-released quality at the published intervals.

How it works

TRELLIS.2 samples a shape in three flow-matching stages — sparse structure (SS), shape SLaT (the 512→1024 cascade), and texture SLaT (guidance = 1, no CFG) — each a short Euler sampler. Both accelerators act on the final velocity pred_v those samplers emit.

Δ⁰F_t = F_t
ΔⁱF_t = (Δⁱ⁻¹F_t − Δⁱ⁻¹F_{t−N}) / N

F̂_{t−k} = F_t + Σ_{i≥1} (ΔⁱF_t / i!) · H̃_i(−k)
H̃_n(x) = σⁿ · H_n(σ·x),   σ ∈ (0,1)
H_0 = 1,  H_1 = 2x,  H_{n+1} = 2x·H_n − 2n·H_{n−1}

Tuning

One shipped configuration; each knob is overridable by env var (takes precedence) or directly on the swapped sampler instances:

import os; os.environ["GF_CARVE_RATIO"] = "0.15"
pipe.enable_faster()
# …or set the instances directly, after enable_faster():
pipe.sparse_structure_sampler.hicache_interval = 2
pipe.shape_slat_sampler.carving_ratio = 0.10

What's added on top of TRELLIS.2

All Microsoft TRELLIS.2 model / decoder / o-voxel code is unchanged. Added files only:

• trellis2/pipelines/samplers/hicache.py — Hermite basis + finite-difference cache
• trellis2/pipelines/samplers/hicache_freq.py — 3D-FFT high-frequency token scoring (the carving signal)
• trellis2/pipelines/samplers/flow_euler_carved.py — the token-carved SLaT sampler (delta-cache step-skip + carving)
• trellis2/pipelines/samplers/flow_euler.py — HiCacheMixin + the accelerated sampler classes
• trellis2/pipelines/samplers/__init__.py — registers the accelerated samplers
• trellis2/pipelines/trellis2_image_to_3d.py — enable_faster() (single config) + the per-stage wiring
• example_faster.py

The accelerators are independent re-implementations of the cited papers on the TRELLIS.2 sampler API.

Credits & license

MIT. Accelerations © 2026 Krishi Attri; bundled TRELLIS.2 © Microsoft Corporation. See LICENSE and NOTICE.

Krishi Attri · krishiattriwork@gmail.com · github.com/Archerkattri

@software{attri2026hermittrellis2,
  author = {Krishi Attri},
  title  = {hermit-trellis2: Training-free Hermite carved-hybrid acceleration of TRELLIS.2 image-to-3D},
  year   = {2026},
  url    = {https://github.com/Archerkattri/hermit-trellis2}
}
@article{hicache2025,
  title   = {HiCache: Training-free Acceleration of Diffusion Models via
             Hermite Polynomial Feature Forecasting},
  journal = {arXiv preprint arXiv:2508.16984}, year = {2025}
}
@article{trellis2,
  title   = {Native and Compact Structured Latents for 3D Generation (TRELLIS.2)},
  journal = {arXiv preprint arXiv:2512.14692}, note = {microsoft/TRELLIS.2}
}

Family

Part of the HiCache++ acceleration family.

• Family hub: hicache-plus-plus — the basis library behind this adapter.
• Sibling: hermit-trellis2-plus-plus — the same base model with the HiCache++ (Dynamic Mode Decomposition / Prony) exponential-forecast variant.