123456789_123456789_123456789_123456789_123456789_

Class: Sketchup::Face

Relationships
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
Instance Chain:
Inherits: Sketchup::Drawingelement

Overview

Faces in SketchUp are flat, 2-sided polygons with 3 or more sides.

Version:

  • SketchUp 6.0

Constant Summary

Instance Attribute Summary

Drawingelement - Inherited

#casts_shadows=

The casts_shadows= method is used to set the Drawingelement to cast shadows.

#casts_shadows?

The casts_shadows? method is used to determine if the Drawingelement is casting shadows.

#hidden=

The hidden= method is used to set the hidden status for an element.

#hidden?

The hidden? method is used to determine if the element is hidden.

#layer

The layer method is used to retrieve the Layer object of the drawing element.

#layer=

The layer= method is used to set the layer for the drawing element.

#material

The material method is used to retrieve the material for the drawing element.

#material=

The material= method is used to set the material for the drawing element.

#receives_shadows=

The receive_shadows= method is used to set the Drawingelement to receive shadows.

#receives_shadows?

The receive_shadows? method is used to determine if the Drawingelement is receiving shadows.

#visible=

The visible= method is used to set the visible status for an element.

#visible?

The visible? method is used to get the visible status for an element.

Entity - Inherited

#deleted?

The deleted? method is used to determine if your entity is still valid (not deleted by another script, for example.).

#valid?

The #valid? method is used to determine if your entity is still valid (not deleted by another script, for example).

Instance Method Summary

Drawingelement - Inherited

#bounds

The #bounds method is used to retrieve the ::Geom::BoundingBox bounding a Drawingelement.

#erase!

The #erase! method is used to erase an element from the model.

Entity - Inherited

#add_observer

The add_observer method is used to add an observer to the current object.

#attribute_dictionaries

The attribute_dictionaries method is used to retrieve the AttributeDictionaries collection attached to the entity.

#attribute_dictionary

The attribute_dictionary method is used to retrieve an attribute dictionary with a given name that is attached to an Entity.

#delete_attribute

The #delete_attribute method is used to delete an attribute from an entity.

#entityID

The entityID method is used to retrieve a unique ID assigned to an entity.

#get_attribute

The #get_attribute method is used to retrieve the value of an attribute in the entity’s attribute dictionary.

#inspect

The #inspect method is used to retrieve the string representation of the entity.

#model

The model method is used to retrieve the model for the entity.

#parent

The parent method is used to retrieve the parent of the entity.

#persistent_id

The #persistent_id method is used to retrieve a unique persistent id assigned to an entity.

#remove_observer

The remove_observer method is used to remove an observer from the current object.

#set_attribute

The set attribute is used to set the value of an attribute in an attribute dictionary with the given name.

#to_s

The #to_s method is used to retrieve the string representation of the entity.

#typename

The typename method retrieves the type of the entity, which will be a string such as “Face”, “Edge”, or “Group”.

Instance Attribute Details

#back_materialSketchup::Material? (rw)

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

Examples:

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)

# Add a material to the back face, then check to see that it was added
face.back_material = "red"
material = face.back_material

Returns:

Version:

  • SketchUp 6.0

#back_material=(material) ⇒ Sketchup::Material (rw)

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

Examples:

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"

Parameters:

Returns:

Version:

  • SketchUp 6.0

#materialSketchup::Material? (rw)

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

Examples:

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)

# Add a material to the face, then check to see that it was added
face.material = "red"
material = face.material

Returns:

Version:

  • SketchUp 6.0

#material=(material) ⇒ Sketchup::Material (rw)

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

Examples:

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"

Parameters:

Returns:

Version:

  • SketchUp 6.0

Instance Method Details

#all_connectedArray<Sketchup::Entity>

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

Examples:

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)
connected = face.all_connected

Returns:

Version:

  • SketchUp 6.0

#areaFloat #area(transform) ⇒ Float

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

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.

Examples:

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

Overloads:

  • #areaFloat

    Returns:

    • (Float)

      the area of the face in square inches.

  • #area(transform) ⇒ Float

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

    Parameters:

    Returns:

    • (Float)

      the area of the face in square inches.

Version:

  • SketchUp 6.0

#classify_point(point) ⇒ Integer

The classify_point method is used to determine if a given Point3d is on the referenced Face.

