scenario-blender-retopology

Blender リトポロジー

エキスパート品質のリトポロジーは、形状を捉え、メッシュが変形できるようにする、必要最小限のループで構成した設計です。ループは目、口、関節の周囲を閉じ、ポールは動かない場所に配置し、ケージではなく細分化後のサーフェスをスカルプトに一致させます。マウスを使えないエージェントでも、データからこれらをすべて構築できますが、明示的に計画した部分でしかエキスパート品質には到達しません。自動リメッシュは静的アセットの仕上げであり、それ以外のすべてにおいては出発点です。ここに記載された兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で進める場合は、ツールのスキーマに基づいて作業し、不足している点を明示してください。

必須の前提知識： scenario-blender-expert（実行チャネル、レビューの反復、5.2 API の変更点）。 ツールキット：scripts/bx_retopo.py （import sys; sys.path.append("<skills>/scenario-blender-retopology/scripts"); import bx_retopo as R）、 すべての座標はスカルプトのローカル空間です。

方針（エキスパートとの差）

• まずデータでマップを作成します。 Kaspar は、頂点を置く前にスカルプト上へ6つのレイヤーを描きます。エッジフロー、主要なクリース、二次的な（表情専用の）クリース、関節、表情の境界、ランドマークです（BCON22 [00:07:55]、00:07:53～00:14:38のフレーム）。エージェントは、座標とループ数で同じマップを記述し（ランドマークはレンダーと R.surface_point から取得）、その後に構築します。
• 予算は頂点数ではなくループ数です。 関節部分の最小構成（Brian Tindall に続く Kaspar）：まぶた、唇、眉をそれぞれ3つの制御点を持つカーブとし、各制御点に2つのハンドルループを配置し、さらに目の両端に2つのコーナーループを追加します。上側と下側の数は同じにします（Dikko、Kaspar、Kenny）。各関節に3ループ、クリース上に1ループ、その両側に沿って2ループを配置します。それ以外は「必要なだけ」です（Kaspar Live #3 [01:56:33]）。
• ポールの価数は3または5とし、動かない場所に配置します。クリースループ上、シェルの縁、顔の中心線上には決して置きません（Kaspar Live #7 [00:11:41]、Live #3 [00:36:54]、Dikko [00:04:49]）。Lampel によると、その理由はピンチが細分化後の結果で密度が急変することにあり、平坦で動かない領域では問題ありません（BCON24 [00:21:18]）。[追加] エージェントのポールは、リング数の削減（単位ごとに4つ）と、自動生成したベース上を階段状に横切るカット境界（頂点の約半数）から生じます。両方を予算に含めてください。
• ループは閉じます。 目や唇の周囲で螺旋状になる場合は作り直します（Dikko）。動かない領域で終わる螺旋は許容されます（Dikko のボディ [00:09:34]、Kaspar の鼻）。
• 細分化後のサーフェスを評価します。 スナップしたケージは細分化すると内側に縮みます。Shrinkwrap のオフセットは凸面を補正しますが、凹面を悪化させます。ケージを調整し、細分化後のサーフェスを一致させてください（Duha BCON23 [00:08:58]）：R.fit_subdiv。Kaspar の Multires Apply Base も同じ処理をしますが、オーバーシュートします（以下で測定）。
• ゲーム向けローポリ = シルエット＋アニメーション用ループ（SpeedChar）：顔の密度はボディの約3倍にします。曲がらない部分には三角形を使い、ねじれた四角形は手作業で分割してベイカーとエンジンの結果を一致させます。ローポリはハイポリよりわずかに外側へ出し、すべてのハードエッジを UV シームにします（On Mars 3D）。
• 自動リメッシュは、静的、スキャン、背景用、またはベイク専用のアセットに適しています（Lampel [00:09:05]、Grant Abbitt、Duha、Jamie Dunbar）。変形するキャラクターには判断力が足りません。羊の例では、エキスパート相当の密度で QuadriFlow を使っても目や口の周りにリングができず、薄い耳が裂けました。

最初に決めておくこと

