Reference 2.0

外部USDファイル/他のLOPノードで作成されたレイヤーの内容を既存シーングラフツリーのブランチで参照します。既存のリファレンスを削除/置換することもできます。

On this page	概要 Tips How to USDのリファレンスの説明ローカル変数パラメータ
Since	19.5

概要 ¶

このノードは、異なる場所にあるPrimsのツリーを現行シーングラフ内で参照することができます。この異なる場所というのは、外部ファイルや他のLOPノードだったり、さらには同じツリー内の異なるPrimsのことを指します。同じソースから複数のリファレンスを作成することができるので、既存のPrimsを再利用することができます。

USDの概念に関する詳細は、 リファレンスの説明 のセクションを参照してください。

Tips ¶

Action パラメータをCreate New Primitivesに設定した場合、 Primitive Path には単一Primパスを指定してください。このパラメータは、リファレンスが作成される度に再評価され、必要に応じて、数値の接尾辞を付けて固有な名前になります。
Action パラメータをEdit Existing Primitivesに設定した場合、 Primitive Path はプリミティブパターンとして解釈されます。そのプリミティブパターンにマッチしたすべてのPrimにリファレンスが追加されます。
リファレンスの追加先に指定したPrimが既にリファレンスを持っている場合、その新しいリファレンスが 既存のリファレンスと合成 されます。その新しいリファレンスを追加する前に既存のリファレンスをクリアする方法は、 Pre-Operation パラメータを参照してください。
このノードで指定したリファレンスのオペレーションは、順番通りに実行されるので、複数のリファレンスを単一Primに追加することができます。例えば、複数入力にCreateアクションを実行して何か新しいPrimsを作成し、その後でInheritアクションを実行して、その新しく作成された各リファレンスPrimにInheritコンポジションアークを追加することができます。

How to ¶

シーングラフツリー内のPrim上でリファレンスされる“ターゲット”としては外部ファイルを指定することが多いですが、このノードでは、他のLOPノードの出力のPrimをリファレンスすることもできます。

