holodepth

3D Model Formatları · glTF / GLB · Uzantılar (Extensions)

KHR_materials_variants glTF'de Materyal Varyant Eşlemesi

«Aynı araba, üç renk seçeneği» için üç ayrı GLB kopyalamak zorunda değilsiniz: core primitive tek material indeksi taşır; Material Slots bunu sabitler; bu sayfa Uzantılar grubunun son derin sorusuna geçer: aynı yüzey için alternatif materyal kartları dosyada nasıl eşlenir?

KHR_materials_variants materyal içeriğini çoğaltmaz; «hangi varyant adı hangi materials[i] indeksine gidecek» haritasını taşır. Kökte variants[] kataloğu (isimler), primitive'te mappings[], isteğe bağlı node'da aktif variant seçimi. Runtime hangi varyantın görüneceğini uygular; dosya tüm seçenekleri bir arada saklar.

Sayfayı bitirdiğinizde şu cümleyi kurabilmelisiniz: «Variants uzantısı isimli SKU listesi + primitive başına material eşlemesi yazar. Varsayılan primitive.material seçim yokken veya fallback için kalır. Clearcoat kartı zenginleştirir; variants hangi kartın takılacağını çoğaltır. Seçim node veya uygulama API'sindedir; format yalnızca tabloyu taşır.»

Bu sayfanın sınırı · komşu konularla ayrım

Bu sayfa variants uzantısının glTF dosya sözleşmesini anlatır:

  • Kök variants[] kataloğu
  • Primitive mappings[]
  • Varsayılan material vs varyant material
  • Node variant seçimi (format)
  • Holodepth teşhis açıları

Bilinçli olarak dışarıda bırakılan konular:

  • Extension mekanizması genel → Extension Sistemi
  • Core tek slot → Material Slots
  • PBR kart içeriği → PBR Yapısı
  • Clearcoat / sheen / transmission → Extension Sistemi kataloğu
  • Üç ayrı mesh kopyası (duplike node) → Node Hiyerarşisi
  • UI dropdown / e-ticaret seçici API → runtime / ürün kodu
  • Draw call birleştirme → Materyal Optimizasyonu (Three.js)

Kısa ayrım: Variants (Format) «eşleme tablosu nedir?» · Material Slots (Format) «tek indeks nedir?» · Material mapping (Runtime) «seçim sahneye nasıl uygulanır?»

Uzantılar grubu dördüncü soru

Uzantı Ne ekler Soru Sayfa
Draco Sıkıştırılmış geometri Mesh baytı nasıl küçülür? KHR_draco_mesh_compression
BasisU KTX2 dokular Texture baytı nasıl küçülür? KHR_texture_basisu
GPU Instancing Çoğaltma attribute'ları Aynı mesh N kez nasıl çizilir? EXT_mesh_gpu_instancing
Materials Variants Alternatif material eşlemesi Renk / trim hangi karta gider? KHR_materials_variants (bu sayfa)

Variants nedir? (Format dilinde)

Zihin modeli: tek gövde, çoklu boya kodu

  • Geometri aynı kapı paneli (mesh/primitive).
  • Core material varsayılan boya (tek indeks).
  • Variants kataloğu SKU listesi: Kırmızı, Mavi, Siyah.
  • Mappings «Kırmızı seçilince materials[4]» tablosu.
  • Runtime hangi SKU aktif, onu primitive'e yazar.

E-ticaret ve konfigüratörlerde «ürün varyantı» UI kavramı vardır. glTF'de karşılığı yapılandırılmış JSON eşlemesidir: yeni mesh üretmeden aynı primitive için alternatif materials indeksleri tanımlanır. Bu, dosyada birden fazla tam model kopyası taşımaktan genelde daha küçük ve daha tutarlıdır.

Variants şunların hiçbiri değildir:

  • LOD seviyesi değil farklı mesh yoğunluğu ayrı primitive/mesh
  • Morph target değil şekil anahtarı Morph Targets'ta
  • Materyal clearcoat katmanı değil tek kartın zenginleşmesi
  • Animasyon clip değil zaman içi hareket Keyframe'de
  • State machine değil ürün kodu katmanı

Material Slots «bu primitive şu an hangi tek kartı kullanıyor» der (core). Variants «aynı primitive için başka kartlar da tanımlı» der (extension). İkisi çakışmaz; birlikte yaşar.

