Houdini Node Library (HNL)

Houdini のノードを Hscript (nodes.cmd) として保存し、独立したブラウザアプリから呼び出すツールです。 選択ノード、ネットワーク全体、シーン全体を登録できます。登録した内容は、現在のネットワークへの追加、新規シーンへのインポート、シーンを開く、のいずれかで復元します。

必要環境

• Windows
• Houdini 20.5 / 21.0 / 22.0（動作確認は 22.0.429。20.5 と 21.0 は Python 3.11 用の起動フックを同梱しています）
• Python 3.11 以降（アプリ本体用。Houdini 内蔵の Python とは別です）
• TortoiseSVN（任意。SVN でバージョン管理するときだけ。コミット・履歴・差分の画面に使います）

インストール

1. pip で導入します（仮想環境の利用をおすすめします）。PySide6 などの依存も一緒に入ります。

   python -m venv hnl-env
   hnl-env\Scripts\pip install houdini-node-library
   

2. Houdini のユーザー設定に package を導入します。

   hnl-env\Scripts\hnl-houdini install
   

   Documents\houdini22.0\packages\hnl.json が作られます。別の版は --houdini-version 21.0、設定フォルダが標準の場所に無いときは --prefs-dir <フォルダ> で指定します。hnl-houdini status で導入状態を、hnl-houdini uninstall で撤去（hnl.json の削除）ができます。

3. Houdini を再起動します。通常どおり起動した Houdini（GUI）では、起動時にブリッジが自動で立ち上がります。ブリッジは 127.0.0.1 だけで待ち受けます。

4. アプリを起動します。

   hnl-env\Scripts\hnl
   

   コンソールは出ません。python -m hnl でも起動できます。起動済みのときは、新しいウィンドウを作らず既存のウィンドウが前面に出ます。Houdini のシェルフ「HNL」の Open Library からも起動できます。

hnl.json には、いま使っている Python の場所が書かれます。Python の環境を作り直したり移動したりしたときは、hnl-houdini install をやり直してください。

ライブラリに載せない直接共有（0.2.0）

Houdini でノードを選んで「Share Selection」を押すと短い共有コード（テキスト HNL1:...、共有フォルダ K7Q2-M9XD、SVN r1234）が出ます。相手は「Receive」でコードを貼って内容を確認し、取り込みます。使い方は docs/user-guide.md の「共有コード」を見てください。

5 分で試す

1. hnl で起動します。「ルートフォルダを追加してください」と出るので「設定を開く」を押します。
2. 「追加...」で空のフォルダを選び、OK を押します。これがライブラリのルートです。
3. Houdini（package 導入済み）でノードを作って選択し、シェルフ「HNL」の Register to Library を押します。ノードを右クリックして HNL: Register to Library でも開けます。
4. 登録画面が開くので、名前（必要ならプロジェクト・部署・タグ）を確認して「登録」を押します。
5. ブラウザでアイテムを選び、「現在のネットワークへ追加」を押します。確認ダイアログで「インポート」を押すと、Houdini にノードが復元されます。

詳しい使い方は docs/user-guide.md、保存形式は docs/format.md、セキュリティと信頼モデルは docs/security.md を見てください。

ランチャーや共有フォルダ・SVN で使う場合

会社のランチャーが Houdini の環境変数やパッケージを管理していて Documents\houdini<版>\packages\hnl.json が読まれないときや、共通の SVN で全員に配りたいときは、一式を任意のフォルダへ書き出します。

hnl-houdini export <出力先フォルダ>

<出力先>/
  hnl.json              Houdini パッケージ定義（相対指定。絶対パスを含まない）
  hnl_package/
    hnl/                アプリ本体 + Houdini 側ファイル
    requirements.txt  hnl.bat  VERSION  README.txt

