Metadata-Version: 2.4
Name: houdini-asset-library
Version: 0.6.3
Summary: Houdini Asset Library: save Houdini nodes as Hscript (cmd) and whole scenes as hip, and recall them from a standalone browser app
Author: hamu-dev
License-Expression: MIT
Keywords: houdini,sidefx,node,library,hscript
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications :: Qt
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6
Requires-Dist: Pillow
Requires-Dist: markdown-it-py
Requires-Dist: mdit-py-plugins
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-qt; extra == "dev"
Dynamic: license-file

# Houdini Asset Library (HAL)

Houdini のシーンやノードを保存し、独立したブラウザアプリから呼び出すツールです。扱うもの（アセット）は 2 種類で、アプリ最上部の「シーン」「ノード」の 2 つのタブで切り替えます。

| 種類 | 対象 | 保存形式 | 呼び出し |
|---|---|---|---|
| **シーンアセット** | 現在のシーン全体 | hip | シーンを開く（名前なし / 保存先を指定）、現在のシーンにマージ。外部ファイルの収集・検索置き換え、環境変数の保存と復元ができる |
| **ノードアセット** | 選択したノード群（または現在のネットワーク全体） | Hscript（cmd） | 現在のネットワークへ追加、新規シーンにインポート、**Houdini のネットワークエディタへドラッグ＆ドロップ** |

Houdini のシェルフ「HAL」は **Save Scene** / **Save Node Asset** / **Open Library** の 3 つです（ノードの右クリックにも「HAL: Save Node Asset」）。アプリは Houdini から起動すると、その Houdini の前に表示されます。

**詳しい使い方は、アプリのメニュー「ヘルプ > 使い方」で読めます**（「詳しいガイド」「保存形式」「セキュリティ」「変更履歴」も同じメニューにあります）。コマンドラインからは `hal-houdini docs` で文書の場所を表示できます。

## 必要環境

- Windows
- Houdini 22.0 / 21.0（22.0.429 と 21.0.512 で動作を確認。20.5 は Python 3.11 用の起動フックを同梱していますが未確認）
- Python 3.11 以降（アプリ本体用。Houdini 内蔵の Python とは別）。**Houdini 21 以降なら付属の Python でアプリを動かせるので、各 PC への Python のインストールは不要です**（方式 B-1）
- TortoiseSVN（任意。SVN でバージョン管理するときだけ）

## 導入

使い方に合わせて 3 つの方式があります。

| 方式 | 向いている場面 | 各 PC に必要なもの |
|---|---|---|
| **A. 個人の PC に入れる** | 1 人で使う、まず試す | Python と `pip install` |
| **B-1. 書き出して共有（Houdini 付属の Python）** | 会社で全員に配る | Houdini 21 以降だけ |
| **B-2. 書き出して共有（各 PC の Python）** | Houdini 20.5 以前も使う | Python と外部ライブラリ |

### 方式 A: 個人の PC に入れる

```
python -m venv hal-env
hal-env\Scripts\pip install houdini-asset-library
hal-env\Scripts\hal-houdini install
```

`hal-houdini install` は、Houdini のユーザー設定に `packages\hal.json` を 1 つ作ります（ほかの設定は変更しません）。Houdini が 22.0 以外のときは `--houdini-version 21.0`、設定フォルダが標準の場所に無いときは `--prefs-dir <フォルダ>` で指定します。Houdini を再起動すると、シェルフ「HAL」が使えます。アプリは `hal-env\Scripts\hal`（または `python -m hal`、シェルフの Open Library）で起動します。

### 方式 B-1 / B-2: 書き出して共有する（ランチャー・共有フォルダ・SVN 向け）

1 台で `pip install` して、共有する場所へ書き出します。各 PC は Houdini を起動するだけです。

```
hal-houdini export <出力先フォルダ> --runtime houdini     # B-1: Houdini 付属の Python で動かす
hal-houdini export <出力先フォルダ>                       # B-2: 各 PC の Python で動かす
```

- 出力は `hal.json`（相対指定）と `hal_package/` です。場所を移しても、別の PC へコピーしても、SVN で共有しても動きます。B-1 は約 2 MB で、各 PC に Python も `pip install` も要りません。`hal_package\hal.bat` でも、Houdini を起動せずにアプリを開けます。
- B-2 は、各 PC で `python -m pip install -r hal_package\requirements.txt` を実行し、使う Python を環境変数 `HAL_PYTHON` で指定します。
- ランチャーが環境変数を直接組み立てている場合は `hal-houdini export --no-json` で書き出し、`hal-houdini env --root <出力先> --format bat` で登録する値を表示します。
- 共通ライブラリを最初から見せたいときは、`hal_package/site_settings.json` に既定のルートを書けます（`--init-site-settings` で雛形を作成）。

## 最初の設定と基本の使い方

