In brief
- Sketchup.active_model returns the Model object used for API operations on the open model.
- Model.entities returns the root drawing context, while Model.active_entities returns the contents of the open group or component.
- When iterating over a selection, using Selection#each is more efficient than retrieving items one index at a time.
- Component instances can share the same definition; use make_unique to make a single instance unique.
The SketchUp Ruby API provides a starting point for inspecting and modifying drawing elements in an open SketchUp model. In the official API documentation, the Model, Entities, Selection, and ComponentInstance classes describe the fundamental ways to work with models, geometry, selections, and components. This guide focuses on building small, verifiable automation steps using methods shown in the documentation. The core classes are listed as dating back to SketchUp 6.0, while some methods were added in later versions, so check the version notes for each method you use.
1. Start with the active model
When working with the API, first get the object for the open model. Sketchup.active_model returns the model the user is currently working in. Through the Model object, you can access drawing elements, materials, component definitions, and the selection. This approach lets you get references to the relevant collections up front rather than repeatedly searching for the model during different operations.
model = Sketchup.active_model
entities = model.entities
materials = model.materials
definitions = model.definitions
selection = model.selectionOne important distinction is the difference between model.entities and model.active_entities. The former contains elements at the model’s root level. If the user has opened a group or component for editing, active_entities returns the elements in the current context; if no editing context is open, it returns the same result as entities. So choose the right collection depending on whether you want to work with the model’s top level or the content the user is currently editing.
2. Inspect the selection efficiently and safely
model.selection represents the drawing elements currently selected. Iterating over each element with each is more efficient than accessing indices one by one. Also, don’t assume that the selection order reflects the order in which the user selected the elements: the documentation explicitly states that element order is not guaranteed.
selection = Sketchup.active_model.selection
puts "Selected elements: #{selection.length}"
selection.each do |element|
puts element.typename
endUse first if an operation concerns just one element; it returns nil if the selection is empty. empty? checks whether anything is selected, while single_object? checks whether the selection can be treated as a single object. Use include? to test whether an element is selected.
Removing elements from the same collection while iterating over a selection can change its size and indices, potentially causing some elements to be skipped. The safe approach recommended in the documentation is to copy the elements to be removed into an array first, then operate on that copy. Also, index access such as selection[0] is not an efficient way to inspect every element. Use remove and clear when you need to remove an element from the selection or clear the selection set.
3. Create geometry in the correct drawing context
New elements such as lines or faces are added to the chosen Entities collection. For example, add_line creates an edge between two points, add_face adds a face, and add_group creates a new group. Use model.entities to work at the root level, and model.active_entities to work within an open group or component context. This ensures that generated geometry is added to the intended part of the model.
If an operation involves multiple model changes, SketchUp’s operation mechanism can record them as a single undoable operation. start_operation begins a new operation, commit_operation completes it, and abort_operation can cancel an operation that has been started if an error occurs. Use these methods to manage related changes consistently within an automation workflow.
model = Sketchup.active_model
model.start_operation("Add line")
begin
model.active_entities.add_line([0, 0, 0], [500, 500, 0])
model.commit_operation
rescue
model.abort_operation
raise
endThe documentation notes that abort_operation is normally called in an error-handling block. It also warns against using this method with transparent operations: cancelling one can also cancel the previous operation it is attached to. If your automation uses transparent operations, handle errors accordingly.
If you need to create a large number of geometry elements, consider Entities#build as well. The API documentation describes this method as a way to create an EntitiesBuilder designed for building geometry in batches with performance in mind. However, don’t infer a specific speed improvement or assume it is suitable for every task beyond what the documentation states.
4. Separate component instances from their definitions
A ComponentInstance references a component definition and a transformation that determines its position in the model. This structure lets the same definition be used for multiple instances in a model. For example, you can get an instance’s definition with definition, inspect its position transformation with transformation, or assign another definition with definition=.
Use make_unique when you need to edit just one instance independently of the others: the method creates a component definition for that instance that is not shared by other instances. Decide in advance whether the change should affect all shared instances or only the selected one. Otherwise, the intended scope of the change may not match the result in the model. The documentation also includes explode, which turns a component into separate drawing elements; don’t use it in workflows where the component needs to remain an instance.
Using the API in architecture and visualization workflows
These methods provide a foundation for architects, interior designers, and SketchUp plugin developers who want to automate recurring model checks or geometric edits. For example, you can inspect elements in the active editing context, evaluate selected objects in bulk, or create repeated geometry as a single operation. The benefits of this approach depend on clearly defining the context in which the automation operates and which instances a component change will affect.
The documentation does not specify hardware requirements or licensing conditions for these API methods, so don’t assume any such requirements. Before implementation, check the method notes for your SketchUp version, especially for functions marked as available in newer versions. For workflows involving bulk geometry creation in large models, consider Entities#build and plan how to manage the current workflow through undoable operations.
Common mistakes
Always using
model.entities: If a group or component is open for editing,active_entitiesmay be the right context.Assuming selection order matches the order in which the user clicked: The API documentation says this order is not guaranteed.
Removing elements from the same collection during
each: Copying the collection withto_afirst prevents elements from being skipped.Ignoring shared definitions when editing a component instance: Consider
make_uniqueif only one instance should be independent.Cancelling a transparent operation with
abort_operation: The documentation warns that this may also cancel the previous operation it is attached to.
Sources
3 sourcesSource texts are not republished; short quotes are marked, everything else is our own summary and commentary.
For small architecture and visualization offices in Turkey, the practical value of this API lies in turning frequently repeated model checks and edits into an automated workflow. Managing the selection, active editing context, and component definitions correctly can reduce manual steps while also lowering the risk of unexpected changes to the model.
The main startup cost is likely to be Ruby API knowledge and compatibility with the existing plugin workflow, rather than new hardware; the sources specify no particular hardware or licensing requirements. Offices would be wise to first test undo behavior, component instance sharing, and method compatibility with their SketchUp version on a small model.
Frequently asked questions
How do you access the active model in the SketchUp Ruby API?
`Sketchup.active_model` provides access to the open model. Through the Model object, you can access collections such as geometry, selection, materials, and component definitions.
What is the difference between entities and active_entities in the SketchUp Ruby API?
`entities` returns elements at the model’s root level. `active_entities` returns elements in the open group or component editing context; if there is no such context, it returns the same result as `entities`.
How can you make a SketchUp component instance unique?
`ComponentInstance#make_unique` creates a component definition for that instance that is not shared by other instances. This lets you apply changes to the instance you made unique.



