Автоматизация моделей в SketchUp Ruby API: компоненты и геометрия

SketchUp Ruby API использует классы модели, геометрии и компонентов, чтобы читать и изменять содержимое открытой модели. В этом руководстве, основанном на официальной документации SketchUp Ruby API, рассматриваются доступ к данным модели, управление экземплярами компонентов и работа с коллекциями геометрии. В документации для основных классов указана версия SketchUp 6.0, однако для некоторых методов действуют более поздние требования к версии. Поэтому следует отдельно проверять примечания к версии для каждого используемого метода.

1. Обращайтесь к содержимому модели в правильном контексте

Отправная точка автоматизации — объект открытой модели, полученный с помощью Sketchup.active_model. Через объект модели можно обращаться к корневой геометрии, определениям компонентов, материалам и коллекции выделения. Так становится ясно, в какой части модели находятся данные, с которыми предстоит работать.

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

model.entities содержит элементы чертежа на корневом уровне модели. Если пользователь редактирует группу или компонент, model.active_entities возвращает элементы этого текущего контекста редактирования. Если активной группы или компонента нет, эта коллекция совпадает с entities. Это различие помогает избежать изменений геометрии не в том контексте.

Например, инструмент, работающий с выделенными элементами, может начинать с коллекции выделения, а инструмент для текущего контекста редактирования — с коллекции активных элементов. Попытка изменить всё содержимое модели, не определив область действия, может привести к нежелательным изменениям.

2. Различайте определение компонента и его экземпляр

В SketchUp определение компонента и его экземпляр — не одно и то же. ComponentDefinition описывает содержащиеся в компоненте элементы, а ComponentInstance представляет размещение этого определения в модели и его трансформацию. На основе одного определения можно создать несколько экземпляров. Изменения определения отражаются на использующих его экземплярах.

Метод definition позволяет узнать, с каким определением связан экземпляр. Можно также переключить его на другое определение; документация указывает, что при этом трансформация позиционирования экземпляра в модели сохраняется.

instance = model.entities[0]
definition = instance.definition
puts definition.name

В этом примере предполагается, что первый элемент — экземпляр компонента. В реальном расширении нужно проверять тип каждого элемента коллекции и учитывать возможность пустого результата. Использование определения компонента можно подсчитать методами count_instances и count_used_instances: первый считает уникальные экземпляры, второй — общее количество экземпляров, использующих это определение в модели.

Если требуется независимо редактировать один экземпляр, можно использовать make_unique. Этот метод создаёт для выбранного экземпляра определение, которое не используется другими экземплярами. Поэтому перед массовым редактированием следует решить, нужно ли применять изменения к общему определению или только к выбранному экземпляру.

3. Эффективно обрабатывайте коллекции геометрии

Entities — коллекция элементов модели или определения компонента. В документации указано, что для последовательного обхода элементов в целом эффективнее использовать метод each, а не обращаться к ним по индексу. Такой подход также делает скрипты, сканирующие коллекцию, более понятными.

model.entities.each do |entity|
  puts entity.typename
end

Если нужен доступ по конкретному индексу, можно использовать entities[index]. Допустимый индекс находится в диапазоне от нуля до длины коллекции минус один; если элемент не найден, метод может вернуть nil. Поэтому при операциях, зависящих от индекса, заданного пользователем, важно проверять результат.

Для создания отдельных элементов геометрии предусмотрены методы вроде add_line для линии, add_circle для окружности и add_face для грани. Для создания большого количества элементов геометрии с учётом производительности метод Entities#build создаёт EntitiesBuilder. В документации этот метод описан как средство для пакетного создания геометрии, однако конкретное увеличение скорости или требования к оборудованию не указаны. Поэтому пользу следует оценивать на реальной геометрии и в рамках рабочего процесса расширения.

Если операцию нужно сохранить как действие, которое можно отменить, можно использовать методы модели start_operation и commit_operation. В случае ошибки официальная документация рекомендует отменить начатую операцию с помощью abort_operation. Также в документации содержится предупреждение: прозрачную операцию отменять не следует.

model.start_operation("Model düzenlemesi")
begin
  # Geometri işlemlerini burada yürütün.
  model.commit_operation
rescue
  model.abort_operation
  raise
end

4. Применение в архитектурном моделировании и визуализации

В архитектурных и интерьерных проектах этот API можно использовать для организации повторяющихся элементов в виде компонентов, проверки содержимого модели и автоматизации повторяющихся операций с геометрией. Например, управление разными размещениями одного и того же определения мебели требует правильного понимания различия между определением и экземпляром. Если элемент нужно сделать независимым, следует рассмотреть вариант make_unique; если требуется общее обновление — работу с общим определением.

При разработке скрипта для автоматизации работы бюро сначала нужно определить область действия: корневая геометрия модели, содержимое открытой группы или выделенные элементы. Затем следует учитывать связь между определением компонента и его экземплярами. Чтобы проверить совместимость расширения с версией SketchUp, изучите сведения о версиях для используемых методов в официальной документации. Поскольку документация не указывает конкретных требований к оборудованию, нельзя дать рекомендацию по определённой конфигурации; при интенсивной обработке геометрии лучше проверить производительность на целевой модели.

Частые ошибки

• Считать коллекции entities и active_entities одинаковыми по области действия.

• Не учитывать, что изменения общего определения отражаются на экземплярах компонента.

• Забывать, что элемент по заданному индексу может отсутствовать, и результатом может быть nil.

• После запуска операции не вызывать commit_operation при успешном завершении и не выполнять соответствующий шаг завершения при ошибке.

Руководство основано на основных классах модели, компонентов и геометрии SketchUp Ruby API, описанных в документации. Поскольку в рассмотренных фрагментах документации не объясняются пути к пунктам меню интерфейса, условия лицензирования или требования к оборудованию, мы не делали предположений на этот счёт.