🍀

Roblox/cube3d-v0.1を試す: テキストから3Dモデルを生成しよう

2025/03/25に公開

Roblox

このノートブックでは、Robloxが開発した3Dモデル生成AIである「Cube3D」を使って、テキストプロンプトから3Dモデルを生成する方法を学びます。Cube3Dは、テキスト記述から詳細な3Dオブジェクトを生成できる強力なAIモデルです。

はじめに

Cube3Dは、Robloxが開発した3D生成AIシステムで、テキスト記述から3Dモデルを生成することができます。このシステムは、形状トークナイザーとテキストから形状への生成モデルを組み合わせたものです。

Cube3Dの主な特徴:

テキストプロンプトから詳細な3Dモデルを生成
様々な形状や物体を生成可能
生成されたモデルは.obj形式で保存可能
オプションでGIFアニメーションとしてレンダリング可能

このノートブックでは、Roblox/cube3d-v0.1モデルを使用して、テキストから3Dモデルを生成する方法を段階的に説明します。

環境セットアップ

まず、必要なライブラリをインストールします。以下のセルを実行してください。

# 必要なライブラリのインストール
!pip install torch trimesh numpy matplotlib
!pip install huggingface_hub
!pip install pymeshlab

# Blenderをインストールする
!apt-get update
!apt-get install -y blender
# BlenderのPython環境にNumPyをインストールする
!blender --background --python-expr "import sys, subprocess; subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'numpy'])"

次に、Roblox/cubeリポジトリをクローンします。

# リポジトリのクローン
!git clone https://github.com/Roblox/cube.git
%cd cube
!pip install -e .

モデルのダウンロード

Hugging Faceからモデルの重みをダウンロードします。

# Hugging Faceからモデルをダウンロード
!mkdir -p model_weights
!huggingface-cli download Roblox/cube3d-v0.1 --local-dir ./model_weights

テキストから3Dモデルを生成する

モデルをダウンロードしたら、テキストプロンプトから3Dモデルを生成できます。以下のコードを実行してください。

# テキストから3Dモデルを生成
!python -m cube3d.generate \
        --gpt-ckpt-path model_weights/shape_gpt.safetensors \
        --shape-ckpt-path model_weights/shape_tokenizer.safetensors \
        --fast-inference \
        --output-dir ./outputs/output1 \
        --prompt "Broad-winged flying blue dragon, elongated, folded legs."

生成されたモデルはoutputsディレクトリに保存されます。

サンプル例

Cube3Dで生成できるいくつかのサンプル例を見てみましょう。以下は、リポジトリに含まれるサンプルプロンプトとそれに対応する3Dモデルです。

ドラゴン

プロンプト: "Broad-winged flying red dragon, elongated, folded legs."

ボート

プロンプト: "a boat"

ブルドーザー

プロンプト: "bulldozer"

剣

プロンプト: "a purple crystal blade fantasy sword with green gem accents."

以下のコードを実行して、独自のプロンプトで3Dモデルを生成してみましょう。

# 独自のプロンプトで3Dモデルを生成
prompt = "Futuristic sports car" # ここにプロンプトを入力
!python -m cube3d.generate \
        --gpt-ckpt-path model_weights/shape_gpt.safetensors \
        --shape-ckpt-path model_weights/shape_tokenizer.safetensors \
        --fast-inference \
        --output-dir ./outputs/custom_output2 \
        --prompt "{prompt}"

高度な使用方法

Pythonライブラリとして使用する

Cube3Dは、Pythonライブラリとしても使用できます。以下のコードは、Pythonスクリプト内でCube3Dを使用する方法を示しています。

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

# モデルの読み込み
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(
    config_path,
    gpt_ckpt_path,
    shape_ckpt_path,
    device=torch.device("cuda" if torch.cuda.is_available() else "cpu"),
)

# 推論
input_prompt = "ノイズキャンセリングヘッドフォン"
mesh_v_f = engine_fast.t2s([input_prompt], use_kv_cache=True)

# 出力の保存
vertices, faces = mesh_v_f[0][0], mesh_v_f[0][1]
trimesh.Trimesh(vertices=vertices, faces=faces).export("output_python_lib.obj")

解像度の調整

生成される3Dモデルの解像度を調整するには、--resolution-baseパラメータを使用します。値が大きいほど高解像度になりますが、処理時間も長くなります。

