class Geom::PolygonMesh

The {#Geom::PolygonMesh} class contains methods to create polygon mesh structures. This is useful if you need to write a custom importer/exporter in Ruby that works at the level of triangulated polygons. For example, you can determine the triangles that make up a 15-sided {#Sketchup::Face} by using this class, or write a {#Sketchup::Importer} that reads a data file, creates a mesh from it, and draws faces based on the mesh.

You can construct a mesh manually using the methods of this class, or you can get a mesh from a face by calling the {Sketchup::Face#mesh} method. See {Sketchup::Entities#add_faces_from_mesh} for an easy way to convert a mesh back into faces.

@example

entities = Sketchup.active_model.active_entities
face = entities.grep(Sketchup::Face).first

mesh = face.mesh

group = entities.add_group
group.entities.add_faces_from_mesh(mesh)

@version SketchUp 6.0

Constants

AUTO_SOFTEN

Constants

HIDE_BASED_ON_INDEX
MESH_NORMALS
MESH_POINTS
MESH_UVQ_BACK
MESH_UVQ_FRONT
NO_SMOOTH_OR_HIDE
SMOOTH_SOFT_EDGES
SOFTEN_BASED_ON_INDEX

Public Class Methods

new(*args) click to toggle source

Create a new empty polygon mesh.

The number of points and polygons are optional and are used as a hint to decide how much space to pre-allocate to speed up adding points and polygons.

As of SketchUp 2021.1 the performance of looking up and inserting points is significantly better provided the mesh was initialized with roughly the correct number of total points.

@example

mesh = Geom::PolygonMesh.new

@note When creating a mesh with normals and/or UVQ data it's critical that

the number of points estimated is equal to or higher than the final number
of points added. If fewer points are estimated the normals and UVQ data
might end up out of sync.

@overload initialize

@return [Geom::PolygonMesh]

@overload initialize(numpts)

@param [Integer] numpts    How many points will be in the mesh.
@return [Geom::PolygonMesh]

@overload initialize(numpts, numpolys)

@param [Integer] numpts    How many points will be in the mesh.
@param [Integer] numpolys  How many polygons will be in the mesh.
@return [Geom::PolygonMesh]

@raise [RangeError] If number of points or polygons are negative numbers.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 205
def initialize(*args)
end

Public Instance Methods

add_point(point) click to toggle source

The {#add_point} method is used to add a point to the mesh.

The index can be used for creating polygons.

@example

mesh = Geom::PolygonMesh.new
point = Geom::Point3d.new(0, 1, 2)
index = mesh.add_point(point)

@param [Geom::Point3d] point

@return [Integer] the index in the mesh for the point

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 57
def add_point(point)
end
add_polygon(*args) click to toggle source

The add_polygon method is used for adding a polygon to a PolygonMesh. All variations of this method require at least 3 elements to define a polygon, although more may be given.

@overload add_polygon(index, index, index, …)

Adds a polygon from a list of the mesh's vertex indices.
@example
  mesh = Geom::PolygonMesh.new
  # add points to mesh...
  mesh.add_point(Geom::Point3d.new(0, 0, 0))
  mesh.add_point(Geom::Point3d.new(1, 0, 0))
  mesh.add_point(Geom::Point3d.new(1, 1, 0))
  polygon_index = mesh.add_polygon(1, 2, 3)
@param [Integer] index
  An index of a vertex in the mesh. Remember that mesh indices start at 1.
@param [Integer] ...
  Additional indices (optional)

@overload add_polygon(index_array)

Adds a polygon from an Array of the mesh's vertex indices.
@example
  mesh = Geom::PolygonMesh.new
  # add points to mesh...
  mesh.add_point(Geom::Point3d.new(0, 0, 0))
  mesh.add_point(Geom::Point3d.new(1, 0, 0))
  mesh.add_point(Geom::Point3d.new(1, 1, 0))
  polygon_index = mesh.add_polygon([1, 2, 3])
@param [Array<Integer>] index_array
  An {Array} of point indices.

@overload add_polygon(point3d, point3d, point3d, …)

Adds a polygon from a list of Point3d objects.
@example
  mesh = Geom::PolygonMesh.new
  point1 = Geom::Point3d.new(0, 1, 2)
  point2 = Geom::Point3d.new(1, 0, 2)
  point3 = Geom::Point3d.new(2, 0, 1)
  polygon_index = mesh.add_polygon(point1, point2, point3)
@param [Geom::Point3d] point3d
@raise [ArgumentError] When using Arrays in place of Point3d objects.
  Normally Arrays may be used in place of Point3d objects in most
  SketchUp methods. This method is an exception to that rule.
@param [Geom::Point3d] ...
  Additional points (optional)

@overload add_polygon(point3d_array)

Adds a polygon from an Array of Point3d objects.
@example
  mesh = Geom::PolygonMesh.new
  point1 = Geom::Point3d.new(0, 1, 2)
  point2 = Geom::Point3d.new(1, 0, 2)
  point3 = Geom::Point3d.new(2, 0, 1)
  polygon_index = mesh.add_polygon([point1, point2, point3])
@param [Array<Geom::Point3d>] point3d_array

@overload add_polygon(array)

Adds a polygon from an Array of 3-element Arrays.
@example
  pts = [[0, 0, 0], [1, 0, 0], [1, 1, 0], [0.5, 2, 0], [0, 1, 0]]
  mesh = Geom::PolygonMesh.new
  polygon_index = mesh.add_polygon(pts)
  Sketchup.active_model.entities.add_faces_from_mesh(mesh)
@param [Array<Array(3)>] array
  An array of arrays of length 3, where the inner arrays are used as if
  they were Point3d objects.

@return [Integer] The index of the polygon in the mesh.

@return [0] Invalid index. Returned if the method failed to create a

polygon.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 137
def add_polygon(*args)
end
count_points() click to toggle source

The {#count_points} method is used to count the number of points in a mesh.

@example

mesh = Geom::PolygonMesh.new
point = Geom::Point3d.new(0, 1, 2)
mesh.add_point(point)
num = mesh.count_points

@return [Integer] the number of points in a mesh

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 151
def count_points
end
count_polygons() click to toggle source

The {#count_polygons} count the number of polygons in the mesh.

@example

mesh = Geom::PolygonMesh.new
point1 = Geom::Point3d.new(0, 1, 2)
point2 = Geom::Point3d.new(1, 0, 2)
point3 = Geom::Point3d.new(2, 0, 1)
mesh.add_polygon(point1, point2, point3)
nump = mesh.count_polygons

@return [Integer] the number of polygons in the mesh

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 167
def count_polygons
end
normal_at(index) click to toggle source

The {#normal_at} method is used to determine the vertex normal at a particular index in the mesh. This only works for meshes retrieved from {Sketchup::Face#mesh} with the PolygonMeshNormals flag.

@example

flags = 4 # PolygonMeshNormals
mesh = face.mesh(flags)
normal = mesh.normal_at(1)

@note Index starts at 1.

@param [Integer] index

The index in the mesh for the vertex normal to be
retrieved

@return [Geom::Vector3d, nil]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 226
def normal_at(index)
end
point_at(index) click to toggle source

The {#point_at} method is used to retrieve the point at a specific index in the mesh.

@example

mesh = Geom::PolygonMesh.new
point1 = Geom::Point3d.new(0, 1, 2)
point2 = Geom::Point3d.new(10, 20, 30)
mesh.add_point(point1)
mesh.add_point(point2)
point_from_index = mesh.point_at(1)

@note Index starts at 1.

@param [Integer] index

The index in the mesh for the point to be retrieved

@return [Geom::Point3d, nil]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 248
def point_at(index)
end
point_index(point) click to toggle source

The {#point_index} method is used to retrieve the index of a point in the mesh.

@example

mesh = Geom::PolygonMesh.new
point1 = Geom::Point3d.new(0, 1, 2)
point2 = Geom::Point3d.new(10, 20, 30)
mesh.add_point(point1)
mesh.add_point(point2)
index = mesh.point_index(point2)

@note Returns 0 if point is not found.

@param [Geom::Point3d] point

@return [Integer] the index in the mesh for the {Geom::Point3d} object

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 269
def point_index(point)
end
points() click to toggle source

The {#points} method is used to retrieve an array of points (vertices) in the mesh

@example

mesh = Geom::PolygonMesh.new
point1 = Geom::Point3d.new(0, 1, 2)
point2 = Geom::Point3d.new(10, 20, 30)
mesh.add_point(point1)
mesh.add_point(point2)
# Returns array of points in the mesh.
points = mesh.points

@return [Array<Geom::Point3d>]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 287
def points
end
polygon_at(index) click to toggle source

The {#polygon_at} method is used to retrieve an array of vertex index values for a polygon at a specific index.

@example

mesh = Geom::PolygonMesh.new
point1 = Geom::Point3d.new(0, 1, 2)
point2 = Geom::Point3d.new(1, 0, 2)
point3 = Geom::Point3d.new(2, 0, 1)
index = mesh.add_polygon(point1, point2, point3)
polygon = mesh.polygon_at(index)

@note Index starts at 1.

@note The returned array can contain negative

values with the sign indicating a hidden edge. For example, a return value
of +[-1, 2, 3]+ indicates that the edge from +1+ to +2+ is hidden. The
negative values should not be used as an index for {#point_at}, take the
absolute value of the index value in the polygon array.  So if you
get +[-1, 2,3]+ use +1+ as the argument to {#point_at}.

@param [Integer] index

The index of the desired polygon.

@return [Array<Geom::Point3d>, nil]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 316
def polygon_at(index)
end
polygon_points_at(index) click to toggle source

The {#polygon_points_at} method is used to retrieve the points for a polygon that is at a specific index in the mesh.

@example

mesh = Geom::PolygonMesh.new
point1 = Geom::Point3d.new(0, 1, 2)
point2 = Geom::Point3d.new(1, 0, 2)
point3 = Geom::Point3d.new(2, 0, 1)
index = mesh.add_polygon(point1, point2, point3)
points = mesh.polygon_points_at(index)

@note Index starts at 1.

@param [Integer] index

An index for a polygon in the mesh.

@return [Array<Geom::Point3d>, nil]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 338
def polygon_points_at(index)
end
polygons() click to toggle source

The {#polygons} method is used to retrieve an array of all polygons in the mesh.

The returned array contains an array that can have a negative value with the sign indicating a hidden edge. For example, a return value of +[-1, 2, 3]+ indicates that the edge from 1 to 2 is hidden.

@example

polygons = polygonmesh.polygons

@return [Array<Array<Integer>>, Array<nil>]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 354
def polygons
end
set_point(index, point) click to toggle source

The {#set_point} method is used to set the point at a specific index in the mesh.

@example

mesh = Geom::PolygonMesh.new
point1 = Geom::Point3d.new(0, 1, 2)
point2 = Geom::Point3d.new(10, 20, 30)
index = mesh.add_point(point1)
mesh.set_point(index, point2)

@note Index starts at 1.

@param [Integer] index

The index where the point will be set.

@param [Geom::Point3d] point

A Point3d object to set at the index.

@return [Geom::PolygonMesh]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 378
def set_point(index, point)
end
set_uv(index, point, front) click to toggle source

The {#set_uv} method is used to define UV mapping coordinates to points in the mesh.

Beware that the polygons connected to the point will share UV coordiates so UV mapping coordinates needs to be continuous across the polygon mesh.

When setting the UV for a point one need to make sure to have the correct index for the point. It's therefore best to add the points using {#add_point} and use the index it returns for following calls to set_uv and {#add_polygon}.

If you are not able to calculate how many points there will be in your mesh make sure to not specify an index in {#set_uv} higher than the number of times you have called {#set_uv}.

@example

mesh = Geom::PolygonMesh.new(4)
# Create points for a triangle.
point1 = Geom::Point3d.new(0, 0, 0)
point2 = Geom::Point3d.new(9, 0, 0)
point3 = Geom::Point3d.new(9, 9, 0)
point4 = Geom::Point3d.new(0, 9, 0)
# Create UV mapping to tile 2x cross triangle.
uv1 = Geom::Point3d.new(0, 0, 0)
uv2 = Geom::Point3d.new(2, 0, 0)
uv3 = Geom::Point3d.new(2, 2, 0)
uv4 = Geom::Point3d.new(0, 2, 0)
# Add points and UV data to mesh.
index1 = mesh.add_point(point1)
index2 = mesh.add_point(point2)
index3 = mesh.add_point(point3)
index4 = mesh.add_point(point4)
mesh.set_uv(index1, uv1, true)
mesh.set_uv(index2, uv2, true)
mesh.set_uv(index3, uv3, true)
mesh.set_uv(index4, uv4, true)
# Add polygons.
mesh.add_polygon(index1, index2, index3)
mesh.add_polygon(index1, index3, index4)

@note If you don't specify how many points you will be adding to the mesh

when you initiate it you may risk the UV data becoming out of sync.

@note Index starts at 1.

@param [Integer] index

An Integer representing the UV index.

@param [Geom::Point3d] point

A Point3d object representing UV coordinates.

@param [Boolean] front

A boolean representing the front or back.

@return [nil]

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 438
def set_uv(index, point, front)
end
transform!(transformation) click to toggle source

The {#transform!} method is used to apply a transformation to a mesh.

@example

point1 = Geom::Point3d.new(100, 200, 300)
tr = Geom::Transformation.new(point1)
mesh = Geom::PolygonMesh.new
point2 = Geom::Point3d.new(0, 1, 2)
mesh.add_point(point2)
mesh.transform!(tr)

@param [Geom::Transformation] transformation

@return [Geom::PolygonMesh]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 456
def transform!(transformation)
end
uv_at(index, front) click to toggle source

The {#uv_at} method is used to access a uv (texture coordinates) at a specific index.

“UVs” is a way of referring to the u,v texture coordinates (as opposed to the X, Y, and Z axis that you construct your meshes on), which are points defining 1-by-1 positions within an image. These coordinates connect to points in your 3D model, to position an image texture onto it's surface (similar to virtual “thumb tacks”)

These coordinates pin an exact spot on an image that you wish to use to texture your model to a specific point on an object's surface. Between these points, your software will stretch the image smoothly. This is what is referred to as UV mapping.

@example

point = mesh.uv_at(1, true)

@note Index starts at 1.

@param [Integer] index

The index for the texture coordinate.

@param [Boolean] front

Set to +true+ to get the UV for the front size,
+false+ for the back side.

@return [Geom::Point3d, nil] a Point3d object where the x equals the u

value and the y equals the v value.
Returns nil on failure.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 490
def uv_at(index, front)
end
uvs(front) click to toggle source

The {#uvs} method is used to retrieve an array of uv coordinates in the mesh.

@example

# Get a mesh with front and back UVs.
mesh = face.mesh(1 | 2)
uvs = mesh.uvs(true)

@param [Boolean] front

@return [Array<Geom::Point3d>]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb, line 506
def uvs(front)
end