入力項目	計画が変わる理由	指定がない場合のデフォルト
目的	映画用ケージは細分化レベル 2 でレンダリングされます（Kaspar）。ゲームでは三角形ポリゴンを使用し、ベイクします	変形するキャラクター：映画向けのオール四角形ポリゴンのケージ
予算	映画：頂点数の上限はなく、ループ数を最小限にします（Kaspar）。ゲーム：三角形ポリゴン数に上限があります	映画向けのスタイライズされた頭部は 1,650～4,100 面、胴体は 9,400～16,500 面（Blender Studio のメッシュ）。ゲーム用キャラクターは 10,000 tris 未満
変形	フェイスリグ、関節、口の移動量（表情の可動範囲）	顔と四肢を変形させます
カメラ	ディテールと密度は最も近い視点に合わせます（SpeedChar）	顔のクローズアップ
スタイル	スタイライズ：トポロジーにしわを作ります。リアル：汎用ベースにディスプレイスメントを加えます（Kaspar）	スタイライズ
対称性	R.topology_report(sculpt)["sym_local_pct"]、ローカル空間	約 98 % を超える場合にのみミラーを使用します（羊はポーズを取っているため 21 %）
分離パーツ	目、歯、髪の束、衣服（胴体を複製したもの）	別オブジェクト

ワークフロー

1. 検査（手順 P1）：穴、多様体性、スケール、回転、対称性を確認します。ゲート：4 項目すべてを記録します。

2. マッピング：まずスカルプターのフェイスセットを読み込みます（R.face_set_map、R.face_set_review、P1b：唇のライン、目のマスク、耳、ひづめ）。座標付きのランドマーク、Numbers テーブルにある特徴ごとのループ数、クリースの一覧（表情シェイプキーを確認）、パーツごとの密度を記録します。ゲート：ジオメトリの作成前にマップを用意します。

3. パーツごとに手法を選択します：

   パーツ	手法	根拠
   目、口、眉（変形する箇所）	carve_rings(corners=, count=(lo, hi))：構造上、上側と下側は同数です。ジオデシックリングを使い、範囲内であれば境界の数を維持します。奇数の境界は先にペアにします（parity_strip）	v2：すべてのクリーンなリングで、目は 24（12/12）、口は 30（15/15）。Kaspar の 18/24 を強制した場合、ポールがさらに 40 個必要でした
   鼻唇溝、顔のフレーム、首（マップライン）	フェイスセットの enclosing_contour に沿って carve_band（P7）：クリーンなループを 1 つ作り、ポールをベースに押し込みます	v2：鼻唇溝はポールが 18 個増加。顔のフレームは任意で、羊ではポールが 64 個増加
   手足、耳、尾、指、角	limb_profile（ジオデシック輪郭を使い、付け根と関節を検出）と socket_tube(count=)（P3b、P8）。直線部分には断面から tube を使用します	v2：1 m の巻いた尾を含む 7 パーツすべてで、関節ごとにリングが 3 つ
   頭蓋骨、胴体、滑らかな塊	QuadriFlow で開始しても問題ありません。それ以外の場合はグリッドパッチを使用します	変形が少ない
   静的プロップ、スキャン、ベイク専用	オブジェクト全体に QuadriFlow を適用します（R.quadriflow）	Lampel、Grant Abbitt
   リアルな人間の頭部	クリーンな汎用ベースメッシュをシュリンクラップしてからフィットします（Kaspar BCON22 [00:20:16]）	ここではスクリプト化されていません

4. 構築：島ごとに分けて、おおまかに作成します（Kaspar：「すべての点の調整にこだわらないこと」）。 R.setup_cage でスタックします（Mirror のクリップ > Shrinkwrap の Target Normal Project > 編集モードで非表示の Subsurf）。ゲート：下記のトポロジーゲートに島ごとに合格すること。

5. リラックスして固定：手作業で作ったレイアウトに R.relax、R.freeze を適用します。QuadriFlow の後には適用しません（カバレッジが 0.44 % から 0.55 % に悪化しました）。

6. 接続：数をそろえて接続します。R.boundary_loops の後、同数のループに R.bridge / R.weld_loops を適用します。大きい側を先に減らします（Kaspar：「手首が 10、手が 16 では、6 個多すぎる」）。ゲート：三角形を作成しないこと。

7. ボリューム：フィルムには R.fit_subdiv（デフォルトの穏やかな設定）を使用します。ゲームには R.push_outside を適用してから R.triangulate_twisted を実行し、エクスポート時に Triangulate モディファイアーを追加します。

8. レビューと引き継ぎ：ゲート、2 枚のレンダーシート、引き継ぎ時の整理（P13）を確認します。エージェントが計画していなかった作業を報告します。

エージェントが到達できる水準（羊で測定。tests/code/blender-retopology/sheep_results.json および compare/metrics.json）