To...	Do this
外部ファイルのPrimをリファレンスする	Primitive Path パラメータを、リファレンスされるPrimの取り付け先となるシーングラフパスに設定します。 Reference Type パラメータを、“Reference Files”または“Payload Files”(詳細はペイロードを参照)に設定します。 File Pattern パラメータを、リファレンスするUSDファイルのファイルパスに設定します。このファイルパスにワイルドカードを含めることで、複数のディスク上のファイルにマッチさせることができます。そうした場合、マッチしたファイル毎に新しいPrimが作成されます。標準のワイルドカードのマッチングだけでなく、この File Pattern パラメータには、特別なトークンの`<LASTMATCH>`を含めることができます。ワイルドカードのパスコンポーネントの後にこのトークンを付けると、このトークンには、そのワイルドカードコンポーネントのマッチングに使用された値が設定されます。そのため、もしディスク上に`/tmp/assets/Book/Book.usd`というファイルが存在すれば、`/tmp/assets//<LASTMATCH>.usd`というリファレンスパス* では`Book.usd`レイヤーが見つかります。このトークンは、アセットの命名規則でUSDファイルが親ディレクトリ名にマッチする必要がある時に非常に役立ちます。その外部ファイルで読み込むPrimを選択したい場合は、 Reference Primitive ポップアップメニューを使用します。通常では、 Reference Primitive パラメータを“Reference Automatically Chosen Primitive”の設定のままにします。特定のPrimを取り込みたいのであれば、 Reference Primitive パラメータを“Reference Specific Primitive”に変更し、 Reference Primitive Path パラメータにそのPrimパスを入力します。
LOPノードの出力からPrimをリファレンスする	リファレンスしたいステージを含んだLOPノードをこのノードのマルチ入力に接続します。接続された入力毎に Primitive Path が再評価され、その Primitive Path にローカル変数を含めることで、その入力コネクション毎に別々のPrimが生成されるようにすることができます。単一接続の場合、 Reference Primitive Path パラメータを取り込むPrimに設定することができます。このノードのマルチ入力に複数の入力を接続する場合: パラメータインターフェースの下部にあるテーブルを使用することで、リファレンスの格納先となるターゲットPrimを明示的に指定することができます。他にも、各入力を参照する回数を別の回数に指定したり、各入力から参照する特定のPrimを指定することができます。 Reference Primitive Path パラメータに、すべての入力内で同じPrimから取り込むシーングラフパスを設定したり、または、エクスプレッションを記述することができます。このエクスプレッションは、このノードのマルチ入力に接続された入力毎に評価されます。エクスプレッションには、(`1`から始まる)現行入力インデックスを示した`@input`ローカル変数(`$IIDX`は廃止)を使用することができます(文字列パラメータでは、エクスプレッションをバッククォートで閉じる必要があることを忘れないでください)。
1番目の入力のシーングラフツリー内の他のPrimをリファレンスする	Primitive Path パラメータに、リファレンスするPrimの取り付け先となるシーングラフパスを設定します。 Reference Type パラメータを、合成のタイプに応じて“Reference From First Input”、“Inherits From First Input”、“Specialize From First Input”のどれかに設定します。単純な“Reference”以外のタイプはどのような時に選択するのかについては、継承と特別化を参照してください。 Reference Primitive パラメータを“Reference Specific Primitive”に設定します。 Reference Primitive Path パラメータに、リファレンスしたいPrimのシーングラフパスを設定します。
すべての既存リファレンスをブロック(遮断)する	Primitive Path パラメータに、現在のところブロックしたいリファレンスを含んでいるPrimのシーングラフパスを設定します。 Pre-Operaiton メニューを“Clear All References”に設定します。
1個の既存リファレンスをブロック(遮断)する	Primitive Path パラメータに、削除したいリファレンスを含んだPrimのシーングラフパスを設定します。削除したいリファレンスを指定できるようにパラメータを設定します。例えば、`lamp.usd`ファイルのリファレンスを削除したいのであれば、 Reference Type パラメータを“Reference Files”に設定し、 File Pattern パラメータに`lamp.usd`を設定します。 Reference Operation を“Remove References”に設定します。
既存ファイルからいくつかのPrimをリファレンスする	まず最初に、 Primitive Type を`None`に設定したPrimitive LOPを使用して、外部ファイルからPrimをリファレンスするPrimを作成します。これらのPrimの名前は、その外部ファイルからリファレンスされるルートPrimの名前に合わせてください。 Parameter Order を`Primitive Path Evaluated Before File Pattern`に設定し、次に、 Action を`Edit Existing Primitives`に設定します。 Primitive Path に、Primitive LOPで作成したPrimのリストを設定します。 Reference Type を“Reference File”または“Payload File”(詳細はペイロードを参照)に設定します。 File Pattern に、参照するUSDファイルのファイルパスを設定します。このファイルパスにはワイルドカードを含めることができません。 Reference Primitive を`Reference Specific Primitive`に設定します。 Reference Primitive Path に、/`strsplit(@primpath, “/”, -1)`のエクスプレッションを設定します。

USDのリファレンスの説明 ¶

リファレンスは、参照したファイル内のツリーを取り込み、そのツリーを現行ツリー内のブランチ上に“inject(注入)”します。

例えば、以下のツリーから始めると仮定します:

参照する前のシーンツリー


/Lights/
    light1
    light2
/Models/
    tableside_lamp

/Models/tableside_lampがlamp.usdを参照し、そのファイルが以下の内容だとします:

lamp.usdの内容


/lamp/
    base
    bulb
    shade
    socket
    switch

このファイルを参照した後のツリーは、以下のようになります。

参照した後のシーンツリー


/Lights/
    light1
    light2
/Models/
    tableside_lamp/
        base
        bulb
        shade
        socket
        switch

参照(/Models/tableside_lamp)を含んだPrimと参照先のPrim(lamp.usd内の/lamp)は、(オピニオン強度で決定したプロパティ値でオーバーライドして)合成されますが、その合成されたPrimは、参照元のPrimの名前を維持します。
内容を参照する時は、参照先のファイル内のPrim(上記の例だと/lamp)を指定しなければなりません。そして、そのPrimはルート(/)にすることができません。そのため、他のレイヤーから参照されることを想定してファイルを作成する時は、単一ルートプリミティブ下にその内容が収まるようにしてください。

