V-Ray App SDK rehberi: Python ile sahne yükleme ve render alma

V-Ray App SDK, V-Ray render motorunu bir uygulamaya entegre etmek isteyen geliştiricilere yönelik bir API sunuyor. Resmî belgeler, render işleminin ana uygulamanın süreci içinde yürütülebileceğini veya dağıtık render kullanılarak bu sürecin dışında gerçekleştirilebileceğini belirtiyor. C++, C#, Python ve Node.js bağlamaları bulunan SDK; sahne yükleme, render modlarını seçme ve işlem durumunu izleme adımlarını kapsıyor. Aşağıdaki rehber, belgelerdeki Python örneğini temel alıyor; kaynak belirli bir SDK sürümü belirtmediği için adımlar sürüm numarasına bağlanmıyor.

1. SDK dosyalarının ve Python modülünün yolunu ayarlayın

V-Ray App SDK’nın gerekli kütüphaneleri bulması için belgelerde öncelikli olarak VRAY_SDK ortam değişkeni gösteriliyor. Bu değişken ayarlandığında SDK bağlaması, V-Ray kütüphanesini ve bağımlılıklarını VRAY_SDK/bin içinde arıyor. Ürünün klasör yapısında /bin dizini bulunmuyorsa VRAY_APPSDK_BIN ile ikili dosyaların bulunduğu klasör doğrudan belirtilebiliyor. Ortam değişkenlerinin kullanılamadığı durumlarda arama yolu çalışma anında da tanımlanabiliyor.

Python bağlamasının çalışması için SDK içindeki python klasörünün Python modül arama yollarına eklenmesi gerekiyor. Belgeler, bunun PYTHONPATH üzerinden yapılabileceğini belirtiyor. Chaos’un setenv betiği gerekli ortam değişkenlerini ayarlayabiliyor: Windows’ta setenv.bat, Linux ve MacOS’ta source setenv.sh kullanılıyor. Python’da kütüphane dizinini çalışma anında belirtmek gerektiğinde vray.setSDKLibraryPath(bin_folder) yöntemi mevcut.

Bu iki yol gereksinimini ayrı ayrı kontrol edin: Python’ın vray modülünü bulması, V-Ray ikili dosyalarının bulunmasıyla aynı konu değil. VRAY_SDK kullanılıyorsa belgelerde belirtilen /bin konumu incelenmeli; klasör yapısı farklıysa VRAY_APPSDK_BIN veya çalışma anında arama yolu seçeneği değerlendirilmelidir.

2. Sahneyi yükleyip renderı başlatın

Temel akışta önce yapılandırılabilir bir VRayRenderer nesnesi oluşturuluyor. Sahne, V-Ray’in yerel sahne biçimi olan .vrscene dosyasından yüklenebiliyor ya da uygulamadaki sahne tanımı V-Ray eklentilerine çevrilerek bellekte hazırlanabiliyor. Ardından start() çağrısıyla render başlatılıyor; görüntü alınıp dosyaya kaydediliyor ve kaynaklar kapatılıyor.

Aşağıdaki Python örneği, belgelerdeki temel akışı gösteriyor:

import vray

with vray.VRayRenderer() as renderer:
    renderer.load('./intro.vrscene')
    renderer.start()
    renderer.waitForRenderEnd(6000)
    image = renderer.getImage()
    image.save('intro.png')

start() beklemeden dönen bir çağrı; V-Ray motoru render işlemini ayrı bir iş parçacığında yürütüyor. Örnekteki waitForRenderEnd(6000), renderın bitmesini bekleyen çağrıdır. Buradaki 6000, dokümantasyon örneğinde geçen bir değerdir; her sahne için önerilen ya da garantili bir render süresi anlamına gelmez. getImage() o andaki görüntü verisini alır, save() ise örnekte bu görüntüyü PNG dosyasına yazar. Belgelerdeki genel iş akışı, işlem tamamlandığında renderer kaynaklarının kapatılmasını da içeriyor.

3. Önizleme ve son çıktı için modu seçin

