# SketchUp Ruby API ile model otomasyonu: seçim, geometri ve bileşenler

Kaynak: https://3dsinifi.com/haber/sketchup-ruby-api-ile-model-otomasyonu-secim-geometri-ve · Kategori: İpuçları · Yayın: 17 Kasım 2026

> SketchUp Ruby API, açık modeldeki geometriye, seçime ve bileşenlere programatik erişim sağlıyor. Bu rehber, resmi belgelerdeki temel yöntemlerle model içeriğini inceleme ve düzenleme akışını ele alıyor.

## Kısaca
- Sketchup.active_model, açık model için API işlemlerinde kullanılacak Model nesnesini verir.
- Model.entities kök çizim bağlamını, Model.active_entities ise açık grup veya bileşenin içeriğini döndürür.
- Seçim üzerinde dolaşırken Selection#each kullanmak, öğeleri indeksle tek tek almaktan daha verimlidir.
- Bileşen örnekleri aynı tanımı paylaşabilir; yalnızca bir örneği farklılaştırmak için make_unique kullanılabilir.

SketchUp Ruby API, açık SketchUp modelindeki çizim öğelerini incelemek ve değiştirmek için bir başlangıç noktası sunuyor. Resmî API belgelerinde Model, Entities, Selection ve ComponentInstance sınıfları; model, geometri, seçim ve bileşenlerle çalışmanın temel yollarını açıklıyor. Bu rehber, belgelerde gösterilen yöntemlerle küçük ve denetlenebilir otomasyon adımlarını kurmaya odaklanıyor. Sınıfların temel sürüm bilgisi SketchUp 6.0 olarak verilirken bazı yöntemler daha yeni sürümlerde eklenmiş; bu nedenle kullanılan yöntemin sürüm notunu ayrıca kontrol etmek gerekiyor.

## 1. Aktif modelden başlayın

API ile çalışırken önce açık modelin nesnesini alın. `Sketchup.active_model`, kullanıcının o anda çalıştığı modeli döndürür. Model nesnesi üzerinden çizim öğelerine, malzemelere, bileşen tanımlarına ve seçime erişilebilir. Bu yaklaşım, farklı işlemlerde tekrar tekrar model aramak yerine gerekli koleksiyonların başında birer başvuru almayı sağlar.

```ruby
model = Sketchup.active_model
entities = model.entities
materials = model.materials
definitions = model.definitions
selection = model.selection
```

Burada önemli ayrım, `model.entities` ile `model.active_entities` arasındadır. İlki modelin kök düzeyindeki öğeleri içerir. Kullanıcı bir grup ya da bileşeni düzenlemek için açmışsa `active_entities`, o sırada üzerinde çalışılan bağlamın öğelerini döndürür; açık düzenleme bağlamı yoksa `entities` ile aynı sonucu verir. Dolayısıyla amaç modelin en üst düzeyini değil, kullanıcının o anda düzenlediği içeriği ele almaksa doğru koleksiyonu seçmek gerekir.

## 2. Seçimi verimli ve güvenli biçimde inceleyin

`model.selection`, o anda seçili çizim öğelerini temsil eder. Seçimdeki her öğeye erişmek için `each` ile dolaşmak, indeksleri sırayla çağırmaktan daha verimlidir. Ayrıca seçim sırasının kullanıcının öğeleri seçme sırasını yansıtacağı varsayılmamalıdır: belgeler, öğelerin sırasının belirli olmadığını açıkça belirtiyor.

```ruby
selection = Sketchup.active_model.selection

puts "Seçili öğe sayısı: #{selection.length}"
selection.each do |element|
  puts element.typename
end
```

İşlem yalnızca tek bir öğeyle ilgiliyse `first` kullanılabilir; seçim boşsa bu yöntem `nil` döndürür. `empty?`, seçim olup olmadığını; `single_object?` ise seçimin tek bir nesne olarak değerlendirilip değerlendirilemeyeceğini kontrol etmeye yarar. Bir öğenin seçili olup olmadığını sınamak için `include?` kullanılabilir.

