How to Configure Classifier-Free Guidance Parameters for 3D Generation in TRELLIS 2

To configure classifier-free guidance (CFG) in TRELLIS 2, set the guidance_strength, guidance_rescale, and guidance_interval parameters when instantiating FlowEulerCfgSampler or FlowEulerGuidanceIntervalSampler from the trellis2.pipelines.samplers module.

TRELLIS 2 implements classifier-free guidance for flow-matching models through a modular mix-in architecture that allows precise control over prompt adherence and sample diversity. Understanding how to configure these parameters is essential for balancing text-to-3D fidelity with generation variety. This guide explains the three tunable CFG parameters and their implementation in the Microsoft TRELLIS 2 codebase.

The Three CFG Parameters Explained

TRELLIS 2 exposes three distinct parameters to control classifier-free guidance behavior during 3D generation. Each parameter serves a specific purpose in the diffusion sampling process.

Guidance Strength (guidance_strength)

The guidance_strength parameter controls the interpolation between positive and negative condition predictions. In trellis2/pipelines/samplers/classifier_free_guidance_mixin.py, the ClassifierFreeGuidanceSamplerMixin._inference_model method implements the weighted sum:

guidance_strength * pred_pos + (1 - guidance_strength) * pred_neg

• A value of 1.0 uses only the positive condition (no CFG)
• A value of 0.0 uses only the negative condition
• Values > 1.0 amplify the influence of the positive prompt, increasing adherence at the cost of diversity

Guidance Rescale (guidance_rescale)

The guidance_rescale parameter prevents over-confident samples by adjusting the variance of the CFG-combined prediction. After computing the weighted sum, the code transfers the standard deviation from the unconditional prediction (x_0_pos) to the CFG result (x_0_cfg). This rescaling occurs in lines 20-27 of classifier_free_guidance_mixin.py and accepts float values between 0.0 and 1.0.

Guidance Interval (guidance_interval)

The guidance_interval parameter limits CFG application to specific timesteps during the diffusion schedule. Implemented in trellis2/pipelines/samplers/guidance_interval_mixin.py, the GuidanceIntervalSamplerMixin._inference_model method checks if guidance_interval[0] <= t <= guidance_interval[1]. Outside this window, the sampler defaults to guidance_strength = 1.0 (unconditional generation). This is useful for applying strong guidance only during early or mid-phase denoising.

Sampler Architecture and Implementation

TRELLIS 2 composes CFG functionality through mix-in classes inherited by concrete sampler implementations.

The base FlowEulerSampler in trellis2/pipelines/samplers/flow_euler.py provides the underlying Euler integration for flow-matching models. Two specialized variants extend this base:

• FlowEulerCfgSampler – Combines Euler sampling with CFG strength and optional rescale
• FlowEulerGuidanceIntervalSampler – Adds time-windowed control via guidance_interval

Both samplers forward CFG arguments to their respective mix-ins through super().sample() calls, enabling the configuration parameters to affect the model predictions during each denoising step.

Configuring CFG in Practice

You can configure classifier-free guidance parameters programmatically when constructing sampler instances for 3D generation pipelines.

Basic CFG Configuration

To apply standard classifier-free guidance with strength and rescale parameters:

import torch
from trellis2.pipelines.samplers.flow_euler import FlowEulerCfgSampler

cfg_sampler = FlowEulerCfgSampler(sigma_min=0.01)

samples = cfg_sampler.sample(
    model=my_flow_model,
    noise=torch.randn(batch_size, channels, *spatial_shape),
    cond=positive_prompt_embeddings,
    neg_cond=negative_prompt_embeddings,
    steps=50,
    rescale_t=1.0,
    guidance_strength=4.5,  # Strong adherence to positive prompt

    guidance_rescale=0.3,   # Moderate variance rescaling

    verbose=True,
)

Time-Windowed Guidance

To limit CFG application to specific diffusion timesteps:

from trellis2.pipelines.samplers.flow_euler import FlowEulerGuidanceIntervalSampler

interval_sampler = FlowEulerGuidanceIntervalSampler(sigma_min=0.01)

samples = interval_sampler.sample(
    model=my_flow_model,
    noise=torch.randn(batch_size, channels, *spatial_shape),
    cond=positive_prompt_embeddings,
    neg_cond=negative_prompt_embeddings,
    steps=50,
    rescale_t=1.0,
    guidance_strength=3.0,
    guidance_interval=(0.2, 0.8),  # Apply CFG only between t=0.2 and t=0.8

    verbose=True,
)

Both samplers return an edict containing samples, pred_x_t, and pred_x_0 for subsequent processing such as voxel rendering or mesh extraction.

Gradio UI Configuration

The TRELLIS 2 repository provides Gradio interfaces in app.py and app_texturing.py that expose CFG parameters through interactive sliders. The UI initializes gr.Slider components for:

• Guidance Strength: Range 1.0 to 10.0 (line 355 in app.py, line 110 in app_texturing.py)
• Guidance Rescale: Range 0.0 to 1.0

While guidance_interval is not exposed in the default UI, you can implement custom pipelines that instantiate FlowEulerGuidanceIntervalSampler directly to access this advanced parameter.

Summary

• Guidance strength interpolates between positive and negative predictions in ClassifierFreeGuidanceSamplerMixin._inference_model, with values > 1.0 amplifying prompt adherence
• Guidance rescale adjusts prediction variance to prevent over-confidence, implemented in the same mix-in class
• Guidance interval restricts CFG to specific timesteps via GuidanceIntervalSamplerMixin, useful for phased generation strategies
• Use FlowEulerCfgSampler for standard CFG or FlowEulerGuidanceIntervalSampler for time-limited guidance
• The Gradio UI in app.py provides sliders for strength and rescale parameters, while interval control requires programmatic sampler construction

Frequently Asked Questions

What is the recommended guidance strength for TRELLIS 2 3D generation?

Typical values range between 3.0 and 7.0 for strong prompt adherence, though the Gradio UI accepts values up to 10.0. Start with 4.5 and adjust based on whether the output matches the text prompt too strictly (reduce) or too loosely (increase).

When should I use guidance rescale?

Enable guidance_rescale (values between 0.1 and 0.5) when you notice artifacts or over-saturated colors in generated 3D assets caused by CFG pushing predictions toward high-confidence modes. This parameter restores variance from the unconditional prediction to maintain natural diversity.

Can I apply classifier-free guidance only during specific generation phases?

Yes. Instantiate FlowEulerGuidanceIntervalSampler and pass a tuple (start, end) to guidance_interval where values represent normalized timesteps between 0 and 1. This applies CFG only within the specified window, reverting to unconditional sampling outside the interval.

Where is the CFG logic implemented in the TRELLIS 2 source code?

The core logic resides in trellis2/pipelines/samplers/classifier_free_guidance_mixin.py for strength and rescale, and trellis2/pipelines/samplers/guidance_interval_mixin.py for time-windowed control. Concrete samplers combining these mix-ins are defined in trellis2/pipelines/samplers/flow_euler.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}