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

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


## はじめに

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

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

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

<blockquote class="twitter-tweet" data-media-max-width="800"><p lang="ja" dir="ltr">ManusにRobloxのオープンソース3D生成「Cude」のGithubのURL渡してGoogle colabのノートブックを作成してもらった⑦<br>resolution-baseを9でやった結果がこちら、、、内装を作りこむ子みたい、、、内部は結構複雑になってる、、、これが匠の技なのか？？！！ <a href="https://t.co/7hC0Vi0oDM">https://t.co/7hC0Vi0oDM</a> <a href="https://t.co/nkgditpFpF">pic.twitter.com/nkgditpFpF</a></p>&mdash; Maki@Sunwood AI Labs. (@hAru_mAki_ch) <a href="https://twitter.com/hAru_mAki_ch/status/1902710769629958649?ref_src=twsrc%5Etfw">March 20, 2025</a></blockquote>

## 環境セットアップ

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

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

```python
# 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リポジトリをクローンします。

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

## モデルのダウンロード

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

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

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

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

```python
# テキストから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モデルを生成してみましょう。

```python
# 独自のプロンプトで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を使用する方法を示しています。

```python
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`パラメータを使用します。値が大きいほど高解像度になりますが、処理時間も長くなります。

```python
# さらに強力な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("ランタイム → ランタイムを再起動 を選択してください。")
```

```python
# 解像度を調整して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"
```

```python
# 解像度を調整して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をインストールしてください。

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

### メモリ不足エラー

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

```python
# メモリ使用量を削減して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"
```

```python
# メモリ使用量を削減して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の公式ウェブサイト](https://www.blender.org/download/)からダウンロードしてください。

---

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

## 📒ノートブック

https://colab.research.google.com/drive/1sv3Xkb5quAvomLjngJ8kW32PmXJylc2c?usp=sharing


## 参考資料

- [Roblox/cube GitHub リポジトリ](https://github.com/Roblox/cube)
- [Roblox/cube3d-v0.1 Hugging Face モデル](https://huggingface.co/Roblox/cube3d-v0.1)
- [Cube: A Roblox View of 3D Intelligence](https://arxiv.org/abs/2503.15475)

 <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>