(ファイルのデフォルトプリミティブを指定することができます。ファイルを参照した際に、そのファイル内の特定のPrimを指定しなかった場合には、そのファイルの“デフォルトプリミティブ”が取得されます。)

リファレンスは、個々の小さなアセットを大きなシーンに再利用するのに役立ちます。特に、 リファレンスは、同じファイルを何回も別のシーングラフ場所に読み込むことができる唯一の方法です (サブレイヤー化はツリー全体に対して動作するので、同じファイルを何回もサブレイヤー化しても何の効果もありません)。

単純なゴミ箱アセット

#usda 1.0
(
   defaultPrim = "TrashCan"
)

def Xform "TrashCan" (
   kind = "component"
)
{
   def Cylinder "Can"
   {
       token axis = "Y"
       bool doubleSided = 0
       double height = 2
       double radius = 1
   }
}

セット内の3部屋でゴミ箱アセットを3回参照したファイル

#usda 1.0
()

def Xform "Scene"
{
   def Xform "Set"
   {
       def "BathroomTrashCan" (
           append references = @./trashcan.usda@
       )
       {
           double3 xformOp:translate = (2, 0, 1.4)
           uniform token[] xformOpOrder = ["xformOp:translate"]
       }

       def "KitchenTrashCan" (
           append references = @./trashcan.usda@
       )
       {
           double3 xformOp:translate = (16.01, 5, -43.072)
           uniform token[] xformOpOrder = ["xformOp:translate"]
       }

       def "OfficeTrashCan" (
           append references = @./trashcan.usda@
       )
       {
           double3 xformOp:translate = (-7.12, 0, 11.9)
           uniform token[] xformOpOrder = ["xformOp:translate"]
       }
   }
}

Reference LOPとStage Manager LOPが参照を作成します。 Graft Stages LOPも同様ですが、これはファイルから参照するのではなくて、LOPネットワーク内のどこからかのシーングラフツリーにブランチを挿入します。

ローカル変数 ¶

@sourcename

参照されているディスク上のファイルの(拡張子を除いた)名前、または、入力コネクションの名前。 Parameter Order がFile Pattern Evaluated Before Primitive Pathの場合にのみ設定されます。

@sourcepath

参照されているディスク上のファイルのフルパス、または、入力コネクションのフルパス。 Parameter Order がFile Pattern Evaluated Before Primitive Pathの場合にのみ設定されます。

@sourceindex

このノードが参照している入力コネクションの増分番号、または、ファイルの増分番号。 Parameter Order がFile Pattern Evaluated Before Primitive Pathの場合にのみ設定されます。

@sourceprim

現行マルチ入力コネクションの増分番号、または、ファイルが何回も参照されている場合はそのファイルの増分番号。 Parameter Order がFile Pattern Evaluated Before Primitive Pathの場合にのみ設定されます。

@sourcenumprim

参照される現行マルチ入力コネクションの総回数、または、ファイルの総回数。 Parameter Order がFile Pattern Evaluated Before Primitive Pathの場合にのみ設定されます。

@prim

このノードが作成した各リファレンスの増分番号、または、リファレンスの追加先の各Primの増分番号。どの Parameter Order 設定でも利用可能です。

@primpath

リファレンスの追加先のPrimのフルパス。 Parameter Order がPrimitive Path Evaluated Before File Patternの場合にのみ設定されます。

パラメータ ¶

References From Multi-input

Enable

マルチ入力からリファレンスのオペレーションを実施します。

Parameter Order

このパラメータをFile Pattern Evaluated Before Primitive Pathに設定すると、 File Pattern パラメータでワイルドカードが利用可能になります。そのパターンにマッチしたファイル毎に Primitive Path が評価され、そのファイルを参照するPrimのパスが生成されます。

このパラメータをPrimitive Path Evaluated Before File Patternに設定すると、各Prim上には単一リファレンスが作成され、参照ファイルまたは参照Primは、そのリファレンスを格納しているPrimパスとして機能することができます。 Primitive Path にマッチしたPrim毎に、 File Pattern と Reference Primitive Path のパラメータが再評価され、現在の Primitive Path にアクセスする機能によって、そのPrimに固有の値を生成することができます。

