Face

class Face

Parent: Drawingelement | Class Index
Methods:all_connected, area, back_material, back_material=, edges, followme, get_UVHelper, loops, mesh, normal, outer_loop, plane, position_material, pushpull, reverse!, vertices |
Sample Code:facetests.rb |

The Face class contains methods modifying and extracting information for faces.

Instance Methods

all_connected
The all_connected method retrieves all of the entities connected to a face.
Syntax:
entities = face.all_connected
Arguments:
Return Value:
entities - the entities connected to the face
Comments:
Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
entity1 = entities[0]
entities = entity1.all_connected
if (entities)
UI.messagebox entities
else
UI.messagebox "Failure"
end

area
The area method is used to retrieve the area of a face in current units.
Syntax:
area = face.area
Arguments:
Return Value:
area - the area of the face in current units (if successful)
Comments:
Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
area = face.area

back_material
The back_material method is used to retrieve the material assigned to the back side of the face.
Syntax:
material = face.back_material
Arguments:
Return Value:
material - a Material object representing the material on the back of the face (if successful)
Comments:
Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
area = face.area
back = face.back_material

back_material=
The back_material= method is used to set the material assigned to the back side of the face.
Syntax:
material = face.back_material = "material_name" | material
Arguments:
"material_name" - the name of a valid material material - a Material object
Return Value:
material - the name of the valid material or the new Material object (if successful)
Comments:
Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
status = face.back_material="red"

edges
The edges method is used to get an array of edges that bound the face.
Syntax:
edges = face.edges
Arguments:
Return Value:
edges - an array of Edge objects (if successful)
Comments:
Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
edges = face.edges

followme
The followme method is used creating a shape by making the face follow along an array of edges.
Syntax:
status = face.followme edge1, edge2, ... status = face.followme [edge1, edge2, ...]
Arguments:
edge1 - an Edge object to follow
Return Value:
status - true if successful, nil if unsuccessful
Comments:
Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
line = entities.add_line point1, point2
begin
status = face.followme line
rescue
UI.messagebox $!.message
end

get_UVHelper
The get_UVHelper object is used to retrieve a UVHelper object for use in texture manipulation on a face.
Syntax:
uvhelper = face.get_UVHelper front, back, texturewriter
Arguments:
front - true if you want the texture coordinates for the front face, false if not back - true if you want the texture coordinates for the back face, false if not texturewriter - a TextureWriter object
Return Value:
uvhelper - a UVHelper object
Comments:
Example:
uvHelp = face.get_UVHelper true, true, tw

loops
The loops method is used to get an array of all of the loops that bound the face.
Syntax:
loops = face.loops
Arguments:
Return Value:
loops - an array of Loop objects if successful
Comments:
Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
loops = face.loops

mesh
The mesh method creates a polygon mesh that represents the face. See the PolygonMesh class for more information.
Syntax:
mesh = face.mesh flags
Arguments:
flags - one or more flags used to generate a polygon mesh (see comments)
Return Value:
mesh - a PolygonMesh object if successful
Comments:

Valid flags are:

0 (Include PolygonMeshPoints)
1 (Include PolygonMeshUVQFront)
2 (Include PolygonMeshUVQBack)
4 (Include PolygonMeshNormals).
Add these numbers together to combine flags. A value of 5 will include all flags, for example.

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
mesh = face.mesh 7

normal
The normal method is used to retrieve the 3d vector normal to the face in the front direction.
Syntax:
vector = face.normal
Arguments:
Return Value:
vector - a Vector3d object if successful
Comments:
Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
normal = face.normal

outer_loop
This method is used to retrieve the outer loop that bounds the face.
Syntax:
loop = face.outer_loop
Arguments:
Return Value:
loop - a Loop object representing the outer loop (if successful)
Comments:
Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
loop = face.outer_loop

plane
The plane method is used to retrieve the plane of the face.
Syntax:
plane = face.plane
Arguments:
Return Value:
plane - a plane that contains the face (if successful)
Comments:
Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
plane = face.plane

position_material
The position_material method is used to position a material on a face.
Syntax:
face.position_material material, pt_array, on_front
Arguments:
material - a Material object pt_array - an array of Point3d objects used to position the material o_front - true to position the texture on the front of the Face or false to position it on the back of the Face.
Return Value:
Comments:
The pt_array must contain 2, 4, 6 or 8 points. The points are used in pairs to tell where a point in the texture image is positioned on the Face. The first point in each pair is a 3D point in the model. It should be a point on the Face. The second point in each pair of points is a 2D point that gives the (u,v) coordinates of a point in the image to match up with the 3D point.
Example:

pushpull
The pushpull method is used to perform a push/pull on a face.
Syntax:
face.pushpull distance
Arguments:
distance - the distance, in current units, to push/pull the face
Return Value:
Comments:
The distance is measured in the direction that the face normal is pointing.
Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
status = face.pushpull 100

reverse!
The reverse! method is used to reverse the face's orientation.
Syntax:
face = face.reverse!
Arguments:
Return Value:
face- the reversed Face object if successful, false if unsuccessful
Comments:
Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
status = face.reverse!

vertices
The vertices method is used to retrieve an array of vertexes used by the edges of the face.
Syntax:
vertices = face.vertices
Arguments:
Return Value:
vertices - an array of Vertex objects
Comments:
Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
vertices = face.vertices