Class: Sketchup::ComponentInstance

Inherits:

Drawingelement

• Object
• Entity
• Drawingelement
• Sketchup::ComponentInstance

Overview

The ComponentInstance class is used to represent component instances of a component definition or components that have been dragged from the Component Browser and placed (thus, instanced) within the Model. Therefore, the ComponentInstance class contains a reference to a corresponding ComponentDefinition object and a Transformation object (which contains the location of the component in the Drawing Window).

Starting from SketchUp 2018+, the ComponentInstance class contains default attributes when created or imported. The attributes are: “Owner”, “Status”. See the Help article for more information. The dictionary cannot be deleted via ruby and an @raise ArgumentError will be raised. The key/value pairs in the dictionary can be deleted safely.

Version:

• SketchUp 6.0

Instance Method Summary

• #add_observer(observer) ⇒ Boolean

  The add_observer method is used to add an observer to the current object.

• #definition ⇒ Sketchup::ComponentDefinition

  The definition method is used to retrieve the component definition for this component instance.

• #definition=(definition) ⇒ Sketchup::ComponentDefinition

  The definition= method is used to set the component definition for this component.

• #equals?(instance) ⇒ Boolean

  The equals? method is used to determine if a component instance is geometrically equivalent to another instance.

• #explode ⇒ Array<Sketchup::Entity>, false

  The explode method is used to explode the component instance into separate entities.

• #glued_to ⇒ Sketchup::Face, ...

  The #glued_to method is used to retrieve the entity that this instance is glued to.

• #glued_to=(drawing_element) ⇒ Sketchup::Face, ...

  The #glued_to= method glues this instance to a drawing element.

• #guid ⇒ String

  The guid method is used to get the base 64 encoded unique id for this SketchUp object.

• #intersect(instance) ⇒ Sketchup::Group^?

  The intersect method is used to compute the boolean intersection of two instances representing manifold solid volumes (this - arg).

• #locked=(lock) ⇒ Boolean

  The locked= method is used to lock a component instance.

• #locked? ⇒ Boolean

  The locked? method is used to determine if a component instance is locked.

• #make_unique ⇒ Sketchup::ComponentInstance

  The #make_unique method is used to create a component definition for this instance that is not used by any other instances.

• #manifold? ⇒ Boolean deprecated Deprecated.

  Use Sketchup::ComponentDefinition#manifold? instead. This method checks the definition, not the instance.

• #move!(transformation) ⇒ Boolean

  The #move! method is used to set the transformation of this component instance, similarly to #transformation= but without recording to the undo stack.

• #name ⇒ String

  The name method is used to get the name of this instance.

• #name=(name) ⇒ Sketchup::ComponentInstance

  The name method is used to set the name of this instance.

• #outer_shell(instance) ⇒ Sketchup::Group^?

  The outer_shell method is used to compute the outer shell of the two instances representing manifold solid volumes (this || arg).

• #remove_observer(observer) ⇒ Boolean

  The remove_observer method is used to remove an observer from the current object.

• #show_differences(instance, verbose) ⇒ Boolean

  The show_differences method is used to determine if a component instance is geometrically equivalent to another instance and in addition move the non- matching and matching geometry to new layers.

• #split(other) ⇒ Array(Sketchup::Group, Sketchup::Group, Sketchup::Group)^?

  The #split method performs a boolean “split” (map overlay) between this component instance (the receiver) and another manifold solid (group or component instance).

• #subtract(instance) ⇒ Sketchup::Group^?

  The subtract method is used to compute the boolean difference of the two instances representing manifold solid volumes (this - arg).

• #transform!(transform) ⇒ Boolean

  Apply a Geom::Transformation to a component instance.

• #transformation ⇒ Geom::Transformation

  The transformation method is used to retrieve the transformation of this instance.

• #transformation=(transformation) ⇒ Object

  The #transformation= method is used to set the transformation of this component instance.

• #trim(instance) ⇒ Sketchup::Group^?

  The #trim method is used to compute the (non-destructive) boolean difference of the two instances representing manifold solid volumes (this - arg).

• #union(instance) ⇒ Sketchup::Group^?

  The union method is used to compute the boolean union of the two instances representing manifold solid volumes (this | arg).

• #volume ⇒ Float

  The volume method is used to compute the volume of this instance if and only if this instance is manifold.

Methods inherited from Drawingelement

#bounds, #casts_shadows=, #casts_shadows?, #erase!, #hidden=, #hidden?, #layer, #layer=, #material, #material=, #receives_shadows=, #receives_shadows?, #visible=, #visible?

Methods inherited from Entity

#attribute_dictionaries, #attribute_dictionary, #delete_attribute, #deleted?, #entityID, #get_attribute, #inspect, #model, #parent, #persistent_id, #set_attribute, #to_s, #typename, #valid?

