Blender Python API bələdçisi: səhnə obyektlərini və operatorları avtomatlaşdırmaq

Bu bələdçidə nə öyrənəcəksiniz?

Blender Python API-si səhnədəki bəzi əməliyyatları kodla təyin etməyə və yenidən icra etməyə imkan verir. Bu bələdçidə işıq verilənlər blokunun və ondan istifadə edən obyektin necə yaradıldığını, obyektin aktiv kolleksiyaya necə bağlanıb yerləşdirildiyini görəcəksiniz. Həmçinin bpy.ops vasitəsilə operator çağırmağı, çağırışdan əvvəl poll() istifadə etməyi və operatorun qaytardığı statusu qiymətləndirməyi nəzərdən keçirəcəyik.

Nümunələr Blender-in rəsmi API sənədlərindəki izahlara əsaslanır. Məqsəd hazır memarlıq avtomatlaşdırma sistemi təqdim etmək deyil, səhnədə əməliyyat aparan skriptlərin əsas hissələrini anlaşıqlı şəkildə tanıtmaqdır. Kod parçalarını öz fayllarınızda istifadə etməzdən əvvəl onların nəyi dəyişdirdiyini yoxlayın və kiçik sınaq səhnəsində sınayın.

Tələblər və versiya qeydi

Bu nümunələrlə işləmək üçün Blender-də Python API-dən istifadə tələb olunur. Sənədlərdə konkret Blender versiya nömrəsi göstərilmədiyindən, burada da versiya uyğunluğu üçün dəqiq nömrə vermək mümkün deyil. Kodu işə salarkən istifadə etdiyiniz Blender quraşdırmasının API sənədlərini yoxlayın. Mənbələrdə hesab tələb olunması, ödəniş və ya xüsusi avadanlıq şərti barədə məlumat verilmir.

Kodlarda bpy modulundan istifadə olunur. Nümunələrdəki API adları və parametrlər Blender-in rəsmi sənədlərində göstərilən istifadəyə əsaslanır. Xüsusilə operatorlar yalnız parametrlərindən deyil, çağırıldıqları kontekstdən də asılı ola bilər. Buna görə operator çağırmazdan əvvəl səhnədəki aktiv obyekti və müvafiq əməliyyat şərtlərini yoxlamaq lazımdır.

Addım-addım: səhnəyə işıq obyekti əlavə edin

Aşağıdakı nümunə Blender-in rəsmi sənədlərindəki işıq yaratma ardıcıllığını göstərir. İşığın verilənlər bloku və səhnədə yer alan obyekt ayrı-ayrılıqda hazırlanır, sonra obyekt aktiv görünüş qatının kolleksiyasına əlavə olunur.

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

Ardıcıllığın ilk hissəsində bpy.context.view_layer vasitəsilə aktiv görünüş qatı əldə edilir. Sonrakı sətirlərdə POINT tipli işıq verilənlər bloku və bu verilənlərdən istifadə edən obyekt yaradılır. Obyekt aktiv kolleksiyaya bağlandıqdan sonra onun yeri təyin olunur; sonda isə obyekt seçilir və aktiv obyekt edilir. Buradakı koordinatlar sənədlərdəki nümunəyə aiddir, konkret interyer və ya memarlıq səhnəsi üçün tövsiyə edilən yerləşdirmə deyil.

Bu addımları yerinə yetirərkən verilənlər bloku yaratmaqla obyekti səhnəyə əlavə etməyi fərqləndirmək faydalıdır. Nümunədə obyektin kolleksiyaya bağlanması onun cari səhnədə görünməsi üçün istifadə olunan addımdır. Kodun sonunda obyektin seçilməsi və aktiv obyekt kimi təyin edilməsi isə növbəti əməliyyatların hansı obyektlə bağlı olacağını müəyyənləşdirir.

Operator çağırmaq və onun işlədilə bilməsini yoxlamaq

Blender sənədlərinə əsasən, bpy.ops C++, Python və ya makro formasında yazılmış operatorları çağırmaq üçün istifadə olunur. Operator parametrləri açar sözlərlə, yəni adlandırılmış parametrlər şəklində ötürülür. Məsələn, aşağıdakı çağırış mesh.subdivide operatoruna iki parametr göndərir:

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

Bu çağırış operatorun hər səhnədə eyni şərtlərlə işləyəcəyi demək deyil. Operator uyğun olmayan kontekstdə çağırılarsa, RuntimeError yarana bilər. Sənədlərdə tövsiyə edilən üsullardan biri operatoru işə salmazdan əvvəl cari şərtləri poll() ilə yoxlamaqdır. Rejimi dəyişdirmə nümunəsi belədir:

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

poll() müsbət nəticə verdikdə rejimi dəyişdirmə operatoru çağırılır. Bu yoxlama operatorun həmin anda cari kontekstdə işlədilə bilib-bilmədiyini qiymətləndirməyə kömək edir; bu, bütün xəta ehtimallarını aradan qaldırdığı kimi başa düşülməməlidir. Sənədlərdə həmçinin xəta hesabatları varsa, operator tamamlandıqdan sonra RuntimeError yarana biləcəyi qeyd olunur.

