Componentes de SketchUp: guía de uso de ComponentInstance y Definition

La documentación de Ruby API de SketchUp explica cómo se representan las instancias de componentes en un modelo y cómo gestionar las definiciones a las que están vinculadas. ComponentInstance representa una instancia de componente colocada en el modelo, mientras que ComponentDefinition representa la definición en la que se basa. La posición de la instancia dentro del modelo también se determina mediante una transformación. Entender esta distinción permite diferenciar entre aplicar cambios compartidos a objetos reutilizados y modificar solo una instancia.

Esta guía se basa en los métodos descritos en la documentación de SketchUp Ruby API para ComponentInstance, DefinitionList y Model. Las notas sobre versiones varían según el método; cuando se especifica una versión concreta, se indica el límite correspondiente.

1. Comprender la relación entre una instancia y su definición

1. Trate la instancia de componente del modelo como algo distinto de su definición. Un ComponentInstance hace referencia a un objeto ComponentDefinition y almacena su posición mediante una transformación. Esta estructura permite que varias instancias colocadas utilicen una misma definición. Por eso, antes de editar una instancia, es importante comprobar a qué definición está vinculada.

2. En Ruby API, Sketchup.active_model devuelve el modelo activo. El método definitions del objeto Model permite acceder a la colección DefinitionList, que contiene los objetos ComponentDefinition del modelo. Por su parte, el método definition de una instancia devuelve directamente la definición a la que está vinculada. Así, examinar todas las definiciones del modelo y encontrar la definición de una instancia concreta son operaciones distintas.

3. Si no quiere que cambien las demás instancias que utilizan la misma definición, considere usar el método make_unique antes de editar una instancia individual. Según la documentación, este método crea una nueva definición para esa instancia, que no utilizan las demás. Esta distinción puede ser útil cuando se quiere modificar solo uno de varios elementos reutilizados, como muebles, puertas o accesorios.

2. Inspeccionar y separar una instancia con Ruby API

El siguiente ejemplo busca el primer objeto ComponentInstance que haya en el contexto de edición del modelo activo. Si encuentra una instancia, imprime el nombre de la definición vinculada y, a continuación, llama a make_unique para crear una definición independiente para esa instancia. El código no recorre toda la lista de definiciones del modelo: obtiene el nombre de la definición mediante el método definition de la instancia seleccionada.

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

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

1. Antes de ejecutar este ejemplo en su modelo, compruebe qué componente se ha seleccionado o cuál se encuentra en el contexto de edición activo. El código obtiene el primer objeto ComponentInstance; no selecciona un componente específico por nombre. Por eso, si hay varios componentes, es importante verificar el resultado y la instancia de destino. Además, make_unique no se limita a mostrar información: crea una definición independiente en el modelo.

2. Cambiar la definición vinculada y cambiar la posición de la instancia son necesidades distintas. El método definition= de ComponentInstance asigna otra definición y, según la documentación, conserva la transformación actual de la instancia. transformation y transformation= sirven para consultar o establecer la transformación. transform! aplica una Geom::Transformation; move! establece la transformación de forma similar, pero no registra la operación en la pila de deshacer. Tenga en cuenta esta diferencia al diseñar los flujos de edición y deshacer del complemento.

3. Trabajar con cuidado con la geometría y las colecciones de definiciones

1. El método explode convierte una instancia de componente en elementos de dibujo independientes. Puede devolver un array de elementos si la operación tiene éxito o false si falla. Si es importante conservar la estructura del componente, evalúe el resultado que esta operación tendrá en el modelo antes de utilizarla. La documentación también enumera operaciones geométricas como intersect, outer_shell, split, subtract, trim y union; algunas están definidas para trabajar con sólidos manifold. Por tanto, no debe suponerse que ofrecerán el mismo resultado con cualquier componente.

2. trim calcula de forma no destructiva la diferencia entre dos sólidos manifold; subtract es el otro método enumerado para realizar una operación de diferencia. La documentación de API también señala que intersect no está disponible en SketchUp Make. El método manifold? de ComponentInstance aparece marcado como obsoleto; según la documentación, para comprobar si una definición es manifold se debe utilizar ComponentDefinition#manifold?. Estas notas muestran que, antes de realizar operaciones geométricas, conviene revisar la descripción del método y el tipo de objeto.

3. DefinitionList incluye métodos para buscar definiciones por índice, nombre o GUID, añadir una definición, cargar un componente desde un archivo y limpiar las definiciones que no se utilizan. purge_unused elimina las definiciones sin uso. Evite eliminar elementos de la colección mientras la recorre con each: la documentación advierte que, al cambiar el número de elementos y los índices, es posible que se omitan algunas definiciones. Si necesita eliminarlas, el enfoque recomendado en la documentación es copiar primero la colección en un array y trabajar sobre esa copia.

4. Comprobar la compatibilidad de versiones y proteger los archivos

1. El método load de DefinitionList se utiliza para cargar un archivo de componente de SketchUp. Según la documentación, desde SketchUp 2021.0 existe la opción allow_newer, que permite cargar modelos guardados con una versión más reciente. Sin embargo, durante la carga puede omitirse cierta información; la documentación de API advierte que no se debe sobrescribir el archivo cargado desde un modelo más reciente. Por ello, conservar el modelo de origen debe formar parte del flujo de trabajo.

2. También hay una nota sobre el comportamiento al volver a cargar un componente desde la misma ruta de archivo. Antes de SketchUp 2023.0, si ya había en el modelo un componente distinto asociado a esa misma ruta, la llamada de carga podía devolver el componente existente en lugar de incorporar el contenido nuevo. Si el archivo parece no haberse actualizado, compruebe la versión de SketchUp y la ruta del archivo; adapte la compatibilidad del código del complemento a los límites de versión indicados en la documentación de origen.

Impacto en los flujos de trabajo de arquitectura, diseño de interiores y visualización

Para los equipos de arquitectura y diseño de interiores que trabajan con muebles, puertas y accesorios repetidos, distinguir entre instancia y definición facilita comprender el alcance de los cambios en el modelo. La relación entre componentes resulta útil cuando se necesitan cambios comunes a través de una definición compartida; si solo se quiere modificar una instancia, make_unique es el método que ofrece la API. Esta distinción puede ayudar a los equipos que trabajan en el modelo a hacer un seguimiento de los elementos que cambian conjuntamente.

Para los equipos de visualización y quienes desarrollan complementos, también es importante verificar que se haya seleccionado la instancia y la definición correctas. Las fuentes no especifican requisitos de hardware, mediciones de rendimiento ni condiciones de licencia. Los aspectos concretos que se deben comprobar son que la versión de SketchUp utilizada admita el método correspondiente y que se conserve el archivo de origen al cargar archivos de versiones más recientes.

Errores frecuentes

• Editar la definición compartida de una instancia sin tener en cuenta que también pueden cambiar las demás instancias.

• Olvidar que el código encuentra el primer objeto ComponentInstance y asumir que selecciona un objeto específico.

• Confundir la asignación de una definición con el cambio de la transformación de posición.

• Usar métodos geométricos que requieren condiciones manifold como si fueran válidos para todos los componentes.

• Eliminar elementos de DefinitionList mientras se recorre la colección.

• Ignorar la advertencia de no sobrescribir el archivo de origen después de cargar un modelo más reciente.