InstaMAT Studioの機能の一部であるPipelineを試してみました。
InstaMAT Piplelineの概要
この記事を作るにあたってVoidberg氏、the_tux氏には多くの協力をいただきました。
ありがとうございます。
InstaMAT Pipelineとは
InstaMAT PipelineはInstaMAT Studioとは別に提供されるツールの一種になります。
特徴として、GUIを用いずコマンドライン上でElement Libraryを書き出すことができます。
使用する上での注意点
InstaMAT PipelineはPionear Licenseでは利用ができません。
利用するためにはPionear License以外のライセンスを導入する必要があります。
筆者はPro Lisenceを導入しているため、どの他のライセンスでは動作などが異なる場合がございます。
（未検証のため）
実際に触ってみる
筆者の環境について
OS:Windows 11
InstaMAT Lisence:Pro License
Date:2025/01/22
導入
Pro Lisence導入後のInstaMAT初回起動時に「InstaMAT パイプラインの設置」のポップアップが起動します。
Pipelineを利用する前提なので、「パスの追加」を選択します。
環境変数を確認するとCドライブのInstaMAT Studioが参照されていることがわかります。
コマンドプロンプトやPowerShellなどで動作確認をします。
InstaMATPipeline
無事にInstaMAT Piplelineを実行することができました。
helpを叩いて中身を確認してみる
前項で実行した出力に「INFO: No application mode specified use '-help' to show help.」、つまりhelpを表示して中身を確認しろ！と注意を受けてしまいました。
まずは、helpの実行からしてみます。
InstaMATPipeline -help
画面を埋め尽くす量のhelpが表示されたかと思います。
helpの出力内容はInstaMAT Pipeline Documentで確認ができます。
InstaMAT Pipeline | InstaMAT Documentation
helpの内容を大まかにまとめる
前項で出力されたhelp中で紹介されている引数をざっくり紹介します。
※コマンド内、「＜、＞」が記法の関係で表記が面倒なので「（、）」で代替しています。
区別はDocumentのhelpを参考ください。
| 引数 | 説明 | 補足 |
| -env [Path] | PipelineとInstaMAT Studioの連携します | InstaMAT PipelineがInstaMATと別の場所にインストールされている場合、InstaMATのインストールディレクトリを指定します |
| -software | GPUではなく、CPUで処理をするときに指定します | - |
| -mode (ApplicationMode) (Path) | コマンドラインからAtomグラフやElementグラフを操作するときに利用します。 | Application ModeはExecute、Info、Search、UnitTest、GenerateDOcumentation、GeneratePreviews、Cook、Packageのいずれかを設定する必要があります。続けてパッケージのパスを指定します。パッケージへの参照パスが存在しないとき、ライブラリ内で利用可能なAtomグラフ、Elementグラフのみ使用可能です。 |
| -graph (Name) (OutputWidth) (OutputHeight) (OutputFormat) (OutputPathFormat) | 実行するグラフ、および出力方法を設定します | 各パラメータに関しては後述 |
| -grayscale | 出力結果はグレースケールに置換（変換）します | グラフがグレースケール非対応の場合は置換せずに出力されます |
| -exportTemplate(ExportTemplatePath) | 指定されたパスから出力テンプレートを読み込みます | ModeでExecuteを指定する必要があります。また、出力テンプレートはInstaMATStudioで作成され、json形式で保存されます。*1 |
| -parameter(Name) (ParameterValue) | パラメータを制御します | ModeをExecuteで実行する必要があります。ParameterValueはjson表記をするよう必要があります。また、Seed値を変更する場合はNameに"Seed"、ParameterValueを「0から100000」の整数を使用します。 |
| -compositionParameter(ConpositionNodeName)(OutputParameter)(InputParameter)(ParameterValue) | 実行されるグラフの出力に入力パラメータを指定したノードを加えて出力ができます | ModeをExecuteで実行する必要があります。 |
| -outputFilter(FilterPattern) | 出力される要素のうち命名フィルタをかけた内容を抽出します | ModeをExecuteで実行する必要があります。フィルタは画像だけでなくメッシュ出力含むすべての出力に適用されます。例えば、「Ambient」、「Tangent」をフィルタにした場合、「Tangent Space Normal」、「Ambient Occlusion」は出力されますが、それ以外の出力は無視されます。 |
| -outputMeshFormat (FileExtension) | メッシュを出力するときのフォーマットを指定します | ModeをExecuteで実行する必要があります。fbx、obj、ilmeから選択する必要があり、指定されないときはfbxが使用されます。 |
| -outputPointCloudFormat(FileExtension) | PointCloudのフォーマットを指定します | ModeをExecuteで実行する必要があります。現在はply形式のみがサポートされているようです。 |
| -graphInfo (Name/ID/GURL) | コマンドライン上でノードの構成を確認できます | ModeをInfoで実行する必要があります。 |
| -graphSerch (Query)(Category) | ライブラリ、パッケージから情報を検索できます | ModeをSerchで実行する必要があります。検索結果はjson形式で出力されます、 |
| -package (context) (task)(value) | パッケージに関する操作（外部リソース・プロジェクト（Atomグラフ・ElementGraph）の追加・削除やパッケージ情報の変更）を行えます | ModeをPackageで実行する必要があります。 |
| -outputFolder (path) | 出力先を指定します | ModeをUnitTest, GenerateDocumentation, GeneratePreviews, Cookで実行する必要があります。 |
| -referenceFolder(path) | 参照画像の出力先を指定します | ModeをUnitTestで実行する必要があります。 |
| -missmatchFolder(path) | 不一致画像の出力先を指定します | ModeをUnitTestで実行する必要があります。 |
| -HTMLOutput(path) | 生成されたHTMLレポートの出力先を指定します | ModeをUnitTestで実行する必要があります。 |
| -HTMLTemplate(TemplatePath) | 生成されたHTMLレポートのテンプレートを設定します | ModeをUnitTest 、HTMLOutputで実行する必要があります。 |
| -validateDocs | グラフを検証し、ドキュメント生成が可能か確認します | ModeをUnitTestで実行する必要があります。 |
| -category | カテゴリを指定するときに利用します | ModeをUnitTest, GenerateDocumentation, GeneratePreviewsで実行する必要があります。複数回指定することで複数のカテゴリを指定できます。また、ModeがGenerateDocumentationの場合、カテゴリが指定されていない場合は全てのカテゴリが出力されます。 |
| -includeTemplates | テストカテゴリにあるグラフテンプレートをユニットテストに含めます | ModeをUnitTestで実行する必要があります |
| -excludeGraph (graphID) | 指定されたグラフIDを持つグラフを単体テストから除外します | ModeをUnitTestで実行する必要があります。また、同時に複数回利用し、複数のグラフを追加することもできます |
| -excludeCategory (Category) | 指定されたカテゴリを除外カテゴリリストに追加します | ModeをGenerateDocumentation, GeneratePreviews, Cookで実行する必要があります。また、同時に複数回利用し、複数のカテゴリを追加することもできます。 |
| -imageFolderBase(URL) | 生成された画像のベースURL（？）を設定します。 | デフォルトは「"/"」です |
| -authorize(email)(LicenseKey) | InstaMAT Pipelineのマシン認証 | 詳細はドキュメント*2 |
| -deauthorize(email)(LicenseKey) | InstaMAT Pipelineのマシン認証解除 | 認証解除が完了するまで24時間かかります |
| -machineKey | マシンの固有番号（認証キー）を取得します | - |
| -authorizeKey(machinekey)(filename)(Email)(LisenceKey) | machinekeyでマシン認証をしたうえでライセンスファイルをfilenameに書き込みます | マシンの代替としてライセンス認証をするために使用されます |
| -ingestLicense(path) | 指定されたパスにあるライセンスファイルでマシン認証を実施します | - |
| -liceneinfo | ライセンス情報を表示します | - |
サンプルコードの実行
では、実際にDocumentに掲載されているサンプルコードを実行してみます。
グラフ実行時の注意
コマンドプロンプトやPowerShell等の実行はInstaMAT Pipleline直下で実行してください。
InstaMAT StudioとInstaMAT Pipelineが同一階層に入っていない場合は以下のコードをあらかじめ実行する必要があるそうです。
InstaMATPipeline -mode Execute -env (InstaMAT Studioのファイルパス)
グラフを出力（ファイル指定なし）
早速、実際にグラフを出力してみましょう。
まずデフォルトで登録されている「Pavement」を出力してみます。
※ドキュメントでは「Arc Pavement」になっていますが、「Pavement」に命名変更されたそうです。
InstaMATPipeline -mode Execute -graph "Pavement" 1024 1024 Normalized8 "ここに格納先を指定\{GRAPH.NAME}_{OUTPUT.NAME}.png"
格納先ですが、CLIを管理者権限で実行していない場合、当然Cドライブ直下やProgram Filesにファイルを格納できませんの注意ください。
処理が完了すると実行ログが出力されます。
＜参照エラー＞
→正しい名称を指定することで解決
＜書き込みエラー＞
→保存先を管理者権限外にするかCLIを管理者権限で実行
今回実行したものは「InstaMAT Studio」に既に保存されているパッケージを出力しました。
では、InstaMAT Studioに登録していないパッケージはどのように出力するのでしょうか
グラフを出力（ファイル名指定）
簡単なElementグラフを作成しました。
パッケージ名を「Pipeline_test」、プロジェクト名を「pipeline_test(graph)」にします。
InstaMAT Studioと全く関係ない場所に保存します。
保存するIMP
（今回はデスクトップ上に「delete_mat」フォルダを作成し、格納しました）
InstaMATPipeline -mode Execute "C:\Users\**ユーザー名**\Desktop\delete_mat\pipeline_test(file).IMP" -graph "pipeline_test(graph)" 1024 1024 Normalized8 "C:\Users\**ユーザー名**\Desktop\delete_mat\test.png"
無事に画像が出力できました。
このように、外部のIMPファイルを読み込ませてファイルをエクスポートすることもできます。
3dモデルの出力
InstaMATのロゴの高さ情報からメッシュを生成するグラフ、およびパッケージを作りました。
ファイル名：mesh_out.IMP
グラフ名：MAT_logo
InstaMATPipeline -mode Execute "C:\Users\ユーザー名\Desktop\delete_mat\mesh_out.IMP" -graph "MAT_logo" 1024 1024 Normalized8 "C:/Users/ユーザー名/Desktop/delete_mat/mat.obj" -outputMeshFormat .obj
mat.objとmat.mtlが出力されました。
Blenderに読み込むとメッシュ化されたInstaMAT Logoが表示されました。
uv展開をする
前項で出力されたロゴはUV展開が適切にされていません。
作成段階で「Mesh UV Unwrap」を挟めば処理は終わりますが、ここでは先ほど作成したグラフを利用するのではなく、出力された3dモデルを利用します。
（あくまで試すためであって、実運用だったら元データを修正します）
InstaMATPipeline -mode Execute -graph "Mesh UV Unwrap" 1024 1024 Normalized8 "C:\Users\ユーザー名\Desktop\delete_mat\uv\uv.obj" -parameter Mesh "file://C:\Users\ユーザー名\Desktop\delete_mat\mat.obj" -outputMeshFormat .obj
このように元々MAT内に備わっている機能を -parameterの引数でファイル参照することで処理を行えます。
ちなみに出力されたUVは画像の通り、InstaMAT Studio側の結果とは何やら異なるようです。
ノードのパラメータを見てみる
先ほど実行した「Mesh UV Unwrap」のパラメータをみてみます。
InstaMATPipeline -mode Info -graphInfo "Mesh UV Unwrap"
該当ノード（グラフ）のパラメータをみることができました。
グレースケール出力
「Blue Noise」ノードのようなグレースケール変換を標準でもつグラフには -grayscale引数を渡すことで出力がグレースケールになります。
InstaMATPipeline -mode Execute -graph "Blue Noise" 1024 1024 Normalized8 "C:\Users\ユーザー名\Desktop\delete_mat\img\test.png" -grayscale
フィルター
複数の出力がある場合に -outputfilter 引数を利用することで出力を制限できます。
メッシュを読込み、ベイクをしたときの出力画像を制限してみます。
ドキュメントの生成
InstaMATPipeline -mode GenerateDocumentation -env "Environment/" -outputFolder "C:\Users\ユーザー名\Desktop\delete_mat\doc2"
上記のコマンドでLibrary.IMPに含まれるすべてのグラフのドキュメントを自動生成できます。
（全件対象のため、実行注意）
ドキュメントはマークダウン記法でエクスポートされます。
範囲を絞る場合は以下のように変更をします。
InstaMATPipeline -mode GenerateDocumentation -env "Environment/" -outputFolder "C:\Users\ユーザー名\Desktop\delete_mat\doc2" -category "Noise"
Noiseカテゴリのみを抽出してエクスポート
InstaMATPipeline -mode GenerateDocumentation -env "Environment/" -outputFolder "C:\Users\bp_19\Desktop\delete_mat\doc3" -excludeCategory "Noise"
Noiseカテゴリのみを除外してエクスポート
おわりに
ここまでInstaMAT Pipelineを参考にわかる範囲で色々と試してみました。
Pipelineの使用用途は単純明快。アセットを作る際に非常に便利かと思いました。
例えば、同じ命名規則で作成されたメッシュ群をテクスチャペイントするときにLayeringプロジェクトでMesh Maskを利用し「サブメッシュ単位」でマスクを作成します。
この内容をElementGraphにインポートし、テクスチャペイントを行う。加えて -parameter引数にメッシュを渡すほか、色情報、シード値を加えることでコマンドライン上でアセットを作ることができるかもしれません。
ただ、グラフ同士を連続的に実行することはできないので、例えばBatファイルなどを作成して連続的に処理をするなど工夫が必要かもしれません。
１から機構を作ることはできませんが、グラフやAtom上で作成された情報をコマンドライン上で実行できる。これが本当に面白いところでした。
また、この記事を書くにあたりInstaMAT Pipelineを触った時間は４時間ほどです。
非常にわかりやすい操作性でした。
*1:InstaMAT Studio> Environment > Output Templates