• 場所を移しても、別の PC へコピーしても、SVN で共有しても動きます。出力は決定的（.pyc なし、テキストは LF、時刻やマシン名なし）なので、再実行しても無駄な差分は出ません。
• Python と依存ライブラリ（requirements.txt）は各 PC に用意します。起動に使う Python は、環境変数 HNL_APP（完全なコマンド）、HNL_PYTHON（python.exe のパス）、出力先と同じ階層の python\ や .venv\、pip 導入環境、pyw/py、PATH 上の pythonw/python の順で決まります。全 PC で Python の場所が同じなら --python <パス> で hnl.json に HNL_PYTHON を書けます。ライブラリが足りないときは、不足分と pip install -r requirements.txt の案内が出ます。
• オプション: --json-name <名前>、--no-json（ランチャーが環境変数を直接設定する場合）、--dry-run、--prune、--init-site-settings。hnl-houdini env [--root <出力先>] [--format bat|ps1|json|plain] で、ランチャーに登録する HOUDINI_PATH（既定の検索パスを表す末尾の & を残す）・PYTHONPATH・HNL_PYTHON の値を表示します。
• 共有の hnl.json を置く場所が分かっているときは hnl-houdini install --packages-dir <フォルダ> でも作れます。hnl-houdini status は、HOUDINI_PACKAGE_DIR などの環境変数で既定の場所の hnl.json が読まれない可能性があるときに知らせます。
• 共通ライブラリを最初から見せたいときは、hnl_package/site_settings.json（または環境変数 HNL_SITE_SETTINGS）に roots と ref_excludes の既定値を書きます。利用者がルートを 1 つも持たない間だけ初期値として使われ、利用者が編集した後は上書きされません。export はこのファイルを上書きも削除もしません。
• 更新: 新しい版を pip で入れる → 同じ出力先へ hnl-houdini export → SVN にコミット。SVN 管理下で不要になったファイルは一覧表示だけです（svn delete は利用者が行う。--prune で作業コピーから消せます）。
• Houdini の Python Shell で import hnl_bridge; hnl_bridge.diagnose() と打つと、ブリッジの場所・サーバーの状態・アプリの起動コマンド・シェルフが HOUDINI_PATH 上にあるかを確認できます。

詳しくは docs/getting-started.md を見てください。

開発者向け

ソースから動かすときの手順です。

python -m venv .venv
.venv\Scripts\pip install -e .[dev]
.venv\Scripts\hnl-houdini install      # ソースの Houdini 側ファイルを読む hnl.json を作る
HNL.bat                                  # または .venv\Scripts\python -m hnl

フォルダ構成:

src/hnl/              アプリ本体 (core / vcs / houdini / ui)
src/hnl/_houdini/     Houdini 側ファイル一式（python/hnl_bridge, python3.11libs, python3.13libs, toolbar, OPmenu.xml）。wheel にも同梱される
tests/                pytest（tests/houdini は Houdini を使う検証スクリプト）
tools/                デモライブラリ生成などの補助スクリプト
docs/                 利用者向け文書、設計メモ、検証結果
HNL.bat               開発用の起動バッチ（リポジトリの .venv を使う）

テストの実行:

.venv\Scripts\python -m pytest -q --ignore=tests/houdini
"%HFS%\bin\hython.exe" tests\houdini\run_tests.py

tests/houdini/ のスクリプトは Houdini が必要です。run_tests.py は hython.exe で、run_e2e.py などは .venv\Scripts\python で実行します（実行すると Houdini が起動するものがあります）。

配布物（wheel と sdist）は python -m build で作ります（pip install build が必要）。

既知の制限

• 保存形式は cmd のみです。.hip ファイルは扱いません。
• 完全には再現できないノード・構造があります（ハードロックのジオメトリ、ノードグループ、VOP 内蔵ノードなど）。登録・共有時に自動で照合し、お知らせとして出します（止めません）。一覧と対処は docs/getting-started.md の「保存されないもの・制限」を見てください。
• 選択外のノードからの入力接続は、復元後に失われます。選択外へのチャンネル参照は参照切れになります。
• 絶対パスで書いたエクスプレッションは、復元後も元のパスを指します。
• ビューポート撮影の画像に Houdini のロゴ透かしが入ることがあります（Apprentice など、ライセンスの種類によります）。
• バージョン管理は SVN のみです。
• Windows 専用です。
• cmd は実行されるコードです。危険な記述が見つかったときだけインポートを止めます（検査は補助です）。信頼する場所・検査・限界の詳細は docs/security.md を見てください。

ライセンス

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