Primitive Path

Create モードでは、このパラメータには単一Primパスを指定します。これは、参照ブランチの取り付け先となるシーングラフパスです。このPrimが存在しなかった場合、このノードはそのPrimを作成します。 Edit モードでは、このパラメータは、このノードの1番目の入力に接続されたステージ上の既存のPrimsに対してマッチされるプリミティブパターンを指定します。ローカル変数を使用することで、そのリファレンスPrimパスを制御することができます。

Action

このノードがマルチ入力コネクションに対して新規Primsを作成するのか、または、既存のPrimsを編集するのか指定します。 Create モードでも、Primが既に存在すればそのPrimを編集しますが、マルチ入力コネクション毎に作成されるリファレンス毎に自動的に固有なPrim名が生成されます。 Edit モードでは、いくつもの既存のPrimsにリファレンスを追加することができます。

Primitive Count

Create モードで、マルチ入力コネクション毎に作成するリファレンスPrimの数を指定します。

Reference Type

リファレンスしたPrimに対して作成するコンポジションアークのタイプ。

Reference Inputs

マルチ入力コネクションからPrimをリファレンスします。

Payload Inputs

マルチ入力コネクションからPrimをペイロードとして参照します。

Make Instanceable

新しいPrimまたは変更されたPrimを(“ネイティブインスタンス”と同様の)インスタンス化可能としてマークします。これによって、同じブランチを複数の場所でリファレンスした場合にメモリが節約されますが、リファレンスしたPrimの子Primsは編集不可になります。このオプションを無効にすると、Primsは明示的に“インスタンス化可能”としてマークされません。代わりに、各Prim上の現在のinstanceable値がそのままになります。

Reference Primitive

マルチ入力コネクションから取り込むPrimを制御します。

Reference Automatically Chosen Primitive

参照した入力コネクションにデフォルトPrimが設定されていれば、そのPrimが使用されます。デフォルトPrimがない場合は、ルートにある最初のXform Primが使用されます。ルートに何もXform Primがない場合は、任意のタイプの最初のルートPrimが使用されます。

Reference Default Primitive

参照した入力コネクションにデフォルトPrimが設定されていれば、そのPrimが使用されます。デフォルトPrimがない場合は、このノード上に警告が表示されます。

Reference Specific Primitive

Reference Primitive Path パラメータのシーングラフパスを参照します。このモードでは、入力テーブルの各行で指定されたリファレンスPrimが Reference Primitive Path パラメータで指定されたリファレンスPrimよりも優先されます。

Reference Primitive Path

Reference Primitive が“Reference Specific Primitive”の時、ここには、参照するPrimのシーングラフパスを指定します。

(このフィールドにautomaticPrimまたはdefaultPrimを設定すると、 Reference Primitive を“Reference Automatically Chosen Primitive”または“Reference Default Primitive”に設定した時の挙動と同じになります。)

File and Internal References

Number of References

このノードは、外部ファイルやシーン内に既に存在するPrimsのリファレンスを何個も追加することができ、各リファレンスを個別に制御することができます。

Enable

マルチパラメータのこのインスタンスのリファレンスを実行します。

Primitive Path

Create モードでは、このパラメータには単一Primパスを指定します。これは、参照ブランチの取り付け先となるシーングラフパスです。このPrimが存在しなかった場合は、このノードがそのPrimを作成します。 Edit モードでは、このパラメータは、このノードの1番目の入力に接続されたステージ上の既存のPrimsに対してマッチされるプリミティブパターンを指定します。利用可能なローカル変数のリストを参照してください。

Action

このノードがマルチ入力コネクションに対して新規Primsを作成するのか、または、既存のPrimsを編集するのか指定します。 Create モードでも、Primが既に存在すればそのPrimを編集しますが、このマルチパラメータインスタンスで作成されるリファレンス毎に自動的に固有なPrim名が生成されます。 Edit モードでは、いくつもの既存のPrimsにリファレンスを追加することができます。

Primitive Count

