Class: Sketchup::Group

Inherits:
Drawingelement show all

Overview

A Group class contains methods for manipulating groups of entities.

Groups in SketchUp are very similar to Components, except that there is no instancing of groups. That means that you always will have one and only one of each of your groups. (In the actual implementation, SketchUp keeps track of groups as a special kind of Component that combines properties of definitions and instances, which is why you will see deprecated methods like Group.make_unique, and the class of observer you attach to Groups are ComponentInstance observers.)

Version:

  • SketchUp 6.0

Instance Method Summary collapse

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) ⇒ Object

The add_observer method is used to add a ComponentInstance observer to the group.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])
status = group.add_observer observer

Returns true if successful, false if unsuccessful.

Parameters:

  • observer —

    An observer.

Returns:

  • true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#copy ⇒ Object

The copy method is used to create a new Group object that is a copy of the group.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])
group2 = group.copy

Returns:

  • group - a new Group object

Version:

  • SketchUp 6.0

#definition ⇒ Object

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

Examples:

group = Sketchup.active_model.entities.add_group
definition = group.definition

Returns:

  • componentdefinition - a ComponentDefinition object if successful

Version:

  • SketchUp 2015

#description ⇒ Object

The description method is used to retrieve the description for the group.

Examples:

depth = 100
width = 100
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 group to the entities in the model
group = entities.add_group

# Get the entities within the group
entities2 = group.entities

# Add a face to within the group
face = entities2.add_face pts
group.description = "This is a Group with a 2d Face"
description = group.description

Returns:

  • description - a string description if successful

Version:

  • SketchUp 6.0

#description=(description) ⇒ Object

The description= method is used to set the description for the group.

Examples:

depth = 100
width = 100
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 group to the entities in the model
group = entities.add_group

# Get the entities within the group
entities2 = group.entities

# Add a face to within the group
face = entities2.add_face pts
group.description = "This is a Group with a 2d Face"
description = group.description
if (description)
  UI.messagebox description
else
  UI.messagebox "Failure"
end

Returns description - the new description if successful

Parameters:

  • description —

    A string description.

Returns:

  • description - the new description if successful

Version:

  • SketchUp 6.0

#entities ⇒ Object

The entities method is used to retrieve a collection of entities in the group.

Examples:

depth = 100
width = 100
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 group to the entities in the model
group = entities.add_group

# Get the entities within the group
entities2 = group.entities

# Add a face to within the group
face = entities2.add_face pts
entities = group.entities
if (entities)
  UI.messagebox entities
else
  UI.messagebox "Failure"
end

Returns:

  • entities - an Entities object if successful

Version:

  • SketchUp 6.0

#equals?(group) ⇒ Object

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

Examples:

entities = Sketchup.active_model.entities
group1 = entities[0]
group2 = entities[1]
status = group1.equals?(group2)

Returns status - true if the groups are geometrically equivalent. Otherwise false.

Parameters:

  • group —

    The group to compare this group with.

Returns:

  • status - true if the groups are geometrically equivalent. Otherwise false.

Returns:

  • (Boolean)

Version:

  • SketchUp 8.0

#explode ⇒ Object

The explode method is used to explode the group into individual entities.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])

array = group.explode
if array
  UI.messagebox "Exploded the group"
else
  UI.messagebox "Failure"
end

Returns:

  • An array of entity objects if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#guid ⇒ Object

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

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])
guid = group.guid

Returns:

  • guid - a unique 22 character string

Version:

  • SketchUp 2014

#intersect(group) ⇒ Object

The intersect method is used to compute the boolean intersection of two groups 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
group1 = entities[0]
group2 = entities[1]
result = group1.intersect(group2)

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

Parameters:

  • group —

    The group to intersect this group with.

Returns:

  • result - 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

#local_bounds ⇒ Object

The local_bounds method returns the BoundingBox object that defines the size of the group in an untransformed state. Useful for determining the original width, height, and depth of a group regardless of its current position or scale. For components, you can get a similar result by checking my_instance.definition.bounds.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])
transformation = Geom::Transformation.new([100,0,0])

# Note that local_bounds_1 and local_bounds_2 will be identical, since
# they both find the bounding box in group's untransformed state.
local_bounds_1 = group.local_bounds
group.transform! transformation
local_bounds_2 = group.local_bounds

Returns:

  • bounds - a BoundingBox object

Version:

  • SketchUp 7.0

#locked=(lock) ⇒ Object

The locked= method is used to lock a group.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])
status = group.locked = true

Returns status - true if the group is locked, false if not

Parameters:

  • lock (Boolean)

Returns:

  • status - true if the group is locked, false if not

Version:

  • SketchUp 6.0

#locked? ⇒ Object

The locked? method is used to determine if a group is locked.

Examples:

depth = 100
width = 100
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 group to the entities in the model
group = entities.add_group
status = group.locked?
UI.messagebox status

Returns:

  • status - true if the group is locked, false if not.

  • (Boolean)

Version:

  • SketchUp 6.0

#make_unique ⇒ Object

The make_unique method is used to force a group to have a unique definition.

Copying a group using the copy tool in SketchUp will create copies of the group that share a common definition until an instance is edited manually or this method is used. If multiple copies are made, all copies share a definition until all copies are edited manually, or all copies have this method used on them. This method ensures that the group uses a unique definition entry in the drawing database.

Examples:

# Assume we have 2 groups, one copied from the other and sharing definitions
groups = Sketchup.active_model.entities.grep(Sketchup::Group)
groups[0].make_unique
if (groups[0].entities.to_a == groups[1].entities.to_a)
  puts "This should not happen since we made the groups unique"
