Class: Geom::PolygonMesh

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

Overview

The 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.

Examples:

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

Constant Summary collapse

AUTO_SOFTEN =

Constants

nil
HIDE_BASED_ON_INDEX =

Stub value.

nil
NO_SMOOTH_OR_HIDE =

Stub value.

nil
SMOOTH_SOFT_EDGES =

Stub value.

nil
SOFTEN_BASED_ON_INDEX =

Stub value.

nil
MESH_NORMALS =

Stub value.

nil
MESH_POINTS =

Stub value.

nil
MESH_UVQ_BACK =

Stub value.

nil
MESH_UVQ_FRONT =

Stub value.

nil

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Geom::PolygonMesh #initialize(numpts) ⇒ Geom::PolygonMesh #initialize(numpts, numpolys) ⇒ Geom::PolygonMesh

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.

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.

Examples:

mesh = Geom::PolygonMesh.new

Overloads:

  • #initialize ⇒ Geom::PolygonMesh
  • #initialize(numpts) ⇒ Geom::PolygonMesh

    Parameters:

    • numpts (Integer) —

      How many points will be in the mesh.

  • #initialize(numpts, numpolys) ⇒ Geom::PolygonMesh

    Parameters:

    • numpts (Integer) —

      How many points will be in the mesh.

    • numpolys (Integer) —

      How many polygons will be in the mesh.

Raises:

  • (RangeError) —

    If number of points or polygons are negative numbers.

Version:

  • SketchUp 6.0



205
206
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 205

def initialize(*args)
end

Instance Method Details

#add_point(point) ⇒ Integer

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

The index can be used for creating polygons.

Examples:

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

Parameters:

Returns:

  • (Integer) —

    the index in the mesh for the point

Version:

  • SketchUp 6.0



57
58
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 57

def add_point(point)
end

#add_polygon(index, index, index, ...) ⇒ Integer, 0 #add_polygon(index_array) ⇒ Integer, 0 #add_polygon(point3d, point3d, point3d, ...) ⇒ Integer, 0 #add_polygon(point3d_array) ⇒ Integer, 0 #add_polygon(array) ⇒ Integer, 0

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.

Overloads:

  • #add_polygon(index, index, index, ...) ⇒ Integer, 0

    Adds a polygon from a list of the mesh’s vertex indices.

    Examples:

    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)

    Parameters:

    • index (Integer) —

      An index of a vertex in the mesh. Remember that mesh indices start at 1.

    • ... (Integer) —

      Additional indices (optional)

  • #add_polygon(index_array) ⇒ Integer, 0

    Adds a polygon from an Array of the mesh’s vertex indices.

    Examples:

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

    Parameters:

    • index_array (Array<Integer>) —

      An Array of point indices.

  • #add_polygon(point3d, point3d, point3d, ...) ⇒ Integer, 0

    Adds a polygon from a list of Point3d objects.

    Examples:

    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)

    Parameters:

    Raises:

    • (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.

  • #add_polygon(point3d_array) ⇒ Integer, 0

    Adds a polygon from an Array of Point3d objects.

    Examples:

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

    Parameters:

  • #add_polygon(array) ⇒ Integer, 0

    Adds a polygon from an Array of 3-element Arrays.

    Examples:

    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)

    Parameters:

    • array (Array<Array(3)>) —

      An array of arrays of length 3, where the inner arrays are used as if they were Point3d objects.

Returns:

  • (Integer) —

    The index of the polygon in the mesh.

  • (0) —

    Invalid index. Returned if the method failed to create a polygon.

Version:

  • SketchUp 6.0



137
138
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 137

def add_polygon(*args)
end

#count_points ⇒ Integer

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

Examples:

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

Returns:

  • (Integer) —

    the number of points in a mesh

Version:

  • SketchUp 6.0



151
152
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 151

def count_points
end

#count_polygons ⇒ Integer

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

Examples:

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

Returns:

  • (Integer) —

    the number of polygons in the mesh

Version:

  • SketchUp 6.0



167
168
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 167

def count_polygons
end

#normal_at(index) ⇒ Geom::Vector3d?

Note:

Index starts at 1.

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.

Examples:

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

Parameters:

  • index (Integer) —

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

Returns:

Version:

  • SketchUp 6.0



226
227
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 226

def normal_at(index)
end

#point_at(index) ⇒ Geom::Point3d?

Note:

Index starts at 1.

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

Examples:

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)

Parameters:

  • index (Integer) —

    The index in the mesh for the point to be retrieved

Returns:

Version:

  • SketchUp 6.0



248
249
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 248

def point_at(index)
end

#point_index(point) ⇒ Integer

Note:

Returns 0 if point is not found.

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

Examples:

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)

Parameters:

Returns:

  • (Integer) —

    the index in the mesh for the Geom::Point3d object

Version:

  • SketchUp 6.0



269
270
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 269

def point_index(point)
end

#points ⇒ Array<Geom::Point3d>

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0



287
288
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 287

def points
end

#polygon_at(index) ⇒ Array<Geom::Point3d>?

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.

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

Examples:

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)

Parameters:

  • index (Integer) —

    The index of the desired polygon.

Returns:

Version:

  • SketchUp 6.0



316
317
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 316

def polygon_at(index)
end

#polygon_points_at(index) ⇒ Array<Geom::Point3d>?

Note:

Index starts at 1.

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

Examples:

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)

Parameters:

  • index (Integer) —

    An index for a polygon in the mesh.

Returns:

Version:

  • SketchUp 6.0



338
339
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 338

def polygon_points_at(index)
end

#polygons ⇒ Array<Array<Integer>>, Array<nil>

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.

Examples:

polygons = polygonmesh.polygons

Returns:

Version:

  • SketchUp 6.0



354
355
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 354

def polygons
end

#set_point(index, point) ⇒ Geom::PolygonMesh

Note:

Index starts at 1.

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

Examples:

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)

Parameters:

  • index (Integer) —

    The index where the point will be set.

  • point (Geom::Point3d) —

    A Point3d object to set at the index.

Returns:

Version:

  • SketchUp 6.0



378
379
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 378

def set_point(index, point)
end

#set_uv(index, point, front) ⇒ nil

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.

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.

Examples:

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)

Parameters:

  • index (Integer) —

    An Integer representing the UV index.

  • point (Geom::Point3d) —

    A Point3d object representing UV coordinates.

  • front (Boolean) —

    A boolean representing the front or back.

Returns:

  • (nil)

Version:

  • SketchUp 2014



438
439
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 438

def set_uv(index, point, front)
end

#transform!(transformation) ⇒ Geom::PolygonMesh

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

Examples:

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)

Parameters:

Returns:

Version:

  • SketchUp 6.0



456
457
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 456

def transform!(transformation)
end

#uv_at(index, front) ⇒ Geom::Point3d?

Note:

Index starts at 1.

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.

Examples:

point = mesh.uv_at(1, true)

Parameters:

  • index (Integer) —

    The index for the texture coordinate.

  • front (Boolean) —

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

Returns:

  • (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



490
491
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 490

def uv_at(index, front)
end

#uvs(front) ⇒ Array<Geom::Point3d>

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

Examples:

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

Parameters:

  • front (Boolean)

Returns:

Version:

  • SketchUp 6.0



506
507
 
# File 'lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb', line 506

def uvs(front)
end