方針	面数	Subdiv-2 平均誤差	内部率	目／口のリング	閉ループエッジ	見た目
Kaspar の手作業によるリトポロジー	2,596	0.24 %	47 %	5,5 / 2	29.9 %	クリーンで、細分化前の形状として自然に見える
QuadriFlow、面積を一致させた予算	4,372	0.14 %	87 %	0 / 0	1.6 %	面が目立ち、耳が裂け、密度が均一
+ 緩やかな fit_subdiv	4,372	0.045 %	53 %	0 / 0	1.6 %	滑らかな大きな形状、でこぼこのひづめ
+ 代わりに Multires Apply Base	4,372	0.11 %	15 %	0 / 0	1.6 %	オーバーシュート
ハイブリッド：目のリング＋耳のチューブ＋緩やかなフィット	4,544	0.042 %	52 %	3,3 / 0	5.9 %	最初のスキル版
スキルを使った E1 実行（新規エージェント：面セット、ワープ、目のリング 4 本、唇のリング 5 本、四肢のチューブ）	5,778	0.040 %	51 %	4,4 / 5（46～48 頂点）	19.4 %	計画的な顔、波打つまぶた、脚の接合部のでこぼこ
v2 ツール、最終版（test_sheep_v2.py：面セット、範囲指定のカウント、コーナー分割、測地線リングとチューブ、鼻唇溝ループ）	4,980	0.028 %	52 %	4,4 のクリーンな 24 頂点リング、12/12 / 5 × 30、15/15	33.9 %	エージェントによる最良の結果：極点は 5.7 %（Kaspar は 5.2 %）、クリーンなリング上にはなし、6 極点もなし。鼻と上唇のパッチは不規則（人による仕上げ）

数値はエージェントに有利に見えます。強めのフィットは 0.043 % を記録しましたが、Kaspar のケージよりでこぼこして見えました。 人間と同等の水準に達しているのは、ハンドルループを含む関節のカウント、表情形状を基に配置するクリースループ、極点のルーティング、顔の外側のループ予算に限られます。レポートにはその旨を記載してください。

数値

項目	値	出典
レンダーのサブディビジョン（フィルム）	2 レベル、ビューポート 1	Kaspar Live #6 [00:21:53]、BCON22 フレーム 00:26:38
関節	曲げる部分に 3 ループ	Kaspar Live #5 [01:37:48]
四肢の始端リング	8 頂点（脚は 8、その後 12）、Dikko の腕は最低 8、通常 10～12、脚は 18	Kaspar Live #4 [00:06:54]、Dikko [00:13:47]
まぶた	まぶたのしわごとに 2 ループ ＋ 横方向に約 4、10/10 の幅の例	Kaspar Live #1 [02:11:22]、Dikko [00:04:16]
Studio メッシュ	99.9 %+ がクワッド、価数 6 以上は 0～4 個（それぞれ報告して正当化）、ポールは頭部の約 1.8 %、胴体の約 5 %、エッジ CV は 0.33～0.8	キャリブレーション（Blender Studio ファイルで bx_audit）
自動リメッシュのヒント（合否判定には使わない）	未編集の均一リメッシュではエッジ CV が約 0.17～0.27、閉ループはほぼ 0 %	キャリブレーション、sheep
ゲーム	頭部は 2,000～3,000 tris、両手で約 1,000、胴体は 5,000～6,000	SpeedChar ep23 [00:09:58]、ep24 [00:50:34]
Base レベルを適用	胴体は 2、頭部、髪、服は 3	Kaspar Live #5 [02:15:03]

品質ゲート

コード（しきい値［追加］、Kaspar の sheep でキャリブレーション：平均 0.24 %、内側 47 %、カバレッジ p95 0.82 %）：

retopo_gate = R.topology_report(retopo)
fit_gate = R.fidelity(retopo, sculpt, levels=2)
gate = {"six_poles_to_justify": retopo_gate["valence_6plus"], "no_rim_poles": retopo_gate["rim_poles"] == 0,
        "quads": retopo_gate["non_quads_visible"] == 0 or retopo_gate["quads_pct"] >= 99.0,
        "subd_fit": fit_gate["mean_pct"] <= 0.3 and 40 <= fit_gate["inside_pct"] <= 60,
        "coverage": fit_gate["cov_p95_pct"] <= 1.0, "loops": R.loop_stats(retopo)}
print(gate)

エッジ長の CV は合否判定には使いません（Studio メッシュは 0.33～0.8 です）。6 ポールは報告して正当化し、禁止はしません（Studio では 0～4 個です）。また、crease_poles == 0、ミラー面では center_poles == 0、R.loops_around(retopo, eye, normal, max_radius) は目と口のそれぞれで少なくとも 3 つの閉じたリングを返し、マージ前にはリング数が一致し、三角形は隠れた領域または剛体領域にのみ配置し、予算を満たすこと（R.tri_count）。目視確認（bx_review、スカルプトと同じビュー）：ワイヤー表示のケージ（リングが密接し、ループが乱れず、ポールが動きの少ない領域にあること）とサブディバイドしたマットキャップ（凹凸、ポールでのピンチ、しわの保持）を確認し、次にケージ単体を確認します。サブディビジョンなしでも形状が読み取れる必要があります（Kaspar Finale [01:58:41]）。references/critique.md に従って採点してください。

