Language: English · Português (README_PT.md)

Text-to-3D and image-to-3D generation powered by Text2D (FLUX.2 Klein SDNQ) → Hunyuan3D-2.1 (SDNQ INT4 quantized). Outputs geometry-only GLB/PLY/OBJ meshes. For texturing and PBR, use Paint3D or GameAssets.

Text3D is also the central mesh operations hub in the monorepo — it owns all mesh post-processing (LOD, collision, remesh, simplify, align).

Text3D generates 3D meshes in two phases:

1. Text2D (text → reference image) — uses FLUX.2 Klein with CPU offload by default; the model is always unloaded before loading Hunyuan3D.
2. Hunyuan3D-2.1 (image → mesh) — marching cubes surface extraction with SDNQ INT4 quantization.

Generation presets (--preset) adjust steps, octree resolution, and chunk count together:

After generation, prepare_mesh_topology runs automatically to repair marching-cubes artifacts (see Mesh Topology).

License: Tencent Hunyuan3D-2.1 weights are under the Tencent Hunyuan Community License — territory restrictions apply. Text2D (FLUX SDNQ) license: see Text2D/README and root README.

cd Shared && pip install -e .
cd Text3D && pip install -e .

Or via the unified installer:

./install.sh text3d

cd Text3D
python -m venv .venv && source .venv/bin/activate
pip install -r config/requirements.txt
pip install -e .

Windows: python -m venv .venv and .\.venv\Scripts\Activate.ps1; or scripts\setup.ps1.

Entry point: text3d (or python -m text3d).

Text-to-3D (Text2D → Hunyuan3D) or image-to-3D (--from-image).

# Text-to-3D (default: balanced preset, feet origin)
text3d generate "a futuristic robot" -o robot.glb

# High quality (large GPU)
text3d generate "chair" --preset hq -o chair.glb

# Fast generation (less VRAM/time)
text3d generate "chair" --preset fast -o chair_fast.glb

# Image-to-3D only (skip Text2D)
text3d generate -i ref.png -o mesh.glb

# Low VRAM (~6 GB): hw-auto applies SDNQ INT4 automatically
text3d generate "object" --preset balanced

# Reproducible seed
text3d generate "sword" --seed 42 -o sword.glb

# Skip mesh repair (keep high-poly for Paint3D texturing)
text3d generate "statue" --skip-remesh -o statue.glb

# Multi-GPU (split Hunyuan weights across GPUs)
text3d generate "scene" --gpu-ids 0,1 -o scene.glb

Preset precedence: When --preset is set, it overrides --steps, --octree-resolution, and --num-chunks. When --quality is set, the QualityEngine resolves preset/guidance/steps/octree/chunks only if the user hasn't explicitly provided them.

Batch image-to-3D from a JSON manifest. Each item must have id, image, and output fields. The Hunyuan3D model stays loaded across all items.

text3d generate-batch manifest.json --output-dir ./outputs --preset balanced --force

Manifest format:

[
  {"id": "item1", "image": "ref1.png", "output": "item1.glb"},
  {"id": "item2", "image": "ref2.png", "output": "item2.glb", "steps": 28, "seed": 42}
]

Accepts all generation flags (--preset, --steps, --guidance, --octree-resolution, --num-chunks, --mc-level, --sdnq-preset, --export-origin, --gpu-ids, --allow-shared-gpu, --force) plus the inference acceleration flags (--volume-decoder, --mc-algo, --compile, --sage-attn, --sdnq-matmul). In batch mode the BiRefNet background remover stays loaded across items (no per-item reload).

--hw-auto (default on) detects the available CUDA hardware and resolves a profile — only filling parameters you didn't set explicitly (--quality, --preset and individual flags always win). Check the detected profile with text3d doctor. Disable with --no-hw-auto or TEXT3D_HW_AUTO=0.

All CUDA profiles default the volume decoder to hierarchical (near-lossless). Multi-GPU weight splitting counts the sum of VRAM for the tier; an explicit --gpu-ids always overrides the auto selection.

All acceleration paths are opt-in — defaults keep the original behavior (dense VanillaVolumeDecoder + skimage marching cubes), except --hw-auto above which is on by default.

Recommended fast profile for batch asset production:

text3d generate-batch manifest.json --preset balanced --volume-decoder hierarchical --mc-algo dmc --compile

Generate a LOD triplet (LOD0/LOD1/LOD2) using quadric decimation. Preserves armatures and animations — no separate path needed for rigged LOD.

# Basic LOD generation
text3d lod model.glb -o ./out_dir --basename prop

# With textured LOD0 (Paint3D output)
text3d lod model.glb -o ./out_dir --painted-mesh painted.glb --target-faces 30000