It is important that return value comparisons be made against the symbolic constants (i.e. PointUnknown, PointInside, PointOnVertex, etc.) rather than the absolute integer values as these values may change from one release to the next.

Examples:

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)

# Check a point that should be outside the face.
pt = Geom::Point3d.new(50, 50, 0)
result = face.classify_point(pt)
if result == Sketchup::Face::PointOutside
  puts "#{pt.to_s} is outside the face"
end

# Check a point that should be outside inside the face.
pt = Geom::Point3d.new(1, 1, 0)
result = face.classify_point(pt)
if result == Sketchup::Face::PointInside
  puts "#{pt.to_s} is inside the face"
end

# Check a point that should be on the vertex of the face.
pt = Geom::Point3d.new(0, 0, 0)
result = face.classify_point(pt)
if result == Sketchup::Face::PointOnVertex
  puts "#{pt.to_s} is on a vertex"
end

# Check a point that should be on the edge of the face.
pt = Geom::Point3d.new(0, 1, 0)
result = face.classify_point(pt)
if result == Sketchup::Face::PointOnEdge
  puts "#{pt.to_s} is on an edge of the face"
end

# Check a point that should be off the plane of the face.
pt = Geom::Point3d.new(1, 1, 10)
result = face.classify_point(pt)
if result == Sketchup::Face::PointNotOnPlane
  puts "#{pt.to_s} is not on the same plane as the face"
end

Parameters:

Returns:

  • (Integer)

    an integer describing where a Point3d is in relation to the referenced Face.

Version:

  • SketchUp 6.0

#clear_texture_position(front)

The #clear_texture_position method is used to remove any explicit texture positioning for a face and have SketchUp display it with the default texture positioning.

Parameters:

  • front (Boolean)

    true Clears on the front side of the face, false the back side.

Version:

  • SketchUp 2022.0

#clear_texture_projection(frontside)

The #clear_texture_projection method is used to clear the texture projection. This is similar to toggling off Projection from the Position Texture tool in the ::UI.

Parameters:

  • frontside (Boolean)

    true for front side, false for back side.

See Also:

Version:

  • SketchUp 2021.1

#edgesArray<Sketchup::Edge>

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0

#followme(edges) ⇒ Boolean #followme(edge) ⇒ Boolean

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

Examples:

model = Sketchup.active_model
entities = model.active_entities

depth = 100
width = 100

# Add the face to the entities in the model
points = [
  Geom::Point3d.new(0, 0, 0),
  Geom::Point3d.new(width, 0, 0),
  Geom::Point3d.new(width, depth, 0),
  Geom::Point3d.new(0, depth, 0)
]
face = entities.add_face(points)

# Add the line which we will "follow" to the entities in the model
point1 = Geom::Point3d.new(0, 0, 0)
point2 = Geom::Point3d.new(0, 0, 100)
edge = entities.add_line(point1, point2)
face.followme(edge)

Overloads:

  • #followme(edges) ⇒ Boolean

    Parameters:

  • #followme(edge) ⇒ Boolean

    Parameters:

Version:

  • SketchUp 6.0

#get_glued_instancesArray<Sketchup::ComponentInstance, Sketchup::Group, Sketchup::Image>

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

ComponentInstance objects that are currently glued to the face.

Examples:

# 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

Returns:

Version:

  • SketchUp 7.0 M1

#get_texture_projection(frontside) ⇒ Geom::Vector3d?

The #get_texture_projection method will return a vector representing the projection for either the front or back side of the face.

Examples:

model = Sketchup.active_model
entities = model.active_entities
materials = model.materials

# Create a face and add it to the model entities
pts = []
pts[0] = [0, 0, 1]
pts[1] = [10, 0, 1]
pts[2] = [10, 10, 1]
face = entities.add_face(pts)

# Export an image to use as a texture
path = Sketchup.temp_dir
full_name = File.join(path, "temp_image.jpg")
model.active_view.write_image(full_name, 500, 500, false, 0.0)

# Create a material and assign the texture to it
material = materials.add("Test Material")
material.texture = full_name

# Assign the new material to our face we created
face.material = material

# Set the projection of the applied material
face.set_texture_projection(face.normal, true)

# Get the projection of the applied material
vector = face.get_texture_projection(true)

Parameters:

  • frontside (Boolean)

    true for front side, false for back side.

Returns:

  • (Geom::Vector3d, nil)

    a vector on success, nil if face is not textured with a projected texture mapping.

