Class: Geom::PolygonMesh

Inherits:
Object
  • Object
show all

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 SketchupImporter 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 Face.mesh method. See Entities.add_faces_from_mesh for an easy way to convert a mesh back into faces.

Examples:

# Grab a mesh from a given face.
my_mesh = some_face.mesh

# Create a new group that we will populate with the mesh.
group = Sketchup.active_model.entities.add_group
group.add_faces_from_mesh my_mesh

Version:

  • SketchUp 6.0

Constant Summary

Geom::PolygonMesh::NO_SMOOTH_OR_HIDE
Geom::PolygonMesh::HIDE_BASED_ON_INDEX
Geom::PolygonMesh::SOFTEN_BASED_ON_INDEX
Geom::PolygonMesh::AUTO_SOFTEN
Geom::PolygonMesh::SMOOTH_SOFT_EDGES

Instance Method Summary collapse

Constructor Details

#initialize(numpts, numpolys) ⇒ Object

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

Examples:

mesh = Geom::PolygonMesh.new

Returns mesh - the new PolygonMesh.

Parameters:

  • numpts (optional)

    How many points will be in the mesh.

  • numpolys (optional)

    How many polygons will be in the mesh.

Version:

  • SketchUp 6.0

Instance Method Details

#add_point(point) ⇒ Object

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)

Returns index - the index in the mesh for the point

Parameters:

  • point

    A Point3d object.

Returns:

  • index - the index in the mesh for the point

Version:

  • SketchUp 6.0

#add_polygon(points) ⇒ Object

The add_polygon method is used for adding a polygon to a polygon 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)

Returns index - the index of the polygon in the mesh if successful.

Parameters:

  • points

    A list of points that represent the polygon's vertices.

Returns:

  • index - the index of the polygon in the mesh if successful.

Version:

  • SketchUp 6.0

#count_pointsObject

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:

  • points - the number of points in a mesh, if successful.

Version:

  • SketchUp 6.0

#count_polygonsObject

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:

  • polygons - the number of polygons in the mesh, if successful

Version:

  • SketchUp 6.0

#normal_at(index) ⇒ Object

The normal_at method is used to determine the normal at a particular index in the mesh. This only works for meshes retrieved from Sketchup::Face.mesh.

Index is 1 based (starts at 1).

Examples:

mesh = face.mesh(4)
normal = mesh.normal_at(1)

Returns normal - a normal on success, nil on failure

Parameters:

  • index

    The index in the mesh where the normal is that you want to retrieve.

Returns:

  • normal - a normal on success, nil on failure

Version:

  • SketchUp 6.0

#point_at(index) ⇒ Object

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

Index is 1 based (starts at 1).

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)

Returns point - a Point3d object on success, nil on failure

Parameters:

  • index

    The index in the mesh where the point is that you want to retrieve.

Returns:

  • point - a Point3d object on success, nil on failure

Version:

  • SketchUp 6.0

#point_index(point) ⇒ Object

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

Returns 0 if point is not found.

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)

Returns index - the index in the mesh for the Point3d object

Parameters:

  • point

    A Point3d object.

Returns:

  • index - the index in the mesh for the Point3d object

Version:

  • SketchUp 6.0

#pointsObject

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.
num = mesh.points

Returns:

  • points - an array of points (vertices) if successful

Version:

  • SketchUp 6.0

#polygon_at(index) ⇒ Object

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

Index is 1 based (starts at 1). 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 positive value of the index value in the polygon array. So if you get [-1, 2,3] use 1 as the arg to point_at.

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)

Returns vertices - an array of vertex index values if successful nil on failure

Parameters:

  • index

    The index of the desired polygon.

Returns:

  • vertices - an array of vertex index values if successful nil on failure

Version:

  • SketchUp 6.0

#polygon_points_at(index) ⇒ Object

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)

Returns points - an array of points that make up the polygon if successful, nil on failure

Parameters:

  • index

    An index for a polygon in the mesh.

Returns:

  • points - an array of points that make up the polygon if successful, nil on failure

Version:

  • SketchUp 6.0

#polygonsObject

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

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.

Examples:

polygons = polygonmesh.polygons

Returns:

  • polygons - an array of polygons if successful

Version:

  • SketchUp 6.0

#set_point(index, point) ⇒ Object

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)

Returns polygonmesh - a PolygonMesh object

Parameters:

  • index

    The index where the point will be set.

  • point

    A Point3d object to set at the index.

Returns:

  • polygonmesh - a PolygonMesh object

Version:

  • SketchUp 6.0

#set_uv(index, point) ⇒ Object

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.

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.

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)

Returns nil

Parameters:

  • index

    An Integer representing the UV index.

  • point

    A Point3d object representing UV coordinates.

Returns:

  • nil

Version:

  • SketchUp 2014

#transform!(transform) ⇒ Object

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)

Returns polygonmesh - the PolygonMesh object

Parameters:

  • transform

    A Transformation object.

Returns:

  • polygonmesh - the PolygonMesh object

Version:

  • SketchUp 6.0

#uv_at(index, front) ⇒ Object

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)

Returns point - a Point3d object where the x equals the u value and the y equals the v value. Returns nil on failure.

Parameters:

  • index

    The index for the texture coordinate.

  • front

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

Returns:

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

#uvs(front) ⇒ Object

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

Returns points - an array of uv coordinates if successful

Parameters:

  • front (Boolean)

Returns:

  • points - an array of uv coordinates if successful

Version:

  • SketchUp 6.0