Hunyuan3D-2をローカルで動かす（何番煎じ？）

# はじめに
下記記事から刺激をもらい、重い腰を上げて「そろそろローカルPCで手を動かしながらAIを動かすんや」という気持ちなったので、[Hunyuan3D-2](https://github.com/Tencent/Hunyuan3D-2)をローカルPCで動かしたときの備忘録を記事にしました。

https://qiita.com/yanosen_jp/items/f98e8b03917b465a92b3

[Hunyuan3D-2](https://github.com/Tencent/Hunyuan3D-2)は下記２つのツール上で動かしました： 
* [pinokio](https://pinokio.computer/)
* [ComfyUI Desktop](https://github.com/Comfy-Org/desktop?tab=readme-ov-file)
:::note info
ネイティブのpython環境でも試してみましたが、 [pinokio](https://pinokio.computer/)と大差はないです。
ブラウザで動かすか、専用のスタンドアローンアプリで動かすかの違いぐらいだと思います。 
:::

# ローカルPC環境
* Windows 11 Pro
* NVIDIA GeForce RTX 4090

# pinokioで動かす

[@yanosen_jpさんの記事](https://qiita.com/yanosen_jp/items/f98e8b03917b465a92b3#pinokio%E3%82%92%E7%94%A8%E3%81%84%E3%81%9F3d%E3%83%A2%E3%83%87%E3%83%AB%E7%94%9F%E6%88%90%E3%83%A9%E3%82%A4%E3%83%96%E3%83%A9%E3%83%AA%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)を参考に[pinokio](https://pinokio.computer/)とモデル（[Hunyuan3D-2](https://github.com/Tencent/Hunyuan3D-2)）をインストールします。
しかし、最新（[acda958](https://github.com/Tencent/Hunyuan3D-2/commit/acda9583e719c820b35e084fb3afe3cb9f124519)）だとテクスチャ生成回り（``hy3dgen\texgen\custom_rasterizer``）でエラーとなりますが、一旦Stopしてまた再開してください。
**環境依存な気はします。** 
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/e2713299-8c37-4a98-9ff1-079127f60715.png" width=30%>

無事にモデルが起動できると下記のような表示となります。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/49cc5dc5-3a6b-4720-8c12-eeba1b635ca7.png" width=30%>

pinokioがランチャーアプリ的な立ち位置で 、モデルを一覧で管理できるので便利です。   
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/45dbef93-7260-445c-b4f9-2b3d1c6f5622.png" width=30%>

:::note info
 pinokioのモデルの保存場所は ``{pinokioルート}\api\{モデル名}``となります。
 <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/e5a72d86-758f-4fa4-b980-9fe05260c0b3.png" width=30%>
:::

## テクスチャ生成  

モデル起動後に``Warning: Texture synthesis is disable due to ...``と表示されると
テクスチャ生成ができません。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/206c1b98-0e6c-4cf1-93dc-74131da9d5b0.png" width=30%>

色々試したんですが、うまくいかなかったです。
試してみたことを記載しておきます。
もし解決できる方法をご存じの方は教えてくださいw

[公式](https://github.com/Tencent/Hunyuan3D-2?tab=readme-ov-file#install-requirements)には``for texture``のコマンドの記述があったので試してみました。
```bat
pip install -r requirements.txt
pip install -e .
# for texture
cd hy3dgen/texgen/custom_rasterizer
python3 setup.py install
cd ../../..
cd hy3dgen/texgen/differentiable_renderer
python3 setup.py install
```

pinokio環境だと下記のような感じです。
```bat
rem モデルのルートに移動
cd {pinokioルート}\api\{モデル名}\app

rem 仮想環境を有効に
env\Scripts\activate

rem テクスチャ生成モジュールのルートに移動  
cd hy3dgen/texgen/custom_rasterizer

rem モジュールをビルド
python setup.py install
```
しかし、「モジュールをビルド」コマンドで下記のようなコンパイルエラーとなりました。
```
D:\AI\pinokio\api\Hunyuan3D-2.git\app\hy3dgen\texgen\custom_rasterizer\lib\custom_rasterizer_kernel\grid_neighbor.cpp(397): error C2398: 要素 '1': 'unsigned __int64' から '_Ty' への変換には縮小変換が必要です
        with
        [
            _Ty=int64_t
        ]
D:\AI\pinokio\api\Hunyuan3D-2.git\app\hy3dgen\texgen\custom_rasterizer\lib\custom_rasterizer_kernel\grid_neighbor.cpp(398): error C2398: 要素 '1': 'unsigned __int64' から '_Ty' への変換には縮小変換が必要です
        with
        [
            _Ty=int64_t
        ]
...
RuntimeError: Error compiling objects for extension
```
もっとスマートな解決方法があるとは思いつつ、ChatGPT先生の回答で下記のような感じで修正するとコンパイルエラーが解消します。
同様の記述がいくつかあるので、同じように修正します。 
```hy3dgen\texgen\custom_rasterizer\lib\custom_rasterizer_kernel\grid_neighbor.cpp
    // 修正前
    texture_positions[0] = torch::zeros({seq2pos.size() / 3, 3}, float_options);
    texture_positions[1] = torch::zeros({seq2pos.size() / 3}, float_options);

    // 修正後
    texture_positions[0] = torch::zeros({static_cast<int64_t>(seq2pos.size() / 3), 3}, float_options);
    texture_positions[1] = torch::zeros({static_cast<int64_t>(seq2pos.size() / 3)}, float_options);
```

上記でコンパイルエラーは解消しますが、次にリンクエラーとなります。
```
error LNK2001: 外部シンボル "public: long * __cdecl at::TensorBase::data_ptr<long>(void)const "
```
こちらもChatGPT先生の回答で、下記のような感じで修正するとリンクエラーが解消します。
```hy3dgen\texgen\custom_rasterizer\lib\custom_rasterizer_kernel\grid_neighbor.cpp
    // 修正前
    long* nptr = grid_neighbors[i].data_ptr<long>();

    // 修正後
    int64_t* nptr = grid_neighbors[i].data_ptr<int64_t>();
```

修正後の再ビルド前に``python setup.py clean --all``を実行してクリーンにしておきます。
pythonでのC++ビルド周りの知見が乏しいので、「そうなんだ。。。」という感じです。。。  

これでビルドが成功するようにはなりました。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/ebba653b-d465-4d8c-bec0-f798ace4260c.png" width=30%>

``differentiable_renderer``の方は普通にビルドできました。
```bat
cd hy3dgen/texgen/differentiable_renderer
python setup.py install
```

これでpinokioを起動してみると「Gen Textured Shape」というボタンが見えるようになりました。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/87952429-b76a-4dd1-9d5a-9e63b2d6b68a.png" width=30%>

だがしかし、``Expected reduction dim to be specified ...``というエラーで諦めました。。。
「Gen Shape」ボタンの方は動作します。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/2ef881ce-7c34-4331-9aca-0bc5c08d6279.png" width=30%>

:::note warn
pythonの環境でも同様にダメそうでした。
:::

# ComfyUI Desktopで動かす

基本は下記記事の手順通りで動かすことが可能です。
ComfyUIビギナー（自分）だと情報量が多くて少し迷ったので、そのメモです。 

https://comfyui-wiki.com/ja/tutorial/advanced/3d/huanyuan3d-2

 最初に[ComfyUI Desktop](https://github.com/Comfy-Org/desktop?tab=readme-ov-file)をインストールします。

## 関連プラグイン／ファイルのインストール

### 関連プラグインをインストールする

下記２つのプラグインを``ComfyUI Manager``の``Install via Git URL``でインストールします。
 * [ComfyUI-Hunyuan3DWrapper](https://github.com/kijai/ComfyUI-Hunyuan3DWrapper)
 * [ComfyUI_essentials](https://github.com/cubiq/ComfyUI_essentials)
 <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/300d9fe7-f759-4977-a97c-35fb004a0ee0.png" width=30%>
 <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/25ece7c7-e66f-439b-92fe-9c7f601756e9.png" width=30%>

:::note warn
#### プラグインインストール時に``security level``のエラーが出る場合  
:::

下記記事のように``security level``を``normal`` ⇒ ``weak``に変更する必要があります。
**変更は自己責任でお願いします。** 

https://note.com/gentle_murre488/n/ne320edb3ba27

変更するファイルは``user\default\ComfyUI-Manager\config.ini``です。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/e488dc8b-789b-47b8-b561-74516e57ad57.png" width=30%>
``` config.ini
[default]
...
security_level = weak
```
### テクスチャ生成コンポーネントをインストール

ComfyUI Desktopのターミナルから下記コマンドを実行するだけです。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/8590f9a8-2840-4f24-b788-fd74b04ea74f.png" width=30%>
```powershell
cd .\custom_nodes\comfyui-hunyan3dwrapper\wheels\
pip install .\custom_rasterizer-0.1.0+torch260.cuda126-cp312-cp312-win_amd64.whl
pip install .\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl 
```

:::note info
``.whl``ファイルとは　（ChatGPT先生の回答）
``.whl``ファイルは、Python における 「wheel（ホイール）」形式のパッケージファイルです。Python のパッケージを効率的に配布・インストールするための ビルド済みバイナリ形式 のひとつです。
:::

### BPT (Boundary Preserving Transform)をインストール（任意）

ComfyUI Desktopのターミナルから下記コマンドを実行します。
```powershell
cd .\custom_nodes\comfyui-hunyan3dwrapper\hy3dgen\shapegen\bpt\
pip install -r .\requirements.txt
```

コマンド実行後、重みファイル[bpt-8-16-500m.pt](https://huggingface.co/whaohan/bpt/blob/refs%2Fpr%2F1/bpt-8-16-500m.pt)をダウンロードして、``custom_nodes\comfyui-hunyan3dwrapper\hy3dgen\shapegen\bpt``にコピーします。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/1cc7c2a4-2539-45dc-a0b7-abf43ee578fe.png" width=30%>

:::note info
``.pt``ファイルとは　（ChatGPT先生の回答）
``.pt`` ファイルは **PyTorch** フレームワークで使われる形式で、通常は以下の2つの目的で使われます：
* **モデルの重み（weights）**：`torch.save(model.state_dict(), 'model.pt')`
* **モデル全体**（構造と重み）：`torch.save(model, 'model.pt')`
:::

## ComfyUI Desktopのワークフロー（単一視点）を実行

### ワークフローファイルを準備
Kijaiさんにご用意してもらっているワークフローファイル（``single_view.json``）を[2.1 ワークフローファイル](https://comfyui-wiki.com/ja/tutorial/advanced/3d/huanyuan3d-2#21-%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB)からダウンロードして、ComfyUI Desktopにドラッグ＆ドロップするだけでワークフローがロードできます。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/342a9184-139d-46b1-a367-e99c902b8ca6.png" width=30%>
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/0112538d-fd48-4008-8290-49dce153e784.png" width=30%>

### モデルをインストール

モデル[Hunyuan3D-2_safetensors](https://huggingface.co/Kijai/Hunyuan3D-2_safetensors/blob/main/hunyuan3d-dit-v2-0-fp16.safetensors)をダウンロードして、``models\diffusion_models``にコピーします。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/f22ce2a5-a566-4abf-bbfb-3611cb28165a.png" width=30%>

:::note info
``.safetensors``ファイルとは　（ChatGPT先生の回答）
``.safetensors``ファイルは、機械学習モデルの重み（パラメータ）を安全かつ効率的に保存するためのファイルフォーマットです。特に最近のAI・ディープラーニングの分野で、モデルの共有に使われることが増えています。
:::

### ワークフローを実行
``Load Image``ノードで画像を選択して、``Run``ボタンを押して実行するだけです。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/bdb14192-d670-4dcf-8f2a-e590e97f58d9.png" width=30%>
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3958164/5b76194d-362a-4a95-91c0-17bf9b908cc6.png" width=30%>

[3. Hunyuan3D 2.0マルチビューワークフロー](https://comfyui-wiki.com/ja/tutorial/advanced/3d/huanyuan3d-2#3-hunyuan3d-20%E3%83%9E%E3%83%AB%E3%83%81%E3%83%93%E3%83%A5%E3%83%BC%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC)も上記と同じ手順で実行できます。