class Entities

 

Parent: Object

Class Index

Methods: [], add_arc, add_circle, add_cline, add_cpoint, add_curve, add_edges, add_face, add_faces_from_mesh, add_group, add_image, add_instance, add_line, add_ngon, add_text, at, clear!, count, each, erase_entities, intersect_with, length, model, parent, transform_by_vectors, transform_entities

 

Sample Code: entitiestests.rb

 

 The Entities class is a container class for all entities in a model (it is a collection of Entity objects). 
 

Instance Methods

 

[]

The [] method is used to retrieve an entity by its index in an array of entities.

Syntax:

entity = entities[index]

Arguments:

index - the index for a specific entity

Return Value:

entity - an Entity object if successful, nil if not found

Comments:

 

Example:

entity1 = entities[1]
if (entity1)
UI.messagebox entity1
else
UI.messagebox "Failure"
end


 

add_arc

The add_arc method is used to create an arc curve segment.

Syntax:

arccurve = entities.add_arc center, xaxis, normal, radius, start_angle, end_angle, numsegs)

Arguments:

center - a Point3d object representing the center

xaxis - a Vector3d object representing xaxis for the arc

normal - a Vector3d object representing normal for the arc

radius - the radius of the arc

start_angle - start angle for the arc

end_angle - end angle for the arc

numsegs - (optional) number of segments in the arc

Return Value:

arccurve - an ArcCurve object if successful

Comments:

 

Example:

centerpoint = Geom::Point3d.new
# Create a circle perpendicular to the normal or Z axis
vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 1,0,0
vector3 = vector.normalize!
model = Sketchup.active_model
entities = model.active_entities
arccurve = entities.add_arc centerpoint, vector2, vector3, 10, 15, 35
UI.messagebox arccurve        


 

add_circle

The add_circle method is used to create a circle

Syntax:

circle = entities.add_circle center, normal, radius, <numseg>

Arguments:

center - a Point3d object representing the center

normal - a Vector3d object representing normal for the arc

radius - the radius of the arc

numsegs - (optional) number of segments in the arc

Return Value:

circle - an Array object containing edges if successful

Comments:

 

Example:

centerpoint = Geom::Point3d.new
# Create a circle perpendicular to the normal or Z axis
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.normalize!
model = Sketchup.active_model
entities = model.active_entities   
edges = entities.add_circle centerpoint, vector2, 10


 

add_cline

The add_cline method is used to create a construction line.

Syntax:

construction_line = entities.add_cline point, vector

construction_line = entities.add_cline point1, point2, <stipple>

Arguments:

point, point1, point2 - a Point3d object

vector - a Vector3d object

<stipple> - an optional stipple pattern. See ConstructionLine.stipple for acceptable patterns.

Return Value:

construction_line - a ConstructionLine object if successful

Comments:

 

Example:

model = Sketchup.active_model
entities = model.active_entities
point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (20,20,20)
constline = entities.add_cline point1,point2
if (constline)
UI.messagebox constline
else
UI.messagebox "Failure"
end


 

add_cpoint

The add_cpoint method is used to create a construction point.

Syntax:

construction_point = entities.add_cpoint point

Arguments:

point - a Point3d object

Return Value:

construction_point - a ConstructionPoint object if successful

Comments:

 

Example:

model = Sketchup.active_model
entities = model.active_entities
point1 = Geom::Point3d.new (100,200,300)
constpoint = entities.add_cpoint point1
if (constpoint)
UI.messagebox constpoint
else
UI.messagebox "Failure"
end


 

add_curve

The add_curve method is used to create a curve from a collection of edges.

Syntax:

curve = entities.add_curve point1, point2, point3, ...

curve = entities.add_curve [point1, point2, point3, ...]

Arguments:

point1 point2, point3... - a Point3d object

[point1, point2, point3...] - an array of Point3d objects

Return Value:

curve - a Curve object if successful

Comments:

The arguments are either Points or an Array of Points.

At least 2 points are required.

Returns a Curve.

Example:

 


 

add_edges

The add_edges method is used to add a set of connected edges to the entities array.

Syntax:

edges = enties.add_edges point1, point2, ...

Arguments:

point1 - a Point3d object

Return Value:

edges - an array of Edge objects if successful

Comments:

 

Example:

model = Sketchup.active_model
entities = model.active_entities
point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (20,20,20)
edges = entities.add_edges point1,point2

if (edges)
UI.messagebox edges
else
UI.messagebox "Failure"
end


 