Create モードで、このマルチパラメータインスタンスで作成するリファレンスPrimの数を指定します。

Reference Type

リファレンスしたPrimに対して作成するコンポジションアークのタイプ。

Reference File

外部USDファイルからPrimを参照します。

Payload File

外部USDファイルからPrimをペイロードとして参照します。

Reference From First Input

1番目の入力のシーングラフツリーの他のPrimを参照します。

Inherit From First Input

(1番目の入力の)シーングラフツリーの他のPrimに“Inherits”コンポジションアークを適用します。このInheritターゲットはまだ存在している必要はありません。

Specialize From First Input

(1番目の入力の)シーングラフツリーの他のPrimに“Specializes”コンポジションアークを適用します。このSpecializeターゲットはまだ存在している必要はありません。

Make Instanceable

File Pattern

Reference Type が“Reference File”または“Payload File”の時、ここには参照するファイルのファイルパスを指定します。このパラメータにはワイルドカードを含めることができます。その場合、ディスク上のマッチしたすべてのファイルが別々のリファレンスとして追加されます。 Create モードでは、これはマッチしたファイル毎に新しいPrimを作成します。 Edit モードでは、マッチしたすべてのファイルは、 Primitive Path パターンにマッチしたすべてのPrim上で参照されます。

スペースで区切ってファイルパスを指定する場合(そのパスにワイルドカード文字が含まれているかどうか関係なく)、そのような各ファイルパスは必ず引用符で閉じてください。このパラメータ値は、まず最初に、トークンに分割され(その引用符のマークを考慮してスペースで区切られます)、次に、各トークンにワイルドカード文字が含まれていればそのトークンは展開され、ワイルドカード文字が含まれていなければ単純にファイルパスとして扱われます。たとえディスク上にマッチしたファイルが見つからなくても、単純なファイルパスがリファレンスとして追加されます。

ワイルドカードのパターン展開は、このノードでそのパターンが初めて展開された時にのみディスクからファイルが走査され、その結果がキャッシュ化されます。このワイルドカードのパターン展開のキャッシュは、 Reload Files ボタンを押すことでクリアすることができます。

Reference Primitive

Reference Type が“Reference File”または“Payload File”の時、これは、外部ファイルから取り込むPrimを制御します。

Reference Automatically Chosen Primitive

参照したファイルにデフォルトPrimが設定されていれば、そのPrimが使用されます。デフォルトPrimがない場合は、ルートにある最初のXform Primが使用されます。ルートに何もXform Primがない場合は、任意のタイプの最初のルートPrimが使用されます。

Reference Default Primitive

参照したファイルにデフォルトPrimが設定されていれば、そのPrimが使用されます。デフォルトPrimがない場合は、このノード上に警告が表示され、マルチパラメータのこのインスタンスが無視されます。

Reference Specific Primitive

Reference Primitive Path パラメータのシーングラフパスを参照します。

Reference Primitive Path

Reference Type が“From First Input”系の時、または、 Reference Primitive が“Reference Specific Primitive”の時、ここには、参照するPrimのシーングラフパスを指定します。

Time Offset (in Frames)

ファイルまたは1番目の入力のターゲットPrimのすべてのタイムサンプルをオフセットします。これを使用することで、参照のアニメーションの時間を変更することができます。

Time Scale

ファイルまたは1番目の入力のターゲットPrimのすべてのタイムサンプルをスケールします。これを使用することで、参照のアニメーションの時間を変更することができます。

Reload Files

クリックすると、このノードで取り込まれたすべてのファイルの内容がリロードされます。また、これはファイルパスのワイルドカードのパターン展開のキャッシュをクリアします。

Composition

Handle Missing Files

外部USDファイルを参照している場合、これは、その参照したファイルが存在しなかった場合のこのノードの挙動を制御します。

Error for Missing Files

このノードがエラーになり、残りのネットワークのクックを停止します。

Warn for Missing Files

このノードは、警告を出して、1番目の入力をそのまま通過させます。

Ignore Missing Files

このノードは、何もメッセージを出さずに見つからなかったファイルを無視し、1番目の入力をそのまま通過させます。

Allow Missing Files on the Stage

