ComponentInstance

SketchUp 6.0+

class

Introduction

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).

Methods

ComponentInstance.add_observerSketchUp 6.0+

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

Arguments:

observer: An observer.

Returns:

: true if successful, false if unsuccessful.

 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

ComponentInstance.definitionSketchUp 6.0+

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

Returns:

componentdefinition: a ComponentDefinition object if successful

 # 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

ComponentInstance.definition=SketchUp 6.0+

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.

Arguments:

definition: A ComponentDefinition object to set.

Returns:

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

 # 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

ComponentInstance.equals?SketchUp 8.0+

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

Arguments:

instance: The instance to compare this instance with.

Returns:

status: true if the instances are geometrically equivalent. Otherwise false.

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

ComponentInstance.explodeSketchUp 6.0+

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

Returns:

entities: an Entities object if successful, false if unsuccessful

 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

ComponentInstance.glued_toSketchUp 6.0+

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

Returns nil if it is not glued to anything.

Returns:

entity: the Entity object that the instance is glued to (if successful)

 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

ComponentInstance.glued_to=SketchUp 6.0+

The glued_to= method glues this instance to a face.

This method will raise an exception if the instance cannot be glued to the given face. Instances cannot be glued if the definition of the instance doesn't support gluing or if the alignment is wrong.

Returns:

face: the Face object where the component is glued if successful

 depth = 100
 width = 100
 path=Sketchup.find_support_file "Bed.skp",
   "Components/Components Sampler/"
 model = Sketchup.active_model
 entities = model.active_entities
 pts = []
 pts[0] = [0, 0, 0]
 pts[1] = [width, 0, 0]
 pts[2] = [width, depth, 0]
 pts[3] = [0, depth, 0]
 # Add the face to the entities in the model
 face = entities.add_face pts
 point = Geom::Point3d.new 10,10,0
 transform = Geom::Transformation.new point
 definitions = model.definitions
 componentdefinition = definitions.load path
 instance = entities.add_instance componentdefinition, transform
 begin
   status = instance.glued_to = face
 rescue
   UI.messagebox $!.message
 end
 if (status)
   UI.messagebox status.to_s
 else
   UI.messagebox "Failure"
 end

ComponentInstance.intersectSketchUp 8.0+

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.

Arguments:

instance: The instance to intersect this instance with.

Returns:

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

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

ComponentInstance.locked=SketchUp 6.0+

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

Returns:

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

 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

ComponentInstance.locked?SketchUp 6.0+

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

Returns:

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

 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?

ComponentInstance.make_uniqueSketchUp 6.0+

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

Returns:

status: true if successful, false if unsuccessful

 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
 status = instance.make_unique

ComponentInstance.manifold?SketchUp 8.0+

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

Returns:

status: true if the instance is manifold. false if the instance is not manifold.

 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?

ComponentInstance.move!SketchUp 6.0+

The move! method is the same as the transform! method, except that it does not record the move as an undo operation.

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

Arguments:

transform: The transform object to apply to the component instance.

Returns:

status: true if successful, false if unsuccessful

 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

ComponentInstance.nameSketchUp 6.0+

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

Returns:

name: the string name of the ComponentInstance

 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

ComponentInstance.name=SketchUp 6.0+

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

Arguments:

name: name - the string name to set

Returns:

instance: the newly named ComponentInstance

 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"

ComponentInstance.outer_shellSketchUp 8.0+

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.

Arguments:

instance: The instance to outer shell this instance with.

Returns:

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

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

ComponentInstance.remove_observerSketchUp 6.0+

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

Arguments:

observer: An observer.

Returns:

: true if successful, false if unsuccessful.

 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

ComponentInstance.show_differencesSketchUp 8.0+

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.

Arguments:

instance: The instance to be compared with.

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

Returns:

status: true if the instances are geometrically equivalent, otherwise false.

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

ComponentInstance.splitSketchUp 8.0+

The split method is used to compute the boolean split (map overlay)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.

Arguments:

instance: The instance to split this instance with.

Returns:

result: A vector (array) of the three resultant groups if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise Qnil is returned. The 3 groups are as follows: The intersection of volume 1 & volume 2, the difference of volume 1 minus volume 2, and the reverse difference of volume 2 minus volume 1.

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

ComponentInstance.subtractSketchUp 8.0+

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.

Arguments:

instance: The instance to subtract this instance from.

Returns:

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

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

ComponentInstance.transform!SketchUp 6.0+

The transform! method is used to apply a transformation to a component instance.

Arguments:

transform: The transform object to apply to the component instance.

Returns:

status: true if successful, false if unsuccessful

 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

ComponentInstance.transformationSketchUp 6.0+

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

Returns:

transformation: the Transformation object if successful

 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

ComponentInstance.transformation=SketchUp 6.0+

The transformation= method is used to set the transformation on this instance.

Arguments:

tranform: A Transformation object to apply.

Returns:

instance: the transformed ComponentInstance

 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

ComponentInstance.trimSketchUp 8.0+

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.

Arguments:

instance: The instance to trim this instance against.

Returns:

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

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

ComponentInstance.unionSketchUp 8.0+

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.

Arguments:

instance: The instance to union this instance with.

Returns:

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

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

ComponentInstance.volumeSketchUp 8.0+

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

Returns:

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

 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