Коротко
- Sketchup.active_model возвращает объект Model, используемый для работы с открытой моделью через API.
- Model.entities возвращает корневой контекст моделирования, а Model.active_entities — содержимое открытой группы или компонента.
- При переборе выделения эффективнее использовать Selection#each, а не получать элементы по одному через индексы.
- Экземпляры компонентов могут использовать одно определение; чтобы изменить только один экземпляр, можно вызвать make_unique.
SketchUp Ruby API позволяет изучать и изменять элементы открытой модели SketchUp. В официальной документации базовые способы работы с моделью, геометрией, выделением и компонентами описаны для классов Model, Entities, Selection и ComponentInstance. Это руководство посвящено созданию небольших, контролируемых сценариев автоматизации на основе методов, представленных в документации. Для базовых версий классов указана SketchUp 6.0, однако некоторые методы появились в более новых версиях, поэтому следует отдельно проверять примечания о версиях для используемых методов.
1. Начните с активной модели
Для работы через API сначала получите объект открытой модели. Sketchup.active_model возвращает модель, с которой пользователь работает в данный момент. Через объект Model можно обращаться к элементам чертежа, материалам, определениям компонентов и выделению. Такой подход позволяет заранее получить ссылки на нужные коллекции, а не искать модель заново для каждой операции.
model = Sketchup.active_model
entities = model.entities
materials = model.materials
definitions = model.definitions
selection = model.selectionВажно различать model.entities и model.active_entities. Первый объект содержит элементы корневого уровня модели. Если пользователь открыл группу или компонент для редактирования, active_entities возвращает элементы текущего контекста; если контекст редактирования не открыт, результат будет таким же, как у entities. Поэтому, если нужно работать не с верхним уровнем модели, а с содержимым, которое пользователь редактирует сейчас, важно выбрать правильную коллекцию.
2. Изучайте выделение эффективно и безопасно
model.selection представляет выбранные в данный момент элементы чертежа. Для доступа к каждому элементу выделения эффективнее использовать each, чем последовательно обращаться к индексам. Также не следует считать, что порядок элементов в выделении соответствует порядку, в котором пользователь их выбирал: документация прямо указывает, что порядок элементов не определён.
selection = Sketchup.active_model.selection
puts "Число выбранных элементов: #{selection.length}"
selection.each do |element|
puts element.typename
endЕсли операция относится только к одному элементу, можно использовать first; если выделение пустое, метод вернёт nil. Метод empty? проверяет, есть ли выделение, а single_object? позволяет определить, можно ли считать выделение одним объектом. Чтобы проверить, выбран ли конкретный элемент, можно использовать include?.
Удаление элементов из той же коллекции во время перебора выделения может изменить её размер и индексы, из-за чего некоторые элементы будут пропущены. В документации рекомендуется сначала скопировать элементы, которые нужно удалить, в массив, а затем работать с этой копией. Кроме того, доступ по индексу, например selection[0], неэффективен для проверки каждого элемента. Чтобы убрать элементы из выделения или очистить его целиком, можно использовать методы remove и clear.
3. Создавайте геометрию в правильном контексте моделирования
Новые элементы, например линии и грани, добавляются в выбранную коллекцию Entities. Так, add_line создаёт ребро между двумя точками, add_face добавляет грань, а add_group создаёт новую группу. Для работы на корневом уровне следует использовать model.entities, а для работы в контексте открытой группы или компонента — model.active_entities. Так созданная геометрия окажется в нужной части модели.
Если операция состоит из нескольких изменений модели, механизм операций SketchUp позволяет записать их как действие, которое можно отменить. start_operation начинает новую операцию, commit_operation завершает её, а в случае ошибки abort_operation может отменить начатую операцию. Используйте эти методы, чтобы последовательно управлять несколькими изменениями в одном сценарии автоматизации.
model = Sketchup.active_model
model.start_operation("Добавить линию")
begin
model.active_entities.add_line([0, 0, 0], [500, 500, 0])
model.commit_operation
rescue
model.abort_operation
raise
endВ документации отмечено, что abort_operation обычно вызывается в блоке обработки ошибок. Для прозрачных (transparent) операций этот метод использовать не рекомендуется: отмена такой операции может отменить и предыдущую операцию, к которой она привязана. Поэтому, если автоматизация работает с прозрачными операциями, обработку ошибок нужно продумать отдельно.
Если требуется создать много геометрических элементов, можно также рассмотреть Entities#build. В API-документации этот метод описан как способ создать EntitiesBuilder, предназначенный для массового создания геометрии с учётом производительности. Однако не следует делать вывод о конкретном приросте скорости или о том, что этот метод подходит для любой задачи, если таких сведений нет в документации.
4. Отделяйте экземпляры компонентов от их определений
ComponentInstance ссылается на определение компонента и трансформацию, которая задаёт его положение в модели. Благодаря этому одно определение можно использовать для нескольких экземпляров модели. Например, определение экземпляра можно получить через definition, изучить его трансформацию положения через transformation или связать его с другим определением с помощью definition=.
Если нужно редактировать один экземпляр отдельно от остальных, можно использовать make_unique: метод создаёт для этого экземпляра определение компонента, которое не используется другими экземплярами. Заранее определите, должно ли изменение затронуть все экземпляры с общим определением или только выбранный экземпляр. Иначе область изменения может не совпасть с ожидаемым результатом в модели. В документации также описан метод explode, который преобразует компонент в отдельные элементы чертежа; его не следует применять в рабочих процессах, где экземпляр должен остаться компонентом.
Применение в архитектуре и визуализации
Эти методы дают базовые возможности архитекторам, дизайнерам интерьеров и разработчикам расширений SketchUp, которые хотят автоматизировать повторяющиеся проверки модели или изменения геометрии. Например, можно проверять элементы в активном контексте редактирования, анализировать выбранные объекты группами или создавать повторяющуюся геометрию в рамках одной операции. Польза такого подхода зависит от того, насколько чётко задано, в какой части модели работает автоматизация и какие экземпляры затронет изменение компонента.
В документации не указаны особые требования к оборудованию или условия лицензирования для этих методов API, поэтому не следует предполагать наличие таких требований. Перед внедрением нужно проверить примечания к методам для используемой версии SketchUp, особенно если функция помечена как появившаяся в более новой версии. Если предстоит создавать геометрию большими объёмами, при оценке Entities#build также следует спланировать управление рабочим процессом с помощью отменяемых операций.
Типичные ошибки
Всегда использовать
model.entities: при редактировании открытой группы или компонента правильным контекстом может бытьactive_entities.Считать, что порядок выделения соответствует порядку кликов пользователя: документация API не гарантирует такой порядок.
Удалять элементы из той же коллекции во время
each: предварительное копирование с помощьюto_aпомогает избежать пропуска элементов.Не учитывать общее определение при редактировании экземпляра компонента: если нужно изменить только один экземпляр, стоит рассмотреть
make_unique.Отменять прозрачную операцию с помощью
abort_operation: документация предупреждает, что это может также отменить связанную с ней предыдущую операцию.
Источники
Источников: 3Тексты источников не перепечатываются; короткие цитаты отмечены, остальное — наш пересказ и комментарий.
Для небольших архитектурных и визуализационных бюро в Турции практическая ценность этого API заключается в возможности превратить повторяющиеся проверки и редактирование моделей в автоматизированный процесс. Правильная работа с выделением, активным контекстом редактирования и определениями компонентов может сократить число ручных действий и снизить риск непредвиденных изменений модели.
На начальные затраты повлияют скорее знание Ruby API и совместимость с текущим рабочим процессом расширений, а не новое оборудование; в источниках не указаны конкретные требования к оборудованию или лицензированию. Бюро стоит сначала проверить на небольшой модели отмену операций, совместное использование определений экземплярами компонентов и совместимость методов с используемой версией SketchUp.
Частые вопросы
Как получить доступ к активной модели в SketchUp Ruby API?
`Sketchup.active_model` предоставляет доступ к открытой модели. Через объект Model можно обращаться к коллекциям геометрии, выделения, материалов и определений компонентов.
Чем отличаются entities и active_entities в SketchUp Ruby API?
`entities` возвращает элементы корневого уровня модели. `active_entities` возвращает элементы открытого контекста редактирования группы или компонента; если такого контекста нет, результат будет таким же, как у `entities`.
Как отделить экземпляр компонента SketchUp от остальных?
`ComponentInstance#make_unique` создаёт для этого экземпляра определение компонента, которое не используется другими экземплярами. Так изменение можно применить только к отделённому экземпляру.



