# Module: AMS::Group

Defined in:
Documentation/ams/group.rb

Since:

• 3.3.0

## Class Method Summary collapse

• Calculate group/component-instance centre of mass from faces.

• Copy group/component-instance without including the undesired entities.

• Compute group/component-instance axes-aligned bounding-box from edges.

• Compute group/component-instance axes-aligned bounding-box from faces.

• Get group/component-instance construction point and line positions.

• Get group/component instance definition.

• Get group/component-instance edges.

• Get group/component instance entities.

• Get group/component-instance faces.

• Get group/component-instance face triplets.

• Get group/component-instance triangular mesh.

• Get group/component-instance triangular mesh collections.

• Get group/component-instance edge vertices.

• Get group/component-instance face vertices.

• Get group/component-instance face vertices collections.

• Split group/component-instance at plane.

## Class Method Details

### .calc_centre_of_mass(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Geom::Point3d

Note:

This method only works with convex groups.

Note:

This function was revised in version 3.6.0.

Calculate group/component-instance centre of mass from faces.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Geom::Point3d)

Since:

• 3.3.0

 ``` 252 253``` ```# File 'Documentation/ams/group.rb', line 252 def calc_centre_of_mass(object, recurse = true, transformation = nil, &entity_validation) end```

### .copy(object, context, transformation = nil, recurse = true) {|sub_entity| ... } ⇒ Sketchup::Group, ...

Note:

This function was revised in version 3.6.0.

Note:

Make sure to wrap this function with a start/commit operation to avoid polluting the undo stack.

Note:

The original `object` is not modified in any way.

Note:

If a block is passed, copied object is made unique.

Note:

The main, copied group is assigned its original name, layer, material, visibility state, casts/receives shadows state; attributes are not copied.

Copy group/component-instance without including the undesired entities.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• context (Sketchup::Entities)

The entities context to paste into.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A transformation matrix, relative to `context`, to apply to the resulting group. Pass `nil` to have the resulting group be applied the matrix of `object`.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

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

A copied group or `nil` if nothing copied.

Since:

• 3.3.0

 ``` 279 280``` ```# File 'Documentation/ams/group.rb', line 279 def copy(object, context, transformation = nil, recurse = true, &entity_validation) end```

### .get_bounding_box_from_edges(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Geom::BoundingBox

Note:

This function was revised in version 3.6.0.

Compute group/component-instance axes-aligned bounding-box from edges.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Geom::BoundingBox)

Since:

• 3.5.0

 ``` 36 37``` ```# File 'Documentation/ams/group.rb', line 36 def get_bounding_box_from_edges(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_bounding_box_from_faces(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Geom::BoundingBox

Note:

This function was revised in version 3.6.0.

Compute group/component-instance axes-aligned bounding-box from faces.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Geom::BoundingBox)

Since:

• 3.3.0

 ``` 55 56``` ```# File 'Documentation/ams/group.rb', line 55 def get_bounding_box_from_faces(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_construction(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Array<Geom::Point3d>

Note:

This function was revised in version 3.6.0.

Get group/component-instance construction point and line positions.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Array<Geom::Point3d>)

An array of points.

Since:

• 3.3.0

 ``` 173 174``` ```# File 'Documentation/ams/group.rb', line 173 def get_construction(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_definition(object) ⇒ Sketchup::ComponentDefinition

Get group/component instance definition.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

Returns:

• (Sketchup::ComponentDefinition)

Since:

• 3.3.0

 ``` 9 10``` ```# File 'Documentation/ams/group.rb', line 9 def get_definition(object) end```

### .get_edges(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Array<Array<Geom::Point3d>>

Note:

This function was revised in version 3.6.0.

Get group/component-instance edges.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Array<Array<Geom::Point3d>>)

An array of edges. Each edge represents an array of two points.

Since:

• 3.3.0

 ``` 75 76``` ```# File 'Documentation/ams/group.rb', line 75 def get_edges(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_entities(object) ⇒ Sketchup::Entities

Get group/component instance entities.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

Returns:

• (Sketchup::Entities)

Since:

• 3.3.0

 ``` 16 17``` ```# File 'Documentation/ams/group.rb', line 16 def get_entities(object) end```

### .get_faces(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Array<Array<Geom::Point3d>>

Note:

This function was revised in version 3.6.0.

Get group/component-instance faces.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Array<Array<Geom::Point3d>>)

An array of faces. Each face represents an array of points.

Since:

