Metadata-Version: 2.4
Name: houdini-node-library
Version: 0.3.0
Summary: Houdini Node 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 Node Library (HNL)

Houdini のノードを Hscript (`nodes.cmd`) として保存し、独立したブラウザアプリから呼び出すツールです。
選択ノード、ネットワーク全体、シーン全体を登録できます。登録した内容は、現在のネットワークへの追加、新規シーンへのインポート、シーンを開く、現在のシーンへのマージ、のいずれかで復元します。
ノード単体・ノード群は Hscript（cmd）で、**シーン全体は hip のまま**保存します（大きなシーンでも数秒で登録・開けるため。0.3.0 から）。

## 必要環境

- 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](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/user-guide.md)、保存形式は [docs/format.md](docs/format.md)、セキュリティと信頼モデルは [docs/security.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](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](docs/getting-started.md) の「保存されないもの・制限」を見てください。
- 選択外のノードからの入力接続は、復元後に失われます。選択外へのチャンネル参照は参照切れになります。
- 絶対パスで書いたエクスプレッションは、復元後も元のパスを指します。
- ビューポート撮影の画像に Houdini のロゴ透かしが入ることがあります（Apprentice など、ライセンスの種類によります）。
- バージョン管理は SVN のみです。
- Windows 専用です。
- cmd は実行されるコードです。危険な記述が見つかったときだけインポートを止めます（検査は補助です）。信頼する場所・検査・限界の詳細は [docs/security.md](docs/security.md) を見てください。

## ライセンス

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