序論
KJ Eye Through Hairは、アニメやイラストでよく見られる「前髪の向こう側にある目や眉が、髪越しに見えているように表現される演出」を、Blender上で再現するためのAdd-onです。キャラクターの目や眉に相当するObject、またはObject内のVertex GroupをTargetとして指定し、その形状を前髪側のObjectへ投影することで、髪に隠れている部分だけを視線方向に応じて見せることができます。単純な円形や楕円形のマスクではなく、指定したMesh Surfaceを利用できるため、目や眉の実際の形状に沿った自然な見え方を作りやすいことが特徴です。
前髪として使用するOccluder Objectは1つに限定されず、複数登録できます。前髪が複数のMeshに分かれているキャラクターや、左右の髪、髪飾り、別パーツとして作られた毛束などにも対応できます。また、Target側も複数のVertex Groupを登録できるため、左目、右目、左眉、右眉といった部位を個別に管理できます。Target Objectの移動、回転、拡大縮小にも追従し、Shape KeyやArmature、Modifierによる形状変化にも対応します。
表示判定は3D ViewportやCameraからの視線を基準に行われ、Targetが実際に前髪の後ろにあるときだけReveal処理が働きます。さらに、現在の視点や位置関係から投影に影響しないTargetはBroad-phase Cullingによって処理を省略し、不要な更新を抑える仕組みも備えています。キャラクター表現でよく使われる「髪で隠れているのに目や眉だけは見せたい」という演出を、手作業でMaterialやMaskを作り込むことなく管理しやすくするAdd-onです。
Documentation Version：v1.0
Add-on Version：v0.3.6
対応：Blender 5.1 / 5.2
N-menu：KJ Eye Through Hair
Category：3D View
更新日：2026年9月13日
概要
KJ Eye Through Hairは、Target Object上のVertex Groupで指定した実際のMesh Surfaceを、現在の3D Viewportまたはレンダー視線に沿って、Occluder Object越しに見えるようにするBlender Extensionです。
代表的な用途は、髪の毛などの前景Meshの後ろにある目や眉を見せる表現です。ただし、特定の人体部位専用ではなく、Target Object、Vertex Group、Occluder Objectの組み合わせとして一般化されています。
主モードでは、Target Vertex Groupに含まれる評価済みMesh Surfaceを直接使用します。円や楕円などの疑似的なShapeへ置き換えるのではなく、実際のTarget Surfaceを投影判定に使用します。
v0.3.6では、複数Target Object、複数Target Vertex Group、複数Occluder Objectに対応しています。
主な機能
複数のTarget Objectを登録できます。
各Target Objectには複数のTarget Vertex Groupを登録できます。
同じ名前のVertex Groupが別Objectに存在しても、それぞれ独立したTargetとして管理されます。
複数のOccluder Objectへ同じReveal処理を適用できます。
「1-Vertex Group Surface」では、Vertex Groupに対応する実際のMesh Triangleを使用します。
Target ObjectやTarget Vertex GroupごとにON/OFFできます。
Target Objectの移動、回転、拡大縮小へ高速追従します。
Shape Key、Armature、ModifierなどによるMesh変形にも対応します。
TargetがOccluderへ影響しない場合は、Broad-phase Cullingによって不要な処理を省略します。
Shared Materialの分離とEEVEE Dithered設定はLive切替できます。
Solid ViewportではTarget Surfaceの補助Overlayを表示できます。
従来のLegacy Reveal Regionsも互換機能として残されています。
対応環境
KJ Eye Through Hair v0.3.6は、Blender 5.1.0以上を最小要件としています。
主な対象VersionはBlender 5.1および5.2です。
UIに「TARGET VERSION – RUNTIME UNVERIFIED」と表示される場合がありますが、これは実行エラーを意味するものではありません。
Blender 5.1 / 5.2を対象Versionとしているものの、Add-on内部の自動Verified登録が設定されていないことを示す情報表示です。
インストール
配布されたZIPファイルは展開せず、そのまま使用します。
Blenderを起動し、PreferencesからExtensions画面を開きます。
右上のメニューから「Install from Disk」を選択します。
KJ Eye Through HairのZIPファイルを指定してインストールします。
インストール後、Extensionを有効にします。
3D ViewportでNキーを押し、Sidebarを表示します。
「KJ Eye Through Hair」タブを選択するとAdd-onのUIが表示されます。
基本操作
最初に、Revealによって見せたいMesh ObjectをTargetとして用意します。
Target Object上に、見せたいSurface範囲を表すVertex Groupを作成します。
KJ Eye Through Hairの「Target Object」で対象Objectを指定し、「Add Target Object to List」を押します。
Target Object Listから編集したいObjectを選択します。
次に「Target Vertex Group」でVertex Groupを選び、「Add Target Vertex Group to List」を押します。
前景となる髪などのMesh Objectを「Occluder Object」で指定し、「Add Occluder Object to List」を押します。
Projection Geometryは通常「1-Vertex Group Surface」を使用します。
最後に「Apply / Rebuild Reveal」を押します。
Material PreviewまたはRendered Viewへ切り替えると、Occluder越しにTarget Surfaceが見える状態を確認できます。
Main Panel
Enable Reveal Through Hair
Default：ON
Add-on全体のReveal機能をON/OFFします。
OFFにしてもTargetやOccluderの登録情報は保持されます。
Reveal Mode
通常はTarget Vertex Groupsを使用します。
旧方式を使用する場合はLegacy Regionsへ切り替えます。
Auto Update
Default：ON
Target Objectの移動、Mesh変形、Shape Key、Armature、Modifierなどの変更へ自動追従します。
Global Reveal Strength
Default：1.0
Range：0～1
Reveal全体の強度を調整します。
0ではRevealなし、1では設定された最大Revealになります。
Apply / Rebuild Reveal
現在のTarget、Target Vertex Group、Occluderの状態をもとにRuntime Shaderを構築または再構築します。
Refresh / Rebuild Region Data
Target Surface情報やRegion情報を再解析して更新します。
Remove Reveal Setup
Occluder Materialへ追加されたReveal Wrapperを除去します。
Demo
「Create / Show Demo」を使うと、動作確認用のTarget SphereとOccluder Cubeを自動生成できます。
Demo Targetには以下のVertex Groupが作成されます。
KJ_Eye_L
KJ_Eye_R
KJ_Brow_L
KJ_Brow_R
初期状態ではKJ_Eye_LがTarget Vertex Groupとして登録されます。
Demo作成後、Target Sphereを移動するとRevealが追従する様子を確認できます。
Occluder Cubeを移動した場合もReveal条件が再評価されます。
「Remove Demo」を押すとDemo用Objectを削除できます。
Target Object
「Target Object」は、新しいTarget Objectを登録するための選択欄です。
Use Selected as Target
現在ActiveになっているMesh ObjectをTarget Object欄へ設定します。
Add Target Object to List
Target Object欄のMeshをTarget Object Listへ登録します。
すでに同じObjectが登録されている場合は、重複行を追加せず既存登録を使用します。
Target Object Listに複数Objectがある場合、クリックして選択した行が、その下に表示されるTarget Vertex Group設定の編集対象になります。
上部のTarget Object欄は新規登録用、Target Object Listは登録済みObjectの管理用です。
Target ObjectをOFFにしても、登録されているTarget Vertex Groupは削除されません。
Revealへの寄与だけが停止します。
Target Vertex Group
Target Vertex Groupは、Target ObjectのどのSurfaceをReveal対象にするかを指定する中心機能です。
Target Vertex Group
現在選択されているTarget Objectに存在するVertex Groupから選択します。
Use Active Vertex Group
Target ObjectのActive Vertex GroupをTarget Vertex Group欄へ設定します。
Add Target Vertex Group to List
現在指定されているVertex GroupをTarget Unitとして登録します。
Add Active Vertex Group
Active Vertex Groupを直接登録します。
Unregister Selected Target
現在選択されているTarget Vertex Group登録を解除します。
同じTarget Objectに複数Vertex Groupを登録できます。
別のTarget Objectに同じ名前のVertex Groupがあっても問題ありません。
内部では「Target Object + Vertex Group」の組み合わせとして独立管理されます。
Target Vertex Group List
各行のチェックボックスでTarget Vertex GroupのRevealへの寄与をON/OFFできます。
OFFにしても登録自体は削除されません。
再度ONにするとRevealへ復帰します。
表示されるTarget Vertex Group Listは、Target Object Listで現在選択されているObjectに所属するGroupだけに限定されます。
Group Weight Threshold
Default：0.05
Range：0.0～1.0
Vertex Group Weightがこの値以上のVertexをTarget候補として扱います。
「1-Vertex Group Surface」では、Triangle単位だけで判定するのではありません。
元のsource polygonを構成する全VertexがThresholdを満たしている場合だけ、そのpolygon由来のTriangleをTarget Surfaceとして採用します。
これにより、Quadの片側Triangleだけが選択される不自然な境界を防止しています。
Thresholdを高くするとTarget Surfaceは小さくなりやすくなります。
Thresholdを高くしすぎて完全なpolygonが残らなくなると、Target Surfaceを作成できなくなります。
Projection Geometry
通常は「1-Vertex Group Surface」を推奨します。
1-Vertex Group Surface
Vertex Groupに含まれる評価済みMesh Surfaceをそのまま使用します。
実際の形状に沿ったRevealが必要な場合はこちらを使用します。
2-View Ray Radius
Target Vertex Groupの中心付近をRadiusで表現する軽量互換モードです。
実Surface形状そのものを必要としない場合に使用できます。
Projection Radius
Default：0.03
「2-View Ray Radius」を使用した場合だけ有効になります。
Target Vertex Group中心周辺の投影半径を設定します。
「1-Vertex Group Surface」では使用しません。
Projection Feather
Default：0.12
Range：0～1
「2-View Ray Radius」専用です。
Reveal開口部のEdgeを柔らかくします。
Depth Margin
Default：0.0005
Occluder SurfaceよりTarget Surfaceがどの程度後方にある必要があるかを設定します。
値を大きくしすぎるとRevealが成立しにくくなる場合があります。
Require Outward-Facing Normal
Default：ON
ONにすると、Target Surfaceが現在のView方向へ向いていることをReveal条件に加えます。
裏側のSurfaceをReveal対象へ含めたくない場合に有効です。
Normal Facing Threshold
Default：0.0
Range：-1.0～1.0
Require Outward-Facing NormalがONの場合に使用します。
値を高くすると、よりView正面へ向いたSurfaceだけがReveal対象になりやすくなります。
Occluder Object
Occluderは、Targetより手前に存在し、Revealによる透過処理を受けるMesh Objectです。
Use Selected as Occluder
現在ActiveなMesh ObjectをOccluder Object欄へ設定します。
Add Occluder Object to List
現在指定されているOccluderを登録します。
Add Selected Objects
複数選択されているMesh Objectを一括してOccluder Listへ登録します。
Unregister Selected Occluder
選択中のOccluder登録を解除します。
必要に応じて、そのObjectへ適用されたReveal Wrapperも除去します。
Occluder Listでは、各Objectを個別にON/OFFできます。
Occluder Material / Render
Isolate Shared Materials
Default：ON
同じMaterialがOccluder以外のObjectでも使われている場合に、Occluder専用Materialへ分離します。
これにより、Reveal処理が非Occluder Objectへ影響することを防ぎます。
OFFにすると元の共有MaterialへReveal Wrapperを適用します。
Live切替に対応しています。
EEVEE Dithered
Default：ON
対応するMaterialへDithered Render Methodを設定します。
Add-on適用前のMaterial状態は保存され、OFFにすると保存されていた状態へ戻します。
こちらもLive切替です。
3D Viewport Solid Assist
Material PreviewとRenderedではOccluder Materialの実透過を使用します。
Solid ViewportではShader透過そのものではなく、Target Surfaceを前面Overlayとして表示します。
Solid Reveal Assist
Default：ON
Solid ViewでTarget Surfaceの補助Overlayを表示します。
Solid Opacity
Default：0.72
Overlayの透明度を設定します。
Show Approximate Axes
Default：OFF
補助的なAxisを表示します。
最終的なReveal状態はMaterial PreviewまたはRenderedで確認してください。
Transform Broad-phase Culling
Debug / Diagnosticsにある「Transform Broad-phase Culling」はDefaultでONです。
Target Objectを移動した際、現在のTarget Vertex GroupがOccluderのReveal結果へ影響しないことを安価なBounds判定で確認できた場合、不要なShader更新を省略します。
v0.3.6では、一度CULLEDになったTarget Unitは時間経過だけでは復帰しません。
Target、Occluder、またはView条件が変わり、Revealへ再び影響する状態になった場合だけACTIVEへ戻ります。
これにより、Target Object移動中にCullとRestoreを繰り返す無駄な処理を抑制しています。
Transform Broad-phase CullingをOFFにした場合は、CULLED中のTarget Unitを正確な状態へ戻します。
Render開始前にも正確なRuntime状態へ同期します。
Auto Update
Auto UpdateがONの場合、Target Objectの移動、回転、拡大縮小、Mesh変形、Shape Key、Armature、Modifier、Frame Changeなどへ自動追従します。
OFFの場合、変更後に「Refresh / Rebuild Region Data」または「Apply / Rebuild Reveal」が必要になる場合があります。
Apply / Rebuild Reveal
Apply / Rebuild Revealでは、現在有効なTarget Unitを解析し、Reveal用Runtime Shaderを構築し、登録済みOccluder MaterialへReveal Wrapperを適用します。
少なくとも、有効なTarget Object、有効なTarget Vertex Group、有効なOccluder Mesh、Occluderに使用可能なMaterialが必要です。
Remove Reveal Setup
OccluderからKJ Eye Through HairのReveal Wrapperを除去します。
Isolate Shared Materialsによって作成された専用Materialがある場合は、可能な範囲で元Materialへ戻します。
Legacy Reveal Regions
Reveal ModeをLegacy Regionsへ切り替えると、旧方式のRegion機能を使用できます。
主なShape Modeは「Approximate / Superellipse」と「Face Region Exact」です。
新しいSceneでは通常、Target Vertex Groupsモードの「1-Vertex Group Surface」を推奨します。
Legacy Regionsは既存ファイルとの互換性維持を目的として残されています。
Parameterの組み合わせ
1-Vertex Group Surface + Outward Normal ON
通常推奨の組み合わせです。
実Mesh Surfaceの形状と向きを反映します。
Triangle数が多くなるほどShader負荷も増えるため、Vertex Groupは必要範囲へ限定するのが効果的です。
Group Weight Thresholdを低くする
Target Surfaceが広くなりやすくなります。
境界付近まで含めたい場合に有効ですが、意図しないpolygonまで含む可能性があります。
Group Weight Thresholdを高くする
強くWeightされた中心部分だけをTargetにしやすくなります。
高くしすぎると完全なpolygonがなくなり、Surfaceを構築できない場合があります。
Outward Normal OFF
Surfaceの表裏方向をReveal条件に使用しません。
背面SurfaceもReveal候補になる可能性があります。
複数Target Group + Broad-phase ON
通常推奨です。
現在Revealへ影響する可能性のあるTarget Unitだけを更新します。
Isolate Shared Materials ON
同じMaterialを複数Objectが共有しているSceneでは推奨です。
非Occluder ObjectへのReveal設定の波及を防止します。
Performance
Exact Surfaceモードでは、Target Vertex Groupから生成されるTriangle数がShader負荷に影響します。
Target Vertex Groupを必要な範囲に限定してください。
使用しないTarget Vertex GroupはOFFにできます。
使用しないTarget ObjectもOFFにできます。
不要なOccluderもOFFにできます。
Transform Broad-phase Cullingは通常ONを推奨します。
Solid ViewではSolid Reveal Assistを使用し、最終確認時だけMaterial PreviewやRenderedへ切り替える方法も有効です。
実Surface精度が不要な場合は2-View Ray Radiusを検討できます。
Troubleshooting
Add-onがInstallできない
配布ZIPを展開せず、Blender ExtensionsのInstall from DiskからZIPを指定してください。
Blender 5.1.0未満は最小要件を満たしません。
N-menuが表示されない
3D Viewport上でNキーを押してください。
KJ Eye Through Hairタブが表示されること、Extension自体がEnableになっていることを確認してください。
Target Vertex Group候補が別Objectのものになっている
Target Object Listで編集したいObjectの行をクリックしてください。
Target Vertex Group UIは、現在選択中のTarget Object List行に連動します。
Target Vertex Groupを追加できない
指定したGroupが現在のTarget Object上に存在するか確認してください。
Threshold以上のVertexが少なすぎる場合や、完全なsource polygonが残らない場合はSurfaceを構築できません。
Revealされない
Target Object、Target Vertex Group、OccluderがONになっていることを確認してください。
Apply / Rebuild Revealを実行してください。
Material PreviewまたはRenderedで確認してください。
OccluderにMaterialがない
Occluderには使用可能なMaterialが必要です。
Materialを追加してから再度Applyしてください。
別ObjectまでRevealの影響を受ける
Isolate Shared MaterialsをONにしてください。
Target Object移動時に重い
Transform Broad-phase CullingをONにしてください。
Target Vertex Groupを必要最小限へ絞ることも有効です。
多数のExact Triangleが常時ACTIVEになる場合は、GPU Shader側の負荷が残る可能性があります。
Target Meshを変形すると一時的に重い
Shape Key、Armature、ModifierなどでGeometry自体が変わる場合はTarget Surface Triangleの再解析が必要です。
単純なObject移動とは処理経路が異なります。
TARGET VERSION – RUNTIME UNVERIFIEDと表示される
対象Versionではあるものの、自動Verified登録が設定されていないことを示しています。
Unsupportedという意味ではありません。
FAQ
Q. Target Objectは1個だけですか？
いいえ。v0.3.6では複数Target Objectを登録できます。
Q. 1つのTarget Objectへ複数Vertex Groupを登録できますか？
はい。
Q. 同じ名前のVertex Groupを複数Objectで使用できますか？
はい。Object + Vertex Groupの組み合わせで独立管理されます。
Q. Target Vertex Indexは必要ですか？
主モードの1-Vertex Group Surfaceでは不要です。
旧仕様との互換目的で内部Propertyが残る場合があります。
Q. Occluderを複数登録できますか？
はい。
Q. Target ObjectをOFFにするとVertex Group登録は削除されますか？
削除されません。
Revealへの寄与だけを停止します。
Q. Target Vertex GroupをOFFにすると登録は削除されますか？
削除されません。
Q. 1-Vertex Group Surfaceは円や楕円近似ですか？
いいえ。
評価済みMeshの完全source polygonから生成されたTriangleを使用します。
Q. Solid Viewでも実際に透過されますか？
Solid Viewでは補助Overlayです。
実際のMaterial透過はMaterial PreviewまたはRenderedで確認します。
Q. Broad-phase Cullingで最終Renderが欠けませんか？
Render開始前に正確なRuntime状態へ同期する処理があります。
用語
Target Object
Revealによって見せる側のMesh Objectです。
Target Unit
Target Object + Target Vertex Groupの組み合わせです。
Target Vertex Group
Reveal対象Surfaceを指定するVertex Groupです。
Occluder
Targetより手前に存在し、Reveal透過処理を受けるMesh Objectです。
1-Vertex Group Surface
Vertex Groupに属する実評価Mesh Surfaceを使用する主Projection Modeです。
Broad-phase Culling
Exact判定の前に、現在のViewやOccluderへ影響しないTarget Unitを省略する処理です。
W2L
World-to-Localの略です。
World SpaceのRay情報をTarget Local Spaceへ変換します。
Reveal Wrapper
Occluderの既存Material Shaderを置き換えず、その出力にReveal処理を追加するNode構造です。
WordPress設定用情報
SEO Title：KJ Eye Through Hair v0.3.6 取扱説明書｜Blender 5.1/5.2 Target Vertex Group透過Add-on
Meta Description：Blender 5.1/5.2対応のKJ Eye Through Hair v0.3.6について、Target Object、Vertex Group、複数Occluder、実Mesh Surface投影、Broad-phase Culling、Material設定、Demo、Troubleshootingまで解説します。
Slug：kj-eye-through-hair-v036-manual
Focus Keyword：KJ Eye Through Hair
Related Keywords：Blender Add-on、Vertex Group、Occluder、透過、Shader、Broad-phase Culling、Blender 5.1、Blender 5.2
KJ Eye Through Hair v0.3.6 継続開発用技術資料
Documentation Version：v1.0
Add-on Version：v0.3.6
用途：継続開発、Debug、Migration、Performance改善
基準日：2026年9月13日
公開区分：INTERNAL
本資料の目的
本資料は、KJ Eye Through Hairを今後継続開発する際に、過去の設計判断、Performance改善の経緯、Runtime構造、Target ObjectとTarget Vertex Groupの所有関係、Material処理、Broad-phase Cullingなどを再解析せずに引き継げるようにするための技術資料です。
実装事実については、v0.3.6のAdd-on Codeを最優先情報とします。
READMEや過去のCHANGELOGに古い仕様が残っている場合は、現行Codeを優先します。
特に、過去READMEの「One Target Object」という表現は現行仕様と一致しません。
v0.3.6では複数Target Objectと複数Target Vertex Groupを実装しています。
Version / Runtime Policy
bl_info.version：0.3.6
ADDON_VERSION：0.3.6
manifest version：0.3.6
manifest schema：1.0.0
Extension ID：kj_eye_through_hair
Minimum Blender：5.1.0
Target Blender：5.1 / 5.2
Runtime Verified Set：未登録
N-menu：KJ Eye Through Hair
Category：3D View
Blender 5.1未満はUnsupportedです。
Blender 5.1 / 5.2はTarget Versionですが、Verified Setが空のためTARGET_UNVERIFIEDとして扱います。
新しい未確認VersionはFUTURE_UNVERIFIEDとして扱います。
開発上の不変条件
Target Unitは必ず「Target Object + Target Vertex Group」で識別します。
同名Vertex Groupが別Objectに存在しても混同しません。
Target ObjectをOFFにしてもChild Group登録を削除しません。
Target Vertex GroupをOFFにしても登録を削除しません。
新しくTarget Objectだけを登録してGroupが0件の場合でも、既存Target Maskを無効化してはいけません。
Final Maskは有効なTarget Unit MaskのMAX unionです。
1-Vertex Group Surfaceは実際の評価済みMesh Surfaceを使用します。
円や楕円などのproxyへ置き換えてはいけません。
Surface採用判定はsource polygon単位で行います。
Quadの片側Triangleだけが残るhalf-polygon artifactを再発させてはいけません。
Pure Object TransformではTriangle座標を再解析せず、World-to-Localのみを更新します。
Shape Key、Armature、Modifier、Mesh変形はEvaluated Meshを反映します。
同一Objectに複数Target Groupがある場合、Evaluated Mesh snapshotはObject単位で共有します。
Add Target Vertex Groupでは既存Target Surfaceを全再構築しません。
Broad-phase CullingはExact結果を近似するものではなく、Exact判定の前段Filterだけに使用します。
Render開始前にはCull状態を正確なRuntime Stateへ同期します。
Occluderの元Shaderは置換せず、Reveal Wrapperで包みます。
Shared Material IsolationおよびDithered設定は可逆Live Toggleとして維持します。
Legacy Regionsは互換機能として保持します。
Architecture
基本構造は次の順序です。
N-menu UI
↓
Scene.kj_eth_settings
↓
Target Object Registry
↓
Target Unit Registry
↓
Evaluated Mesh Analysis
↓
Per-Target Surface ShaderNodeTree
↓
Per-Object World-to-Local Ray Transform
↓
Shared Ray/Triangle Kernel
↓
Per-Unit Triangle MAX Union
↓
Master Target Unit MAX Union
↓
Runtime Reveal Group
↓
Occluder Material Reveal Wrapper
↓
Material Preview / Rendered
補助処理としてDepsgraph Handler、Frame Handler、Render Handler、GPU Draw Handler、Debug Textがあります。
Scene Root
Scene Propertyとして「bpy.types.Scene.kj_eth_settings」を使用します。
KJETH_SettingsをPointerPropertyとして登録します。
SceneごとにTarget Registry、Occluder Registry、各種設定を保持します。
Target Object Registry
Target Object RegistryはKJETH_TargetObjectItemで管理します。
主な情報はenabledとobjectです。
Target Object Listに登録行が存在する場合、Active RowがTarget Vertex Group UIの編集Ownerになります。
上部のcharacter_objectは登録前のstaging selectorとして扱います。
Target Object List行をObject Pickerとして使用してはいけません。
行はSelection LabelとEnabled Checkboxを基本とします。
Target Unit Registry
Target Vertex GroupはKJETH_TargetItemで管理します。
主なPropertyはenabled、target_object、vertex_group、runtime_group_name、runtime_vertex_group、runtime_target_objectです。
Runtime Unit KeyはTarget Object + Vertex Groupから構成します。
同名GroupでもOwner Objectが異なれば別Unitです。
Occluder Registry
OccluderはKJETH_OccluderItemで管理します。
主なPropertyはenabledとobjectです。
有効なOccluder List Rowが存在する場合はListを実際のRegistryとして扱います。
上部のOccluder Object欄は追加対象用のstaging selectorとして扱います。
Legacy Region Registry
Legacy Reveal RegionsはKJETH_RevealRegionで管理します。
主なPropertyはname、enabled、vertex_group、shape_mode、strength、weight_threshold、depth_marginなどです。
Superellipse関連ParameterもLegacy compatibilityのため残します。
主なProperty
enabledはGlobal Reveal Gateです。
auto_updateはHandlerによる自動更新を制御します。
transform_broadphase_cullingはTransform時のConservative Cullを制御します。
reveal_modeはTarget Vertex GroupsとLegacy Regionsを切り替えます。
character_objectはTarget stagingまたはfallbackです。
target_group_weight_thresholdはVertex Group membership thresholdです。
target_projection_geometryはExact SurfaceとRadius Modeを切り替えます。
target_projection_radiusはRadius Mode専用です。
target_projection_featherもRadius Mode専用です。
target_depth_marginはOccluderからTargetまでのDepth条件です。
require_outward_normalはSurface Facing条件です。
normal_facing_thresholdはFacing Dot Thresholdです。
global_reveal_strengthはFinal Reveal Strengthです。
isolate_shared_materialsはShared Materialの所有関係を制御します。
set_ditheredはEEVEE Dithered状態を制御します。
solid_assistはSolid Overlayを制御します。
solid_opacityはOverlay Alphaです。
debug_show_axesはDebug Axis表示です。
UI Class Map
KJETH_PT_mainはMain Panelです。
KJETH_PT_demoはDemo Panelです。
KJETH_PT_targetsはTarget / Occluder Registry Panelです。
KJETH_PT_regionsはLegacy Reveal Regionsです。
KJETH_PT_materialはOccluder Material / Renderです。
KJETH_PT_viewportはSolid Assistです。
KJETH_PT_debugはDebug / Diagnosticsです。
KJETH_UL_target_objectsはTarget Object Listです。
KJETH_UL_target_groupsはTarget Vertex Group Listです。
KJETH_UL_occludersはOccluder Listです。
KJETH_UL_reveal_regionsはLegacy Region Listです。
Operator Map
kj_eth.set_characterはActive MeshをTarget staging fieldへ設定します。
kj_eth.use_active_target_vertex_groupはActive Target ObjectのActive Vertex Groupをstaging fieldへ設定します。
kj_eth.target_object_add_primaryはTarget ObjectをRegistryへ登録します。
kj_eth.target_object_removeはTarget Object登録を解除します。
kj_eth.target_group_add_currentはTarget Vertex Groupを登録し、Incremental Runtime Updateを実行します。
kj_eth.target_group_add_activeはActive Vertex Groupを直接登録します。
kj_eth.target_group_removeは選択Target Unitを解除します。
kj_eth.set_hairはActive MeshをOccluder staging fieldへ設定します。
kj_eth.occluder_add_primaryはOccluderをRegistryへ登録します。
kj_eth.occluder_add_selectedは選択Meshを一括登録します。
kj_eth.occluder_removeはOccluder登録を解除します。
kj_eth.applyはRuntime Group構築とMaterial Wrapper適用を行います。
kj_eth.refreshはRuntime Target / Region Dataを更新します。
kj_eth.removeはReveal Wrapperを除去します。
kj_eth.create_demoはDemo生成とSetupを実行します。
kj_eth.show_demoは既存Demoを表示します。
kj_eth.remove_demoはDemoを削除します。
Target Surface Selection Algorithm
中心となる処理は_analyze_target_vertex_group_prepared()です。
Source Object上のVertex Groupを取得します。
Evaluated Mesh各VertexについてVertex Group Weightを読みます。
Weightがtarget_group_weight_threshold以上のVertexをSelected Setへ登録します。
Weighted CenterおよびNormalを計算します。
次にsource polygonを確認します。
Polygonを構成するすべてのVertexがSelected Setに含まれている場合だけ、そのPolygonをvalid_polygonとして採用します。
mesh.loop_trianglesからvalid_polygon由来のTriangleだけを抽出します。
Triangle座標はTarget Local Coordinatesとして保持します。
Overlay用Local / World Triangle Cacheを作成します。
Broad-phase用Local AABBも同時に作成します。
重要なのは、Triangleだけの3頂点判定ではなく、そのTriangleの元になったsource polygon全体を判定することです。
これによりQuad境界にDiagonal Half-Faceが発生する問題を防止します。
Object-batched Evaluated Mesh Analysis
同じTarget ObjectへEye_L、Eye_R、Brow_L、Brow_Rなど複数Groupを登録した場合、Groupごとにto_mesh()を繰り返してはいけません。
Object.evaluated_get()
↓
to_mesh()
↓
calc_loop_triangles()
↓
Mesh Geometry Preparation
↓
Group A Analysis
↓
Group B Analysis
↓
Group C Analysis
↓
to_mesh_clear()
という構造を維持します。
Evaluated Mesh取得はObjectにつき1回です。
各GroupのWeight判定、Polygon Membership、Triangle抽出は独立して行います。
Exact Ray / Triangle Kernel
共有Node Group名は「KJ_ETH_RayTriangleKernel_v021」です。
内部のRay / Triangle判定はMöller–Trumbore方式です。
Python側ではTriangleごとにA、Edge1、Edge2、Face NormalなどのStatic Valueを事前計算します。
Shader側ではView依存のRay Origin、Incoming、Ray Directionを動的に評価します。
概念的なHit条件は、determinantがepsilonより大きいこと、uとvがTriangle内部であること、u + vが1以下であること、tがDepth Marginより大きいこと、Facing条件を満たすことです。
Triangle HitのUnionはBalanced MAX Treeを使用します。
長いSerial MAX Chainへ戻してはいけません。
World-to-Local Transform Strategy
Target TriangleはTarget Local Coordinatesで保持します。
Target Objectを移動、回転、拡大縮小した場合でもTriangle Constant自体は作り直しません。
World SpaceのOccluder Shading RayをTarget Local Spaceへ変換するWorld-to-Local Constantsだけを更新します。
同じTarget ObjectにEye_L、Eye_R、Brow_L、Brow_Rが存在してもObject Transformは共通です。
そのためObject単位のW2L Blockを共有します。
関連関数は_target_world_to_local_components()、_build_target_world_to_local_rays()、_set_target_world_to_local_constants()、_ensure_master_object_ray()です。
Target Runtime Node Ownership
Master Node Group Prefixは「KJ_ETH_ViewDependentReveal_v021」です。
Triangle Kernelは「KJ_ETH_RayTriangleKernel_v021」です。
Per Target Surface Groupは「KJ_ETH_TargetSurface_v021」です。
Prefixにv021が残っているのはRuntime Identityの歴史的互換性によるものです。
Add-on Versionが0.3.6だからという理由だけでPrefixを単純Renameしてはいけません。
既存Blend FileとのMigrationへ影響する可能性があります。
Master Mask Union
Final Maskは有効なTarget Unit MaskのMAX unionです。
Object A / Group 1
Object A / Group 2
Object B / Group 1
Object B / Group 2
↓
MAX
↓
Final Target Mask
新しいTarget Objectだけを登録してGroupが0件の場合、そのObjectはMask 0相当として扱います。
他の既存Target Maskを無効にしてはいけません。
Incremental Add Target Group
v0.3.1以降では、Target Vertex Groupを追加した際にRuntime全体を再構築しません。
新規Target Unitだけを解析します。
そのUnitのTarget Surface Subgroupだけを構築または更新します。
既存のObject W2L Blockがあれば再利用します。
Master Target Nodeを追加または更新します。
最後に軽量なMAX Union / Outputだけを更新します。
Overlay CacheもTarget Unit単位で追加します。
Add Target中はHandler Suspend Transactionで処理します。
これによりAdd操作自身が発生させるDepsgraph Geometry通知を重複処理しません。
Transform Fast Path
Target ObjectのPure Transformでは_update_target_transform_only()を優先します。
変更されたObjectだけを処理します。
Matrix Signatureが変化したObjectだけW2Lを更新します。
Geometry Analysisは実行しません。
Solid Overlayは必要な場合だけ更新します。
Material Preview / RenderedではSolid Overlay更新を省略します。
Solid Overlay更新は最大約30fpsへThrottleします。
TransformとGeometry Flagが同時に通知された場合、Transformは即処理し、Geometry処理はDeferredへ回します。
Deferred Geometry Refresh
Transform操作中にBlenderがGeometry Updateも通知する場合、毎イベントでEvaluated Meshを再解析しないようDeferred Queueへまとめます。
Deferred Geometry処理自身がDepsgraph Callbackを発生させるため、Handler Suspend Transaction内で実行します。
Geometry-only変更の場合はTargeted Geometry Refreshを実行します。
Persistent Broad-phase Culling
v0.3.6の主要なPerformance最適化です。
Target Vertex GroupごとにLocal AABBを保持します。
Target Object移動時、Exact計算の前に現在のTarget UnitがOccluderへ影響する可能性があるかを安価に判定します。
主な判定材料はMaterial / Rendered View Context、Target Unit Local AABB、Occluder Projected Bounds、NDC Rectangle Overlap、View Frustum、Conservative Depth Relationshipです。
NDC Marginは0.05です。
v0.3.6ではTime-based CULL-RESTOREを完全廃止しています。
CULLED Stateは、条件が再びRelevantになるまで保持します。
Target移動時は、そのTarget Objectに属するUnitだけを再判定します。
Occluder TransformまたはGeometry Change時は、現在CULLED中のUnitだけを再判定します。
Material / Rendered View Matrixが変化した場合も、CULLED Unitだけを再判定します。
CULLEDからACTIVEへ戻る場合は、最新W2Lを先に書き、その後Enabledを1へ戻します。
この順序はStale W2Lによる一瞬の古いReveal Mask表示を防止するため重要です。
Broad-phase State Machine
ACTIVE状態でBroad-phaseが「現在はRevealへ影響しない」と判定した場合、CULLEDへ移行します。
CULLEDではEnabled Socketを0にし、不要なW2L Writeを省略します。
時間が経過しただけではACTIVEへ戻しません。
Target、Occluder、Viewなどの条件変更により再びRelevantになった場合だけACTIVEへ戻します。
ACTIVE復帰時には最新W2Lを書き、その後Enabledを1へ設定します。
View-change Re-evaluation
CULLED Unitが存在するときだけView Signatureを監視します。
Draw PathではNodeTreeを書き換えません。
View MatrixのSignature変化だけを記録します。
その後Timer側でCULLED Unitを再判定します。
ACTIVE Unitしか存在しない場合は不要なView Re-evaluationを増やさない設計を維持します。
Occluder Material Wrapper
Occluderの既存Material Shaderを削除または置換してはいけません。
Reveal処理はWrapperとして挿入します。
Wrapper Nodeは「KJ_ETH_WRAPPER」Prefixで識別します。
Remove時にはWrapperを除去し、元のMaterial Connectionを可能な限り復元します。
Shared Material Isolation
isolate_shared_materialsはDefaultでONです。
ONの場合、Materialが他Objectでも共有されていればOccluder専用Copyを作成します。
非Occluder Objectが使うOriginal MaterialへReveal Wrapperを残さないことが重要です。
OFFの場合はOriginal Shared MaterialへReveal Wrapperを適用します。
Live Toggleとして動作し、切り替え時に可能な範囲で元状態へ戻します。
EEVEE Dithered Backup / Restore
set_ditheredはDefaultでONです。
ON時にはMaterialの既存Render状態をBackupした後、Ditheredを有効化します。
同じMaterialで繰り返しApplyしてもBackup元を上書きしてはいけません。
OFF時およびReveal Remove時にはPre-KJ状態へ戻します。
Geometry Refresh
Geometry Refreshでは、ObjectごとにEvaluated Meshを1回取得します。
そのObjectに所属するTarget Vertex Groupだけを再解析します。
Triangle CountやTopologyが互換ならConstant Updateを優先できます。
必要な場合だけTarget Surface Groupを再構築します。
Broad-phaseのACTIVE / CULLED Stateは可能な限り維持します。
Local Bounds Cacheも更新します。
Pure TransformとGeometry Refreshを混同してはいけません。
Render Exactness Contract
Viewport Broad-phase CullingはPerformance Optimizationです。
最終Renderの形状を近似する機能ではありません。
Render開始前にはCULLED Unitを正確なStateへ戻します。
その後Runtime Refreshを実行します。
今後さらにGPU Optimizationを追加する場合も、このRender-pre Exact Contractを維持する必要があります。
Legacy Regions
Legacy v0.0.3系のRegion方式を互換機能として保持します。
主なShape ModeはSUPERELLIPSEとFACE_EXACTです。
SUPERELLIPSEはMask Expand、Width Scale、Height Scale、Shape Power、Feather、Minimum Half Sizeなどを使用します。
FACE_EXACTはEvaluated Meshの完全なFace Regionを使用します。
Legacy Modeを新しい主機能へ流用しないことを推奨します。
Demo Structure
Demo Collection名はKJ_ETH_Demoです。
Target Object名はKJ_ETH_Demo_CharacterSphereです。
Occluder Object名はKJ_ETH_Demo_HairCubeです。
Vertex GroupはKJ_Eye_L、KJ_Eye_R、KJ_Brow_L、KJ_Brow_Rです。
Demo Objectはkj_eth_demo_owned Custom Propertyで識別します。
Create Demo中はAuto Updateを一時的にOFFにしてBatch Property Assignmentを行い、apply_setup()を1回だけ実行します。
終了後は短時間のHandler Suppressionを設定します。
Debug Log
Debug Text Datablock名はKJ_ETH_DebugLogです。
DxxxはDemo関連です。
AxxxxはTarget Group Analysisです。
A-BATCHはObject Batch Analysisです。
NxxxxはNode Rebuildです。
ADD-TARGETはIncremental Addです。
HxxxxはDepsgraph Handlerです。
XFORMはTransform Fast Pathです。
GEOM-TARGETEDはGeometry Refreshです。
DEFERはDeferred Geometryです。
HSUSPはHandler Suspend Transactionです。
CULL-REEVALはPersistent Culled Unit Re-evaluationです。
Performance Regressionを評価するときは、Viewportの体感だけでなくTagごとの処理時間も比較します。
v0.3.6 実測Sample
2026年9月13日に取得したSample Logでは、Create Demo Totalは約0.1476秒でした。
Initial Runtime Rebuildは42 Triangleで約0.0996秒でした。
Brow_L 20 Triangleの追加は約0.0301秒でした。
Eye_L 42 Triangleの再追加は約0.0738秒でした。
Eye_R 42 Triangleの追加は約0.1203秒でした。
Brow_R 20 Triangleの追加は約0.0399秒でした。
4 Active Unit時のTransform Handlerは、表示されたSampleで概ね約0.0013～0.0033秒でした。
4 UnitすべてがCULLEDの場合は概ね約0.0002～0.0005秒でした。
4 Unit、124 TriangleのTargeted Geometry Refreshは約0.2070秒でした。
これらは特定PC、特定SceneでのSampleであり一般性能保証値ではありません。
現在のBottleneck評価
Pure TransformのPython Handlerは、v0.3.6時点ですでに低コストです。
4 Target Unit、124 TriangleがACTIVEなMaterial Preview / Rendered Viewで体感が重い場合、次に疑うべき候補はGPU Shader側のPer-pixel Exact Ray / Triangle Evaluationです。
これはDebug Logからの合理的推定であり、GPU Profilerによる直接計測はまだ実施していません。
今後はACTIVE 4 UnitとCULLED 4 UnitのViewport FPSまたはGPU Timingを比較し、Shader Bottleneckであることを確認してから次の最適化へ進むべきです。
次段階候補：Triangle Cluster Broad-phase
次のPerformance最適化候補として、Target Unit内のTriangleをClusterへ分割する方法があります。
Target Unit
↓
Triangle Cluster
↓
Cluster Conservative Bounds
↓
Relevant Clusterだけ有効化
↓
Exact Triangle Kernel
ただし、Shader Node上でEnabled=0のBranchがGPUで実際にどの程度計算省略されるかは測定が必要です。
実装前にGPU Bottleneckであることを確認します。
Cluster選択処理のOverheadがTriangle削減効果を上回らないことを確認します。
Exact結果を変えないことを必須条件とします。
Render-pre Exact Contractも維持します。
Performance Regression Checklist
次Versionでは、Create Demo Total、Initial 42 Triangle Rebuild、20 Triangle Group追加、42 Triangle Group追加、1 Active Unit Transform、4 Active Unit Transform、1 Fully Culled Unit Transform、4 Fully Culled Unit Transform、4 Unit Geometry Refresh、View-change Re-evaluation、Occluder Transform Re-evaluation、Render-pre Exact Restoreを比較します。
単に「重い」「軽い」という体感だけで判定せず、Debug Logで数値を比較します。
Functional Regression Checklist
Target Object List Rowをクリックすると編集Ownerが切り替わること。
上部Target Object FieldがStaging Selectorとして残ること。
Target Object OFFでもChild Group登録を保持すること。
複数Target Objectが独立して動作すること。
同名Vertex Groupが別Objectで独立すること。
既存Target Groupを再追加したとき重複行を作らないこと。
Target Group OFFはそのUnitだけをGateすること。
Source Polygon全Vertex Ruleが維持されること。
Diagonal Half-Quad Artifactが再発しないこと。
Outward Facing、Normal Threshold、Depth Marginが機能すること。
Pure G/R/SでTriangle再解析しないこと。
CULLED StateがRelevantになるまで持続すること。
再Activation時に最新W2Lを先に書くこと。
View Changeで必要なCULLED Unitが復帰できること。
Occluder移動でも必要なCULLED Unitが復帰できること。
Shape Key、Armature、Modifier ChangeでSurface更新されること。
同一ObjectのEvaluated Mesh取得が1回に集約されること。
複数Occluderへ同一Reveal Maskを適用できること。
Occluder OFFまたはUnregister時にMaterial状態を可能な限り復元すること。
Shared Material Isolationが非Occluderへ影響しないこと。
Dither OFFでPre-KJ状態へ戻ること。
Render前にCULLED UnitがExact Stateへ戻ること。
Known Limitations / Risks
Runtime Verified Setは空です。
Blender 5.1 / 5.2を対象としていますが、自動Verified Stampはありません。
Shared MaterialのOriginal復元にはMaterial Nameへ依存する箇所があります。
Exact Triangle数が増えるほどShader Node Instance数とGPU Evaluation Costが増加します。
Geometry RefreshはTransform Fast Pathより重くなります。
Legacy RegionsとTarget Vertex Group ModeはReveal Modeで切り替えて使用します。
READMEの一部には旧One Target Object仕様の表現が残っています。
Blender実機用のAutomated Test Suiteは現行Package内に確認できません。
Migration History
v0.0.14ではTarget TriangleをLocal Coordinatesへ保存する方式へ変更しました。
Object G/R/SはW2L Constantsだけで追従する設計へ変更しました。
Source Polygon全Vertex Ruleもこの系統で確立しました。
v0.0.15では共有Möller–Trumbore Kernel、Static Triangle ValueのPython Precompute、Balanced MAX Treeを導入しました。
v0.0.17～0.0.18では複数Occluder RegistryとMaterial Restoreを追加しました。
v0.0.27ではTrue Multi-Target Object Runtimeへ移行し、Target UnitをObject + Vertex Groupとして定義しました。
v0.0.28ではTarget Object List RowをSelection-onlyへ変更し、Child Target Group UIをActive Target Object RowでScopeする方式へ整理しました。
v0.3.0ではShared Material IsolationとDithered設定をLive Toggle化しました。
v0.3.1ではIncremental Add Target GroupとObject-batched Evaluated Mesh Analysisを導入しました。
v0.3.2ではChanged-object-only W2L Update、Deferred Geometry、Solid Overlay Throttlingを追加しました。
v0.3.3ではAdd Target処理をHandler Suspend Transaction化しました。
v0.3.4ではConservative Target Unit Broad-phase Cullingを導入しました。
v0.3.5ではCull Restore Debounceを試しましたが、Transform Event間隔だけでは操作終了を正確に判断できないことが判明しました。
v0.3.6ではTime-based Restoreを廃止し、Persistent Condition-driven CULLED Stateへ変更しました。
Internal Constants / Naming
NODE_GROUP_PREFIXはKJ_ETH_ViewDependentReveal_v021です。
RAY_TRIANGLE_KERNEL_GROUP_NAMEはKJ_ETH_RayTriangleKernel_v021です。
TARGET_SURFACE_GROUP_PREFIXはKJ_ETH_TargetSurface_v021です。
MASTER_UNION_TAGはkj_eth_master_union_v021です。
MASTER_TARGET_NODE_TAGはkj_eth_master_target_node_v021です。
WRAPPER_NODE_PREFIXはKJ_ETH_WRAPPERです。
OWNED_KEYはkj_eth_ownedです。
ORIGINAL_MATERIAL_KEYはkj_eth_original_materialです。
Demo CollectionはKJ_ETH_Demoです。
Demo TargetはKJ_ETH_Demo_CharacterSphereです。
Demo OccluderはKJ_ETH_Demo_HairCubeです。
Debug TextはKJ_ETH_DebugLogです。
Overlay Minimum Intervalは約1/30秒です。
Add Target後のPost Suspendは0.10秒です。
Broad-phase NDC Marginは0.05です。
Node Group Prefixのv021表記は単純Renameしないでください。
既存Runtime GroupとのMigrationへ影響する可能性があります。
Runtime Cache
主要Cacheは_TARGET_SIGNATURE_CACHE、_TARGET_OBJECT_MATRIX_CACHE、_TARGET_LOCAL_OVERLAY_CACHE、_OVERLAY_LAST_UPDATE、_TARGET_CULLED_UNITS、_BROADPHASE_VIEW_SIGNATURES、_BROADPHASE_VIEW_DIRTY、_DEFERRED_GEOMETRYです。
Load PostおよびUnregister時には適切にClearします。
新しいCacheを追加する場合はScene Scopeを基本とし、別Scene間でStateを混在させないようにします。
Error / Fallback Policy
Incremental処理に失敗した場合はFull refresh_runtime()へFallbackする経路を残します。
PerformanceのためにFallbackを削除してはいけません。
Correctnessを優先します。
Error LogにはTarget Object名、Vertex Group名など、原因特定に必要な情報を含めます。
Save / Load Behavior
Persistent User DataはScene PropertyGroupおよびCollectionPropertyとして.blendへ保存されます。
Runtime-only DiagnosticsはSKIP_SAVEとします。
Node GroupやMaterial WrapperはBlend Dataとして残る場合があります。
Load PostではRuntime CacheをClearし、その後の更新で再同期します。
Preset Save、User Library、Export機能はv0.3.6では確認できません。
Parameter Dependency Map
Enable Reveal Through HairはFinal Reveal Gateです。
Reveal ModeがTarget Vertex Groupsの場合、Target Object List、Target Vertex Group List、Projection Geometry、Occluder Listを使用します。
Projection Geometryが1-Vertex Group Surfaceの場合、Group Weight Threshold、Depth Margin、Outward Normal、Normal Thresholdが主Parameterです。
Projection Geometryが2-View Ray Radiusの場合、Projection RadiusとProjection Featherを使用します。
Reveal ModeがLegacy Regionsの場合、Region List、Superellipse Parameter、Face Exactを使用します。
Isolate Shared MaterialsはOccluder Material Ownershipを制御します。
EEVEE DitheredはMaterial Render StateのBackup / Restoreを制御します。
Transform Broad-phase CullingはTransform時のW2L Write抑制とPersistent CULLED Stateを制御します。
今後の開発方針
現在のTarget移動Python Pathは十分軽量化されています。
次にPerformance改善を行う場合は、GPU Shaderが本当にBottleneckであることを測定してから進めます。
単にNode数を減らす目的でExact Ray / Triangle Algorithmを簡略化してはいけません。
一般化できない特定Preset専用の例外処理も追加しません。
既存機能を削除して軽量化するのではなく、Broad-phase、Caching、Incremental Updateなど、結果を変えずに不要処理を省略する方向を優先します。
将来のVersionでも、Target Object + Target Vertex GroupというTarget Unit定義、Source Polygon全Vertex Rule、Per-object W2L、MAX Union、Render-pre Exact Contractを維持することを基本方針とします。