Seçim üzerinde dolaşırken aynı koleksiyondan öğe silmek, koleksiyonun boyutunu ve indislerini değiştirebilir; bu da bazı öğelerin atlanmasına yol açabilir. Belgelerin önerdiği güvenli yaklaşım, silinecek öğeleri önce diziye kopyalamak ve sonra bu kopya üzerinde işlem yapmaktır. Ayrıca `selection[0]` gibi indeks erişimi her öğeyi incelemek için verimli bir tercih değildir. Seçimden öğe kaldırmak ya da seçim kümesini temizlemek gerekiyorsa `remove` ve `clear` yöntemleri kullanılabilir.

## 3. Geometriyi doğru çizim bağlamında oluşturun

Çizgi veya yüz gibi yeni öğeler, seçilen `Entities` koleksiyonuna eklenir. Örneğin `add_line`, iki nokta arasında bir kenar oluşturur; `add_face` yüz ekler, `add_group` ise yeni bir grup oluşturur. Kök düzeyde işlem yapmak için `model.entities`, açık grup veya bileşen bağlamında çalışmak için `model.active_entities` tercih edilmelidir. Böylece üretilen geometri, modelin amaçlanan bölümüne eklenir.

Bir işlem birden çok model değişikliğinden oluşuyorsa SketchUp’ın operasyon mekanizması değişiklikleri geri alınabilir bir işlem olarak kaydetmeye yardımcı olur. `start_operation` yeni bir operasyon başlatır, `commit_operation` bunu tamamlar; hata durumunda `abort_operation` başlatılmış operasyonu iptal edebilir. Bu yöntemleri, birbirinden bağımsız küçük değişiklikleri tek bir otomasyon akışında tutarlı biçimde yönetmek için kullanın.

```ruby
model = Sketchup.active_model
model.start_operation("Çizgi ekle")

begin
  model.active_entities.add_line([0, 0, 0], [500, 500, 0])
  model.commit_operation
rescue
  model.abort_operation
  raise
end
```

Belgeler, `abort_operation` yönteminin normalde hata yakalama bölümünde çağrıldığını belirtir. Şeffaf (transparent) operasyonlarda ise bu yöntemi kullanmama uyarısı vardır; böyle bir operasyonu iptal etmek, bağlandığı önceki operasyonu da iptal edebilir. Bu nedenle otomasyon şeffaf operasyonlarla çalışıyorsa hata yönetimi ayrıca ele alınmalıdır.

Çok sayıda geometri öğesi üretilecekse `Entities#build` de değerlendirilebilir. API belgesi bu yöntemi, performansı gözeterek toplu geometri oluşturmak için tasarlanmış bir `EntitiesBuilder` oluşturma yolu olarak tanımlar. Ancak belgelerde verilen içeriğin dışına çıkarak belirli bir hız kazancı ya da her iş için uygun olduğu sonucu çıkarılmamalıdır.

## 4. Bileşen örneklerini tanımdan ayırın

Bir `ComponentInstance`, bileşen tanımına ve model içindeki konumunu belirleyen dönüşüme başvurur. Bu yapı, aynı tanımın modelde birden çok örnek olarak kullanılabilmesini sağlar. Örneğin bir örneğin tanımını `definition` ile alabilir, `transformation` ile konum dönüşümünü inceleyebilir veya `definition=` ile başka bir tanıma bağlayabilirsiniz.

Örneklerden yalnızca birini diğerlerinden bağımsız düzenlemek gerektiğinde `make_unique` kullanılabilir: bu yöntem, söz konusu örnek için başka örneklerin kullanmadığı bir bileşen tanımı oluşturur. Düzenlemenin tüm paylaşılan örneklere mi, yoksa yalnızca seçilen örneğe mi uygulanacağı önceden belirlenmelidir. Aksi halde tasarlanan değişiklik kapsamı ile modeldeki sonuç farklı olabilir. Bileşeni ayrı çizim öğelerine dönüştüren `explode` yöntemi de belgelerde yer alır; ancak bu, bileşen örneği olarak kalmasını isteyen iş akışlarında kullanılmamalıdır.

