Компоненты SketchUp: руководство по Component Instance и Definition

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

Руководство основано на описаниях ComponentInstance, DefinitionList и Model в SketchUp Ruby API. Сведения о версиях для разных методов различаются; для возможностей с указанной версией отдельно приводятся соответствующие ограничения.

1. Разберитесь в связи экземпляра и определения компонента

1. Рассматривайте экземпляр компонента отдельно от его определения. ComponentInstance ссылается на объект ComponentDefinition и хранит преобразование, задающее его положение. Благодаря этому одно определение могут использовать несколько размещенных в модели экземпляров. Поэтому перед редактированием экземпляра важно проверить, с каким определением он связан.

2. В Ruby API Sketchup.active_model возвращает активную модель. Метод definitions объекта Model предоставляет доступ к коллекции DefinitionList, содержащей объекты ComponentDefinition этой модели. Метод definition экземпляра напрямую возвращает определение, с которым он связан. Таким образом, просмотр определений всей модели и поиск определения конкретного экземпляра — это разные операции.

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

2. Изучите и отделите экземпляр с помощью Ruby API

В примере ниже выполняется поиск первого объекта ComponentInstance в контексте редактирования активной модели. Если экземпляр найден, код выводит имя связанного с ним определения, а затем вызовом make_unique создает для этого экземпляра отдельное определение. Код не перебирает весь список определений модели: имя определения берется через метод definition выбранного экземпляра.

model = Sketchup.active_model
instance = model.active_entities.grep(Sketchup::ComponentInstance).first

if instance
  puts instance.definition.name
  instance.make_unique
end

1. Прежде чем запускать этот пример в своей модели, убедитесь, какой компонент выбран или находится в активном контексте редактирования. Код получает первый объект ComponentInstance и не выбирает компонент по имени. Поэтому, если в модели несколько компонентов, важно проверить вывод и целевой экземпляр. Вызов make_unique не просто отображает информацию, а создает в модели отдельное определение.

2. Изменение связанного определения и изменение положения экземпляра — разные задачи. Метод definition= объекта ComponentInstance назначает другое определение; в документации указано, что при этом сохраняется текущее преобразование экземпляра. Методы transformation и transformation= позволяют получить или задать преобразование. Метод transform! применяет Geom::Transformation, а move! аналогичным образом задает преобразование, но не записывает операцию в стек отмены. Учитывайте это различие при проектировании логики редактирования и отмены в плагине.

3. Осторожно работайте с геометрией и коллекциями определений

1. Метод explode преобразует экземпляр компонента в отдельные элементы чертежа. В случае успеха он может вернуть массив элементов, а в случае неудачи — false. Если важно сохранить структуру компонента, перед использованием метода оцените, к каким последствиям он приведет в модели. В документации также перечислены геометрические операции intersect, outer_shell, split, subtract, trim и union; некоторые из них предназначены для работы с замкнутыми твердотельными объектами. Не следует считать, что они будут одинаково работать с любым компонентом.

2. Метод trim неразрушающим образом вычисляет разность между двумя замкнутыми твердотельными объектами; subtract — еще один из перечисленных методов для операции вычитания. В документации API также отмечено, что intersect недоступен в SketchUp Make. Метод manifold? объекта ComponentInstance помечен как устаревший; согласно документации, для проверки замкнутости определения следует использовать ComponentDefinition#manifold?. Эти замечания показывают, почему перед геометрическими операциями нужно проверять описание метода и тип объекта.

3. DefinitionList содержит методы для поиска определений по индексу, имени или GUID, добавления новых определений, загрузки компонентов из файлов и очистки неиспользуемых определений. Метод purge_unused удаляет неиспользуемые определения. При обходе коллекции с помощью each не удаляйте элементы из этой же коллекции: документация предупреждает, что из-за изменения количества элементов и индексов некоторые определения могут быть пропущены. Если удаление необходимо, в документации рекомендуется сначала скопировать коллекцию в массив, а затем работать с этой копией.

4. Проверьте совместимость версий и сохранность файлов

1. Метод load из DefinitionList используется для загрузки файла компонента SketchUp. Согласно документации, начиная с SketchUp 2021.0 доступен параметр allow_newer, позволяющий загружать модели, сохраненные в более новых версиях. Однако при загрузке некоторые данные могут быть пропущены; документация API предупреждает, что не следует сохранять поверх файла, загруженного из более новой модели. Поэтому сохранение исходной модели должно быть частью рабочего процесса.

2. Для поведения при повторной загрузке компонента по тому же пути к файлу также есть примечание о версиях. До SketchUp 2023.0, если в модели уже находился другой компонент, связанный с тем же путем, вызов загрузки мог вернуть существующий компонент вместо получения нового содержимого. Если файл выглядит необновленным, проверьте версию SketchUp и путь к файлу; учитывайте ограничения версий, указанные в документации, при проверке совместимости кода плагина.

Влияние на рабочие процессы в архитектуре, дизайне интерьеров и визуализации

Для архитектурных и интерьерных команд, использующих повторяющиеся элементы мебели, двери и оснащение, различие между экземпляром и определением помогает понимать, на какую часть модели повлияют изменения. Связь с общим определением удобна, когда нужно внести общие изменения; если же требуется изменить только один экземпляр, для этого в API предусмотрен метод make_unique. Такое разделение помогает командам, работающим над моделью, отслеживать, какие элементы меняются вместе.

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

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

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

• Забывать, что код находит первый объект ComponentInstance, и предполагать, будто он выбирает конкретный объект.

• Считать назначение определения и изменение преобразования положения одной и той же операцией.

• Использовать геометрические методы с условием замкнутости так, будто они будут работать с любым компонентом.

• Удалять элементы из DefinitionList во время обхода этой же коллекции.

• Игнорировать предупреждение о сохранении поверх исходного файла после загрузки модели из более новой версии.