• 3.3.0

 ``` 114 115``` ```# File 'Documentation/ams/group.rb', line 114 def get_faces(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_polygons_from_faces(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Array<Array<Geom::Point3d>>

Note:

This function was revised in version 3.6.0.

Get group/component-instance face triplets.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Array<Array<Geom::Point3d>>)

An array of polygons. Each polygon represents an array of three points - a triplet.

Since:

• 3.3.0

 ``` 193 194``` ```# File 'Documentation/ams/group.rb', line 193 def get_polygons_from_faces(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_triangular_mesh(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Geom::PolygonMesh

Note:

This function was revised in version 3.6.0.

Get group/component-instance triangular mesh.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Geom::PolygonMesh)

Everything merged into one mesh.

Since:

• 3.3.0

 ``` 212 213``` ```# File 'Documentation/ams/group.rb', line 212 def get_triangular_mesh(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_triangular_meshes(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Array<Geom::PolygonMesh>

Note:

This function was revised in version 3.6.0.

Get group/component-instance triangular mesh collections. Each sub-group, sub-component, a collection of connected faces is reserved its own mesh.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Array<Geom::PolygonMesh>)

An array of meshes.

Since:

• 3.3.0

 ``` 232 233``` ```# File 'Documentation/ams/group.rb', line 232 def get_triangular_meshes(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_vertices_from_edges(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Array<Geom::Point3d>

Note:

This function was revised in version 3.6.0.

Get group/component-instance edge vertices.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Array<Geom::Point3d>)

An array of points.

Since:

• 3.3.0

 ``` 94 95``` ```# File 'Documentation/ams/group.rb', line 94 def get_vertices_from_edges(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_vertices_from_faces(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Array<Geom::Point3d>

Note:

This function was revised in version 3.6.0.

Get group/component-instance face vertices.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Array<Geom::Point3d>)

An array of points.

Since:

• 3.3.0

 ``` 133 134``` ```# File 'Documentation/ams/group.rb', line 133 def get_vertices_from_faces(object, recurse = true, transformation = nil, &entity_validation) end```

### .get_vertices_from_faces2(object, recurse = true, transformation = nil) {|sub_entity| ... } ⇒ Array<Array<Geom::Point3d>>

Note:

This function was revised in version 3.6.0.

Get group/component-instance face vertices collections.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A coordinate system in which the computation is to be performed. Usually this parameter is set to the coordinate system `object` is associated to. Pass `nil` to have the computation performed in `object`'s local space.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Array<Array<Geom::Point3d>>)

An array of point collections from every included sub-group/sub-component instance. Each point collection represents an array of points.

Since:

• 3.3.0

 ``` 154 155``` ```# File 'Documentation/ams/group.rb', line 154 def get_vertices_from_faces2(object, recurse = true, transformation = nil, &entity_validation) end```

### .split(object, point, normal, context, transformation = nil, recurse = true) {|sub_entity| ... } ⇒ Array<Sketchup::Group, Sketchup::ComponentInstance, nil>

Note:

Make sure to wrap this function with a start/commit operation to avoid polluting the undo stack.

Note:

The original `object` is not modified in any way.

Note:

Copied groups are assigned their original name, layer, material, visibility state, casts/receives shadows state; attributes are not copied.

Split group/component-instance at plane.

Parameters:

• object (Sketchup::Group, Sketchup::ComponentInstance)

A group or a component instance.

• point (Geom::Point3d)

A point on plane in `context` coordinates.

• normal (Geom::Vector3d)

Plane normal in `context` coordinates.

• context (Sketchup::Entities)

The entities context to paste into.

• transformation (Geom::Transformation, nil) (defaults to: nil)

A transformation matrix, relative to `context`, to apply to the resulting groups. Pass `nil` to have the resulting groups be applied the matrix of `object`.

• recurse (Boolean) (defaults to: true)

Whether to process sub-groups and sub-component instances.

Yields:

• A procedure for determining whether a particular sub-group or a sub-component-instance is to be considered a part of the operation.

Yield Parameters:

• sub_entity (Sketchup::Group, Sketchup::ComponentInstance)

Yield Returns:

• (Boolean)

Pass `true` to have `sub_entity` included in the operation; pass `false` to have `sub_entity` ignored.

Returns:

• (Array<Sketchup::Group, Sketchup::ComponentInstance, nil>)

An array of two items. Each item is either a group, a component-instance, or nil if turned out empty, during the split operation.

Since:

• 3.6.0

 ``` 308 309``` ```# File 'Documentation/ams/group.rb', line 308 def split(object, point, normal, context, transformation = nil, recurse = true, &entity_validation) end```