Blender Python API rehberi: sahne nesneleri ve operatörleri otomatikleştirme

Bu rehberde ne öğreneceksiniz?

Blender Python API’si, sahne üzerinde yapılan bazı işlemleri kodla tanımlamaya ve yeniden uygulamaya imkân verir. Bu rehberde, bir ışık veri bloğu ve onu kullanan nesnenin nasıl oluşturulacağını; nesnenin etkin koleksiyona nasıl bağlanıp konumlandırılacağını göreceksiniz. Ayrıca bpy.ops üzerinden operatör çağırma, çağrıdan önce poll() kullanma ve operatörün dönüş durumunu değerlendirme konularını ele alacağız.

Örnekler Blender’ın resmi API belgelerindeki açıklamalara dayanıyor. Amaç, hazır bir mimari otomasyon sistemi sunmak değil; sahne üzerinde işlem yapan betiklerin temel parçalarını anlaşılır biçimde tanıtmak. Kod parçalarını kendi dosyalarında kullanmadan önce, neyi değiştirdiklerini inceleyip küçük bir test sahnesinde denemek gerekir.

Gereksinimler ve sürüm notu

Bu örnekler Blender’da Python API’siyle çalışmayı gerektiriyor. Belgelerde kullanılan belirli bir Blender sürüm numarası belirtilmediğinden, burada da sürüm uyumluluğu için kesin bir numara verilemiyor. Kodları çalıştırırken kullanılan Blender kurulumunun API belgelerini kontrol edin. Kaynaklarda hesap gerekliliği, ücret veya özel bir donanım koşulu açıklanmıyor.

Kodlar bpy modülünü kullanır. Örneklerde görülen API adları ve parametreler, Blender’ın resmi belgelerindeki kullanımlara dayanıyor. Özellikle operatörler, sadece parametrelerine değil, çalıştırıldıkları bağlama da bağlı olabilir. Bu nedenle bir operatörü çağırmadan önce sahnedeki etkin nesne ve ilgili işlem koşulları gözden geçirilmelidir.

Adım adım: sahneye bir ışık nesnesi ekleyin

Aşağıdaki örnek, Blender’ın resmi belgelerinde yer alan ışık oluşturma akışını gösteriyor. Işık veri bloğu ile sahnede yer alan nesne ayrı ayrı hazırlanıyor; ardından nesne etkin görünüm katmanının koleksiyonuna ekleniyor.

import bpy
view_layer = bpy.context.view_layer
# Create new light data-block.
light_data = bpy.data.lights.new(name="New Light", type='POINT')
# Create new object with our light data-block.
light_object = bpy.data.objects.new(name="New Light", object_data=light_data)
# Link light object to the active collection of current view layer,
# so it'll appear in the current scene.
view_layer.active_layer_collection.collection.objects.link(light_object)
# Place light to a specified location.
light_object.location = (5.0, 5.0, 5.0)
# And finally select it and make it active.
light_object.select_set(True)
view_layer.objects.active = light_object

Akışın ilk bölümünde bpy.context.view_layer üzerinden etkin görünüm katmanı alınır. Sonraki satırlarda POINT türünde bir ışık veri bloğu ve bu veriyi kullanan bir nesne oluşturulur. Nesne etkin koleksiyona bağlandıktan sonra konumu atanır; son olarak seçilir ve etkin nesne yapılır. Buradaki koordinatlar belgedeki örneğe aittir, belirli bir iç mekân veya mimari sahne için önerilen yerleşim anlamına gelmez.

Bu adımları takip ederken veri bloğu oluşturma ile nesneyi sahneye eklemeyi birbirine karıştırmamak yararlı olur. Nesneyi koleksiyona bağlamak, onun mevcut sahnede yer alması için örnekte kullanılan adımdır. Kodun sonunda nesnenin seçilmesi ve etkin nesne olarak atanması ise sonraki işlemlerin hangi nesneyle ilişkili olacağını belirler.

Operatör çağırma ve çalıştırılabilirliği denetleme

Blender belgelerine göre bpy.ops, C++, Python veya makro biçiminde yazılmış operatörleri çağırmak için kullanılır. Operatör özellikleri anahtar sözcüklerle, yani isim verilmiş parametrelerle aktarılır. Örneğin aşağıdaki çağrı, mesh.subdivide operatörüne iki özellik gönderir:

import bpy
bpy.ops.mesh.subdivide(number_cuts=3, smoothness=0.5)

Bu çağrı, her sahnede aynı koşullarda çalışacağı anlamına gelmez. Operatör uygun olmayan bir bağlamda çağrılırsa RuntimeError oluşabilir. Belgelerde önerilen yöntemlerden biri, operatörü çalıştırmadan önce poll() ile mevcut koşulları sınamaktır. Mod değiştirme örneği şu şekildedir:

import bpy
if bpy.ops.object.mode_set.poll():
    bpy.ops.object.mode_set(mode='EDIT')

