Automating SketchUp Models with the Ruby API: Components and Geometry

The SketchUp Ruby API uses model, geometry, and component classes to read and modify the contents of the open model. Based on SketchUp’s official Ruby API documentation, this guide focuses on accessing model data, managing component instances, and working with geometry collections. The documentation lists SketchUp 6.0 as the version for the core classes, though some methods have requirements for newer versions. Check the version notes for each method you plan to use.

1. Access model contents in the right context

The starting point for an automation workflow is the open model object returned by Sketchup.active_model. Through the model object, you can access sections such as root geometry, component definitions, materials, and the selection collection. This makes it easier to identify where the data to be processed is located within the model.

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

model.entities contains the drawing elements at the model’s root level. If the user is editing a group or component, model.active_entities returns the elements in that active editing context. If no group or component is open, this collection is the same as entities. This distinction helps prevent commands from modifying geometry in the wrong context.

For example, a tool that processes selected elements can start with the selection collection, while a tool that works within the current editing context can start with the active entities collection. Modifying the entire model directly without first establishing the scope can lead to unintended changes.

2. Distinguish a component definition from an instance

In SketchUp, a component definition and a component instance are not the same thing. ComponentDefinition describes the elements a component contains; ComponentInstance represents a placement of that definition in the model, along with its transformation. Multiple instances can be created from the same definition. Edits to the definition are reflected in the instances that use it.

You can find out which definition an instance uses with the definition method. It is also possible to assign the instance to another definition; the documentation notes that the instance’s placement transformation in the model is preserved during this change.

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

This example assumes that the first element is a component instance. In a real extension, check the type of each element in the collection and handle the possibility of an empty result. You can use the count_instances and count_used_instances methods on a component definition to count its usage: the first counts distinct instances, while the second counts the total instances in the model that use the definition.

Use make_unique when a single instance needs to be edited independently. This method creates a definition for that instance that is not shared with other instances. Before making bulk edits, decide whether the change should apply to the shared definition or only to the selected instance.

3. Work with geometry collections efficiently

Entities is a collection of elements in the model or in a component definition. The documentation generally recommends using each to iterate through elements rather than accessing them by index, as it is more efficient. This approach also makes scripts that scan collections easier to follow.

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

When access by a specific index is required, you can use entities[index]. However, a valid index is between zero and one less than the collection’s length, and the method may return nil if no element is found. It’s therefore important to check the result when an operation depends on an index supplied by the user.

Methods such as add_line for creating a line, add_circle for a circle, and add_face for a face are available. To create many geometry elements with performance in mind, the Entities#build method creates an EntitiesBuilder. The documentation describes this method as intended for bulk geometry creation, but does not specify a particular speed increase or hardware requirement. Any benefit should therefore be measured using the geometry and extension workflow of the actual project.

If an operation needs to be recorded as a reversible step, use the model-level start_operation and commit_operation methods. In case of an error, the official documentation shows abort_operation for canceling the operation. It also warns that a transparent operation should not be aborted.

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. Use in architectural and visualization workflows

In architectural modeling and interior design projects, this API can be used to organize repeated elements as components, inspect model contents, and automate recurring geometry operations with scripts. For example, managing different placements of the same furniture definition requires correctly distinguishing the definition from its instances. Use make_unique when an element needs to be made independent; if a shared update is desired, consider working with the shared definition.

When developing an office automation script, first define the scope: will it process root model geometry, the contents of an open group, or selected elements? Then account for the relationship between component definitions and instances. To check that an extension is compatible with a given SketchUp version, review the version information in the official documentation for the methods it uses. Since the documentation specifies no particular hardware requirements, no specific hardware recommendation can be made; it’s best to test performance on the target model, especially for intensive geometry operations.

Common mistakes

• Treating the entities and active_entities collections as though they have the same scope.

• Failing to account for edits to a shared definition being reflected in its component instances.

• Ignoring that an item accessed by index may not exist and the result may be nil.

• Failing to call commit_operation on the successful path or manage the appropriate closing step on the error path after starting an operation.

This guide is based on the core model, component, and geometry classes documented in the SketchUp Ruby API. Interface menu paths, licensing terms, and hardware requirements are not covered in these documentation excerpts, so no assumptions have been made about them.