class Sketchup::Entities

The {Sketchup::Entities} class is a collection of Entity objects, either in a {Sketchup::ComponentDefinition} or directly in the {Sketchup::Model}. A {Sketchup::Entities} object corresponds to a drawing context in the GUI.

@version SketchUp 6.0

Public Instance Methods

[](entity_index) click to toggle source

The {#[]} method is used to retrieve an entity by its index in an array of entities. The index is a number between 0 and entities.length - 1. In general, it is preferable to use the {#each} method to iterate though all of the entities in the collection as it will be much more efficient.

@example

entities = Sketchup.active_model.entities
entity = entities[0]

@param [Integer] entity_index

The index for a specific entity.

@return [Sketchup::Entity, nil] an {Sketchup::Entity} object if successful,

+nil+ if not found

@see at

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 35
def [](entity_index)
end
active_section_plane() click to toggle source

The active_section_plane method is used to access the currently active section plane in the Entities object.

@example

sp = Sketchup.active_model.entities.active_section_plane
puts "Active section plane is #{sp}" if !sp.nil?

@return [Sketchup::SectionPlane, nil] the active SectionPlane or nil if none is active.

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 48
def active_section_plane
end
active_section_plane=(sec_plane) click to toggle source

The active_section_plane= method is used to set the active section plane in the Entities object.

@example

entities = Sketchup.active_model.entities
sp = entities.add_section_plane([50, 50, 0], [1.0, 1.0, 0])
entities.active_section_plane = sp

@param [Sketchup::SectionPlane, nil] sec_plane

the SectionPlane object to be set active. Pass nil to
deactivate any active section plane.

@return [Sketchup::SectionPlane, nil] the SectionPlane object that was set active.

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 66
def active_section_plane=(sec_plane)
end
add_3d_text(string, alignment, font, is_bold = false, is_italic = false, letter_height = 1.0, tolerance = 0.0, z = 0.0, is_filled = true, extrusion = 0.0) click to toggle source

The add_3d_text is used to create 3D text. It will be added as edges and faces drawn at the origin.

@example

# Draw the word "test" at the origin of the model, aligned left, in
# Arial Bold, not italics, 1" in size, best tolerance quality, filled,
# with an extrusion size of 5".
entities = Sketchup.active_model.entities
success = entities.add_3d_text('test', TextAlignLeft, "Arial",
  true, false, 1.0, 0.0, 0.5, true, 5.0)

@param [String] string

The text to create.

@param [Integer] alignment

Number that defines the alignment. There are constants
called TextAlignLeft, TextAlignRight, and
TextAlignCenter that can be passed.

@param [String] font

font name.

@param [Boolean] is_bold

true for bold.

@param [Boolean] is_italic

true for italic.

@param [Numeric] letter_height

Height of the text in inches.

@param [Numeric] tolerance

Tolerance of the curve creation. Defaults to
0.0, which creates the highest possible curve quality.

@param [Numeric] z

z position in inches.

@param [Boolean] is_filled

true for filled, which will put a face between the edges of the letters.

@param [Numeric] extrusion

Extrusion depth in inches.

@return [Boolean] true if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 116
def add_3d_text(string, alignment, font, is_bold = false, is_italic = false, letter_height = 1.0, tolerance = 0.0, z = 0.0, is_filled = true, extrusion = 0.0)
end
add_arc(*args) click to toggle source

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

@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
edges = entities.add_arc centerpoint, vector2, vector3, 10, 15.degrees, 135.degrees
arccurve = edges.first.curve

@overload add_arc(center, xaxis, normal, radius, start_angle, end_angle)

@param [Geom::Point3d]  center      A Point3d object representing the center .
@param [Geom::Vector3d] xaxis       A Vector3d object representing xaxis for the arc.
@param [Geom::Vector3d] normal      A Vector3d object representing normal for the arc.
@param [Numeric]        radius      The radius of the arc.
@param [Numeric]        start_angle Start angle for the arc, in radians.
@param [Numeric]        end_angle   End angle for the arc, in radians.
@return [Array<Sketchup::Edge>]     an array of Edge objects that define the arc.

@overload add_arc(center, xaxis, normal, radius, start_angle, end_angle, num_segments)

@param [Geom::Point3d]  center       A Point3d object representing the center .
@param [Geom::Vector3d] xaxis        A Vector3d object representing xaxis for the arc.
@param [Geom::Vector3d] normal       A Vector3d object representing normal for the arc.
@param [Numeric]        radius       The radius of the arc.
@param [Numeric]        start_angle  Start angle for the arc, in radians.
@param [Numeric]        end_angle    End angle for the arc, in radians.
@param [Integer]        num_segments How many segments to draw.
@return [Array<Sketchup::Edge>]      an array of Edge objects that define the arc.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 154
def add_arc(*args)
end
add_circle(center, normal, radius, numsegs = 24) click to toggle source

The add_circle method is used to create a circle.

@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

@param [Geom::Point3d] center

A Point3d object representing the center.

@param [Geom::Vector3d] normal

A Vector3d object representing normal for the arc.

@param [Numeric] radius

The radius of the arc.

@param [Integer] numsegs

The number of segments.

@return [Array<Sketchup::Edge>] an Array object containing edges if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 183
def add_circle(center, normal, radius, numsegs = 24)
end
add_cline(*args) click to toggle source

The {#add_cline} method is used to create a construction line. This can be finite or infinite.

@example

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

@overload add_cline(start_point, end_point, stipple = '-')

Creates a finite construction line.
@param [Geom::Point3d] start_point
@param [Geom::Point3d] end_point
@param [String] stipple  See {ConstructionLine#stipple=} for acceptable
  patterns.

@overload add_cline(point, vector, stipple = '-')

Creates an infinite construction line.
@param [Geom::Point3d] point
@param [Geom::Point3d] vector
@param [String] stipple  See {ConstructionLine#stipple=} for acceptable
  patterns.

@return [Sketchup::ConstructionLine]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 215
def add_cline(*args)
end
add_cpoint(point) click to toggle source

The add_cpoint method is used to create a construction point.

@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

@param [Geom::Point3d] point

A Point3d object.

@return [Sketchup::ConstructionPoint] a ConstructionPoint object if

successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 238
def add_cpoint(point)
end
add_curve(*args) click to toggle source

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

The arguments are either Points or an Array of Points. At least 2 points are required.

@example

entities = Sketchup.active_model.entities
curve = entities.add_curve [0,0,0], [0,10,0], [1,20,0]

@overload add_curve(points)

@param [Array<Geom::Point3d>] points

@overload add_curve(*points)

@param [Array<Geom::Point3d>] points

@return [Array<Sketchup::Edge>]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 261
def add_curve(*args)
end
add_dimension_linear(*args) click to toggle source

The {#add_dimension_linear} method adds a linear dimension to the entities.

@example

entities = Sketchup.active_model.entities
# From point to point
dim = entities.add_dimension_linear [50, 10, 0], [100, 10, 0], [0, 20, 0]
# Between edge vertices
edge = entities.add_edges([50,50,0], [40,10,0])[0]
v0 = edge.start
v1 = edge.end
dim = entities.add_dimension_linear v0, v1, [0, 0, 20]
# From an edge's midpoint to a construction point
p0 = edge.start.position
p1 = edge.end.position
mp = Geom::Point3d.new((p0.x+p1.x)/2.0, (p0.y+p1.y)/2.0, (p0.z+p1.z)/2.0)
cp = entities.add_cpoint [50, 10, 0]
dim = entities.add_dimension_linear [edge, mp], cp, [20, 0, 0]
# alternatively, the start params could be passed in separately
dim = entities.add_dimension_linear edge, mp, cp, [20, 0, 0]

@example Instance path

instance = Sketchup.active_model.active_entities.grep(Sketchup::ComponentInstance).first
edge = instance.definition.entities.grep(Sketchup::Edge).first
instance_path = Sketchup::InstancePath.new([instance, edge])
start_point = edge.start.position
end_point = edge.end.position
vector = Geom::Vector3d.new(30, 30, 0)
Sketchup.active_model.entities.add_dimension_linear([instance_path, start_point], [instance_path, end_point], vector)

@example Instance path as an array

instance = Sketchup.active_model.active_entities.grep(Sketchup::ComponentInstance).first
edge = instance.definition.entities.grep(Sketchup::Edge).first
path = [instance, edge]
start_point = edge.start.position
end_point = edge.end.position
vector = Geom::Vector3d.new(30, 30, 0)
Sketchup.active_model.entities.add_dimension_linear([path, start_point], [path, end_point], vector)

@overload add_dimension_linear(start_pt_or_entity, end_pt_or_entity, offset_vector)

@param [Geom::Point3d, Sketchup::Entity] start_pt_or_entity
  the reference point and/or entity at the start of
  the dimension. This parameter can take several
  forms:
@param [Geom::Point3d, Sketchup::Entity] end_pt_or_entity
  the reference point and/or entity at the end
  of the dimension. This parameter takes the exact
  same forms as 'start_pt_or_entity'.
@param [Geom::Vector3d] offset_vector
  the parallel offset vector from the reference line
  to the dimension line measured from the 'start'
  reference point.

@overload add_dimension_linear(start_instance_path, end_instance_path, offset_vector)

@note Added in SketchUp 2019.
@param [Array<Sketchup::InstancePath, Geom::Point3d>] start_instance_path An array
  containing a {Sketchup::InstancePath} and a {Geom::Point3d}.
@param [Array<Sketchup::InstancePath, Geom::Point3d>] end_instance_path An array
  containing a {Sketchup::InstancePath} and a {Geom::Point3d}.
@param [Geom::Vector3d] offset_vector The parallel offset vector from the
  reference line to the dimension line measured from the start reference
  point.

@overload add_dimension_linear(start_array, end_array, offset_vector)

@note Added in SketchUp 2019.
@param [Array(Array<Entity>, Geom::Point3d)] start_array
  The {Array<Entity>} must contain one or more {Sketchup::ComponentInstance}'s
  and a leaf entity. The leaf entity can be a {Sketchup::Vertex},
  {Sketchup::ConstructionPoint}, {Sketchup::ConstructionLine}, or
  {Sketchup::Edge}. The {Geom::Point3d} is the point associated with the leaf entity.
@param [Array(Array<Entity>, Geom::Point3d)] end_array
  The {Array<Entity>} must contain one or more {Sketchup::ComponentInstance}'s
  and a leaf entity. The leaf entity can be a {Sketchup::Vertex},
  {Sketchup::ConstructionPoint}, {Sketchup::ConstructionLine}, or
  {Sketchup::Edge}. The {Geom::Point3d} is the point associated with the leaf entity.
@param [Geom::Vector3d] offset_vector The parallel offset vector from the
  reference line to the dimension line measured form the start reference
  point.

@return [Sketchup::DimensionLinear] the created dimension

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 348
def add_dimension_linear(*args)
end
add_dimension_radial(arc_curve, leader_break_pt) click to toggle source

The add_dimension_radial method adds a radial dimension (i.e arc/circle radius/diameter dimension) to the entities.

@example

entities = Sketchup.active_model.entities
# Create a circle
centerpoint = Geom::Point3d.new(10, 10, 0)
vector = Geom::Vector3d.new(0, 0, 1)
edges = entities.add_circle centerpoint, vector, 10
circle = edges[0].curve
dim = entities.add_dimension_radial circle, [30, 30, 0]

@param [Sketchup::ArcCurve] arc_curve

an ArcCurve object to which the dimension is to be
attached.

@param [Geom::Point3d] leader_break_pt

a Point3d for the break point on the leader where the
dimension text is attached.

@return [Sketchup::DimensionRadial] the created dimension

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 374
def add_dimension_radial(arc_curve, leader_break_pt)
end
add_edges(*args) click to toggle source

The {#add_edges} method is used to add a set of connected edges to the {Sketchup::Entities} collection.

@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

@note If the points form a closed loop, the first and last vertex will not

merge. If you intend to create a face from the edges, use {#add_face}
directly.

@overload add_edges(points)

@param [Array<Geom::Point3d>] points At least two points required.
@return [Array<Sketchup::Edge>]

@overload add_edges(*points)

@param [Array<Geom::Point3d>] points At least two points required.
@return [Array<Sketchup::Edge>]

@return [Array<Sketchup::Edge>] an array of Edge objects if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 404
def add_edges(*args)
end
add_face(*args) click to toggle source

The add_face method is used to create a face. You can call this method a number of ways:

- entities.add_face(edge1, edge2, edge3, ...)
- entities.add_face(edgearray)
- entities.add_face(pt1, pt2, pt3, ...)
- entities.add_face([pt1, pt2, pt3,...])
- entities.add_face(curve)

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

Note that a special case exists for any face created on the ground plane, in which case the vertex order is ignored and the face is always facing down.

@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)

@overload add_face(entities)

@param [Array<Sketchup::Edge>, Array<Geom::Point3d>, Sketchup::Curve] entities

@overload add_face(*entities)

@param [Array<Sketchup::Edge>, Array<Geom::Point3d>] entities

@return [Sketchup::Face, nil]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 446
def add_face(*args)
end
add_faces_from_mesh(polygon_mesh, smooth_flags = Geom::PolygonMesh::AUTO_SOFTEN|Geom::PolygonMesh::SMOOTH_SOFT_EDGES, f_material = nil, b_material = nil) click to toggle source

The {#add_faces_from_mesh} method is used to add Face objects to the collection of entities from a PolygonMesh.

The smooth_flags parameter can contain any of the following values if passed. The constants were added in SketchUp 2014. For previous versions, numeric values have to be specified instead of the Ruby constants.

  • 0: {Geom::PolygonMesh::NO_SMOOTH_OR_HIDE}

  • 1: {Geom::PolygonMesh::HIDE_BASED_ON_INDEX} (Negative point index will hide the edge.)

  • 2: {Geom::PolygonMesh::SOFTEN_BASED_ON_INDEX} (Negative point index will soften the edge.)

  • 4: {Geom::PolygonMesh::AUTO_SOFTEN} (Interior edges are softened.)

  • 8: {Geom::PolygonMesh::SMOOTH_SOFT_EDGES} (All soft edges will also be smooth.)

The 3rd and 4th parameters will accept a {sketchup::Material} object or a string name of a material currently in the model.

@example

pm = Geom::PolygonMesh.new
pm.add_point([ 0, 0, 0]) # 1
pm.add_point([10, 0, 0]) # 2
pm.add_point([10,10, 0]) # 3
pm.add_point([ 0,10, 0]) # 4
pm.add_point([20, 0, 5]) # 5
pm.add_point([20,10, 5]) # 6
pm.add_polygon(1, -2, 3, 4)
pm.add_polygon(2, 5,6, -3)

# Create a new group that we will populate with the mesh.
group = Sketchup.active_model.entities.add_group
material = Sketchup.active_model.materials.add('green')
smooth_flags = Geom::PolygonMesh::NO_SMOOTH_OR_HIDE
group.entities.add_faces_from_mesh(pm, smooth_flags, material)

@param [Geom::PolygonMesh] polygon_mesh

@param [Integer] smooth_flags

flags for softening and smoothing of edges.

@param [Sketchup::Material, String] f_material

material to paint front faces with.

@param [Sketchup::Material, String] b_material

material to paint back faces with.

@return [Integer] Number of faces created

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 496
def add_faces_from_mesh(polygon_mesh, smooth_flags = Geom::PolygonMesh::AUTO_SOFTEN|Geom::PolygonMesh::SMOOTH_SOFT_EDGES, f_material = nil, b_material = nil)
end
add_group(*args) click to toggle source

The add_group method is used to create an empty group or a group with entities.

@example

model = Sketchup.active_model
entities = model.active_entities
group = entities.add_group

@note Calling add_group with entities in its parameters has been known to

crash SketchUp before version 8.0. It is preferable to create an empty
group and then add things to its Entities collection.

@overload add_group(entities)

@param [Array<Sketchup::Entity>] entities
  an entities collection to add to the group.

@overload add_group(*entities)

@param [Array<Sketchup::Entity>] entities
  an entities collection to add to the group.

@return [Sketchup::Group]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 524
def add_group(*args)
end
add_image(path, point, width, height = 0.0) click to toggle source

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

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, 300
if (image)
  UI.messagebox image
else
  UI.messagebox "Failure"
end

@param [String] path

A path for the image file.

@param [Geom::Point3d] point

A Point3d object representing the insertion point of
the image.

@param [Numeric] width

Width for the image.

@param [Numeric] height

height for the image if you want to control
width and height independently. Leave as default +0.0+ when you want it
to be relative to the aspect ratio.

@return [Sketchup::Image, nil] an Image object if successful.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 562
def add_image(path, point, width, height = 0.0)
end
add_instance(definition, transform) click to toggle source

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

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

@param [Sketchup::ComponentDefinition] definition

A ComponentDefinition object.

@param [Geom::Transformation] transform

A Transformation object.

@return [Sketchup::ComponentInstance] a ComponentInstance object if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 593
def add_instance(definition, transform)
end
add_line(point1, point2) click to toggle source

The add_line method is used to add an edge to the collection of entities. This is not to be confused with the concept of a “line” from a geometric sense, which is an invisible object represented by an Array of a point and a vector. (See the Array class for more information on geometric lines in SketchUp.)

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

@param [Geom::Point3d] point1

Point3d object representing the edge's starting point.

@param [Geom::Point3d] point2

Point3d object representing the edge's ending point.

@return [Sketchup::Edge] a Edge object if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 625
def add_line(point1, point2)
end
add_ngon(center, normal, radius, numsides = 24) click to toggle source

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

@example

entities = Sketchup.active_model.entities
center = Geom::Point3d.new
normal = Geom::Vector3d.new(0,0,1)
radius = 100
numsides = 6
edges = entities.add_ngon center, normal, radius, numsides

@param [Geom::Point3d] center

A Point3d object representing the center of the polygon.

@param [Geom::Vector3d] normal

A Vector3d object.

@param [Numeric] radius

A radius.

@param [Integer] numsides

The number of sides for the polygon.

@return [Array<Sketchup::Edge>] an array of Edges that make up the polygon if

successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 654
def add_ngon(center, normal, radius, numsides = 24)
end
add_observer(observer) click to toggle source

The add_observer method is used to add an observer to the current object.

@example

entities = Sketchup.active_model.entities
status = entities.add_observer observer

@param [Object] observer

An observer.

@return [Boolean] true if successful, false if unsuccessful.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 669
def add_observer(observer)
end
add_section_plane(plane) click to toggle source

The add_section_plane method adds a section plane object to the entities.

@example

# Create a section plane
model = Sketchup.active_model
sp = model.entities.add_section_plane([50, 50, 0], [1.0, 1.0, 0])
# Activate it
sp.activate
# Make sure section planes are visible
model.rendering_options['DisplaySectionPlanes'] = true

@param plane

the geometric plane where the SectionPlane object is to
be created. Refer to the Geom module for information on
how planes are represented.

@return [Sketchup::SectionPlane, nil] the created SectionPlane object if

successful, nil on failure.

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 692
def add_section_plane(plane)
end
add_text(*args) click to toggle source

The {#add_text} method adds a note or label text entity to the entities.

@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

@example Instance path

instance = Sketchup.active_model.active_entities.grep(Sketchup::ComponentInstance).first
edge = instance.definition.entities.grep(Sketchup::Edge).first
instance_path = Sketchup::InstancePath.new([instance, edge])
point = edge.start.position
vector = Geom::Vector3d.new(30, 30, 0)
Sketchup.active_model.entities.add_text("mytext", [instance_path, point], vector)

@example Instance path as an array

instance = Sketchup.active_model.active_entities.grep(Sketchup::ComponentInstance).first
edge = instance.definition.entities.grep(Sketchup::Edge).first
path = [instance, edge]
point = edge.start.position
vector = Geom::Vector3d.new(30, 30, 0)
Sketchup.active_model.entities.add_text("mytext", [path, point], vector)

@overload add_text(text, point, vector)

@bug SketchUp 2019.0 had a regression bug where an error was thrown if
  +point+ was provided as a {Sketchup::Vertex} or {Sketchup::InputPoint}.
  This was fixed in SketchUp 2019.1.
@param [String] text The text string to add.
@param [Geom::Point3d, Sketchup::Vertex, Sketchup::InputPoint] point
  A Point3d object representing the insertion point.
@param [Geom::Vector3d] vector The Vector representing an arrow leader.

@overload add_text(text, instance_path_and_pt, vector)

@version SketchUp 2019
@param [String] text The text to add.
@param [Array<Sketchup::InstancePath, Geom::Point3d>] instance_path_and_pt
  The array containing a {Sketchup::InstancePath} and a {Geom::Point3d}.
@param [Geom::Vector3d] vector The vector representing an arrow leader.

@overload add_text(text, instance_array_and_pt, vector)

@version SketchUp 2019
@param [String] text The text to add.
@param [Array(Array<Sketchup::Entity>, Geom::Point3d)] instance_array_with_pt
  The array containing one or more {Sketchup::ComponentInstance}'s and a
  leaf entity. The leaf entity can be a {Sketchup::Vertex},
  {Sketchup::ConstructionPoint}, {Sketchup::ConstructionLine}, or
  {Sketchup::Edge}. The {Geom::Point3d} is the point associated with the
  leaf entity.
@param [Geom::Vector3d] vector The vector representing an arrow leader.

@return [Sketchup::Text] a Text object if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 753
def add_text(*args)
end
at(entity_index) click to toggle source

The {#at} method is an alias for {#[]}.

@example

entities = Sketchup.active_model.entities
entity = entities.at(0)

@param [Integer] entity_index

The index for a specific entity.

@return [Sketchup::Entity, nil]

@see []

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 770
def at(entity_index)
end
clear!() click to toggle source

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

@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!

@return [Boolean] true if successful, false if unsuccessful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 788
def clear!
end
count() click to toggle source

@example

model = Sketchup.active_model
entities = model.entities
entities.add_cpoint([10, 10, 10])
number = entities.count

@note Since SketchUp 2014 the count method is inherited from Ruby's

+Enumable+ mix-in module. Prior to that the {#count} method is an alias
for {#length}.

@return [Integer]

@see length

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 807
def count
end
each() click to toggle source

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

@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| puts entity }

@note Don't remove content from this collection while iterating over it with

{#each}. This would change the size of the collection and cause elements to
be skipped as the indices change. Instead copy the current collection to an
array using +to_a+ and then use +each+ on the array, when removing content.

@return [nil]

@version SketchUp 6.0

@yieldparam [Sketchup::Entity] entity

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 831
def each
end
erase_entities(*args) click to toggle source

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

@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, so erase it.
UI.messagebox entities
entities.erase_entities entities[1]
UI.messagebox entities

@overload erase_entities(entities)

@param [Array<Sketchup::Entity>] entities

@overload erase_entities(*entities)

@param [Array<Sketchup::Entity>] entities

@return [nil]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 868
def erase_entities(*args)
end
fill_from_mesh(polygon_mesh, weld_vertices = true, smooth_flags = Geom::PolygonMesh::AUTO_SOFTEN|Geom::PolygonMesh::SMOOTH_SOFT_EDGES, f_material = nil, b_material = nil) click to toggle source

The {#fill_from_mesh} method is used to add faces and edges to the collection of entities from a {Geom::PolygonMesh}. It requires that the entities collection to be filled is empty. It has higher performance than {#add_faces_from_mesh}, but does less error checking as it builds the geometry.

The smooth_flags parameter can contain any of the following values if passed. The constants were added in SketchUp 2014. For previous versions, numeric values have to be specified instead of the Ruby constants:

  • 0: {Geom::PolygonMesh::NO_SMOOTH_OR_HIDE}

  • 1: {Geom::PolygonMesh::HIDE_BASED_ON_INDEX} (Negative point index will hide the edge.)

  • 2: {Geom::PolygonMesh::SOFTEN_BASED_ON_INDEX} (Negative point index will soften the edge.)

  • 4: {Geom::PolygonMesh::AUTO_SOFTEN} (Interior edges are softened.)

  • 8: {Geom::PolygonMesh::SMOOTH_SOFT_EDGES} (All soft edges will also be smooth.)

The 4rd and 5th parameters will accept a {Sketchup::Material} object or a string name of a material currently in the model.

@example

pm = Geom::PolygonMesh.new
pm.add_point([ 0, 0, 0]) # 1
pm.add_point([10, 0, 0]) # 2
pm.add_point([10,10, 0]) # 3
pm.add_point([ 0,10, 0]) # 4
pm.add_point([20, 0, 5]) # 5
pm.add_point([20,10, 5]) # 6
pm.add_polygon(1, -2, 3, 4)
pm.add_polygon(2, 5, 6, -3)

# Create a new group that we will populate with the mesh.
group = Sketchup.active_model.entities.add_group
material = Sketchup.active_model.materials.add('red')
smooth_flags = Geom::PolygonMesh::HIDE_BASED_ON_INDEX
group.entities.fill_from_mesh(pm, true, smooth_flags, material)

@param [Geom::PolygonMesh] polygon_mesh

@param [Boolean] weld_vertices

This argument has no effect and is kept for
compatibility reasons. Points are always
merged.

@param [Integer] smooth_flags

flags for softening and smoothing of edges.

@param [Sketchup::Material, String] f_material

material to paint front faces with.

@param [Sketchup::Material, String] b_material

material to paint back faces with.

@return [Boolean]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 926
def fill_from_mesh(polygon_mesh, weld_vertices = true, smooth_flags = Geom::PolygonMesh::AUTO_SOFTEN|Geom::PolygonMesh::SMOOTH_SOFT_EDGES, f_material = nil, b_material = nil)
end
intersect_with(recurse, transform1, entities1, transform2, hidden, entities2) click to toggle source

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

@example

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

@param [Boolean] 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).

@param [Geom::Transformation] transform1

The transformation for this entities object.

@param [Sketchup::Entities] entities1

The entities object where you want the intersection
lines to appear.

@param [Geom::Transformation] transform2

The transformation for entities1.

@param [Boolean] hidden

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

@param [Sketchup::Entity, Array<Sketchup::Entity>] entities2

A single entity, or an array of entities.

@return [nil]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 961
def intersect_with(recurse, transform1, entities1, transform2, hidden, entities2)
end
length() click to toggle source

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

@example

model = Sketchup.active_model
entities = model.entities
entities.add_cpoint([10, 10, 10])
number = entities.length

@return [Integer]

@see size

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 978
def length
end
model() click to toggle source

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

@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

@return [Sketchup::Model] the model that contains the collection of

entities if successful.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 996
def model
end
parent() click to toggle source

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.

@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

@return [Sketchup::ComponentDefinition, Sketchup::Model] the object that

contains the collection of entities if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 1015
def parent
end
remove_observer(observer) click to toggle source

The remove_observer method is used to remove an observer from the current object.

@example

entities = Sketchup.active_model.entities
status = entities.remove_observer observer

@param [Object] observer

An observer.

@return [Boolean] true if successful, false if unsuccessful.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 1031
def remove_observer(observer)
end
size() click to toggle source

The {#size} method is an alias for the {#length} method.

@example

model = Sketchup.active_model
entities = model.entities
entities.add_cpoint([10, 10, 10])
number = entities.size

@return [Integer]

@see length

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 1047
def size
end
transform_by_vectors(sub_entities, vectors) click to toggle source

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

@example

# Raise vertices in selection by their distance to the origin.
model = Sketchup.active_model
entities = model.active_entities
with_vertices = entities.select { |entity| entity.respond_to?(:vertices) }
vertices = with_vertices.flat_map(&:vertices).uniq
lengths = vertices.map { |vertex| vertex.position.distance(ORIGIN) }
vectors = lengths.map { |length| Geom::Vector3d.new(0, 0, length) }

entities.transform_by_vectors(vertices, vectors)

@param [Array<Sketchup::Entity>] sub_entities

An array of entities to transform.

@param [Array<Geom::Vector3d>] vectors

An array of vectors to apply.

@return [Sketchup::Entities]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 1073
def transform_by_vectors(sub_entities, vectors)
end
transform_entities(transform, entities) click to toggle source

The transform_entities method is used to apply a transform to several sub-entities all at once.

If you are transforming entities in the active drawing context or any of its parent drawing contexts, the transformation will be interpreted as relative to the global coordinate system. Otherwise the transformation will be interpreted as being on the local coordinate system.

@example

entities = Sketchup.active_model.entities
entity1 = entities.add_line([0,0,0],[100,100,100])
entity2 = entities.add_line([0,0,0],[200,-10,-10])

transformation = Geom::Transformation.new([100,0,0])
entities.transform_entities(transformation, [entity1, entity2])

@param [Geom::Transformation] transform

The Transformation to apply.

@param [Array<Sketchup::Entity>] entities

An array or series of entities to transform.

@return [Boolean] false if the entities array was empty.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 1101
def transform_entities(transform, entities)
end
weld(edges) click to toggle source

The {#weld} method takes a set of edges and find all possible chains of edges and connect them with a {Sketchup::Curve}.

A curve will not cross another curve. They will split where multiple curves meet.

@example

model = Sketchup.active_model
edges = model.selection.grep(Sketchup::Edge)
curves = model.active_entities.weld(edges)

@param [Array<Sketchup::Edge>] edges

@raise [ArgumentError] if the given entities are not part of the same

{Sketchup::Entities} collection.

@return [Array<Sketchup::Curve>]

@version SketchUp 2020.1

# File lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb, line 1123
def weld(edges)
end