Output files: {basename}_lod0.glb, {basename}_lod1.glb, {basename}_lod2.glb.

Isotropic remesh — geometry only, no texture preservation. Ideal for simplifying before texturing with Paint3D.

text3d remesh model.glb -o simplified.glb --target-faces 24000

Remesh with texture reprojection — preserves UV layout and materials. Re-meshes to uniform triangles (pymeshlab isotropic) then re-projects the original texture via xatlas + closest-point sampling.

text3d remesh-textured painted.glb -o remeshed.glb --target-faces 6000
text3d remesh-textured model.glb -o out.glb --target-faces 10000 --texture-size 4096

Generate a simplified collision mesh (convex hull + quadric decimation) suitable for physics in Unity/Godot/Unreal.

text3d collision model.glb -o collision.glb
text3d collision model.glb -o coll.glb --max-faces 500 --no-convex-hull

Align the largest +Z face normal to the ground plane. Useful for correcting models generated flat-side-up (e.g., crystal/pedestal orientation). Includes a height-ratio guard to avoid "folding" humanoid models when the heuristic fails.

text3d align-plus-z model.glb -o corrected.glb
text3d align-plus-z model.glb -o corrected.glb --min-height-ratio 0.3

Convert mesh between formats (PLY, OBJ, GLB).

text3d convert mesh.ply --output mesh.glb
text3d convert mesh.obj -o mesh.glb --rotate

Show current GPU processes via nvidia-smi. Useful when exclusive-GPU checks fail or to identify processes consuming VRAM.

text3d gpu-processes

Check PyTorch, CUDA, and VRAM availability. Reports per-GPU memory, CUDA version, and the PYTORCH_CUDA_ALLOC_CONF setting.

text3d doctor

Show system info, GPU details, HF cache path, and default output directory.

text3d info

List all models used by Text3D (Text2D, Hunyuan3D shape, Hunyuan3D Paint reference).

text3d models

Install the Cursor Agent Skill (.cursor/skills/text3d/SKILL.md) into a game project.

text3d skill install --target ./my-game --force

prepare_mesh_topology runs automatically after every generate and generate-batch call. It repairs marching-cubes artifacts to produce clean, game-ready meshes:

Known artifacts: Hunyuan3D marching-cubes outputs tend to have thick/double walls and tiny cracks. For manual repair: merge/manifold and close only very small holes before making watertight — do not treat the large base opening (e.g., crate after removing pedestal) as a defect.

Skip for texturing: Use --skip-remesh to disable the isotropic remeshing step, preserving the high-poly mesh for better Paint3D texturing quality.

Quality tiers map to generation presets via the QualityEngine (quality-profiles.yaml):

The QualityEngine uses soft resolution — it only fills defaults when the user hasn't explicitly set a parameter. Use --quality and optionally --category to let the engine tune parameters automatically, or override individual flags as needed.

Default output directory: outputs/meshes/.

Supported formats: GLB (default), PLY, OBJ.

Text3D is the central mesh operations hub in the monorepo. It owns all mesh operations:

• LOD generation — text3d lod (preserves armatures/animations)
• Collision mesh — text3d collision
• Remesh (geometry) — text3d remesh
• Remesh (textured) — text3d remesh-textured
• Simplify — via --max-faces in generate
• Mesh alignment — text3d align-plus-z
• Format conversion — text3d convert

GameAssets delegates all mesh ops to Text3D subprocesses — it does not contain mesh code. The recommended full pipeline:

text3d generate → paint3d texture → text3d lod → text3d collision → game handoff

Or via GameAssets:

gameassets batch --manifest manifest.csv

For PBR maps from a diffuse image (not GLB), use Materialize / texture2d materialize.

from text3d import HunyuanTextTo3DGenerator
from text3d.utils import save_mesh

# Text-to-3D
with HunyuanTextTo3DGenerator(verbose=True) as gen:
    mesh = gen.generate(prompt="a red car")
    save_mesh(mesh, "car.glb", format="glb")

# Image-to-3D (skip Text2D)
with HunyuanTextTo3DGenerator(verbose=True) as gen:
    mesh = gen.generate_from_image("ref.png")
    save_mesh(mesh, "mesh.glb")

cd Text3D && pip install -e ".[dev]"
pytest tests/
ruff check .
ruff format .

Full CI: make check (from repo root) runs lint, format check, typecheck, and tests.

• Tencent Hunyuan3D-2.1 — GitHub, HuggingFace (shape: hunyuan3d-dit-v2-1, SDNQ INT4)
• Text2D — FLUX.2 Klein (SDNQ Disty0 by default; optional BFL BF16 via TEXT2D_MODEL_ID) in the monorepo text2d package

MIT