Class: Sketchup::Entities

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb

Overview

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

Version:

  • SketchUp 6.0

Instance Method Summary collapse

Instance Method Details

#[](entity_index) ⇒ Sketchup::Entity?

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.

Examples:

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

Parameters:

  • entity_index (Integer) —

    The index for a specific entity.

Returns:

See Also:

Version:

  • SketchUp 6.0



35
36
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 35

def [](entity_index)
end

#active_section_plane ⇒ Sketchup::SectionPlane?

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

Examples:

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

Returns:

Version:

  • SketchUp 2014



48
49
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 48

def active_section_plane
end

#active_section_plane=(sec_plane) ⇒ Sketchup::SectionPlane?

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

Examples:

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

Parameters:

  • sec_plane (Sketchup::SectionPlane, nil) —

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

Returns:

Version:

  • SketchUp 2014



66
67
 
# 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) ⇒ Boolean

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

1.0, tolerance = 0.0, z = 0.0, is_filled = true, extrusion = 0.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.

Examples:

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

Returns:

  • (Boolean) —

    true if successful

Version:

  • SketchUp 6.0



118
119
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 118

def add_3d_text(string, alignment, font, is_bold = false, is_italic = false, letter_height)
end

#add_arc(center, xaxis, normal, radius, start_angle, end_angle) ⇒ Array<Sketchup::Edge> #add_arc(center, xaxis, normal, radius, start_angle, end_angle, num_segments) ⇒ Array<Sketchup::Edge>

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

Examples:

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

Overloads:

  • #add_arc(center, xaxis, normal, radius, start_angle, end_angle) ⇒ Array<Sketchup::Edge>

    Returns an array of Edge objects that define the arc.

    Parameters:

    • center (Geom::Point3d) —

      A Point3d object representing the center .

    • xaxis (Geom::Vector3d) —

      A Vector3d object representing xaxis for the arc.

    • normal (Geom::Vector3d) —

      A Vector3d object representing normal for the arc.

    • radius (Numeric) —

      The radius of the arc.

    • start_angle (Numeric) —

      Start angle for the arc, in radians.

    • end_angle (Numeric) —

      End angle for the arc, in radians.

    Returns:

  • #add_arc(center, xaxis, normal, radius, start_angle, end_angle, num_segments) ⇒ Array<Sketchup::Edge>

    Returns an array of Edge objects that define the arc.

    Parameters:

    • center (Geom::Point3d) —

      A Point3d object representing the center .

    • xaxis (Geom::Vector3d) —

      A Vector3d object representing xaxis for the arc.

    • normal (Geom::Vector3d) —

      A Vector3d object representing normal for the arc.

    • radius (Numeric) —

      The radius of the arc.

    • start_angle (Numeric) —

      Start angle for the arc, in radians.

    • end_angle (Numeric) —

      End angle for the arc, in radians.

    • num_segments (Integer) —

      How many segments to draw.

    Returns:

Version:

  • SketchUp 6.0



156
157
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 156

def add_arc(*args)
end

#add_circle(center, normal, radius, numsegs = 24) ⇒ Array<Sketchup::Edge>

The add_circle method is used to create a circle.

Examples:

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

Parameters:

  • center (Geom::Point3d) —

    A Point3d object representing the center.

  • normal (Geom::Vector3d) —

    A Vector3d object representing normal for the arc.

  • radius (Numeric) —

    The radius of the arc.

  • numsegs (Integer) (defaults to: 24) —

    The number of segments.

Returns:

Version:

  • SketchUp 6.0



185
186
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 185

def add_circle(center, normal, radius, numsegs = 24)
end

#add_cline(start_point, end_point, stipple = '-') ⇒ Sketchup::ConstructionLine #add_cline(point, vector, stipple = '-') ⇒ Sketchup::ConstructionLine

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

Examples:

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)

Overloads:

Returns:

Version:

  • SketchUp 6.0



217
218
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 217

def add_cline(*args)
end

#add_cpoint(point) ⇒ Sketchup::ConstructionPoint

The add_cpoint method is used to create a construction point.

Examples:

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

Parameters:

Returns:

Version:

  • SketchUp 6.0



240
241
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 240

def add_cpoint(point)
end

#add_curve(points) ⇒ Array<Sketchup::Edge> #add_curve(*points) ⇒ Array<Sketchup::Edge>

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.

Examples:

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

Overloads:

Returns:

Version:

  • SketchUp 6.0



263
264
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 263

def add_curve(*args)
end

#add_dimension_linear(start_pt_or_entity, end_pt_or_entity, offset_vector) ⇒ Sketchup::DimensionLinear #add_dimension_linear(start_instance_path, end_instance_path, offset_vector) ⇒ Sketchup::DimensionLinear #add_dimension_linear(start_array, end_array, offset_vector) ⇒ Sketchup::DimensionLinear

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

[instance_path, end_point], vector)

vector)

Examples:

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]

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 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],

Overloads:

Returns:

Version:

  • SketchUp 2014



