Roblox Cube

The multi-part decomposition pipeline takes a pre-encoded shape latent and a list of part names to return individual meshes for each part.

Workflow:

1. Initialize PartShapeDenoiserPipeline with your config and checkpoint paths.
2. Load an existing mesh and sample its surface using sample_surface.
3. Convert the surface to a torch tensor and use parts_pipe.encode_shape(surface) to obtain latents.
4. Call parts_pipe.input_to_part_shape with a ShapeInput object containing your part prompts and latents.

Best Practices for Input Meshes:

• Ensure the mesh is canonically aligned (+Y up, +Z forward).
• Use a watertight, single-surface mesh. Avoid meshes with duplicated inner/outer shells.

import torch
import trimesh

from cube_part.pipelines import PartShapeDenoiserPipeline, ShapeInput
from cube_part.utils.mesh import load_mesh, sample_surface

parts_pipe = PartShapeDenoiserPipeline(
    config_path="configs/shape_denoiser_multimesh.yaml",
    checkpoint_path="weights/multi_part_dit.safetensors",
    vae_checkpoint_path="weights/vae.safetensors",
    extract_geometry_fn_name="extract_geometry_coarse_to_fine",
)

mesh, _, _ = load_mesh("examples/inputs/jellyfish_car.glb")
surface = sample_surface(mesh, num_samples=128_000)
surface = (
    torch.from_numpy(surface).to(parts_pipe.device).unsqueeze(0).float()
)
latents, _ = parts_pipe.encode_shape(surface)

part_meshes = parts_pipe.input_to_part_shape(
    ShapeInput(prompt=[["body", "wheels"]], latents=latents),
    guidance_scale=7.5,
    num_inference_steps=50,
)

for i, (vertices, faces) in enumerate(part_meshes):
    if vertices is not None:
        trimesh.Trimesh(vertices, faces).export(f"part_{i:02d}.glb")

Integrate Cube into your Python applications using the Engine or EngineFast classes.

• EngineFast: Optimized for CUDA devices. Use Engine for other devices.
• t2s(prompts, ...): The text-to-shape method.
  • use_kv_cache: Boolean to enable caching.
  • resolution_base: Float to control quality/speed.
  • top_p: Float (< 1) to control randomness (None is deterministic).

Returns a list containing [vertices, faces] for each prompt.

import torch
import trimesh
from cube3d.inference.engine import Engine, EngineFast

# load ckpt
config_path = "cube3d/configs/open_model.yaml"
gpt_ckpt_path = "model_weights/shape_gpt.safetensors"
shape_ckpt_path = "model_weights/shape_tokenizer.safetensors"
engine_fast = EngineFast( # only supported on CUDA devices, replace with Engine otherwise
    config_path, 
    gpt_ckpt_path, 
    shape_ckpt_path, 
    device=torch.device("cuda"), # Replace with "mps" on Metal-compatible devices
)

# inference
input_prompt = "A pair of noise-canceling headphones"
# NOTE: Reduce `resolution_base` for faster inference and lower VRAM usage
# The `top_p` parameter controls randomness between inferences:
#   Float < 1: Keep smallest set of tokens with cumulative probability ≥ top_p. Default None: deterministic generation.
mesh_v_f = engine_fast.t2s([input_prompt], use_kv_cache=True, resolution_base=8.0, top_p=0.9)

# save output
vertices, faces = mesh_v_f[0][0], mesh_v_f[0][1]
_ = trimesh.Trimesh(vertices=vertices, faces=faces).export("output.obj")

You can generate 3D models from text prompts using the cube3d.generate module.

Key Arguments:

• --gpt-ckpt-path: Path to shape_gpt.safetensors.
• --shape-ckpt-path: Path to shape_tokenizer.safetensors.
• --prompt: The text description of the object.
• --bounding-box-xyz: (v0.5+) Specifies the bounding box dimensions.
• --fast-inference: Optional flag for faster generation (not supported on MacOS or low-VRAM GPUs).
• --render-gif: Optional flag to render a turntable GIF (requires Blender >= 4.3 in PATH).
• --resolution-base: Controls output quality (4.0 to 9.0 recommended). Lower values are faster but coarser.

# Basic generation
python -m cube3d.generate \
            --gpt-ckpt-path model_weights/shape_gpt.safetensors \
            --shape-ckpt-path model_weights/shape_tokenizer.safetensors \
            --fast-inference \
            --prompt "A tall pagoda" \
            --bounding-box-xyz 1.0 2.0 1.5