|
SketchUp Ruby API Reference |
The Entities class is a container class for all entities in a model (it is a collection of Entity objects).
Parent: Object
Methods: [], add_3d_text, 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_observer, add_text, at, clear!, count, each, erase_entities, intersect_with, length, model, parent, remove_observer, transform_by_vectors, transform_entities
Example Code: entitiestests.rb
The [] method is used to retrieve an entity by its index in an array of entities.
entity = entities[index]
index - the index for a specific entity
entity - an Entity object if successful, nil if not found
entity1 = entities[1]
if (entity1)
UI.messagebox entity1
else
UI.messagebox "Failure"
end
The add_3d_text is used to create 3D text.
construction_point = entities.add_3d_text string, alignment, fontName, bold, italic, worldSize, tol, baseZ,filled,extrusion
type is TextAlignRight, TextAnlignRight, TextAlignCenter
worldSize (see 3D text dialog)
The add_arc method is used to create an arc curve segment.
arccurve = entities.add_arc center, xaxis, normal, radius, start_angle, end_angle, numsegs)
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
arccurve - an ArcCurve object if successful
centerpoint = Geom::Point3d.new# Create a circle perpendicular to the normal or Z axisvector = Geom::Vector3d.new 0,0,1vector2 = Geom::Vector3d.new 1,0,0vector3 = vector.normalize!model = Sketchup.active_modelentities = model.active_entitiesarccurve = entities.add_arc centerpoint, vector2, vector3, 10, 15, 35UI.messagebox arccurve
The add_circle method is used to create a circle
circle = entities.add_circle center, normal, radius, <numseg>
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
circle - an Array object containing edges if successful
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
The add_cline method is used to create a construction line.
construction_line = entities.add_cline point, vector
construction_line = entities.add_cline point1, point2, <stipple>
point, point1, point2 - a Point3d object
vector - a Vector3d object
<stipple> - an optional stipple pattern. See ConstructionLine.stipple for acceptable patterns.
construction_line - a ConstructionLine object if successful
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
The add_cpoint method is used to create a construction point.
construction_point = entities.add_cpoint point
point - a Point3d object
construction_point - a ConstructionPoint object if successful
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
The add_curve method is used to create a curve from a collection of edges.
curve = entities.add_curve point1, point2, point3, ...
curve = entities.add_curve [point1, point2, point3, ...]
point1 point2, point3... - a Point3d object
[point1, point2, point3...] - an array of Point3d objects
curve - a Curve object if successful
The arguments are either Points or an Array of Points. At least 2 points are required.
The add_edges method is used to add a set of connected edges to the entities array.
edges = enties.add_edges point1, point2, ...
point1 - a Point3d object
edges - an array of Edge objects if successful
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
The add_face method is used to create a face.
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
edge1 - a Edge object
point1 - a Point3d object
curve - a Curve object
face - a Face object if successful
For the last form that takes a Curve, the curve must be closed - like a circle.
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
the add_faces_from_mesh is used to add Face objects to the collection of entities from a PolygonMesh.
faces = entities.add_faces_from_mesh polygonmesh
polygonmesh - a Polygon mesh object
faces - an array of Face objects if successful
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
The add_group method is used to create an empty group.
group = entities.add_group
group - an empty Group object if successful
model = Sketchup.active_model
entities = model.active_entities
group = entities.add_group
if (group)
UI.Messagebox group
else
UI.Messagebox "Failure"
end
The add_image method is used to add an image to the collection of entities.
image = entities.add_image filename, point, width, <height>
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.
image - an Image object if successful.
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.
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
The add_instance method adds a component instance to the collection of entities.
componentinstance = entities.add_instance componentdefinition, transformation
componentdefinition - a ComponentDefinition object
transformation - a Transformation object
componentinstance - a ComponentInstance object 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 "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
The add_line method is used to add an edge to the collection of entities.
edge = entities.add_line point1, point2
point1 - a Point3d object representing the starting point of the line
point2 - a Point3d object representing the ending point of the line
edge - a Edge object if successful
This method is the same as add_edges method, but returns a single edge.
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
The add_observer method is used to add an observer to the current object.
status = object.add_observer observer
observer - an observer
true if successful, false if unsuccessful.
The add_ngon method is used to create a multi-sided polygon.
edges - entities.add_ngon center, normal, radius, numsides
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
edges - an array of Edges that make up the polygon if successful
The add_text method adds a note or label text entity to the entities
text = entities.add_text "text", point, <vector>
text - the text string to add
point - a Point3d object representing the insertion point
<vector> - (optional) vector representing the direction of the text
text - a Text object if successful
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.
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
The at method is an alias for []. See [].
The clear! method is used to remove all entities from the collection of entities.
status = entities.clear!
status - true if successful, false if unsuccessful
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!
The count method is an alias for the length method. See length.
The each method is used to iterate through the entities in the collection of entities.
entities.each { | entity | ... }
entity - a variable that will hold each Entity object as they are found if successful
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 }
The erase_entities method is used to erase one or more entities from the model.
entities.erase_entities entities
entities - an entity or array of entities
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
The intersect_with method is used to intersect an entities, component instance, or group object with a entities object.
entities.intersect_with recurse, transformation1, entities1, transformation2, hidden, entites2
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
The length method is used to retrieve the number of entities in the collection of entities.
length = entities.length
length - the number of entities in the collection of entities if successful
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
The model method is used to retrieve the model that contains the collection of entities.
model = entities.model
model - the model that contains the collection of entities if successful
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
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.
parent = entities.parent
parent - the object that contains the collection of entities if successful
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
The remove_observer method is used to remove an observer from the current object.
status = object.remove_observer observer
observer - an observer
true if successful, false if unsuccessful.
The transform_by_vectors method is used to apply several vectors to several entities all at once.
entities = entities.transform_by_vectors entities vectors
The transform_entities method is used to apply a transformation to the collection of entities.
status = entities.transform_entities transformation entity1, entity2, entity3, ...
status = entities.transform_entities transformation [ent1, ent2, ent3, ...]
entity1 - an entity that will be transformed
transformation - the transformation applied to the entities
status - true if successful, false if unsuccessful
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