パス形式の仕様
このページでは、パス形式について説明し、パスツールに含まれる関数を使用してその形式のデータを操作するためのガイダンスを提供します。
形式の仕様
このセクションでは、パスドキュメント （または画像）をエンコードする方法について説明します：
Pathsドキュメントはパスのリストです。各パスは、32ビット浮動小数点カラーテクスチャでエンコードされたセグメントのリストを記述します。
テクスチャは、「上」($pos.y < 0.5)と「下」($pos.y > 0.5)の部分に分割されます。
「上」の部分のピクセルのデータは、「下」の部分の一致するピクセルと意味的に密接に関連し、逆も同様です。
*uv\_pos*を’top’パーツのピクセルの2Dアドレス（$posなど）にします。
この文書の残りの部分：
- top[uv_pos].XYZWは、上部のピクセルに格納されている4つのフロートを参照します。
top[uv_pos] == sample_color(paths, uv_pos) - bottom[uv_pos].XYZWは、最下部の一致するピクセルに格納されている4つのフロートを参照します。
bottom[uv_pos] == sample_color(paths, uv_pos + Float2(0, 0.5))
top[uv_pos]とbottom[uv_pos]を組み合わせると、ドキュメントの意味単位U[uv_pos]が形成され、8つのフロートで構成されます。
文書ヘッダー
すべてのパス文書は、文書ヘッダーで始まります。 これは最初の意味単位U[(0,0)]:
パスの数（[0; 16777216]の正の整数でなければなりません）。
空のパスがある場合は、ここで数えられます。 ですから、「デコードするパスヘッダーの数」と考えることができます。
YZ
このドキュメントのピクセルサイズ（正確にはFloat2(1,1) / $size）。
これは、出力サイズが異なるピクセルプロセッサーまたはFx-Mapからパスを読み取る場合などに便利です。
幅
1/16 = 0.0625（ヘッダーフラグ）
この文書で定義された最後の頂点のアドレス。 これは、新しいデータを追加する場合に便利です。
したがって、実際には、最後の頂点のアドレスよりも（スキャンライン順に）大きいアドレスであればどれでもかまいません。 範囲は、 ]0, 1[×]0,.5[
ZW
未使用。浮動小数2(0, 1)である必要があります。
パスヘッダー
ドキュメントのヘッダの直後にnumber-of-paths = top[(0,0)].X path-headersが続き、1つ一つが意味単位です。
E.g. ドキュメント内に3つのパスがある場合、それらはU[(0,1)*pixel_size], U[(0,2)*pixel_size]およびU[(0,3)*pixel_size] (pixel_size = top[(0,0)].YZ)に保存されます。
1行のピクセルに収まらないパスがある場合、残りのパスヘッダーはスキャンライン順に次の行に書き込まれます。
NULLのパスヘッダー(top[...].XYZW = Float4(0,0,0,0))を使用できます。このようなパスは空のパスとして使用できます。
N番目のパスのパスヘッダーは、アドレスpath\_addrで次のように定義されます：
このパス内の頂点数。 [0, 16777216]の範囲内である必要があります。
クローズパスの開始パスと終了頂点が同じ場所にある場合は、2つの頂点がカウントされます。
頂点が0のパスは有効なパスです。
年
Is_closedフラグ：パスが閉じている場合（例：円）は1、それ以外の場合（例：直線）。
Z
パスのインデックス N. は path_addr と完全に一致する必要があります（以下の注を参照）。
幅
ヘッダーフラグ： 1/16 = 0.0625。
開始（または最初の）頂点アドレス。
ZW
終了（または最後）の頂点のアドレス。
Utils/pixel\_index\_to\_positionを使用して、Nからpath\_addrを計算できます： path\_addr = pixel\_index\_to\_position(N+1)頂点情報
頂点は、ヘッダー（文書ヘッダーまたはパスヘッダー）の後の画像内の任意の場所に表示されます。 頂点は様々な「種類」（開始、中間、終了）にすることができ、2つのアドレスポインター（「リンク」）を使用して明示的にリンクされています。
StartおよびEnd 頂点は、この点で特別です。閉じた頂点または任意のリンクされたパスのネットワークを表現できるようにするには、一方のリンクを実際に使用して、同じパスを表す他のすべてのStartまたはEnd 頂点を循環リンクしたリストを作成します。 このように互いに一致する頂点を「同胞」と呼ぶ。 [歓迎されるイラスト]
正式には、アドレス*vert\_addr*の各頂点は次のように定義されています：
頂点の位置。 座標には、NaNまたは±inf以外の任意の浮動小数点値を使用できます。 このレベルでのタイリングの概念は存在しないので（各フィルタの実装によって扱えるかどうかは関係ありません）、パスはユークリッド平面上で定義されているはずです。
Z
頂点パスのインデックス。 1つの頂点は1つのパスにのみ属することができます。 （既に説明したように、開始および終了頂点には兄弟を設定できます）。 パスインデックスはパスヘッダの取得に使用できるので（上のパスヘッダの節を参照）、必ず同期しておいてください。
幅
頂点の種類。 値の符号と絶対値が分割されます。
符号の部分では、値0は実際には頂点がないことを意味します（他のすべてのコンポーネントも0でなければなりません）。 負の値を指定すると、頂点は「コーナー」としてマークされます。正の値を指定すると、頂点は「滑らか」になります。 コーナーモードとスムーズモードの頂点は、純粋な分離アトリビュートであり、他のパスエンコーディングに影響を与えたり意味を持ったりすることはありません。
絶対値部では、ピクセルの種類(Start, Mid, End)と別のフラグ(trivial_link)が符号化される：
-
0.125：終了頂点 （図形の最後の頂点。常に非簡易リンクです。以下を参照してください）
-
0.25: 頂点を開始します（図形の最初の頂点。常に非簡易リンクです。以下を参照してください）
-
0.5：重要なリンクを含む中間頂点
-
1: 頂点の途中に簡易リンクがあります
「簡易リンク」とは、前のパスと次の頂点（現在の頂点のリスト内）が左のピクセル(vert_addr-(0,pixel_size))に格納され、右のピクセル(vert_addr+(0,pixel_size))に格納されることを意味し、「非簡易リンク」とは、これらの少なくとも1つが他の場所に格納されることを意味します。
リンクの「三元性」に関係なく、リンクの信頼できる値は下部に保存されます。
XY
このパスの前の頂点のアドレス。 開始頂点の場合は、次の兄弟頂点を指します。
if |top[vert_addr].W| = 1, then bottom[vert_addr].XY = vert_addr - (0,pixel_size)
ZW
このパスの次の頂点のアドレス。 エンド頂点の場合、これは次の兄弟頂点を指します。
if |top[vert_addr].W| = 1, then bottom[vert_addr].ZW = vert_addr + (0,pixel_size)
パス情報の読み書き
独自のパス処理ノードを作成する場合は、いくつかのツールがあります。
基本は、Paths 頂点プロセッサおよびPaths 頂点プロセッサシンプルノードによって提供されます。これらのノードは基本的にピクセルプロセッサーと同じように使用できます。
頂点プロセッサノードが提供するパス（より多くの入力テクスチャ、またはより多くの前後の頂点）以上の機能が必要な場合は、このグラフの実装をコピーすることをお勧めします(Get(“%perVertex”)ノードをカスタム処理で置き換えると仮定します)。
しかし、頂点単位の機能を適用するよりもエイリアンな作業を行いたい場合は、以下の説明で使用できるツールを詳しく説明します。 これらは通常、他のパスノード(paths_tools.sbs)と同じパッケージに含まれる小さなヘルパー関数です。 （これらの関数は、ライブラリおよび ノードメニュー には表示されません）。
'読み取り’関数
Readフォルダーには、パスに関する情報を収集するのに便利ないくつかの情報があります。
特定のピクセルに関する情報を提供する場合もあります。 これらはすべて*top*部分のサンプルされたFloat4値を入力として受け取ります。 これらの実装を見ると、非常にシンプルです。 そのポイントは、単なる原子ノードよりも多くの意味を伝えることにある。
is\_headerを含むパスであることを確認し、current\_pixel\_is\_document\_headerがfalseを返したことを前提としています。is\_vertexをチェックする必要はありません）。is\_vertexをチェックする必要はありません）。is\_vertexをチェックする必要はありません）。is\_start\_vertex || is\_mid\_vertexのショートハンドです。 Fx-Mapベースの処理で、各セグメントを一度に処理する場合に便利です。is\_vertexを確認する必要はありません。回答がtrueの場合は、確実に頂点を確認してください）。 このフラグはまだ公式ノードではサポートされていないことに注意してください。頂点の場合は、底部をサンプリングしなくても、前後の頂点の位置を簡単に推定できるかどうかを示します。 （注：頂点以外の場合は、常にfalseが返されます）。
これを直接使用するのではなく、sample\_next\*またはsample\_prev\*のいずれかの関数を使用して処理を行うことをお勧めします。
トップパーツのサンプリング値*sampled*とその位置*sampled\_position*を指定して、次の（それぞれ前の）頂点のトップパーツのサンプリング値を返し、この近隣の（トップパーツの）位置にFloat2変数*next\_sampled\_pos*を設定します(<戻り値> = SampleColor(next_sampled_pos, image0))。 *input0PixSize*は、パスのピクセルサイズ(top[(0,0)].YZ)と等しくなければなりません。
現在のピクセル(*sampled*)が 開始 頂点の場合、sample_prevによってこの頂点の次の兄弟が返されます。同様に、それが 終了 頂点の場合、sample_nextによってこの頂点の次の兄弟が返されます（つまり、望むものではない可能性があります）。 この問題を解決するには、以下の*sample\_next\_advanced*と*sample\_prev\_advanced*を参照してください。
簡単にするために、パス情報はinput0!に格納されていると見なされます。 また、関数のドキュメントの状態とは異なり、*next\_sampled\_pos*を事前に宣言する必要はありません。 *[out]next\_sampled\_pos*は、この2番目の「戻り値」が存在することを通知するダミーパラメーターです。
*paths\_trace* Fx-Mapは、3番目のIterateノードのIterationsパラメーターで使用方法の例を確認できます。
'書き込み’関数
Writeフォルダーには、Fx-Mapで書き込み可能なFloat4を構築する小さなヘルパーがあります。
実際、Fx-Mapは描画する前にRGBとAlphaを掛け合わせるので、実際の値は掛け合わされずに補正されます。 例えばピクセルプロセッサーでこれらの関数を使用する場合は、前乗算を自分で再適用するか、カスタムバージョン（ユースケースに合わせて最適化され、使用が簡単なバージョン）を作成することをお勧めします。document<>header指定したパスの数を宣言して、文書ヘッダーの最上部を構築します。document<>last<>vertex<>spec最後の頂点アドレスを指定する文書ヘッダの*bottom*部分を構築する（A.1を参照）。path<>headerパス*nbVertices*の頂点の数、*isClosed*フラグ、および*pathIndex*に基づいて、パスヘッダーの上部を構築します。start<>vertex、mid<>vertex、end<>vertex頂点の最上部を構築し、位置、種類、その他のオプションを適宜設定します。mid_vertexおよび hasTrivialLinks パラメーターのバージョン情報：適切な値を設定することをお勧めします。ただし、リンクが重要な値であるかどうかを判断できない場合は、安全にfalseに設定できます（生成されたパスの処理に時間がかかります）。パスのヘッダと頂点に対するボトムパートビルダはありません。どちらもトップ部分への2つのリンクをエンコードするので、この関数は本質的に2つのFloat2からのベクトルFloat4コンストラクタになります。 Fx-Mapを使用して書く場合は、XYZをWで除算することを忘れないでください（WはアドレスのYです。Wをnullにすることはできません）。Paths Polygonノードをホストするpaths_polygon.sbs パッケージで、これらの関数の適切な使用例を確認できます。### パスを処理するメソッド通常は、ピクセルプロセッサーまたはFx-Mapを使用して、次のような長所と短所のあるカスタム処理を実装します。FX-MapFx-Mapベースのソリューションは通常、パス全体（またはパス）または累積パス（たとえば、デシメーションまたはテッセレーション後に頂点を再パックするなど）のグローバルな知識を必要とする高レベルの操作を実行する場合に推奨されます。 また、この方法は最も簡単です。初めてカスタム処理を行う場合は、Fx-Mapを使用することをお勧めします。ただし、速度が遅くなる可能性があります。そもそもFx-Mapに精通している必要があります。 これに該当しない場合は、固有のドキュメントを確認してください。Fx-Mapを使用したパスの読み取りと書き込みの方法について理解するには、paths_trace.sbsのPreview Pathsの実装と、paths_polygon.sbsのPaths Polygonを参照することをお勧めします。ピクセルプロセッサーピクセルプロセッサソリューションは、「ローカル」情報のみが必要な場合に適しています。 ここでは、空間的（要素間の距離）ではなく、位相的（頂点が互いにリンクしている）に「ローカル」を意味します。 これが頂点プロセッサの実装方法です。 通常、ピクセルプロセッサはFx-Mapよりも高速です。これは、各ピクセルの機能が並列に評価され、アクセスされるデータの量が限られているためです。 現在のピクセルしか変更できないため、実装作業の方がはるかに重要な場合があります。具体的なユースケースに応じて言うべきことはたくさんありますが、最初にすべきことは、自分がどこにいるか確認することです。上位($pos.y < 0.5)または下位($pos.y > 0.5)のパーツにいますか？ 専用の変数（例： *isTop*）で、*vert.addr*浮動小数点2を作成して、その値を上部の*$pos*、下部の$pos - (0,0.5)にすることを推奨します。vert.addrとは何ですか？ これをサンプリングして、何かあるかどうか(W != 0)をチェックし、あるとしたらどうなるかを正確にチェックします。 ヘッダー(W = 0.0625) （*Read/is\_header*でチェック）または頂点（Read/is\_vertexでチェック） ヘッダーの場合は、ドキュメントヘッダーですか、パスヘッダーですか？ （*Read/current\_pixel\_is\_document\_header*を使用して確認できます）。 ヘルパー関数の1つまたは複数を使用して、興味を引くものと一致させます。