Instance Method Details

#add_observer(observer) ⇒ Boolean

The add_observer method is used to add an observer to the current object.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.add_observer observer

Parameters:

• observer (Object) —

  An observer.

Returns:

• (Boolean) —

  true if successful, false if unsuccessful.

Version:

• SketchUp 6.0

#definition ⇒ Sketchup::ComponentDefinition

The definition method is used to retrieve the component definition for this component instance.

Examples:

# First create an instance for us to look at.
entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)

# You can get an instance's definition with this method.
definition = componentinstance.definition

Returns:

• (Sketchup::ComponentDefinition) —

  a ComponentDefinition object if successful

Version:

• SketchUp 6.0

#definition=(definition) ⇒ Sketchup::ComponentDefinition

The definition= method is used to set the component definition for this component.

This method causes the instance to use a different definition, but it will use the same transformation to position it in the Model.

Examples:

# Assumes that the active model contains two different components.
instance1 = Sketchup.active_model.entities[0]
instance2 = Sketchup.active_model.entities[1]

# Grab handles to our two definitions.
definition1 = instance1.definition
definition2 = instance2.definition

# Replace 2nd instance with the 1st definition.
instance2.definition = definition1

Parameters:

• definition (Sketchup::ComponentDefinition) —

  A ComponentDefinition object to set.

Returns:

• (Sketchup::ComponentDefinition) —

  the ComponentDefinition object that was set if successful, false if unsuccessful

Version:

• SketchUp 6.0

#equals?(instance) ⇒ Boolean

The equals? method is used to determine if a component instance is geometrically equivalent to another instance.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
status = instance1.equals?(instance2)

Parameters:

• instance (Sketchup::ComponentInstance) —

  The instance to compare this instance with.

Returns:

• (Boolean)

Version:

• SketchUp 8.0

#explode ⇒ Array<Sketchup::Entity>, false

The explode method is used to explode the component instance into separate entities.

Examples:

# Assuming 'instance' is a ComponentInstance object
instance = Sketchup.active_model.active_entities.grep(Sketchup::ComponentInstance).first
entities = instance.explode

Returns:

• (Array<Sketchup::Entity>, false) —

  An array of entity objects if successful, false if unsuccessful

Version:

• SketchUp 6.0

#glued_to ⇒ Sketchup::Face, ...

The #glued_to method is used to retrieve the entity that this instance is glued to.

Examples:

point = Geom::Point3d.new(10, 20, 30)
transform = Geom::Transformation.new(point)
model = Sketchup.active_model
entities = model.active_entities
path = Sketchup.find_support_file("Bed.skp", "Components/Components Sampler/")
definitions = model.definitions
componentdefinition = definitions.load(path)
instance = entities.add_instance(componentdefinition, transform)
status = instance.glued_to

Returns:

• (Sketchup::Face, Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil)

Version:

• SketchUp 6.0

#glued_to=(drawing_element) ⇒ Sketchup::Face, ...

The #glued_to= method glues this instance to a drawing element. When moving this other drawing elment with the Move tool, the glued instance moves with it.

In SketchUp 2021.1 support for passing Group, Sketchup::ComponentInstance and Image was added.

Examples:

model = Sketchup.active_model
entities = model.active_entities

# Create a face
face = entities.add_face([[0, 0, 0], [100, 0, 0], [100, 100, 0], [0, 100, 0]])

# Add component
path = Sketchup.find_support_file("Bed.skp", "Components/Components Sampler/")
point = Geom::Point3d.new(10, 10, 0)
transformation = Geom::Transformation.new(point)
definitions = model.definitions
definition = definitions.load(path)
instance = entities.add_instance(definition, transformation)

# Make component "gluable"
definition.behavior.is2d = true

# Glue the component to the face.
# If you now move the face, the component will follow.
instance.glued_to = face

Parameters:

• drawing_element (Sketchup::Face, Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil)

Returns:

• (Sketchup::Face, Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil) —

  the entity the instance was glued to.

Raises:

• ArgumentError if the Behavior for this component doesn't allow gluing, if the alignment is wrong, or if this would lead to cyclic gluing.

Version:

• SketchUp 6.0

#guid ⇒ String

The guid method is used to get the base 64 encoded unique id for this SketchUp object.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
guid = componentinstance.guid

Returns:

• (String) —

  a unique 22 character string

Version:

• SketchUp 2014

#intersect(instance) ⇒ Sketchup::Group^?

Note:

This method is not available in SketchUp Make.