# さらに強力なGPUメモリクリア
import torch
import gc
import os

# 使用状況を確認
print("クリア前:")
print(f"割り当て済みメモリ: {torch.cuda.memory_allocated()/1024**3:.2f} GB")
print(f"キャッシュメモリ: {torch.cuda.memory_reserved()/1024**3:.2f} GB")

# より強力なクリア方法
# 1. すべてのCUDAデバイスをリセット
device = torch.device('cuda')
torch.cuda.empty_cache()
torch.cuda.synchronize()

# 2. すべてのGPUテンソルをCPUに移動し、削除
for obj in gc.get_objects():
    try:
        if torch.is_tensor(obj) and obj.device.type == 'cuda':
            obj.detach().cpu()
            del obj
    except:
        pass

# 3. すべての変数をリセット（注意：これは実行中の変数も消去します）
# このセルのみ実行し、他のセルで使用している変数に注意してください
for name in dir():
    if not name.startswith('_'):
        del globals()[name]

# 4. ガベージコレクション実行
import torch
import gc
import os
gc.collect()
torch.cuda.empty_cache()
torch.cuda.synchronize()

# 5. 利用可能なGPUメモリ状態を再確認（ここで再インポートが必要）
import torch
print("\nクリア後:")
print(f"割り当て済みメモリ: {torch.cuda.memory_allocated()/1024**3:.2f} GB")
print(f"キャッシュメモリ: {torch.cuda.memory_reserved()/1024**3:.2f} GB")

# 6. 最終手段：NVIDIAドライバレベルでのリセット（Colabでは限定的にしか機能しない場合があります）
if torch.cuda.memory_allocated() > 1 * 1024**3:  # 1GB以上のメモリが残っている場合
    print("\n警告: メモリ使用量が高いままです。ランタイムの再起動を推奨します。")
    print("ランタイム → ランタイムを再起動 を選択してください。")

# 解像度を調整して3Dモデルを生成
!python -m cube3d.generate \
        --gpt-ckpt-path model_weights/shape_gpt.safetensors \
        --shape-ckpt-path model_weights/shape_tokenizer.safetensors \
        --fast-inference \
        --resolution-base 6.0 \
        --output-dir ./outputs/resolution_output2 \
        --prompt "Ancient stone statue"

# 解像度を調整して3Dモデルを生成
!python -m cube3d.generate \
        --gpt-ckpt-path model_weights/shape_gpt.safetensors \
        --shape-ckpt-path model_weights/shape_tokenizer.safetensors \
        --fast-inference \
        --resolution-base 9.0 \
        --output-dir ./outputs/resolution_output3 \
        --prompt "Ancient stone statue"

トラブルシューティング

CUDA関連のエラー

Windows環境でCUDAエラーが発生する場合は、以下のコマンドを実行してCUDAサポート付きのPyTorchをインストールしてください。

# CUDAサポート付きのPyTorchをインストール
# !pip install torch --index-url https://download.pytorch.org/whl/cu124 --force-reinstall

メモリ不足エラー

GPUメモリが不足している場合は、--fast-inferenceフラグを削除するか、より小さい--resolution-base値を使用してください。

# メモリ使用量を削減して3Dモデルを生成
!python -m cube3d.generate \
        --gpt-ckpt-path model_weights/shape_gpt.safetensors \
        --shape-ckpt-path model_weights/shape_tokenizer.safetensors \
        --resolution-base 4.0 \
        --output-dir ./outputs/resolution4_output \
        --prompt "small house"

# メモリ使用量を削減して3Dモデルを生成
!python -m cube3d.generate \
        --gpt-ckpt-path model_weights/shape_gpt.safetensors \
        --shape-ckpt-path model_weights/shape_tokenizer.safetensors \
        --resolution-base 9.0 \
        --output-dir ./outputs/resolution9_output \
        --prompt "small house"

GIFレンダリングの問題

GIFレンダリングを行うには、Blenderがインストールされ、システムのPATHに追加されている必要があります。Blenderがインストールされていない場合は、Blenderの公式ウェブサイトからダウンロードしてください。

このノートブックを通じて、Roblox/cube3d-v0.1モデルを使用してテキストから3Dモデルを生成する方法を学びました。さまざまなプロンプトを試して、独自の3Dモデルを作成してみてください！

📒ノートブック

参考資料