現在のところファイルが存在しなくても、リファレンスを編集します。このノードとその下流のノードでは、おそらくファイルが見つからない旨についてUSDライブラリから警告が出されます。

Pre-Operation

“No Pre-opertation”以外の値に設定すると、このノードは、このノード上の既存のリファレンスをクリアします。

No Pre-Operation

Primitive Path にあるPrim上の既存リファレンスをクリアしません。

Clear Reference Edits in Active Layer

現在のアクティブレイヤー で作成されたこのPrim上のリファレンスのリストの追加/削除の編集をクリアします。

これは非破壊的なUSD編集ではありません 。アクティブレイヤー内で現在“保留中”の以前のノードから変更をアンドゥーすることとほぼ同様です。

Clear All References

どのレイヤーが編集されているかどうかに関係なく、このPrim上のすべての既存リファレンスがマスクされるように、指定したReference Typeをオーバーライドします。これによって、このノードで指定したリファレンスのみが残るように白紙状態にすることができます。

Reference Operation

このノードによって追加された新しいリファレンスを Primitive Path のPrim上の既存リファレンスに作用させる方法。

Prim上のリファレンスを編集する時、実際にはリストの編集をしています。これらの編集は、すべての弱いレイヤーを合成またはリストから明示的に特定のアイテムを削除することで作成されるリストの先頭または末尾に追加して表現されています。

Add as Strongest References in Prepend List

新しいリファレンスを、下位レイヤーのどのリファレンスよりも強く、現行アクティブレイヤー内のこれまでの“先頭に追加した”編集よりも強くします。

Add as Weakest References in Prepend List

新しいリファレンスを、下位レイヤーのどのリファレンスよりも強く、現行アクティブレイヤー内のこれまでの“先頭に追加した”編集よりも弱くします。

Add as Strongest References in Append List

新しいリファレンスを、下位レイヤーのどのリファレンスよりも弱く、現行アクティブレイヤー内のこれまでの“末尾に追加した”編集よりも強くします。

Add as Weakest References in Append List

新しいリファレンスを、下位レイヤーのどのリファレンスよりも弱く、現行アクティブレイヤー内のこれまでの編集よりも弱くします。

Remove References

このノードによってリファレンスされたレイヤーまたはPrimsは、Destination Primitive上のリファレンスのリストに追加ではなく削除されます。

この削除は、リスト編集として表現されているので、どのレイヤーがオリジナルのリファレンスを編集したかどうかに関係なく、リファレンスのリストから特定のレイヤーを選択的に削除することができます。

Created Primitives

Primitive Kind

Primitive Path にPrimが存在しなかった場合、このノードがそのPrimを作成します。このノードがそのPrimを作成する必要がある場合、そのPrimには、このKindが設定されます。

Parent Primitive Type

Primitive Path にPrimが存在しなかった場合、このノードがそのPrimを作成します。このノードがそのPrimを作成する必要がある場合、その途中で作成する必要のある中間Primsがこのタイプになります。

Primitives

Action パラメータが Edit モードの時にこのパラメータがノードに表示され、既存のPrimsをいくつも指定することができます。ここでは、このノードが操作するPrim(s)を指定することができます。テキストボックスの横にある選択ボタンをクリックすることで、シーングラフツリーからPrimsを選択することができます。プリミティブパターンを使用することで、コレクション内のすべてのPrimsのマッチングを含む高度なマッチングを行なうこともできます。

Primitive Path

Action パラメータが Create モードの時にこのパラメータがノードに表示され、単一Primパスを指定することができます。これは、参照ブランチの取り付け先となるシーングラフパスです。リファレンスしたPrimは、このPrim上にオーバーレイされ、そのリファレンスしたPrimの子PrimsはこのPrimの子Primsになります。このPrimが存在しなかった場合は、このノードがそのPrimを作成します。

Action

このノードで新規Primを作成するのか、または、既存のPrimsを編集するのかを選択します。 Create モードは、既存のPrimも編集しますが、このモードでは1個のPrimしか指定できません。 Edit モードは、1個のノードでいくつものPrimsにリファレンスを追加することができます。

Make Instanceable