See Also:

Version:

  • SketchUp 2014

#get_UVHelper(front = true, back = true) ⇒ Sketchup::UVHelper #get_UVHelper(front = true, back = true, texturewriter) ⇒ Sketchup::UVHelper

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

Examples:

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)

Overloads:

  • #get_UVHelper(front = true, back = true) ⇒ Sketchup::UVHelper

    True if you want the texture coordinates for the front face, false if not.

    True if you want the texture coordinates for the back face, false if not.

    Parameters:

    • front (Boolean) (defaults to: true)
    • back (Boolean) (defaults to: true)
  • #get_UVHelper(front = true, back = true, texturewriter) ⇒ Sketchup::UVHelper

    True if you want the texture coordinates for the front face, false if not.

    True if you want the texture coordinates for the back face, false if not.

    An optional TextureWriter object.

    Parameters:

Version:

  • SketchUp 6.0

#loopsArray<Sketchup::Loop>

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0

#mesh(flags = 0) ⇒ Geom::PolygonMesh

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

Valid flags are:

  • 0: Include PolygonMeshPoints,

  • 1: Include PolygonMeshUVQFront,

  • 2: Include PolygonMeshUVQBack,

  • 4: Include PolygonMeshNormals.

Use bitwise OR to combine flags. A value of 7 will include all flags, for example.

Examples:

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)

kPoints = 0
kUVQFront = 1
kUVQBack = 2
kNormals = 4
flags = kPoints | kUVQFront | kUVQBack | kNormals # equals to 7
mesh = face.mesh(flags)

Parameters:

  • flags (Integer) (defaults to: 0)

    One or more flags used to generate a mesh.

Version:

  • SketchUp 6.0

#normalGeom::Vector3d

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0

#outer_loopSketchup::Loop

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

Examples:

# 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

Returns:

Version:

  • SketchUp 6.0

#planeArray(Float, Float, Float, Float)

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

Examples:

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

Returns:

  • (Array(Float, Float, Float, Float))

    a plane that contains the face (if successful)

Version:

  • SketchUp 6.0

#position_material(material, points, on_front) ⇒ Face, false #position_material(material, points, on_front, projection) ⇒ Face, false

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

The points argument must contain 2, 4, 6 or 8 points. The points are used in pairs to describe 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. 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.

Examples:

model = Sketchup.active_model
entities = model.active_entities

# Create a face and add it to the model entities
points = [
  Geom::Point3d.new(0, 0, 1),
  Geom::Point3d.new(9, 0, 1),
  Geom::Point3d.new(9, 9, 1),
  Geom::Point3d.new(0, 9, 1),
]
face = entities.add_face(points)

# Export an image to use as a texture
path = Sketchup.temp_dir
full_name = File.join(path, "temp_image.jpg")
model.active_view.write_image(full_name, 500, 500, false, 0.0)

# Create a material and assign the texture to it
material = model.materials.add("Test Material")
material.texture = full_name

# Assign the new material to our face we created
face.material = material

mapping = [
  Geom::Point3d.new(3,0,0), # Model coordinate
  Geom::Point3d.new(0,0,0), # UV coordinate
]
on_front = true
face.position_material(material, mapping, on_front)

Overloads:

  • #position_material(material, points, on_front) ⇒ Face, false

    This variant positions a material on the face’s plane without projection.

    Parameters:

    • material (Sketchup::Material)
    • points (Array<Geom::Point3d>)

      An array of Point3d objects used to position the material. The points should be on the plane of the face. If they are not they will be projected to the face’s plane.

    • on_front (Boolean)

      true to position the texture on the front of the Face or false to position it on the back of the Face.

  • #position_material(material, points, on_front, projection) ⇒ Face, false

    This variant positions a material on the face’s plane with projection.

    Parameters:

    • material (Sketchup::Material)
    • points (Array<Geom::Point3d>)

      An array of Point3d objects used to position the material. The points should be on the same plane. The plane should be parallel to the projection vector. If they are not on a plane parallel to the projection vector they will be projected to such a plane.

    • on_front (Boolean)

      true to position the texture on the front of the Face or false to position it on the back of the Face.

    • projection_vector (Geom::Vector3d)

      The direction of the texture projection.

    Version:

    • SketchUp 2021.1

Returns:

  • (Face, false)

    the face upon success, false if material or texture if not valid.