## Mimarlık ve görselleştirme iş akışında kullanımı

Bu yöntemler, tekrarlanan model kontrollerini veya geometrik düzenlemeleri otomatikleştirmek isteyen mimar, iç mimar ve SketchUp eklenti geliştiricileri için temel oluşturur. Örneğin aktif düzenleme bağlamındaki öğeleri incelemek, seçili nesneleri topluca değerlendirmek ya da tekrar eden geometriyi bir işlem olarak oluşturmak mümkündür. Bu yaklaşımın yararı, otomasyonun modelin hangi bölümünde çalıştığının ve bileşen değişikliğinin hangi örnekleri etkilediğinin açıkça kurulmasına bağlıdır.

Belgelerde bu API yöntemleri için özel donanım gereksinimi veya lisans koşulu belirtilmiyor; dolayısıyla bu başlıklarda bir gereklilik varsayılmamalı. Uygulama öncesinde kullanılan SketchUp sürümüyle ilgili yöntem notları, özellikle daha yeni sürüm etiketi taşıyan işlevler için kontrol edilmeli. Büyük modellerde toplu geometri üretimi söz konusuysa `Entities#build` değerlendirilirken, mevcut iş akışının geri alınabilir operasyonlarla nasıl yönetileceği de planlanmalı.

## Sık yapılan hatalar

- Her durumda `model.entities` kullanmak: Açık bir grup ya da bileşen düzenleniyorsa `active_entities` doğru bağlam olabilir.
- Seçim sırasını kullanıcının tıklama sırası sanmak: API belgeleri bu sıralamanın garanti edilmediğini söylüyor.
- `each` sırasında aynı koleksiyondan öğe silmek: Önce `to_a` ile kopya almak öğelerin atlanması riskini önler.
- Bir bileşen örneğini düzenlerken tanımın paylaşılmasını göz ardı etmek: Yalnızca tek örneğin ayrışması gerekiyorsa `make_unique` düşünülmelidir.
- Şeffaf operasyonu `abort_operation` ile iptal etmek: Belgeler, bunun bağlı olduğu önceki operasyonu da iptal edebileceği konusunda uyarıyor.

## Pro ipucu
Seçimdeki öğeleri incelerken indekslerle dolaşmak yerine `selection.each` kullanın; öğe silecekseniz önce `selection.to_a` ile kopya alın.

## 3dsınıfı yorumu
Türkiye’de küçük mimarlık ve görselleştirme ofisleri için bu API’nin pratik değeri, sık tekrarlanan model kontrollerini ve düzenlemeleri bir otomasyon akışına dönüştürebilmesinde. Özellikle seçimi, aktif düzenleme bağlamını ve bileşen tanımlarını doğru yönetmek; elle yapılan adımları azaltırken modelde beklenmedik değişiklik riskini de düşürebilir.

Başlangıç maliyetini belirleyen unsur burada yeni donanımdan çok, Ruby API bilgisi ve mevcut eklenti iş akışına uyum olacaktır; kaynaklar belirli donanım veya lisans koşulu vermiyor. Ofislerin önce küçük bir modelde operasyonların geri alınmasını, bileşen örneklerinin paylaşımını ve kullandıkları SketchUp sürümündeki yöntem uygunluğunu sınaması yerinde olur.

## Kaynaklar
- [ruby.sketchup.com](https://ruby.sketchup.com/Sketchup/Model.html) (özet)
- [ruby.sketchup.com](https://ruby.sketchup.com/Sketchup/Entities.html) (özet)
- [ruby.sketchup.com](https://ruby.sketchup.com/Sketchup/ComponentInstance.html) (özet)

_Yapay zekâ ile yazıldı, kaynaklarla doğrulandı. © 3dsınıfı_