1. `hal` で起動し、「ルートフォルダを追加してください」で「設定を開く」を押します。「追加...」で空のフォルダを選びます。これがライブラリのルート（保存先）です。共有フォルダでも構いません。
2. Houdini でノードを選び、シェルフの **Save Node Asset**（右クリックの「HAL: Save Node Asset」）を押します。シーン全体は **Save Scene** です。
3. 登録画面で名前（必要ならプロジェクト・部署・タグ・サムネイル）を確認して「登録」を押します。
4. アプリの「ノード」タブでアイテムを選び、「現在のネットワークへ追加」を押します。ノードが復元されます。グリッドやリストから、**Houdini のネットワークエディタへドラッグ＆ドロップ**して置くこともできます（設定でオフにできます）。「シーン」タブでは、シーンを開く・現在のシーンにマージができます。

**一時的なアイテムとリンクで渡す**: 専用の共有機能はありません。1 回きりで渡したいものは、登録ダイアログで「一時的（有効期限つき）」にチェックして登録し（既定 7 日）、「リンクをコピー」で出る `hal://item/<id>` をチャットに貼ります。相手は検索欄に貼ると、そのアイテムが選択されます（同じルート＝共有フォルダを見ていることが前提です）。期限が過ぎたものは、登録した本人のアプリが自動で削除します。

アイテムは `item.json`・`nodes.cmd`（または `scene.hip`）などを含む 1 アイテム 1 フォルダで、ルートの中に作られます。

## 更新

- 方式 A: `pip install --upgrade houdini-asset-library` のあと、Houdini を再起動します。
- 方式 B: 新しい版を入れた環境から、同じ出力先へ `hal-houdini export <出力先>` を実行します（`--runtime` は前回の値が引き継がれます）。SVN を使っている場合はコミットします。

更新があると、アプリの下部に 1 行のお知らせが出ます（作業は止まりません。**アプリが自分で更新を実行することはありません**）。確認は pip で入れた場合に 1 日 1 回 pypi.org へバージョンを問い合わせるだけで、設定の「更新の確認」でオフにできます。管理者は `site_settings.json` の `"update_check": "off"` で全員分を止められます。`hal-houdini check-update` で手動確認もできます。

**旧版（Houdini Node Library / HNL 0.5.x 以前）から**: 名前が 0.6.0 で変わりました。`pip uninstall houdini-node-library` のあと上の手順で入れ直します。設定（`%APPDATA%\HNL`）は初回起動時に `%APPDATA%\HAL` へコピーされ、既存のライブラリはそのまま読めます。

## アンインストール

```
hal-env\Scripts\hal-houdini uninstall
hal-env\Scripts\pip uninstall houdini-asset-library
```

方式 B は、ランチャーや共有の場所から書き出したフォルダを外します。ライブラリのフォルダ（登録したアイテム）は削除されません。設定は `%APPDATA%\HAL` にあります。

## 通信とセキュリティ

通信するのは同じ PC 内の Houdini（`127.0.0.1` のみ、セッションごとのトークンで認証）だけです。例外は上記の更新の確認です。**cmd と hip は実行されるコード**です。インポート前に危険な記述を検査し、明らかに危険なものだけ止めますが、検査は補助です。ライブラリに書き込める人を、信頼できる範囲に限ってください。詳しくは、アプリの「ヘルプ > セキュリティ」を見てください。

## 既知の制限

- 完全には再現できないノード・構造があります（ハードロックしたジオメトリ、ノードグループ、VOP 内蔵ノードなど）。登録時に自動で照合し、お知らせとして出します（止めません）。ノードアセットは、選択外のノードからの入力接続が復元後に失われ、絶対パスで書いたエクスプレッションは元のパスを指します。
- SideFX Labs など「各 PC に入っている前提」の HDA は同梱せず、依存として記録します。読み込む Houdini に無いときは、確認が出て該当ノードを除いて読み込めます。
- ドラッグ＆ドロップは、`HOUDINI_PATH` の先頭に別の `externaldragdrop.py` があるときや、Houdini 21 の一部の場面で制限があります（表示倍率 100% 以外は未検証）。
- ビューポート撮影のサムネイルに、ライセンスの種類によって Houdini のロゴ透かしが入ることがあります。
- バージョン管理は SVN のみです。Windows 専用です。

## 開発者向け

```
python -m venv .venv
.venv\Scripts\pip install -e .[dev]
.venv\Scripts\hal-houdini install      # ソースの Houdini 側ファイルを読む hal.json を作る
.venv\Scripts\python -m hal
.venv\Scripts\python -m pytest -q --ignore=tests/houdini
```

利用者向けの文書は `src/hal/docs/`（アプリと wheel に同梱）、設計メモ・検証結果は `docs/` にあります。`tests/houdini/` のスクリプトは Houdini が必要で、`run_tests.py` は `hython.exe` で実行します。配布物は `python -m build` で作ります。

## ライセンス

MIT License です。全文は `LICENSE` を参照してください。