end

Returns:

  • group - the unique group

Version:

  • SketchUp 6.0

#manifold? ⇒ Object

The manifold? method is used to determine if a group is manifold.

Examples:

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

Returns:

  • status - true if the group is manifold. false if the group is not manifold.

  • (Boolean)

Version:

  • SketchUp 8.0

#move!(transform) ⇒ Object

The move! method is used to apply a transformation to the group.

This method is the same as the transform! method except that it does not record the move in an undo operation. This method is useful for transparently moving things during an animation.

Examples:

point = Geom::Point3d.new 500,500,500
t = Geom::Transformation.new point
depth = 100
width = 100
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 group to the entities in the model
group = entities.add_group

# Get the entities within the group
entities2 = group.entities

# Add a face to within the group
face = entities2.add_face pts
UI.messagebox "Group before Move"
group = group.move! t
if (group)
  UI.messagebox "Group after move"
  UI.messagebox group
else
  UI.messagebox "Failure"
end

Returns group - the transformed Group object if successful

Parameters:

  • transform —

    A Transformation object.

Returns:

  • group - the transformed Group object if successful

Version:

  • SketchUp 6.0

#name ⇒ Object

The name method is used to retrieve the name of the group.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])
group.name = "A Line"
name = group.name

Returns:

  • name - The name of the group if successful

Version:

  • SketchUp 6.0

#name=(name) ⇒ Object

The name= method is used to set the description for the group.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])
group.name = "A Line"
name = group.name

Returns name - a new name if successful

Parameters:

  • name —

    A string name.

Returns:

  • name - a new name if successful

Version:

  • SketchUp 6.0

#outer_shell(group) ⇒ Object

The outer_shell method is used to compute the outer shell of the two groups 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
group1 = entities[0]
group2 = entities[1]
result = group1.outer_shell(group2)

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

Parameters:

  • group —

    The group to outer shell this group with.

Returns:

  • result - 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) ⇒ Object

The remove_observer method is used to remove a ComponentInstance observer from the group.

Examples:

group = Sketchup.active_model.entities[0]
if group != nil
  if group.is_a? Sketchup::Group
    status = group.remove_observer observer
  end
end

Returns true if successful, false if unsuccessful.

Parameters:

  • observer —

    An observer.

Returns:

  • true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#show_differences(group, verbose) ⇒ Object

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

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

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

Examples:

entities = Sketchup.active_model.entities
group1 = entities[0]
group2 = entities[1]
status = group1.show_differences(group2, true)

Returns status - true if the groups are geometrically equivalent. Otherwise false.

Parameters:

  • group —

    The group 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 groups are geometrically equivalent. Otherwise false.

Version:

  • SketchUp 8.0

#split(group) ⇒ Object

The split method is used to compute the boolean split (map overlay) of the two groups 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
group1 = entities[0]
group2 = entities[1]
result = group1.split(group2)

Result - A vector (array) of the three resultant groups if the two objects (this and arg) represent manifold solids and the operation succeeds otherwise nil 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.

Parameters:

  • group —

    The group to split this group 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 nil 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.

Version:

  • SketchUp 8.0

#subtract(group) ⇒ Object

The subtract method is used to compute the boolean difference of the two groups 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
group1 = entities[0]
group2 = entities[1]
result = group1.subtract(group2)

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

Parameters:

  • group —

    The group to subtract this group from.

Returns:

  • result - 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

#to_component ⇒ Object

The to_component method is used to convert the group to a component instance.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])

# change the group to a component instance
group.to_component

Returns:

  • instance - the new ComponentInstance object

Version:

  • SketchUp 6.0

#transform!(transform) ⇒ Object

The transform! method is used to apply a transformation to a group.

Examples:

point = Geom::Point3d.new 500,500,500
t = Geom::Transformation.new point
depth = 100
width = 100
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 group to the entities in the model
group = entities.add_group

# Get the entities within the group
entities2 = group.entities

# Add a face to within the group
face = entities2.add_face pts
UI.messagebox "Group before Move"
group = group.transform! t
if (group)
  UI.messagebox "Group after move"
  UI.messagebox group
else
  UI.messagebox "Failure"
end

Returns group - a transformed group object if successful

Parameters:

  • transform —

    A Transformation object.

Returns:

  • group - a transformed group object if successful

Version:

  • SketchUp 6.0

#transformation ⇒ Object

The transformation method is used to retrieve the transformation for the group.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])

trans = group.transformation

Returns:

  • transformation - a Transformation object if successful

Version:

  • SketchUp 6.0

#transformation=(transform) ⇒ Object

The transformation= method is used to set the transformation for the group.

Examples:

# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])

new_transform = Geom::Transformation.new([100,0,0])
group.transformation = new_transform

Returns group - the newly trasformed group

Parameters:

  • transform —

    The Transformation object to apply

Returns:

  • group - the newly trasformed group

Version:

  • SketchUp 6.0

#trim(group) ⇒ Object

The trim method is used to compute the (non-destructive) boolean difference of the two groups 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
group1 = entities[0]
group2 = entities[1]
result = group1.trim(group2)

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

Parameters:

  • group —

    The group to trim this group against.

Returns:

  • result - 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(group) ⇒ Object

The union method is used to compute the boolean union of the two groups 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
group1 = entities[0]
group2 = entities[1]
result = group1.union(group2)

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

Parameters:

  • group —

    The group to union this group with.

Returns:

  • result - 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 ⇒ Object

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

Examples:

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

Returns:

  • volume - If the group represents a manifold volume, volume will be a positive value. If volume is negative, the group is not manifold.

Version:

  • SketchUp 8.0