Automatización de modelos con SketchUp Ruby API: guía de componentes y geometría

SketchUp Ruby API utiliza clases de modelo, geometría y componentes para leer y modificar el contenido del modelo abierto. Esta guía, basada en la documentación oficial de SketchUp Ruby API, aborda especialmente cómo acceder a los datos del modelo, gestionar instancias de componentes y operar sobre colecciones de geometría. Aunque la documentación indica SketchUp 6.0 como versión de referencia para las clases básicas, algunos métodos tienen requisitos de versión más recientes; por ello, conviene revisar por separado las notas de versión del método que se vaya a utilizar.

1. Accede al contenido del modelo desde el contexto correcto

El punto de partida de un flujo de automatización es el modelo abierto, obtenido con Sketchup.active_model. A través del objeto del modelo se puede acceder a secciones como la geometría raíz, las definiciones de componentes, los materiales y la colección de selección. Así queda claro en qué parte del modelo se encuentran los datos que se van a procesar.

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

model.entities incluye los elementos de dibujo del nivel raíz del modelo. Si el usuario está editando un grupo o componente, model.active_entities devuelve los elementos de ese contexto de edición. Si no hay ningún grupo o componente abierto, esta colección coincide con entities. Tener clara esta diferencia ayuda a evitar que un comando modifique geometría del contexto equivocado.

Por ejemplo, en una herramienta que vaya a operar sobre los elementos seleccionados, la colección de selección puede ser el punto de partida. En cambio, para una herramienta que deba trabajar en el contexto de edición actual, puede convenir empezar por la colección de elementos activos. Intentar modificar directamente todo el contenido del modelo sin delimitar el alcance de la operación puede provocar cambios no deseados.

2. Distingue entre la definición y la instancia de un componente

En SketchUp, la definición de un componente y su instancia no son lo mismo. ComponentDefinition describe los elementos que contiene el componente; ComponentInstance representa una colocación de esa definición en el modelo y su transformación. Es posible crear varias instancias a partir de una misma definición. Los cambios realizados en la definición se reflejan en las instancias que la utilizan.

Puedes averiguar a qué definición está vinculada una instancia mediante el método definition. También es posible asignarle otra definición; la documentación indica que, al hacerlo, se conserva la transformación de posicionamiento de la instancia en el modelo.

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

Este ejemplo presupone que el primer elemento es una instancia de componente. En una extensión real, conviene comprobar el tipo de cada elemento de la colección y contemplar la posibilidad de que el resultado esté vacío. A través de la definición de un componente, puedes contar su uso con los métodos count_instances y count_used_instances: el primero cuenta las distintas instancias y el segundo, el total de instancias del modelo que utilizan esa definición.

Cuando se necesita editar una sola instancia de forma independiente, se puede usar make_unique. Este método crea una definición para esa instancia que no comparten las demás. Por eso, antes de hacer cambios en bloque, hay que decidir si se aplicarán a la definición compartida o solo a la instancia seleccionada.

3. Procesa las colecciones de geometría de forma eficiente

Entities es la colección de elementos que contiene el modelo o una definición de componente. La documentación indica que, en general, es más eficiente recorrer los elementos con el método each que acceder a ellos mediante índices. Este enfoque también facilita la lectura del código de los scripts que recorren una colección.

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

Si necesitas acceder a un índice concreto, puedes usar entities[index]. Sin embargo, los índices válidos van de cero a la longitud de la colección menos uno, y el método puede devolver nil si no encuentra el elemento. Por tanto, en operaciones que dependan de un índice elegido por el usuario, es importante comprobar ese resultado.

Hay métodos como add_line para crear una línea, add_circle para un círculo y add_face para una cara. Para generar muchos elementos de geometría teniendo en cuenta el rendimiento, el método Entities#build crea un EntitiesBuilder. La documentación describe este método como una herramienta para la generación de geometría en bloque, pero no especifica un aumento de velocidad concreto ni requisitos de hardware. Por eso, el beneficio en un proyecto real debe medirse con la geometría y el flujo de trabajo de la extensión que se utilicen.

Si la operación debe registrarse como un paso reversible, se pueden utilizar los métodos del modelo start_operation y commit_operation. En caso de error, la documentación oficial indica que se puede cancelar la operación iniciada con abort_operation. También advierte que una operación transparente no debe cancelarse.

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. Uso en flujos de trabajo de arquitectura y visualización

En proyectos de modelado arquitectónico e interiorismo, esta API puede utilizarse para organizar elementos repetidos como componentes, inspeccionar el contenido del modelo y automatizar operaciones recurrentes de geometría mediante scripts. Por ejemplo, gestionar distintas colocaciones de una misma definición de mobiliario requiere distinguir correctamente entre definición e instancia. Si se necesita independizar un elemento, puede considerarse la opción make_unique; si se busca una actualización compartida, conviene trabajar con la definición común.

Al desarrollar un script de automatización para una oficina, primero hay que delimitar el alcance: ¿se procesará la geometría raíz del modelo, el contenido de un grupo abierto o los elementos seleccionados? Después, hay que tener en cuenta la relación entre la definición y la instancia del componente. Para comprobar la compatibilidad de la extensión con la versión de SketchUp, se deben revisar los datos de versión de los métodos utilizados en la documentación oficial. Como la documentación no especifica requisitos de hardware, no es posible recomendar un equipo concreto; para operaciones de geometría intensivas, es más conveniente probar el rendimiento con el modelo de destino.

Errores frecuentes

• Usar las colecciones entities y active_entities como si abarcaran el mismo contexto.

• No tener en cuenta que los cambios en una definición compartida se reflejan en las instancias del componente.

• Pasar por alto que el elemento obtenido mediante un índice puede no existir y que el resultado puede ser nil.

• No gestionar el cierre adecuado de la operación: commit_operation en el flujo correcto y el paso correspondiente en caso de error.

Esta guía se basa en las clases básicas de modelo, componentes y geometría documentadas en SketchUp Ruby API. Los fragmentos consultados de la documentación no explican rutas de menús de la interfaz, condiciones de licencia ni requisitos de hardware, por lo que no se han hecho suposiciones al respecto.