Class: Sketchup::EntitiesBuilder

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

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



114
115
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb', line 114

def add_edge(*args)
end

#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



149
150
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb', line 149

def add_edges(*args)
end

#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



207
208
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb', line 207

def add_face(*args)
end

#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



226
227
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb', line 226

def entities
end

#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



251
252
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb', line 251

def valid?
end

#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



269
270
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb', line 269

def vertex_at(position)
end