Entities

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