poll() olumlu sonuç verdiğinde mod değiştirme operatörü çağrılır. Bu kontrol, operatörün o anki bağlamda çalıştırılabilir olup olmadığını değerlendirmeye yardım eder; tüm hata ihtimallerini ortadan kaldırdığı şeklinde yorumlanmamalıdır. Belgeler, hata raporları varsa operatör tamamlandıktan sonra RuntimeError oluşabileceğini de belirtiyor.

Operatörlerin dönüşü de dikkate alınmalıdır. Beklenen biçimde tek bir sonuç değeri yerine bir durum kümesi döndürürler. Belgelerde yaygın durumlar FINISHED ve CANCELLED olarak açıklanıyor. CANCELLED, işlemin iptal edildiğini ve değişiklik yapılmadığını gösterebilir. Bu nedenle bir betikte yalnızca operatör satırının çalıştırılmış olmasına güvenmek yerine, dönen durumu da değerlendirmek gerekir.

Bağlamı değiştirme ve mimari iş akışlarına etkisi

Operatörün gördüğü bağlamı değiştirmek için belgelerde temp_override kullanımı açıklanıyor. Bu yöntemle, operatörün seçili veya etkin veriler yerine belirli veriler üzerinde çalışması sağlanabilir. Örneğin bağlam üyeleri arasında etkin nesne ya da seçili nesneler bulunabilir. Kaynakta, mevcut bağlamın kopyasını temel alan bir yaklaşımın tercih edilmesi gerektiği; aksi hâlde operatörün ihtiyaç duyduğu bilgilerin ayrıca bulunmasının gerekeceği belirtiliyor.

Burada önemli olan, geçici bağlamı yalnızca tek bir değişkeni değiştirerek kurup diğer gereksinimleri gözden kaçırmamaktır. temp_override kullanırken operatörün ihtiyaç duyabileceği bağlam üyelerini birlikte değerlendirin. Mevcut bağlamdan hareket etmek, gerekli verileri sıfırdan toplamaya çalışmaktan daha kontrollü bir başlangıç sağlar.

Mimarlar, iç mimarlar ve görselleştirme sanatçıları için bu API temelleri; tekrarlanan sahne işlemlerini kodla tarif etmenin nasıl mümkün olduğunu gösterir. Nesne oluşturma, koleksiyona bağlama ve konum verme adımlarını ayrı ayrı görmek, bir betiğin neyi değiştirdiğini takip etmeyi kolaylaştırabilir. Ancak kaynaklar, bu örneklerin belirli bir mimari iş akışını otomatikleştirdiğini veya performansı artırdığını iddia etmiyor.

Ofis ya da eğitim ortamında betik kullanırken, hedef koleksiyonu ve etkin nesneyi kontrol edin; sahne verisini değiştiren denemeleri öncelikle kopya bir dosyada yapın. Ekipte farklı Blender sürümleri varsa kodu kullanılan kurulumlarda ayrı ayrı doğrulayın. Belgelerde donanım, ücret veya sürüm uyumluluğuna ilişkin kesin koşullar verilmediğinden, bu başlıklarda varsayım yapmak yerine mevcut kurulumda test etmek gerekir.

Sık yapılan hatalar ve sonraki adımlar

İlk hata, bpy.ops çağrılarının bağlamdan bağımsız çalıştığını varsaymaktır. Operatörü kullanmadan önce hangi verinin etkin olduğunu kontrol edin ve uygun olduğunda poll() ile çağrılabilirliğini sınayın. İkinci hata, çağrının her durumda başarılı olduğunu düşünmektir. FINISHED ve CANCELLED gibi dönüşleri inceleyin; hata raporlarının RuntimeError oluşturabileceğini hesaba katın.

Nesne oluştururken veri bloğu hazırlama, nesne oluşturma, koleksiyona bağlama, konum atama ve nesneyi etkinleştirme adımlarını takip edin. Beklenen sonuç ortaya çıkmadığında hangi aşamada sorun olduğunu bu şekilde daha kolay ayırabilirsiniz. Yeni bir operatöre geçerken resmi API belgesinde parametreleri ve bağlamla ilgili açıklamaları inceleyin; ardından küçük bir test sahnesinde sonuçları doğrulayın.

Sonraki aşamada temp_override örneklerini inceleyip bağlam üyelerinin nasıl aktarıldığını test edebilirsiniz. Bu yöntemi kullanırken operatörün hangi bağlam bilgilerine ihtiyaç duyduğunu belirleyin. Sahne üzerinde kapsamlı değişiklik yapan betikleri gerçek proje dosyasında denemeden önce kopya dosyada çalıştırmak, sonuçları gözden geçirmek için daha kontrollü bir yol sunar.

Kaynak ve lisans

Bu rehber, Blender’ın bpy.ops ve bpy.types.Object API belgelerindeki açıklama ve örneklerden Türkçeye uyarlanmıştır. Her iki kaynak da CC BY-SA 4.0 lisanslıdır.