Operatorların qaytardığı nəticə də nəzərə alınmalıdır. Onlar gözlənilən şəkildə tək dəyər deyil, statuslar dəsti qaytarır. Sənədlərdə geniş yayılmış statuslar FINISHED və CANCELLED kimi göstərilir. CANCELLED əməliyyatın ləğv edildiyini və heç bir dəyişiklik edilmədiyini ifadə edə bilər. Buna görə skriptdə yalnız operator sətrinin icra olunmasına güvənmək əvəzinə, qaytarılan statusu da qiymətləndirmək lazımdır.

Konteksti dəyişdirmək və bunun memarlıq iş axınlarına təsiri

Sənədlərdə operatorun gördüyü konteksti dəyişdirmək üçün temp_override istifadəsi izah olunur. Bu üsulla operatoru seçilmiş və ya aktiv verilənlər əvəzinə konkret verilənlər üzərində işlətmək mümkündür. Məsələn, kontekst üzvlərinə aktiv obyekt və ya seçilmiş obyektlər daxil ola bilər. Mənbədə cari kontekstin surətini əsas götürən yanaşmaya üstünlük verilməsi tövsiyə olunur; əks halda operatorun ehtiyac duyduğu məlumatları ayrıca tapmaq lazım gələcək.

Burada vacib məqam müvəqqəti konteksti yalnız bir dəyişəni dəyişməklə qurub digər tələbləri nəzərdən qaçırmamaqdır. temp_override istifadə edərkən operatorun ehtiyac duya biləcəyi kontekst üzvlərini birlikdə nəzərdən keçirin. Cari kontekstdən başlamaq, lazım olan məlumatları sıfırdan toplamağa çalışmaqdan daha nəzarətli başlanğıc imkanı yaradır.

Memarlar, interyer dizaynerləri və vizuallaşdırma mütəxəssisləri üçün bu API əsasları təkrarlanan səhnə əməliyyatlarını kodla təsvir etməyin mümkünlüyünü göstərir. Obyekt yaratmaq, kolleksiyaya bağlamaq və yerini təyin etmək addımlarını ayrı-ayrılıqda görmək skriptin nəyi dəyişdirdiyini izləməyi asanlaşdıra bilər. Bununla belə, mənbələr bu nümunələrin konkret memarlıq iş axınını avtomatlaşdırdığını və ya məhsuldarlığı artırdığını iddia etmir.

Ofis və ya təlim mühitində skriptlərdən istifadə edərkən hədəf kolleksiyanı və aktiv obyekti yoxlayın; səhnə verilənlərini dəyişdirən sınaqları əvvəlcə faylın surətində aparın. Komandada müxtəlif Blender versiyalarından istifadə edilirsə, kodu hər quraşdırmada ayrıca yoxlayın. Sənədlərdə avadanlıq, ödəniş və ya versiya uyğunluğu ilə bağlı dəqiq şərtlər verilmədiyindən, bu məsələlərdə fərziyyə yürütməkdənsə mövcud quraşdırmada sınaq aparmaq lazımdır.

Tez-tez rast gəlinən səhvlər və növbəti addımlar

İlk səhv bpy.ops çağırışlarının kontekstdən asılı olmadığını düşünməkdir. Operatoru istifadə etməzdən əvvəl hansı verilənlərin aktiv olduğunu yoxlayın və mümkün olduqda çağırıla bilməsini poll() ilə sınayın. İkinci səhv çağırışın hər vəziyyətdə uğurla nəticələnəcəyini güman etməkdir. FINISHED və CANCELLED kimi qaytarılan statusları yoxlayın, xəta hesabatlarının RuntimeError yarada biləcəyini nəzərə alın.

Obyekt yaradarkən verilənlər bloku hazırlamaq, obyekt yaratmaq, onu kolleksiyaya bağlamaq, yerini təyin etmək və aktivləşdirmək addımlarını izləyin. Gözlənilən nəticə alınmadıqda, problemin hansı mərhələdə yarandığını belə daha asan müəyyənləşdirə bilərsiniz. Yeni operatorla işləməyə başlayarkən onun parametrlərini və kontekstlə bağlı qeydləri rəsmi API sənədlərindən yoxlayın, sonra nəticələri kiçik sınaq səhnəsində təsdiqləyin.

Növbəti mərhələdə temp_override nümunələrini araşdırıb kontekst üzvlərinin necə ötürüldüyünü sınaya bilərsiniz. Bu üsuldan istifadə edərkən operatorun hansı kontekst məlumatlarına ehtiyac duyduğunu müəyyənləşdirin. Səhnədə geniş dəyişikliklər edən skriptləri real layihə faylında sınamazdan əvvəl onun surətində işə salmaq nəticələri yoxlamaq üçün daha nəzarətli üsuldur.

Mənbə və lisenziya

Bu bələdçi Blender-in bpy.ops və bpy.types.Object API sənədlərindəki izah və nümunələr əsasında Azərbaycan dilinə uyğunlaşdırılıb. Hər iki mənbə CC BY-SA 4.0 lisenziyası ilə yayımlanıb.