Faces

This is part 5 of Scott Conover's AU 2009 class on analysing building geometry.

Faces in the Revit API can be described as mathematical functions of two input parameters 'u' and 'v', where the location of the face at any given point in XYZ space is a function of the parameters. The U and V directions are automatically determined based on the shape of the given face. Lines of constant U or V can be represented as gridlines on the face:

U and V gridlines on a cylindrical face

You can use the UV parameters to evaluate a variety of properties of the face at any given location:

All of the vectors returned are non-normalized.

Face types

Revit uses a variety of curve types to represent face geometry in a document, including the following with their corresponding Revit API representation classes:

Here is the definition and some notes on each of these:

Mathematical representation

Mathematical representations of all of the Revit face types are given in Appendix B of Scott's handout document, and we include them here as well for easy online access. This section describes the face types encountered in Revit geometry, their properties, and their mathematical representations.

PlanarFace

A plane defined by origin and unit vectors in U and V. Its parametric equation is

P(u,v) = P0 + u nu + v nv
CylindricalFace

A face defined by extruding a circle along an axis. The Revit API provides the following properties:

The parametric equation for this face is:

P(u,v) = P0 + rx cos(u) + ry sin(u) + v naxis
ConicalFace

A face defined by rotation of a line about an axis. The Revit API provides the following properties:

The parametric equation for this face is:

P(u,v) = P0 + v [sin(α) (rx cos(u) + ry sin(u)) + cos(α) naxis]
RevolvedFace

A face defined by rotation of an arbitrary curve about an axis. The Revit API provides the following properties:

The parametric equation for this face is:

P(u,v) = P0 + C(v) [rx cos(u) + ry sin(u) + naxis]
RuledFace

A ruled surface is created by sweeping a line between two profile curves or between a curve and a point. The Revit API provides the curve(s) and point(s) as properties.

If both curves are valid, the parametric equation for this surface is:

P(u,v) = C1(u) + v (C2(u) - C1(u) )

If one of the curves is replaced with a point, the equations simplify to one of:

P(u,v) = P1 + v (C2(u) - P1 )
P(u,v) = C1(u) + v (P2 - C1(u) )

A ruled face with no curves and two points is degenerate and will not be returned.

HermiteFace

A cubic Hermite spline face. The Revit API provides:

The parametric representation of this surface between nodes (u1, v1) and (u2, v2) is:

P(u,v) = UT [MH] [B} [MH]T V

Here, U = [u3 u2 u 1]T, V = [v3 v2 v 1]T, and MH is the Hermite matrix:

[MH] =
  2-2 1 1 
 -3 3-2-1 
  0 0 1 0 
  1 0 0 0 

B is the coefficient matrix obtained from the face properties at the interpolation points:

[B] =
 Pu1v1Pu1v2P'v(u1v1)P'v(u1v2) 
 Pu2v1Pu2v2P'v(u2v1)P'v(u2v2) 
 P'u(u1v1)P'u(u1v2)P'uv(u1v1)P'uv(u1v2) 
 P'u(u2v1)P'u(u2v2)P'uv(u2v1)P'uv(u2v2) 

Face analysis and processing

Several Face member methods provide tools suitable for use in geometric analysis:

The Intersect method can be used in to identify:

The next instalment of this series will look at face edges and their directions and parametrisation.