V-Ray App SDK, Interactive ve Production olmak üzere iki render modu sunuyor. Interactive, sahne ayarlarını denerken hızlı önizleme ve kalitenin aşamalı biçimde artmasını sağlıyor. Production ise yapılandırması tamamlanmış sahneden nihai görüntü almak için uygun. Belgelerde VRayRenderer sınıfının varsayılan modu Interactive (CPU) olarak belirtiliyor.

Her iki mod da CPU veya GPU ile çalışabiliyor. Belgeler, GPU tarafında NVIDIA sistemleri için CUDA ve OptiX; Apple sistemleri için Metal ve MetalRT seçeneklerini listeliyor. Hangi seçeneğin kullanılacağı mevcut donanım ve çalışma ortamına göre belirlenmeli; kaynak her sahne için geçerli tek bir tercih önermiyor.

Render modu, VRayRenderer nesnesinin renderMode özelliği üzerinden değiştirilebiliyor. Belgeler, farklı renderlar arasında geçiş yaparken sahneyi yeniden yüklemenin veya renderer’ı yeniden oluşturmanın gerekmediğini belirtiyor. Böylece aynı sahne önce Interactive modda kontrol edilip ardından Production moduna alınabiliyor.

4. Render ilerlemesini ve sorunları takip edin

Uygulama, renderer’ın durum değişikliği olayını dinleyerek renderın başlaması, tamamlanması veya hata nedeniyle durması gibi gelişmeleri izleyebilir. Nihai görüntü IDLE_DONE durumunda hazır olur; render devam ederken o ana kadarki görüntü de alınabilir.

Asenkron start() çağrısında PREPARING durumu önem taşıyor. Belgeler, bu aşamadan çıkılmadan sahne veya renderer üzerinde değişiklik yapılmaması gerektiğini; bu tür girişimlerin reddedileceğini bildiriyor. V-Ray’in sahne yükleme ve render sırasında oluşturduğu mesajlar da log olayıyla yakalanabiliyor. Bu olay, mesaj metninin yanı sıra bilgi, uyarı, hata veya hata ayıklama seviyesini de iletebiliyor.

Olay geri çağrıları render iş parçacığından ayrı bir iş parçacığında çalışıyor. Bu düzen, callback işlemlerinin render sürecine ek yük bindirmeden yürütülmesini amaçlıyor; ancak yavaş callback’ler diğer callback’lerin çalışmasını geciktirebilir. Bu nedenle olay işleyicilerini kısa tutmak ve ağır işleri doğrudan callback içinde yürütmemek uygun olur.

Mimarlık ve görselleştirme iş akışına etkisi

App SDK, V-Ray renderını başka bir yazılıma entegre etmek veya render sürecini özel bir uygulamadan yönetmek isteyen geliştiriciler ve teknik ekipler için anlam taşıyor. Mimarlık, iç mekân tasarımı ve archviz alanlarında .vrscene yükleme ve render alma akışı, daha geniş bir iş akışına dahil edilebilir. Ancak belgeler hazır bir mimari yazılım entegrasyonu ya da kullanıcı arayüzü sunduğunu söylemiyor; SDK’nın kullanımı yazılım geliştirme çalışması gerektiriyor.

Uygulamaya geçmeden önce Python modül yolunun, V-Ray kütüphane dizininin ve seçilen CPU/GPU modunun çalışma ortamıyla uyumlu olduğu doğrulanmalı. Kaynaklarda fiyat, lisans koşulları veya sürümler arası uyumluluk bilgisi yer almıyor; bu başlıklar ayrıca kontrol edilmeli. Üretim sürecine geçmeden önce kullanılacak render modunun mevcut donanımla çalıştığını test etmek de önemli.

Sık yapılan hatalar

• Klasör yapısını kontrol etmeden yalnızca VRAY_SDK ayarlamak; gerektiğinde VRAY_APPSDK_BIN veya çalışma anındaki arama yolu seçeneklerini değerlendirmemek.

• Python modül yoluyla V-Ray ikili dosyalarının arama yolunu aynı ayar sanmak.

• start() sonrasında PREPARING aşamasında sahne veya renderer ayarlarını değiştirmeye çalışmak.

• Örnekteki 6000 değerini her render için kesin bekleme süresi olarak kabul etmek.

• Render sırasında ara görüntü alınabildiğini, tamamlanmış görüntünün ise IDLE_DONE durumunda hazır olduğunu gözden kaçırmak.