Raises:

  • ArgumentError if the provided points are not in the size of 2, 4, 6 or 8.

  • ArgumentError if the provided points could not be computed to a valid UV mapping.

See Also:

Version:

  • SketchUp 6.0

#pushpull(distance, copy = false) ⇒ nil

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.

Examples:

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)

Parameters:

  • distance (Length)

    The distance to push/pull the face.

  • copy (Boolean) (defaults to: false)

    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.

Version:

  • SketchUp 6.0

#reverse!Face, false

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

Examples:

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!

Returns:

  • (Face, false)

    the reversed Face object if successful, false if unsuccessful

Version:

  • SketchUp 6.0

#set_texture_projection(vector, frontside) ⇒ Boolean

Deprecated.

This function never worked correctly. It’s not capable of controlling the position and orientation of the texture. In some cases it produced an invalid model. As of SketchUp 2021.1 the method simply raises NotImplementedError.

The #set_texture_projection method is used to set the texture projection direction.

Parameters:

  • vector (Geom::Vector3d)

    representing the direction of the projection. Use nil to remove the projection.

  • frontside (Boolean)

    true for front side, false for back side.

See Also:

Version:

  • SketchUp 2014

#texture_positioned?(front) ⇒ Boolean

The #texture_positioned? method is used to check if the face has a texture that is positioned.

A texture is positioned when it’s not using the default texture coordinates.

When a user uses the Paint Bucket Tool to apply a material sampled from the Material Browser it will use default texture coordinates and not be positioned. It will be positioned if the user uses the Position Texture Tool.

When an API user uses Sketchup::Drawinglement#material= the texture is not positioned. It will be positioned when the API user uses #position_material. It it also positioned of the face was crafted via ::Geom::PolygonMesh.

Examples:

model = Sketchup.active_model
entities = model.active_entities
faces = entities.grep(Sketchup::Face).select { |face|
  face.texture_positioned?(true) || face.texture_positioned?(false)
}

Parameters:

  • front (Boolean)

    true Checks the front side of the face, false the back side.

See Also:

Version:

  • SketchUp 2021.1

#texture_projected?(front) ⇒ Boolean

The #texture_projected? method is used to check if the face has a texture that is projected.

A texture is projected when the user enables this property via the Position Texture Tool.

It is also projected when the API user passes a projection vector to #position_material.

Parameters:

  • front (Boolean)

    true Checks the front side of the face, false the back side.

See Also:

Version:

  • SketchUp 2021.1

#uv_tile_at(position, front) ⇒ Array<Geom::Point3d>?

The #uv_tile_at method is used to get the corner positions (model and UV) of a UV tile.

The UV tile bounds the given reference point on the plane of the face. If the reference isn’t on the plane of the face it will be projected onto it.

The world coordinates are on the plane of the face unless the texture is projected. When the texture is projected the the world points are on an arbitrary plane that is perpendicular to the projection direction.

The returned coordinates are arranged to be compatible with #position_material.

Getting the bounds of the UV tile under the cursor:

The red quadrilateral represents the model points returned.

Examples:

Copy material from front to back

model = Sketchup.active_model
model.active_entities.grep(Sketchup::Face) { |face|
  material = face.material

  if material&.texture.nil?
    face.back_material = material
  end

  reference = face.vertices.first.position
  mapping = face.uv_tile_at(reference, true)
  if face.texture_projected?(true)
    projection = face.get_texture_projection(true)
    face.position_material(material, mapping, false, projection)
  else
    face.position_material(material, mapping, false)
  end
}

Iterate each set of world and UV coordinates

model = Sketchup.active_model
faces = model.active_entities.grep(Sketchup::Face)
face = faces.find { |face| face.material&.texture }
reference = face.vertices.first.position
mapping = face.uv_tile_at(reference, true)
mapping.each_slice(2) { |position, uv|
  puts "World: #{position.inspect} - UV: #{uv.inspect}"
}

Parameters:

  • position (Geom::Point3d)

    Model position on the face’s plane that will be bounded by the UV tile.

  • front (Boolean)

    true Checks the front side of the face, false the back side.

Returns:

  • (Array<Geom::Point3d>, nil)

    A set of 8 points. Each stride of two is first a model space point, the second a UV coordinate. nil if the face doesn’t have a texture on the given side.

See Also:

Version:

  • SketchUp 2021.1

#verticesArray<Sketchup::Vertex>

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0