com.orsoncharts.graphics3d

## Class Face

- java.lang.Object
- - com.orsoncharts.graphics3d.Face

- Direct Known Subclasses:
    ChartBox3D.ChartBoxFace, DoubleSidedFace, LabelFace, TaggedFace

      public class Face
      extends java.lang.Object

  Represents a face in one `Object3D`, defined in terms of vertex indices. It is expected (but not enforced) that all the vertices for the face lie within a single plane. The face will be visible from the "front" side only, which is a function of the order in which the vertices are specified. A special subclass, `DoubleSidedFace`, is visible from both front and back.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Face(Object3D owner, int[] vertices)` Creates a new face with the specified vertices that is part of the 3D `owner` object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `float` | `calculateAverageZValue(Point3D[] points)` Returns the average z-value.
    `double[]` | `calculateNormal(Point3D[] points)` Calculates the normal vector for this face.
    `java.awt.geom.Path2D` | `createPath(java.awt.geom.Point2D[] pts)` Creates and returns a path for the outline of this face.
    `java.awt.Color` | `getColor()` A convenience method that looks up and returns the color for this face (obtained by querying the object that owns the face).
    `int` | `getOffset()` Returns the offset to add to the vertex indices.
    `boolean` | `getOutline()` Returns `true` if an outline should be drawn for this face, and `false` otherwise.
    `Object3D` | `getOwner()` Returns the object that this face belongs too (as passed to the constructor).
    `java.lang.String` | `getTag()` Returns the tag for this face (always `null` for this class, subclasses may override).
    `int` | `getVertexCount()` Returns the number of vertices in this face.
    `int` | `getVertexIndex(int i)` Returns the index for the specified vertex.
    `boolean` | `isFrontFacing(java.awt.geom.Point2D[] projPts)` Returns `true` if this face is front facing, and `false` otherwise.
    `void` | `setOffset(int offset)` Sets the offset to add to the vertex indices.
    `java.lang.String` | `toString()` Returns a string representation of this instance, primarily for debugging purposes.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Face

          public Face(Object3D owner,
                      int[] vertices)

      Creates a new face with the specified vertices that is part of the 3D `owner` object. Most faces will have at least three vertices, but a special case with just two vertices (representing a line) is permitted.
      Parameters:
        `owner` - the object that owns the face (`null` not permitted).
        `vertices` - the indices of the vertices (array length >= 2).
      Since:
        1.3

  - ### Method Detail

    - #### getOwner

          public Object3D getOwner()

      Returns the object that this face belongs too (as passed to the constructor).
      Returns:
        The owner (never `null`).
      Since:
        1.3

    - #### getOffset

          public int getOffset()

      Returns the offset to add to the vertex indices.
      Returns:
        The offset.

    - #### setOffset

          public void setOffset(int offset)

      Sets the offset to add to the vertex indices.
      Parameters:
        `offset` - the offset.

    - #### getVertexCount

          public int getVertexCount()

      Returns the number of vertices in this face.
      Returns:
        The number of vertices in this face.

    - #### getVertexIndex

          public int getVertexIndex(int i)

      Returns the index for the specified vertex.
      Parameters:
        `i` - the vertex index.
      Returns:
        The index.

    - #### getColor

          public java.awt.Color getColor()

      A convenience method that looks up and returns the color for this face (obtained by querying the object that owns the face). The color is not stored as an attribute of the face, because typically an object has many faces that are all the same color.
      Returns:
        The color (never `null`).

    - #### getOutline

          public boolean getOutline()

      Returns `true` if an outline should be drawn for this face, and `false` otherwise. The value is obtained by querying the object that owns the face.
      Returns:
        A boolean.

    - #### getTag

          public java.lang.String getTag()

      Returns the tag for this face (always `null` for this class, subclasses may override). The `TaggedFace` class overrides this method.
      Returns:
        `null`.
      Since:
        1.3

    - #### calculateNormal

          public double[] calculateNormal(Point3D[] points)

      Calculates the normal vector for this face.
      Parameters:
        `points` - the vertices of the object that this face belongs to (these can be in world or eye coordinates).
      Returns:
        The normal vector.

    - #### calculateAverageZValue

          public float calculateAverageZValue(Point3D[] points)

      Returns the average z-value.
      Parameters:
        `points` - the points.
      Returns:
        The average z-value.

    - #### isFrontFacing

          public boolean isFrontFacing(java.awt.geom.Point2D[] projPts)

      Returns `true` if this face is front facing, and `false` otherwise.
      Parameters:
        `projPts` - the projection points.
      Returns:
        A boolean.

    - #### createPath

          public java.awt.geom.Path2D createPath(java.awt.geom.Point2D[] pts)

      Creates and returns a path for the outline of this face.
      Parameters:
        `pts` - the projected points for the world (`null` not permitted).
      Returns:
        A path.
      Since:
        1.3

    - #### toString

          public java.lang.String toString()

      Returns a string representation of this instance, primarily for debugging purposes.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        A string.