123456789_123456789_123456789_123456789_123456789_

Class: Sketchup::EntitiesBuilder

Relationships
Inherits: Object

Overview

Note:

Like ::Geom::PolygonMesh there is minimal validation checks made on the input to the creation of the geometry. Vertices are de-duplicated and edges sharing the same vertices will be de-duplicated. But no intersection of overlapping entities is made. It leaves a higher responsibility on the API user to produce valid geometry.

Note:

While using Entities#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 Entities container geometry is added to. Doing so can break the vertex-cache that de-duplicates the vertices.

The EntitiesBuilder is an interface 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.

Before the Entities Builder was introduced there were two ways of adding geometry; the add_* methods of Entities and ::Geom::PolygonMesh.

The former is slow as the methods perform intersection, splitting and merging of overlapping geometry. This is useful when creating tools similar to the Line and Rectangle tool.

::Geom::PolygonMesh is fast, but it doesn't provide granular control per face or edge added.

Entities Builder is similar to ::Geom::PolygonMesh in speed, but with the flexibility of Entities's add_* methods.

(See "Creating a triangulated grid" example)

rdoc-image:../images/entities-builder-grid-example.png

Examples:

Creating a triangulated grid

model = Sketchup.active_model
model.start_operation('Create Grid', true)
model.entities.build { |builder|
  # Creates a grid similar to Sandbox Tools, with each square
  # triangulated with a soft+smooth edge.
  10.times { |x|
    10.times { |y|
      # 4 {--} 3
      #   |\ |
      #   | \|
      # 1 {--} 2
      pt1 = Geom::Point3d.new(x, y, 0)
      pt2 = Geom::Point3d.new(x + 1, y, 0)
      pt3 = Geom::Point3d.new(x + 1, y + 1, 0)
      pt4 = Geom::Point3d.new(x, y + 1, 0)
      face1 = builder.add_face([pt1, pt2, pt4])
      face2 = builder.add_face([pt2, pt3, pt4])
      material = (x + y).odd? ? 'red' : 'maroon'
      face1.material = material
      face2.material = material
      edge = builder.add_edge(pt2, pt4)
      edge.soft = true
      edge.smooth = true
    }
  }
}
model.commit_operation

See Also:

Version:

  • SketchUp 2022.0

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#valid? ⇒ Boolean (readonly)

Indicates whether the builder object is valid and can be used.

A builder object is only valid within the scope of the block given to Entities#build.

When this return false, calling any other method on the builder will raise an error.

Examples:

model = Sketchup.active_model
cached_builder = nil
model.entities.build { |builder|
  p builder.valid? # => true
  cached_builder = builder # Don't hold on to builder objects.
}
p cached_builder.valid? # => false

Version:

  • SketchUp 2022.0

Instance Method Details

#add_edge(point1, point2) ⇒ Sketchup::Edge #add_edge(points) ⇒ Sketchup::Edge
Also known as: #add_line

Note:

Does not split intersecting faces or edges.

Adds a Edge to the #entities collection.

Examples:

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

Overloads:

Raises:

  • (ArgumentError) —

    If the points are considered equal.

  • (RuntimeError) —

    If the builder is not valid.

See Also:

Version:

  • SketchUp 2022.0

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

Note:

Does not split intersecting faces or edges.

Adds a continuous set of Edge's to the #entities collection.

Examples:

model = Sketchup.active_model
model.entities.build { |builder|
  edges = builder.add_edges([0, 0, 0], [6, 0, 0], [9, 0, 8]) # => 2 edges
  edges.each { |edge|
    edge.material = 'red'
  }
}

Overloads:

Returns:

  • (Array<Sketchup::Edge, nil>) —

    In the array, for each pair in points an edge is returned. If two point are so close they are considered identical then nil is returned.

Raises:

  • (RuntimeError) —

    If the builder is not valid.

See Also:

Version:

  • SketchUp 2022.0

#add_face(outer_loop) ⇒ Sketchup::Face #add_face(*outer_loop) ⇒ Sketchup::Face #add_face(outer_loop, holes: inner_loops) ⇒ Sketchup::Face #add_face(*outer_loop, holes: inner_loops) ⇒ Sketchup::Face

Note:

Does not split intersecting faces or edges.

Adds a Face to the #entities collection.

Examples:

Adding a simple face

model = Sketchup.active_model
model.entities.build { |builder|
  face = builder.add_face([[0, 0, 0], [6, 0, 0], [6, 8, 0], [0, 8, 0]])
  face.material = 'red'
}

Adding an edge with two holes

model = Sketchup.active_model
model.entities.build { |builder|
  outer_loop = [[0, 0, 0], [8, 0, 0], [8, 9, 0], [0, 9, 0]]
  hole1 = [[1, 1, 0], [3, 1, 0], [3, 8, 0], [1, 8, 0]]
  hole2 = [[4, 1, 0], [7, 1, 0], [7, 8, 0], [4, 8, 0]]
  face = builder.add_face(outer_loop, holes: [hole1, hole2])
}

Overloads:

Raises:

  • (ArgumentError) —

    If points are not planar.

  • (ArgumentError) —

    If any of the loops doesn't have at least 3 points.

  • (RuntimeError) —

    If the builder is not valid.

See Also:

Version:

  • SketchUp 2022.0

#add_line(*args)

Alias for #add_edge.

#entities ⇒ Sketchup::Entities

The Entities collection the EntitiesBuilder will add the geometry to.

Examples:

model = Sketchup.active_model
model.entities.build { |builder|
  p builder.entities == model.entities # => true
}

Raises:

  • (RuntimeError) —

    If the builder is not valid.

Version:

  • SketchUp 2022.0

#vertex_at(position) ⇒ Sketchup::Vertex?

Finds an existing Vertex for the given position, otherwise returns nil.

Examples:

model = Sketchup.active_model
model.entities.build { |builder|
  edge = builder.add_edge([1, 0, 0], [9, 0, 0])
  builder.vertex_at([0, 0, 0]) => nil
  builder.vertex_at([9, 0, 0]) => #<Sketchup::Vertex>
}

Version:

  • SketchUp 2022.0