Class: Sketchup::EntitiesBuilder

Inherits:
Object
  • Object
show all

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 Sketchup::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)

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 Method Summary # collapse

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 Sketchup::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:

Returns:

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 Sketchup::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:

Returns:

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

↑ #entities ⇒ Sketchup::Entities

The Sketchup::Entities collection the Sketchup::EntitiesBuilder will add the geometry to.

Examples:

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

Returns:

Raises:

  • (RuntimeError) —

    If the builder is not valid.

Version:

  • SketchUp 2022.0

↑ #valid? ⇒ Boolean

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 Sketchup::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

Returns:

  • (Boolean)

Version:

  • SketchUp 2022.0

Known Bugs:

  • Prior to SketchUp 2023.0 this returned 0 for success instead of true. In Ruby 0 evaluates as true so conditional logic still worked.

↑ #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>
}

Returns:

Version:

  • SketchUp 2022.0