add_face

The add_face method is used to create a face.

Syntax:

entities.add_face edge1, edge2, edge3, ...

entities.add_face [edge1, edge2, edge3, ...]

entities.add_face point1, point2, point3, point 4

entities.add_face [point 1, point2, point3, ....]

entities.add_face curve

Arguments:

edge1 - a Edge object

point1 - a Point3d object

curve - a Curve object

Return Value:

face - a Face object if successful

Comments:

For the last form that takes a Curve, the curve must be closed - like a circle.

Example:

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 face to the entities in the model
face = entities.add_face pts
if (face)
UI.messagebox face
else
UI.messagebox "Failure"
end


 

add_faces_from_mesh

the add_faces_from_mesh is used to add Face objects to the collection of entities from a PolygonMesh.

Syntax:

faces = entities.add_faces_from_mesh polygonmesh

Arguments:

polygonmesh - a Polygon mesh object

Return Value:

faces - an array of Face objects if successful

Comments:

 

Example:

model = Sketchup.active_model
entities = model.active_entities
mesh = Geom::PolygonMesh.new
faces = entities.add_faces_from_mesh mesh
if (faces)
UI.messagebox faces
else
UI.messagebox "Failure"
end


 

add_group

The add_group method is used to create an empty group.

Syntax:

group = entities.add_group

Arguments:

 

Return Value:

group - an empty Group object if successful

Comments:

 

Example:

model = Sketchup.active_model
entities = model.active_entities
group = entities.add_group
if (group)
UI.Messagebox group
else
UI.Messagebox "Failure"
end


 

add_image

The add_image method is used to add an image to the collection of entities.

Syntax:

image = entities.add_image filename, point, width, <height>

Arguments:

filename - a filename for the image file

point - a Point3d object representing the insertion point of the image

width - width for the image.

<height> - (optional) height for the image if you want to control width and height independently.

Return Value:

image - an Image object if successful.

Comments:

The width and height are measured in model units (i.e. inches). If the height is not given, then it is computed from the width to preserve the aspect ratio of the image.

Example:

model = Sketchup.active_model
entities = model.active_entities
point = Geom::Point3d.new 10,20,30
image = entities.add_image Shapes.jpg point 3000
if (image)
UI.messagebox image
else
UI.messagebox "Failure"
end


 

add_instance

The add_instance method adds a component instance to the collection of entities.

Syntax:

componentinstance = entities.add_instance componentdefinition, transformation

Arguments:

componentdefinition - a ComponentDefinition object

transformation - a Transformation object

Return Value:

componentinstance - a ComponentInstance object if successful

Comments:

 

Example:

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 "BedTraditional.skp" ,"Components/Furniture/"
definitions = model.definitions
componentdefinition = definitions.load path
instance = entities.add_instance componentdefinition, transform
if (instance)
UI.messagebox instance
else
UI.messagebox "Failure"
end


 

add_line

The add_line method is used to add an edge to the collection of entities.

Syntax:

edge = entities.add_line point1, point2

Arguments:

point1 - a Point3d object representing the starting point of the line

point2 - a Point3d object representing the ending point of the line

Return Value:

edge - a Edge object if successful

Comments:

This method is the same as add_edges method, but returns a single edge.

Example:

model = Sketchup.active_model
entities = model.active_entities
point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (20,20,20)
line = entities.add_line point1,point2
if (line)
UI.messagebox line
else
UI.messagebox "Failure"
end


 

add_ngon

The add_ngon method is used to create a multi-sided polygon.

Syntax:

edges - entities.add_ngon center, normal, radius, numsides

Arguments:

center - a Point3d object representing the center of the polygon

normal - a Vector3d object

radius - a radius

numsides - the number of sides for the polygon

Return Value:

edges - an array of Edges that make up the polygon if successful

Comments:

 

Example:

 


 

add_text

The add_text method adds a note or label text entity to the entities

Syntax:

text = entities.add_text "text", point, <vector>

Arguments:

text - the text string to add

point - a Point3d object representing the insertion point

<vector> - (optional) vector representing the direction of the text

Return Value:

text - a Text object if successful

Comments:

Add a note or label Text entity. The first form adds a note (text with no leader.) The second form adds text with a leader.

text = a String which is the text to add.

pt = the location of the note, or the point that the label is pointing to.

vec = a vector from pt to the start of the text for a label.

Example:

coordinates = [10, 10, 10]
model = Sketchup.active_model        
entities = model.entities
point = Geom::Point3d.new coordinates
text = entities.add_text "This is a Test", point


 