354
355
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 354

def add_dimension_linear(*args)
end

#add_dimension_radial(arc_curve, leader_break_pt) ⇒ Sketchup::DimensionRadial

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

Examples:

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]

Parameters:

  • arc_curve (Sketchup::ArcCurve) —

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

  • leader_break_pt (Geom::Point3d) —

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

Returns:

Version:

  • SketchUp 2014



380
381
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 380

def add_dimension_radial(arc_curve, leader_break_pt)
end

#add_edges(points) ⇒ Array<Sketchup::Edge> #add_edges(*points) ⇒ Array<Sketchup::Edge>

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.

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

Examples:

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

Overloads:

Returns:

See Also:

Version:

  • SketchUp 6.0



414
415
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 414

def add_edges(*args)
end

#add_face(entities) ⇒ Sketchup::Face? #add_face(*entities) ⇒ Sketchup::Face?

Note:

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.

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.

Examples:

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)

Overloads:

Returns:

See Also:

Version:

  • SketchUp 6.0



463
464
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 463

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) ⇒ Integer

The #add_faces_from_mesh method is used to add Face entities to the collection of entities from a Geom::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.

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

Examples:

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)

Parameters:

  • polygon_mesh (Geom::PolygonMesh)
  • smooth_flags (Integer) (defaults to: Geom::PolygonMesh::AUTO_SOFTEN|Geom::PolygonMesh::SMOOTH_SOFT_EDGES) —

    flags for softening and smoothing of edges.

  • f_material (Sketchup::Material, String) (defaults to: nil) —

    material to paint front faces with.

  • b_material (Sketchup::Material, String) (defaults to: nil) —

    material to paint back faces with.

Returns:

  • (Integer) —

    Number of faces created

See Also:

Version:

  • SketchUp 6.0



520
521
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 520

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(entities) ⇒ Sketchup::Group #add_group(*entities) ⇒ Sketchup::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.

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

Examples:

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

Overloads:

Returns:

Version:

  • SketchUp 6.0



548
549
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 548

def add_group(*args)
end

#add_image(path, point, width, height = 0.0) ⇒ Sketchup::Image?

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.

Examples:

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

Parameters:

  • path (String) —

    A path for the image file.

  • point (Geom::Point3d) —

    A Point3d object representing the insertion point of the image.

  • width (Numeric) —

    Width for the image.

  • height (Numeric) (defaults to: 0.0) —

    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.

Returns:

Version:

  • SketchUp 6.0



586
587
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 586

def add_image(path, point, width, height = 0.0)
end

#add_instance(definition, transform) ⇒ Sketchup::ComponentInstance

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

Examples:

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

Parameters:

Returns:

Version:

  • SketchUp 6.0



617
618
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 617

def add_instance(definition, transform)
end

#add_line(point1, point2) ⇒ Sketchup::Edge

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.

Examples:

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

Parameters:

  • point1 (Geom::Point3d) —

    Point3d object representing the edge’s starting point.

  • point2 (Geom::Point3d) —

    Point3d object representing the edge’s ending point.

Returns:

See Also:

Version:

  • SketchUp 6.0



656
657
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 656

def add_line(point1, point2)
end

#add_ngon(center, normal, radius, numsides = 24) ⇒ Array<Sketchup::Edge>

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

Examples:

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

Parameters:

  • center (Geom::Point3d) —

    A Point3d object representing the center of the polygon.

  • normal (Geom::Vector3d) —

    A Vector3d object.

  • radius (Numeric) —

    A radius.

  • numsides (Integer) (defaults to: 24) —

    The number of sides for the polygon.

Returns:

Version:

  • SketchUp 6.0



685
686
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 685

def add_ngon(center, normal, radius, numsides = 24)
end

#add_observer(observer) ⇒ Boolean

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

Examples:

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

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0



700
701
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 700

def add_observer(observer)
end

#add_section_plane(plane) ⇒ Sketchup::SectionPlane?

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

Examples:

# 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

Parameters:

  • plane —

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

Returns:

Version:

  • SketchUp 2014



723
724
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 723

def add_section_plane(plane)
end

#add_text(text, point, vector) ⇒ Sketchup::Text #add_text(text, instance_path_and_pt, vector) ⇒ Sketchup::Text #add_text(text, instance_array_and_pt, vector) ⇒ Sketchup::Text

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

Examples:

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

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)

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)

Overloads:

Returns:

Version:

  • SketchUp 6.0



784
785
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 784

def add_text(*args)
end

#at(entity_index) ⇒ Sketchup::Entity?

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

Examples:

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

Parameters:

  • entity_index (Integer) —

    The index for a specific entity.

Returns:

See Also:

Version:

  • SketchUp 6.0



801
802
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 801

def at(entity_index)
end

#build {|builder| ... } ⇒ nil

Note:

While using #build it is important to not add or remove vertices by other means of the builder. Also don’t modify the position of the vertices in the Sketchup::Entities container geometry is added to. Doing so can break the vertex-cache that de-duplicates the vertices.

