Face

class

• Introduction
• Methods
• • all_connected
  • area
  • back_material
  • back_material=
  • classify_point
  • edges
  • followme
  • get_UVHelper
  • get_glued_instances
  • loops
  • material
  • material=
  • mesh
  • normal
  • outer_loop
  • plane
  • position_material
  • pushpull
  • reverse!
  • vertices

Introduction

Methods

Face.all_connectedSketchUp 6.0+

The all_connected method retrieves all of the entities connected to a face.

Returns:

entities

the entities connected to the face

 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

 # Assuming nothing else was in the model, first entity should be an Edge.
 entity1 = entities[0]
 if entity1.typename == "Edge"
   connected = entity1.all_connected
 end

 if (connected)
   UI.messagebox connected
 else
   UI.messagebox "Failure"
 end

Face.areaSketchUp 6.0+

The area method is used to retrieve the area of a face in current units.

You can pass in an optional Transformation (or an array that can represent a transformation), to correct for a parent group's transformation. For example, if a face is inside of a group that is scaled to 200%, the area method will return the unscaled area of the face. So by passing a 200% transformation object to this method, you can account for that to get the "visual" area of the face.

Arguments:

tranform

(optional) A Transformation object or array that can be interpreted as a Transformation object.

Returns:

area

the area of the face in current units (if successful)

 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

Face.back_materialSketchUp 6.0+

The back_material method is used to retrieve the material assigned to the back side of the face.

Returns:

material

a Material object representing the material on the back of the face (if successful)

 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

Face.back_material=SketchUp 6.0+

The back_material= method is used to set the material assigned to the back side of the face.

Arguments:

material

A Material object or the name of a valid material.

Returns:

material

the name of the valid material or the new Material object (if successful)

 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"

Face.classify_pointSketchUp 6.0+

The classify_point method is used to determine if a given Point3d is on your face. The return value will be from this list:

• 0: PointUnknown,
• 1: PointInside,
• 2: PointOnEdge,
• 4: PointOnVertex,
• 8: PointOutside,
• 16: PointNotOnPlane.

Arguments:

point

A Point3d.

Returns:

result

an integer describing where a Point3d is in relation to your face.

  
 model = Sketchup.active_model
 entities = model.active_entities
 pts = []
 pts[0] = [0, 0, 0]
 pts[1] = [9, 0, 0]
 pts[2] = [9, 9, 0]
 pts[3] = [0, 9, 0]

 # Add the face to the entities in the model
 face = entities.add_face pts
 test_point = Geom::Point3d.new(50,50,0)

 # Find out how the point relates to the face.
 result = face.classify_point(test_point)

Face.edgesSketchUp 6.0+

The edges method is used to get an array of edges that bound the face.

Returns:

edges

an array of Edge objects (if successful)

 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

Face.followmeSketchUp 6.0+

The followme method is used creating a shape by making the face follow along an array of edges.

Arguments:

edge1

An Edge object to follow.

Returns:

status

true if successful, nil if unsuccessful

 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

Face.get_UVHelperSketchUp 6.0+

The get_UVHelper object is used to retrieve a UVHelper object for use in texture manipulation on a face.

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.

Returns:

uvhelper

a UVHelper object

 model = Sketchup.active_model
 entities = model.active_entities
 pts = []
 pts[0] = [0, 0, 0]
 pts[1] = [9, 0, 0]
 pts[2] = [9, 9, 0]
 pts[3] = [0, 9, 0]

 # Add the face to the entities in the model
 face = entities.add_face pts
 tw = Sketchup.create_texture_writer
 uvHelp = face.get_UVHelper true, true, tw

Face.get_glued_instancesSketchUp 7.0.10247 (M1)+

The get_glued_instances method returns an Array any ComponentInstances that are glued to the face.

Arguments:

materials

A Materials object.

Returns:

instances

An array of ComponentInstance objects that are currently glued to the face.

 # Create a series of points that define a new face.
 model = Sketchup.active_model
 entities = model.active_entities
 pts = []
 pts[0] = [0, 0, 0]
 pts[1] = [9, 0, 0]
 pts[2] = [9, 9, 0]
 pts[3] = [0, 9, 0]

 # Add the face to the entities in the model
 face = entities.add_face pts
 glued_array = face.get_glued_instances

Face.loopsSketchUp 6.0+

The loops method is used to get an array of all of the loops that bound the face.

Returns:

loops

an array of Loop objects if successful

 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

Face.materialSketchUp 6.0+

The material method is used to retrieve the material assigned to the front of the face. (This method is inherited from the Drawingelement parent class.)

Returns:

material

a Material object representing the material on the front of the face (if successful)

 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
 mat = face.material

Face.material=SketchUp 6.0+

The material= method is used to set the material assigned to the front side of the face. (This method is inherited from the Drawingelement parent class.)

Arguments:

material

A Material object or the name of a valid material.

Returns:

material

the name of the valid material or the new Material object (if successful)

 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.material = "red"

Face.meshSketchUp 6.0+

The mesh method creates a polygon mesh that represents the face. See the PolygonMesh class for more information.

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.

Arguments:

flags

One or more flags used to generate a mesh (see comments).

Returns:

mesh

a PolygonMesh object if successful

 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

Face.normalSketchUp 6.0+

The normal method is used to retrieve the 3D vector normal to the face in the front direction.

Returns:

vector

a Vector3d object if successful

 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

Face.outer_loopSketchUp 6.0+

This method is used to retrieve the outer loop that bounds the face.

Returns:

loop

a Loop object representing the outer loop (if successful)

 # Create a series of points that define a new face.
 model = Sketchup.active_model
 entities = model.active_entities
 pts = []
 pts[0] = [0, 0, 0]
 pts[1] = [9, 0, 0]
 pts[2] = [9, 9, 0]
 pts[3] = [0, 9, 0]

 # Add the face to the entities in the model
 face = entities.add_face pts
 loop = face.outer_loop

Face.planeSketchUp 6.0+

The plane method is used to retrieve the plane of the face. See the Array class for information on how planes are stored.

Returns:

plane

a plane that contains the face (if successful)

 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

Face.position_materialSketchUp 6.0+

The position_material method is used to position a material on a face.

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.

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.

Returns:

nil

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

 material = model.materials[0]
 pt_array = []
 pt_array[0] = Geom::Point3d.new(3,0,0)
 pt_array[1] = Geom::Point3d.new(0,0,0)
 on_front = true
 face.position_material material, pt_array, on_front

Face.pushpullSketchUp 6.0+

The pushpull method is used to perform a push/pull on a face.

The distance is measured in the direction that the face normal is pointing.

Arguments:

distance

The distance, in current units, to push/pull the face.

copy

Create a new push/pull starting face if true (equivalent of pressing CTRL while in SketchUp), do not create a push/pull starting face if false.

Returns:

nil

 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, true

Face.reverse!SketchUp 6.0+

The reverse! method is used to reverse the face's orientation, meaning the front becomes the back.

Returns:

face

the reversed Face object if successful, false if unsuccessful

 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!

Face.verticesSketchUp 6.0+

The vertices method is used to get an array of all of the vertices that bound the face.

Returns:

vertices

an array of Vertex objects if successful

 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