Used vs Required: seçim sözleşmesi

Tipik ilan ( Extension · Used/Required): 

"extensionsUsed": ["KHR_materials_variants"]

Variants çoğu pakette Used yeterlidir: loader desteklemiyorsa varsayılan primitive.material ile devam edilir (sessiz düşüş). Tüm ürün deneyimi varyanta bağlıysa Required yazılabilir; bu durumda desteklemeyen viewer modeli reddeder. Holodepth: konfigüratör SKU'su zorunluysa Required + uygulama tarafında variant seçimini zorunlu kılın; yalnızca «bonus renk» ise Used yeterlidir.

Variants ilan matrisi
Durum Görünüm
Used + destek var + variant seçildi Doğru alternatif materyal
Used + destek yok Varsayılan material (core)
Used + destek var + seçim yok Varsayılan material
Required + destek yok Yükleme hatası

Kök katalog: variants[]

Uzantı gövdesi kök extensions nesnesinde (asset seviyesi) varyant listesini taşır: 

"extensions": {
  "KHR_materials_variants": {
    "variants": [
      { "name": "Beige" },
      { "name": "Red" },
      { "name": "Black" }
    ]
  }
}

Her elemanın name alanı isteğe bağlıdır ama ürün/loader için kritik pratiktir. İndeks sırası (0, 1, 2…) mappings ve node seçiminde referanstır; isim değil indeks sözleşmesi geçerlidir. Material Slots'taki indeks kaydırma tuzağının varyant yüzü: export sırası değişince «Red» artık 1 değil 2 olabilir.

İsim vs indeks

Runtime variants.findByName("Red") pattern'i name alanına bağlıdır. Holodepth: DCC/export'ta varyant adlarını bilinçli yazın; kodda mümkünse isimden indeks çözümleyip oturum boyunca indeks kullanın.

Primitive mappings[]: eşleme tablosu

Her ilgili mesh.primitives[] kaydında extension gövdesi: 

"primitives": [{
  "material": 0,
  "attributes": { "POSITION": 0, "NORMAL": 1 },
  "extensions": {
    "KHR_materials_variants": {
      "mappings": [
        { "material": 1, "variants": [0] },
        { "material": 2, "variants": [1] },
        { "material": 3, "variants": [2] }
      ]
    }
  }
}]

Her mapping kaydı:

  • material: materials[] indeksi (alternatif kart)
  • variants: hangi katalog indekslerinde bu kart geçerli

Aynı variant indeksi birden fazla primitive'te farklı material'e gidebilir (kapı paneli kırmızı, jant siyah gibi). Tek primitive'te birden fazla mapping aynı variant indeksini hedeflememeli; çakışma belirsiz seçim üretir.

Varsayılan material

Core primitive.material hâlâ vardır: aktif varyant seçilmediğinde veya loader variants desteklemediğinde kullanılan fallback. Holodepth: varsayılanı «en yaygın SKU» yapın; mappings ile tutarlı olsun (Beige hem default hem variant 0).

Node seçimi: aktif varyant

Dosya «hangi seçenekler var» der; «şu an hangisi aktif» bilgisini isteğe bağlı node extension'ında taşıyabilir: 

"nodes": [{
  "name": "CarRoot",
  "mesh": 0,
  "extensions": {
    "KHR_materials_variants": {
      "variant": 1
    }
  }
}]

variant değeri kök katalog indeksidir (ör. 1 = Red). Alt node'lar miras politikası runtime/loader'a bağlıdır; format yalnızca node başına öneri yazar. «Variants var ama hep default görünüyor» teşhisinin bir numaralı nedeni: node variant alanı yok ve uygulama seçim yapmıyor.

Node hiyerarşisi bağlamı Node Hiyerarşisi'ndedir; bu sayfa yalnızca «seçim dosyada nereye yazılabilir» sorusunu kapatır.

Variants vs duplike mesh: dosya stratejisi

İki paketleme modeli
Yaklaşım Artı Eksi
KHR_materials_variants Tek geometri, çok kart Tüm kartlar GLB'de (bellek)
3 ayrı GLB İndirme başına küçük dosya Geometri 3×, senkron riski
1 GLB + CDN query Ürün esnekliği CDN/önbellek politikası