Creates an Sketchup::EntitiesBuilder that can be used to generate bulk geometry with performance in mind. This is particularly useful for importers where the geometry is already well defined and one wants to recreate it without further processing.

The call to #build starts an implicit operation, even if no other model changes are made within the block. This is not the same as Model#start_operation, so it’s still recommended to wrap all model changes, including #build with Model#start_operation and Model#commit_operation.

Refer to the documentation of Sketchup::EntitiesBuilder for more details.

Examples:

model = Sketchup.active_model
model.entities.build { |builder|
  edge = builder.add_edge([0, 0, 0], [9, 0, 0])
  edge.material = 'red'
  face = builder.add_face([[0, 0, 0], [9, 0, 0], [9, 9, 0], [0, 9, 0]])
  face.material = 'maroon'
}

Yields:

  • (builder)

Yield Parameters:

Returns:

  • (nil)

See Also:

Version:

  • SketchUp 2022.0



842
843
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 842

def build
end

#clear! ⇒ Boolean

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

Examples:

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!

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful

Version:

  • SketchUp 6.0



860
861
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 860

def clear!
end

#count ⇒ Integer

Note:

Since SketchUp 2014 the count method is inherited from Ruby’s Enumerable mix-in module. Prior to that the #count method is an alias for #length.

Examples:

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

Returns:

  • (Integer)

See Also:

Version:

  • SketchUp 6.0



879
880
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 879

def count
end

#each {|entity| ... } ⇒ nil

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.

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

Examples:

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 }

Yield Parameters:

Returns:

  • (nil)

Version:

  • SketchUp 6.0



903
904
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 903

def each
end

#erase_entities(entities) ⇒ nil #erase_entities(*entities) ⇒ nil

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

Examples:

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

Overloads:

Returns:

  • (nil)

Version:

  • SketchUp 6.0



940
941
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 940

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) ⇒ Boolean

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:

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

Examples:

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)

Parameters:

  • polygon_mesh (Geom::PolygonMesh)
  • weld_vertices (Boolean) (defaults to: true) —

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

  • smooth_flags (Integer) (defaults to: Geom::PolygonMesh::AUTO_SOFTEN|Geom::PolygonMesh::SMOOTH_SOFT_EDGES) —

    flags for softening and smoothing of edges.

  • f_material (Sketchup::Material, String) (defaults to: nil) —

    material to paint front faces with.

  • b_material (Sketchup::Material, String) (defaults to: nil) —

    material to paint back faces with.

Returns:

  • (Boolean)

See Also:

Version:

  • SketchUp 6.0



1005
1006
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1005

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) ⇒ nil

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

Examples:

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

Parameters:

  • recurse (Boolean) —

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

  • transform1 (Geom::Transformation) —

    The transformation for this entities object.

  • entities1 (Sketchup::Entities) —

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

  • transform2 (Geom::Transformation) —

    The transformation for entities1.

  • hidden (Boolean) —

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

  • entities2 (Sketchup::Entity, Array<Sketchup::Entity>) —

    A single entity, or an array of entities.

Returns:

  • (nil)

Version:

  • SketchUp 6.0



1040
1041
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1040

def intersect_with(recurse, transform1, entities1, transform2, hidden, entities2)
end

#length ⇒ Integer

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

Examples:

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

Returns:

  • (Integer)

See Also:

Version:

  • SketchUp 6.0



1057
1058
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1057

def length
end

#model ⇒ Sketchup::Model

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

Examples:

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

Returns:

  • (Sketchup::Model) —

    the model that contains the collection of entities if successful.

Version:

  • SketchUp 6.0



1075
1076
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1075

def model
end

#parent ⇒ Sketchup::ComponentDefinition, Sketchup::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.

Examples:

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

Returns:

Version:

  • SketchUp 6.0



1094
1095
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1094

def parent
end

#remove_observer(observer) ⇒ Boolean

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

Examples:

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

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0



1110
1111
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1110

def remove_observer(observer)
end

#size ⇒ Integer

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

Examples:

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

Returns:

  • (Integer)

See Also:

Version:

  • SketchUp 2014



1126
1127
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1126

def size
end

#transform_by_vectors(sub_entities, vectors) ⇒ Sketchup::Entities

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

Examples:

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

Parameters:

Returns:

Version:

  • SketchUp 6.0



1152
1153
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1152

def transform_by_vectors(sub_entities, vectors)
end

#transform_entities(transform, entities) ⇒ Boolean

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.

Examples:

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

Parameters:

Returns:

  • (Boolean) —

    false if the entities array was empty.

Version:

  • SketchUp 6.0



1180
1181
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1180

def transform_entities(transform, entities)
end

#weld(edges) ⇒ Array<Sketchup::Curve>

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

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

Examples:

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

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if the given entities are not part of the same Sketchup::Entities collection.

Version:

  • SketchUp 2020.1



1202
1203
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb', line 1202

def weld(edges)
end