The intersect method is used to compute the boolean intersection of two instances representing manifold solid volumes (this - arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.intersect(instance2)

Parameters:

• instance (Sketchup::ComponentInstance) —

  The instance to intersect this instance with.

Returns:

• (Sketchup::Group, nil) —

  The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

• SketchUp 8.0

#locked=(lock) ⇒ Boolean

The locked= method is used to lock a component instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.locked = true

Parameters:

• lock (Boolean)

Returns:

• (Boolean) —

  true if the component instance is locked. False if the instance is not locked.

Version:

• SketchUp 6.0

#locked? ⇒ Boolean

The locked? method is used to determine if a component instance is locked.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.locked?

Returns:

• (Boolean)

Version:

• SketchUp 6.0

#make_unique ⇒ Sketchup::ComponentInstance

The #make_unique method is used to create a component definition for this instance that is not used by any other instances. If the component is already unique in the model, nothing happens.

Examples:

point = Geom::Point3d.new(10,20,30)
transform = Geom::Transformation.new(point)
model = Sketchup.active_model
entities = model.active_entities

path = Sketchup.find_support_file("Bed.skp",
  "Components/Components Sampler/")
definitions = model.definitions
componentdefinition = definitions.load(path)
instance = entities.add_instance(componentdefinition, transform)
# Returns unique component instance
instance.make_unique

Returns:

• (Sketchup::ComponentInstance) —

  returns itself

Version:

• SketchUp 6.0

#manifold? ⇒ Boolean

Deprecated.

Use Sketchup::ComponentDefinition#manifold? instead. This method checks the definition, not the instance.

The manifold? method is used to determine if an instance is manifold.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.manifold?

Returns:

• (Boolean)

See Also:

• Sketchup::ComponentDefinition#manifold?

Version:

• SketchUp 8.0

#move!(transformation) ⇒ Boolean

Note:

Despite the name being similar to #transform!, this method closer corresponds to #transformation=.

The #move! method is used to set the transformation of this component instance, similarly to #transformation= but without recording to the undo stack.

This method is useful for moving entities inside of an animation or page transition.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
new_transformation = Geom::Transformation.new([100,0,0])
componentinstance.move!(new_transformation)

Parameters:

• transformation (Geom::Transformation)

Returns:

• (Boolean) —

  true if successful, false if unsuccessful

Version:

• SketchUp 6.0

#name ⇒ String

The name method is used to get the name of this instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
name = componentinstance.name

Returns:

• (String) —

  the string name of the ComponentInstance

Version:

• SketchUp 6.0

#name=(name) ⇒ Sketchup::ComponentInstance

The name method is used to set the name of this instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
componentinstance.name = "Sang"

Parameters:

• name (String) —

  the string name to set

Returns:

• (Sketchup::ComponentInstance) —

  the newly named ComponentInstance

Version:

• SketchUp 6.0

#outer_shell(instance) ⇒ Sketchup::Group^?

The outer_shell method is used to compute the outer shell of the two instances representing manifold solid volumes (this || arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.outer_shell(instance2)

Parameters:

• instance (Sketchup::ComponentInstance) —

  The instance to outer shell this instance with.

Returns:

• (Sketchup::Group, nil) —

  The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

• SketchUp 8.0

#remove_observer(observer) ⇒ Boolean

The remove_observer method is used to remove an observer from the current object.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
status = componentinstance.remove_observer observer

Parameters:

• observer (Object) —

  An observer.

Returns:

• (Boolean) —

  true if successful, false if unsuccessful.

Version:

• SketchUp 6.0

#show_differences(instance, verbose) ⇒ Boolean

The show_differences method is used to determine if a component instance is geometrically equivalent to another instance and in addition move the non- matching and matching geometry to new layers.

This method will move both instances to Layer0. Geometry that is the same in both components will be moved to a new layer named def_name + “_same”. Geometry that is not the same will be moved to a layer named def_name + “_diff”.

If verbose is true, a list of all the geometry that is different from one component to the other is displayed texturally in the Ruby Console.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
status = instance1.show_differences(instance2, true)

Parameters:

• instance (Sketchup::ComponentInstance) —

  The instance to be compared with.

• verbose (Boolean) —

  A boolean flag indicating whether to display a textural report of the found differences to the Ruby console.

Returns:

• (Boolean) —

  true if the instances are geometrically equivalent, otherwise false.

Version:

• SketchUp 8.0

#split(other) ⇒ Array(Sketchup::Group, Sketchup::Group, Sketchup::Group)^?

Note:

Both operands must be manifold solids (see #manifold?). Non‑manifold geometry returns nil.

Note:

The returned groups are always new objects; any prior references to the original receiver or argument are invalid after this call.

Note:

All three result groups are placed on Layer0, regardless of original layer assignments.

Note:

Materials and attribute dictionaries are not fully preserved. Faces with default materials may inherit what was previously a container material; new faces get the default material.

Note:

The Intersection group can be empty (contain no geometry) when volumes only touch or one lies entirely within the other without producing new partitioning geometry.

Note:

Undo will restore pre‑split objects but object references you held beforehand become stale; reacquire them if needed.

Note:

Not available in SketchUp Make.

The #split method performs a boolean “split” (map overlay) between this component instance (the receiver) and another manifold solid (group or component instance). The operation partitions the combined volumes into:

• Difference2: (other - self)

• Difference1: (self - other)

• Intersection: (self ∩ other)

The originals (self and other) are ERASED and replaced by three newly created groups representing these volumes.

Examples:

model = Sketchup.active_model
g1 = model.entities.add_group
g1.entities.add_face([0, 0, 0], [100, 0, 0], [100, 100, 0], [0, 100, 0]).pushpull(50)
g2 = model.entities.add_group
g2.entities.add_face([50, -25, 0], [150, -25, 0], [150, 75, 0], [50, 75, 0]).pushpull(50)
diff2, diff1, inter = g1.to_component.split(g2) # Order: Difference2, Difference1, Intersection
puts [diff2.name, diff1.name, inter.name] # => ["Difference2","Difference1","Intersection"]

Parameters:

• other (Sketchup::ComponentInstance, Sketchup::Group) —

  The other solid to split with.

Returns:

• (Array(Sketchup::Group, Sketchup::Group, Sketchup::Group), nil) —

  Returns an Array of three new groups [Difference2, Difference1, Intersection] on success, or nil if either operand is not a manifold solid or the operation fails.

See Also:

• #union
• #intersect
• #subtract
• #trim

Version:

• SketchUp 8.0

#subtract(instance) ⇒ Sketchup::Group^?

Note:

This method is not available in SketchUp Make.

The subtract method is used to compute the boolean difference of the two instances representing manifold solid volumes (this - arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.subtract(instance2)

Parameters:

• instance (Sketchup::ComponentInstance) —

  The instance to subtract this instance from.

Returns:

• (Sketchup::Group, nil) —

  The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

• SketchUp 8.0

#transform!(transform) ⇒ Boolean

Apply a Geom::Transformation to a component instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0, 0, 0])
componentinstance = entities.add_instance(definition, transformation)
new_transformation = Geom::Transformation.new([100, 0, 0])
componentinstance.transform! new_transformation

Parameters:

• transform (Geom::Transformation) —

  The transformation object to apply to the component instance.

Returns:

• (Boolean)

Version:

• SketchUp 6.0

#transformation ⇒ Geom::Transformation

The transformation method is used to retrieve the transformation of this instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
t = componentinstance.transformation

Returns:

• (Geom::Transformation) —

  the Transformation object if successful

Version:

• SketchUp 6.0

#transformation=(transformation) ⇒ Object

Note:

As of SketchUp 2026, this will raise an error if the Geom::Transformation is not invertible. Prior to 2026 this would silently set the transformation possibly causing rendering or editing problems.

The #transformation= method is used to set the transformation of this component instance.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
new_transformation = Geom::Transformation.new([100,0,0])
componentinstance.transformation = new_transformation

Parameters:

• transformation (Geom::Transformation)

Raises:

• ArgumentError if the Geom::Transformation is not invertible (as of Sketchup 2026)

Version:

• SketchUp 6.0

#trim(instance) ⇒ Sketchup::Group^?

Note:

Trimming object instance2 using instance1 results in a new trimmed version of instance2. If the trim is successful the original instance2 is erased and a newly trimmed version is created. This new version, derived from the trimming operation, will possess a new GUID and will be returned.

Note:

This method is not available in SketchUp Make.

The #trim method is used to compute the (non-destructive) boolean difference of the two instances representing manifold solid volumes (this - arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.trim(instance2)

Parameters:

• instance (Sketchup::ComponentInstance) —

  The instance to trim this instance against.

Returns:

• (Sketchup::Group, nil) —

  The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

• SketchUp 8.0

#union(instance) ⇒ Sketchup::Group^?

Note:

This method is not available in SketchUp Make.

The union method is used to compute the boolean union of the two instances representing manifold solid volumes (this | arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Examples:

entities = Sketchup.active_model.entities
instance1 = entities[0]
instance2 = entities[1]
result = instance1.union(instance2)

Parameters:

• instance (Sketchup::ComponentInstance) —

  The instance to union this instance with.

Returns:

• (Sketchup::Group, nil) —

  The resultant group if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil is returned.

Version:

• SketchUp 8.0

#volume ⇒ Float

The volume method is used to compute the volume of this instance if and only if this instance is manifold.

Examples:

entities = Sketchup.active_model.entities
definition = Sketchup.active_model.definitions[0]
transformation = Geom::Transformation.new([0,0,0])
componentinstance = entities.add_instance(definition, transformation)
volume = componentinstance.volume

Returns:

• (Float) —

  If the instance represents a manifold volume, volume will be a positive value. If volume is negative, the instance is not manifold.

Version:

• SketchUp 8.0