Holodepth: konfigüratörde 5–10 renk variants mantıklıdır; 200 trim kombinasyonunda kart sayısı şişer, o noktada procedural materyal veya runtime texture swap ürün kararıdır (format dışı veya farklı pipeline). Variants «hazır kart değiştir» içindir; shader parametresi animate etmek değil.

PBR, texture ve çoklu primitive

Her mapping yalnızca materials[i] indeksine işaret eder; kartın içeriği ( PBR Yapısı, Texture Referansları) bağımsızdır. Kırmızı ve Mavi varyant farklı baseColorTexture taşıyabilir; ikisi de aynı primitive'e mappings ile bağlanır.

Çok primitive mesh'te (kapı, cam, jant) her primitive kendi mappings listesine sahip olabilir. Aynı global variant indeksi tüm parçalarda tutarlı SKU anlamına gelir; parça başına farklı mapping tabloları «tam trim paketi» oluşturur.

Draco / BasisU ile birlikte

Variants materyal indeksini değiştirir; geometri ( Draco) ve doku encoding ( BasisU) ayrı uzantılardır. Üçü aynı GLB'de birleşebilir: sıkıştırılmış mesh + KTX2 kartlar + renk varyant eşlemesi.

Runtime sınırı: tablo vs seçim

glTF dosyasında UI dropdown, URL query, e-ticaret sepeti yoktur. Format varyant kataloğu + mappings taşır; uygulama aktif indeksi seçer ve loader/material atamasını günceller ( Material mapping).

Holodepth kuralı: dosya sözleşmesi yeşil değilse (mappings bozuk, indeks OOB) UI kodu düzeltemez. Önce katalog uzunluğu, mapping material geçerliliği, variant indeks aralığı kontrol edilir.

Holodepth perspektifleri çoğu dokümanda olmayan açılar

«Variants = çoklu materyal» özeti üretimde yetersiz kalır.

Material indeksi taşması

Mapping material: 99 ama materials.length === 12 bozuk dosyadır. Validator kaçırabilir; envanterde her mapping için material < materials.length şarttır.

Variant indeksi taşması

variants: [5] ama katalog 3 eleman: tanımsız SKU. max(mapping.variants) < catalog.length taraması Holodepth standardıdır.

Yetim materyal kartı

materials[7] yalnızca variants mapping'de kullanılıyor, hiçbir default primitive'te yok: geçerli ama «görünmez» kart. Envanter: hangi kartlar yalnızca mapping'de?

Kısmi mappings

Yalnızca gövde primitive'inde mappings var, camda yok: cam her varyantta aynı kalır. Bilinçli tasarım olabilir; «cam da değişmeli» beklentisi export hatası değil, eksik mapping'dir.

Variants vs clearcoat

İki farklı varyant kartının biri clearcoat extension'lı, diğeri değil: geçerlidir. Variants kart seçimi değiştirir; clearcoat kart içeriğini zenginleştirir. Karıştırmayın.

Altı soruluk variants teşhisi

Variants katmanı kontrol listesi
Soru Yeşil ise Kırmızı ise bak
Used'da variants var mı? İlan tamam Gizli gövde
Kök variants[] dolu mu? SKU katalog var Boş uzantı
Primitive mappings var mı? Eşleme tanımlı «Varyant yok» hissi
material / variant indeksleri geçerli mi? OOB yok Export remap
Node variant veya runtime seçim var mı? Aktif SKU Hep default
Default material mantıklı mı? Fallback doğru Yanlış «showroom» rengi

Holodepth içgörüsü

«Renk değişmiyor» teşhisinde önce PBR kartına değil katalog + mappings + seçim üçlüsüne bakın: variants listesi var mı, ilgili primitive mappings dolu mu, aktif variant indeksi set edildi mi? Üçü yeşilse sorun kart içeriğinde veya runtime material swap'tadır.

Uzantılar grubu kapanır

Dört uzantı derin sayfası tamamlandı: Draco, BasisU, GPU Instancing (planlanan omurga), Variants. Sıradaki Holodepth dalları:

  1. Web İçin Kullanım Neden glTF, GLB vs glTF, boyut, runtime performans
  2. Runtime materyal Material mapping
  3. Materyal omurgası özeti Extension Sistemi

Format okuyucusu özeti: variants = isimli SKU kataloğu + primitive mappings + isteğe bağlı node seçimi. Materyal içeriği materials[]'dedir; variants yalnızca hangi kartın ne zaman takılacağını çoğaltır.