よくある間違い

間違い	こう見える	修正
QuadriFlow の閉じた目のスリットの周囲をカービングする	すべての目のリングが奇数（47、45）で、全クワッドの修正ができない	カービングする前に、2つの奇数境界の間に R.parity_strip を配置する
高密度カットからカウントを引き継ぐ、または大幅に下げすぎる	目のリングが46〜48、またはポール密度が9.5 %	count=(lo, hi)：削減単位ごとにポールが4つ増えます。この範囲により、羊のポール密度は9.5から5.7 %になりました
サーフェスが接触している箇所で3D最近傍検索を使う	バンドカットやソケットカットが頬に沿った耳に食い込む	測地場、curve_verts、方向を考慮した nearest_vertex（バンドとチューブに組み込み済み）
エッジフローループに狭いリングを使う	サブディビジョン後に稜線ができる	バンドの spacing をエッジ長に設定します。狭くするのはクリースだけです
スナップしたケージを納品する	スカルプト内にサブディバイドされたサーフェスがある（87 %）	R.fit_subdiv
ボリュームにシュリンクラップオフセットを使う	キャビティが悪化する	フィットを使い、オフセットは0にします
小さな高密度メッシュで生の quadriflow_remesh を使う	CANCELED、「マニフォールドである必要があります」と表示される	R.quadriflow（スケール調整、ボクセルフォールバック）
QuadriFlow の対称性をデフォルトの True のままにする	ポーズ付きメッシュで間違った半分が処理される	対称でない限り symmetry=False にします
自動リメッシュをリラックスする	先端や耳が縮む	手作業で作成したレイアウトだけをリラックスします
Mark Sharp / Seam を目印として使う	シェーディングが崩れる（4.1以降）、アンラップが切れる	retopo_crease 属性（P5）
奇数ループにグリッドフィルを使う	FINISHED、面が0	最初にカウントします。R.grid_fill はエラーを発生させます
パーツを早い段階で接続する	新しいループがすべての場所に走る	アイランド化し、カウントを確認して、最後にマージします
平均誤差を信頼する	凹凸のあるフィットが通る	マットキャップで確認し、穏やかにフィットさせます
Apply Base の後に再度シュリンクラップする	ボリュームがまた失われる	絶対にしないでください（Kaspar Live #6 [00:20:08]）
ゲーム用のクワッドが非平面のままになっている	ノーマルマップに線が出る	R.triangulate_twisted を使い、エクスポート時に Triangulate を有効にします

Blender 5.2 に関する注意事項

• Hidden Wire はRetopology オーバーレイです（overlay.show_retopology、4.5 以降はオフセット 0.01 m）。 「Project Individual Elements」は snap_elements_individual = {'FACE_PROJECT'} です。GUI のみです。
• Slide Relax はRelax Slideブラシアセットです（ストロークにはウィンドウが必要です。bx_gui）。ヘッドレスでは R.relax を使用します。F2、LoopTools、BSurfaces は拡張機能です。mesh.circularize、space_edge_loops_evenly、 flatten は組み込みです。mesh.select_by_pole_count は存在します（4.4）。
• BCON22 ビルドの Shrinkwrap には Smooth Factor 0.05 / Repeat 1 が表示されていました（フレーム 00:22:53）。5.2.1 の Shrinkwrap にはこのオプションはありません。
• sharp_edge は 4.1 以降、常に適用されます。Auto Smooth は廃止されました（Smooth by Angle モディファイアー）。
• Apply Base は object.multires_base_apply(apply_heuristic=True) です。QuadriFlow はショートカットがなくなり、 上記の注意点があります。

参考資料

• references/procedures.md：テスト済みコード、P0 から P14 まで（検査、フェースセット P1b、スタック、チューブ、測地線による四肢 P3b、フリーズ／リラックス、注釈、QuadriFlow、マップラインのループと リング、ソケット、ボリューム、チェック、ゲーム、表情テスト、引き継ぎ、AI メッシュの仕上げ）。コードを書く前に読み込んでください。
• references/expert-notes.md：タイムスタンプ付きの専門家による原則、フェースとボディのループマップ、 服、ゲームのルール、羊の実験の全容。顔、体、服、ゲーム用メッシュを計画する際に読み込んでください。
• references/critique.md：自分のリトポロジーを評価するための基準です。レビューのたびに読み込んでください。
• references/sources.md：ベストなタイムスタンプ付きのソース動画全 24 本。