at

The at method is an alias for []. See [].

Syntax:

 

Arguments:

 

Return Value:

 

Comments:

 

Example:

 


 

clear!

The clear! method is used to remove all entities from the collection of entities.

Syntax:

status = entities.clear!

Arguments:

 

Return Value:

status - true if successful, false if unsuccessful

Comments:

 

Example:

coordinates = [10, 10, 10]
model = Sketchup.active_model        
entities = model.entities
point = Geom::Point3d.new coordinates
text = entities.add_text "This is a Test", point
UI.messagebox "Clearing All"
status = entities.clear!


 

count

The count method is an alias for the length method. See length.

Syntax:

 

Arguments:

 

Return Value:

 

Comments:

 

Example:

 


 

each

The each method is used to iterate through the entities in the collection of entities.

Syntax:

entities.each { | entity | ... }

Arguments:

entity - a variable that will hold each Entity object as they are found if successful

Return Value:

 

Comments:

 

Example:

coordinates = [10, 10, 10]
model = Sketchup.active_model        
entities = model.entities
point = Geom::Point3d.new coordinates
text = entities.add_text "This is a Test", point
entities.each { | entity| UI.messagebox entity }


 

erase_entities

The erase_entities method is used to erase one or more entities from the model.

Syntax:

entities.erase_entities entities

Arguments:

entities - an entity or array of entities

Return Value:

 

Comments:

 

Example:

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 face to the entities in the model
face = entities.add_face pts
# I just happen to know that the second entity in the
# entities objects is an edge.
UI.messagebox entities
// Erase an edge
entities.erase_entities entities[1]
UI.messagebox entities


 

intersect_with

The intersect_with method is used to intersect an entities, component instance, or group object with a entities object.

Syntax:

entities.intersect_with recurse, transformation1, entities1, transformation2, hidden, entites2

Arguments:

recurse - true if you want this entities object to be recursed (intersection lines will be put inside of groups and components within this entities object)

transformation1 - the transformation for this entities object

entities1 - the entities where you want the intersection lines to appear

transformation2 - the transformation for entities1

hidden - true if you want hidden geometry in this entities object to be used in the intersection

entities2 - an entities object, or an array of entity

Return Value:

 

Comments:

 

Example:

 

 

 

length

The length method is used to retrieve the number of entities in the collection of entities.

Syntax:

length = entities.length

Arguments:

 

Return Value:

length - the number of entities in the collection of entities if successful

Comments:

 

Example:

coordinates = [10, 10, 10]
model = Sketchup.active_model        
entities = model.entities
point = Geom::Point3d.new coordinates
text = entities.add_text "This is a Test", point
length = entities.length


 

model

The model method is used to retrieve the model that contains the collection of entities.

Syntax:

model = entities.model

Arguments:

 

Return Value:

model - the model that contains the collection of entities if successful

Comments:

 

Example:

coordinates = [10, 10, 10]
model = Sketchup.active_model        
entities = model.entities
point = Geom::Point3d.new coordinates
text = entities.add_text "This is a Test", point
model = entities.model


 

parent

The parent method is used to retrieve the parent or object that contains the collection of entities. A parent can be either a Model or ComponentDefinition object.

Syntax:

parent = entities.parent

Arguments:

 

Return Value:

parent - the object that contains the collection of entities if successful

Comments:

 

Example:

coordinates = [10, 10, 10]
model = Sketchup.active_model        
entities = model.entities
point = Geom::Point3d.new coordinates
text = entities.add_text "This is a Test", point
parent = entities.parent


 

transform_by_vectors

The transform_by_vectors method is used to apply several vectors to several entities all at once.

Syntax:

entities = entities.transform_by_vectors entities vectors

Arguments:

 

Return Value:

 

Comments:

 

Example:

 


 

transform_entities

The transform_entities method is used to apply a transformation to the collection of entities.

Syntax:

status = entities.transform_entities transformation entity1, entity2, entity3, ...

status = entities.transform_entities transformation [ent1, ent2, ent3, ...]

Arguments:

entity1 - an entity that will be transformed

transformation - the transformation applied to the entities

Return Value:

status - true if successful, false if unsuccessful

Comments:

 

Example:

model = Sketchup.active_model
entities = model.active_entities
point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (20,20,20)
t = Geom::Transformation.new
line = entities.add_line point1,point2
begin
status = entities.transform_entities t, line
rescue
UI.messagebox $!.message
end