com.orsoncharts.graphics3d

## Class Object3D

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

- Direct Known Subclasses:
    Dot3D, LineObject3D

      public class Object3D
      extends java.lang.Object

  An object defined in 3D space by (a) a list of coordinates, and (b) a list of faces. This class has methods to calculate projected points in 2D when a `ViewPoint3D` is provided.
  This class also contains a collection of static methods for constructing common 3D objects.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `CLASS_KEY` The key for storing the object class as an optional property for this object.
    `static java.lang.String` | `COLOR_PREFIX` A prefix used for setting color properties for an object.
    `static java.lang.String` | `ITEM_KEY` The key for storing item keys as property values.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Object3D(java.awt.Color color)` Creates a new object, initially with no vertices or faces.
    `Object3D(java.awt.Color color, boolean outline)` Creates a new object, initially with no vertices or faces.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDoubleSidedFace(int[] vertices)` Adds a double-sided face for the given vertices (specified by index value) and color.
    `void` | `addFace(Face face)` Adds a face for this object.
    `void` | `addFace(int[] vertices)` Adds a face for the given vertices (specified by index value).
    `void` | `addFace(int[] vertices, java.lang.String tag)` Adds a tagged face for the given vertices (specified by index value).
    `void` | `addVertex(double x, double y, double z)` Adds a new object vertex with the specified coordinates.
    `void` | `addVertex(Point3D vertex)` Adds a new object vertex.
    `Point3D[]` | `calculateEyeCoordinates(ViewPoint3D viewPoint)` Returns the eye coordinates of the object's vertices.
    `java.awt.geom.Point2D[]` | `calculateProjectedPoints(ViewPoint3D viewPoint, double d)` Calculates the projected points for the object's vertices, for the given viewpoint.
    `static Object3D` | `createBar(double xWidth, double zWidth, double x, double y, double z, double zero, java.awt.Color barColor, java.awt.Color baseColor, java.awt.Color topColor, boolean inverted)` Creates a bar with the specified dimensions and color.
    `static Object3D` | `createBox(double x, double xdim, double y, double ydim, double z, double zdim, java.awt.Color color)` Creates a box centered on `(x, y, z)` with the specified dimensions.
    `static Object3D` | `createCube(double size, double x, double y, double z, java.awt.Color color)` Creates a cube centered on `(x, y, z)` with the specified `size`.
    `static Object3D` | `createLabelObject(java.lang.String label, java.awt.Font font, java.awt.Color fgColor, java.awt.Color bgColor, double x, double y, double z, boolean reversed, boolean doubleSided)` Creates a label object, which has a single transparent face in the Z-plane plus associated label attributes.
    `static Object3D` | `createOctahedron(double size, double xOffset, double yOffset, double zOffset, java.awt.Color color)` Creates an octahedron.
    `static java.util.List<Object3D>` | `createPieLabelMarkers(double radius, double explodeRadius, double base, double height, double angle1, double angle2)` Returns two 3D objects (sheets in the y-plane) that can be used as alignment anchors for the labels of a pie segment.
    `static Object3D` | `createPieSegment(double radius, double explodeRadius, double base, double height, double angle1, double angle2, double inc, java.awt.Color color)` Creates a pie segment with the specified attributes.
    `static Object3D` | `createSphere(double radius, int n, double x, double y, double z, java.awt.Color extColor, java.awt.Color intColor)` Creates an approximation of a sphere.
    `static Object3D` | `createTetrahedron(double size, double xOffset, double yOffset, double zOffset, java.awt.Color color)` Creates a tetrahedron.
    `static Object3D` | `createYSheet(double size, double x, double y, double z, java.awt.Color color, boolean invert)` Creates a square flat surface in the x-z plane (constant y) with a single face.
    `static Object3D` | `createZSheet(double size, double x, double y, double z, java.awt.Color color)` Creates a square flat surface in the x-y plane (constant z).
    `java.awt.Color` | `getColor()` Returns the default face color as specified in the constructor.
    `java.awt.Color` | `getColor(Face face)` Returns the color for a specific face.
    `int` | `getFaceCount()` Returns the number of faces.
    `java.util.List<Face>` | `getFaces()` Returns the faces for this object.
    `boolean` | `getOutline()` Returns the outline flag.
    `boolean` | `getOutline(Face face)` Returns `true` if an outline should be drawn for the specified face, and `false` otherwise.
    `java.lang.Object` | `getProperty(java.lang.String key)` Returns the value of the property with the specified key, or `null` if there is no property defined for that key.
    `int` | `getVertexCount()` Returns the number of vertices for this object.
    `void` | `setOutline(boolean outline)` Sets the outline flag.
    `void` | `setProperty(java.lang.String key, java.lang.Object value)` Sets the value of a property, overwriting any existing value.

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

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

- - ### Field Detail

    - #### CLASS_KEY

          public static final java.lang.String CLASS_KEY

      The key for storing the object class as an optional property for this object.
      Since:
        1.4
      See Also:
        Constant Field Values

    - #### ITEM_KEY

          public static final java.lang.String ITEM_KEY

      The key for storing item keys as property values.
      Since:
        1.3
      See Also:
        Constant Field Values

    - #### COLOR_PREFIX

          public static final java.lang.String COLOR_PREFIX

      A prefix used for setting color properties for an object.
      Since:
        1.3
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Object3D

          public Object3D(java.awt.Color color)

      Creates a new object, initially with no vertices or faces.
      Parameters:
        `color` - the default face color (`null` not permitted).
      Since:
        1.3

    - #### Object3D

          public Object3D(java.awt.Color color,
                          boolean outline)

      Creates a new object, initially with no vertices or faces.
      Parameters:
        `color` - the default face color (`null` not permitted).
        `outline` - the default flag that determines whether face outlines are drawn.
      Since:
        1.3

  - ### Method Detail

    - #### getColor

          public java.awt.Color getColor()

      Returns the default face color as specified in the constructor.
      Returns:
        The color (never `null`).
      Since:
        1.3

    - #### getOutline

          public boolean getOutline()

      Returns the outline flag.
      Returns:
        The outline flag.
      Since:
        1.3

    - #### setOutline

          public void setOutline(boolean outline)

      Sets the outline flag. This determines the default setting for whether or not the faces of this object have their outlines drawn when rendered.
      Parameters:
        `outline` - the new flag value.
      Since:
        1.3

    - #### getProperty

          public java.lang.Object getProperty(java.lang.String key)

      Returns the value of the property with the specified key, or `null` if there is no property defined for that key.
      Parameters:
        `key` - the property key (`null` not permitted).
      Returns:
        The value (possibly `null`).
      Since:
        1.3

    - #### setProperty

          public void setProperty(java.lang.String key,
                                  java.lang.Object value)

      Sets the value of a property, overwriting any existing value. One application for this is storing item key references to link a 3D object back to the data item that it represents (the key for this is `ITEM_KEY`).
      Parameters:
        `key` - the key (`null` not permitted).
        `value` - the value (`null` permitted).
      Since:
        1.3

    - #### getColor

          public java.awt.Color getColor(Face face)

      Returns the color for a specific face. If the face has a tag, then this method will look for a property with the key COLOR_PREFIX + tag and return that color, otherwise it returns the default color for the object.
      Parameters:
        `face` - the face (`null` not permitted).
      Returns:
        The color for the specified face (never `null`).
      Since:
        1.3

    - #### getOutline

          public boolean getOutline(Face face)

      Returns `true` if an outline should be drawn for the specified face, and `false` otherwise.
      Parameters:
        `face` - the face (`null` not permitted).
      Returns:
        A boolean.
      Since:
        1.3

    - #### getVertexCount

          public int getVertexCount()

      Returns the number of vertices for this object.
      Returns:
        The number of vertices.

    - #### addVertex

          public void addVertex(double x,
                                double y,
                                double z)

      Adds a new object vertex with the specified coordinates.
      Parameters:
        `x` - the x-coordinate.
        `y` - the y-coordinate.
        `z` - the z-coordinate.

    - #### addVertex

          public void addVertex(Point3D vertex)

      Adds a new object vertex.
      Parameters:
        `vertex` - the vertex (`null` not permitted).

    - #### getFaceCount

          public int getFaceCount()

      Returns the number of faces.
      Returns:
        The number of faces.

    - #### addFace

          public void addFace(int[] vertices)

      Adds a face for the given vertices (specified by index value).
      Parameters:
        `vertices` - the vertices (all should lie in a plane).
      Since:
        1.3

    - #### addFace

          public void addFace(int[] vertices,
                              java.lang.String tag)

      Adds a tagged face for the given vertices (specified by index value).
      Parameters:
        `vertices` - the vertices (all should lie in a plane).
        `tag` - the tag (`null` not permitted).
      Since:
        1.3

    - #### addDoubleSidedFace

          public void addDoubleSidedFace(int[] vertices)

      Adds a double-sided face for the given vertices (specified by index value) and color.
      Parameters:
        `vertices` - the vertices (all should lie in a plane).
      Since:
        1.3

    - #### addFace

          public void addFace(Face face)

      Adds a face for this object.
      Parameters:
        `face` - the face (`null` not permitted).

    - #### getFaces

          public java.util.List<Face> getFaces()

      Returns the faces for this object. Note that the list returned is a direct reference to the internal storage for this `Object3D` instance, so callers should take care not to modify this list unintentionally.
      Returns:
        The faces.

    - #### calculateProjectedPoints

          public java.awt.geom.Point2D[] calculateProjectedPoints(ViewPoint3D viewPoint,
                                                                  double d)

      Calculates the projected points for the object's vertices, for the given viewpoint.
      Parameters:
        `viewPoint` - the view point (`null` not permitted).
        `d` - the projection distance.
      Returns:
        The projected points.

    - #### calculateEyeCoordinates

          public Point3D[] calculateEyeCoordinates(ViewPoint3D viewPoint)

      Returns the eye coordinates of the object's vertices.
      Parameters:
        `viewPoint` - the view point (`null` not permitted).
      Returns:
        The eye coordinates.

    - #### createYSheet

          public static Object3D createYSheet(double size,
                                              double x,
                                              double y,
                                              double z,
                                              java.awt.Color color,
                                              boolean invert)

      Creates a square flat surface in the x-z plane (constant y) with a single face.
      Parameters:
        `size` - the sheet size.
        `x` - the x-coordinate for the center of the square.
        `y` - the y-coordinate.
        `z` - the z-coordinate for the center of the square.
        `color` - the color (`null` not permitted).
        `invert` - invert the order of the face
      Returns:
        The sheet.

    - #### createZSheet

          public static Object3D createZSheet(double size,
                                              double x,
                                              double y,
                                              double z,
                                              java.awt.Color color)

      Creates a square flat surface in the x-y plane (constant z).
      Parameters:
        `size` - the sheet size.
        `x` - the x-coordinate of a point on the surface.
        `y` - the y-coordinate of a point on the surface.
        `z` - the z-coordinate of a point on the surface.
        `color` - the color.
      Returns:
        The sheet.

    - #### createCube

          public static Object3D createCube(double size,
                                            double x,
                                            double y,
                                            double z,
                                            java.awt.Color color)

      Creates a cube centered on `(x, y, z)` with the specified `size`.
      Parameters:
        `size` - the size.
        `x` - the x-offset.
        `y` - the y-offset.
        `z` - the z-offset.
        `color` - the color (`null` not permitted).
      Returns:
        The cube (never `null`).

    - #### createBox

          public static Object3D createBox(double x,
                                           double xdim,
                                           double y,
                                           double ydim,
                                           double z,
                                           double zdim,
                                           java.awt.Color color)

      Creates a box centered on `(x, y, z)` with the specified dimensions.
      Parameters:
        `x` - the x-coordinate.
        `xdim` - the length of the box in the x-dimension.
        `y` - the y-coordinate.
        `ydim` - the length of the box in the y-dimension.
        `z` - the z-coordinate.
        `zdim` - the length of the box in the y-dimension.
        `color` - the color (`null` not permitted).
      Returns:
        The box (never `null`).
      See Also:
        `createCube(double, double, double, double, java.awt.Color)`

    - #### createTetrahedron

          public static Object3D createTetrahedron(double size,
                                                   double xOffset,
                                                   double yOffset,
                                                   double zOffset,
                                                   java.awt.Color color)

      Creates a tetrahedron.
      Parameters:
        `size` - the size.
        `xOffset` - the x-offset.
        `yOffset` - the y-offset.
        `zOffset` - the z-offset.
        `color` - the color (`null` not permitted).
      Returns:
        A tetrahedron.

    - #### createOctahedron

          public static Object3D createOctahedron(double size,
                                                  double xOffset,
                                                  double yOffset,
                                                  double zOffset,
                                                  java.awt.Color color)

      Creates an octahedron.
      Parameters:
        `size` - the size.
        `xOffset` - the x-offset.
        `yOffset` - the y-offset.
        `zOffset` - the z-offset.
        `color` - the color (`null` not permitted).
      Returns:
        An octahedron.

    - #### createSphere

          public static Object3D createSphere(double radius,
                                              int n,
                                              double x,
                                              double y,
                                              double z,
                                              java.awt.Color extColor,
                                              java.awt.Color intColor)

      Creates an approximation of a sphere.
      Parameters:
        `radius` - the radius of the sphere (in world units).
        `n` - the number of layers.
        `x` - the x-coordinate of the center of the sphere.
        `y` - the y-coordinate of the center of the sphere.
        `z` - the z-coordinate of the center of the sphere.
        `extColor` - the exterior color (`null` not permitted).
        `intColor` - the interior color (`null` not permitted).
      Returns:
        A sphere.

    - #### createPieSegment

          public static Object3D createPieSegment(double radius,
                                                  double explodeRadius,
                                                  double base,
                                                  double height,
                                                  double angle1,
                                                  double angle2,
                                                  double inc,
                                                  java.awt.Color color)

      Creates a pie segment with the specified attributes.
      Parameters:
        `radius` - the radius.
        `explodeRadius` - the explode radius (0.0 if not exploded).
        `base` - the base.
        `height` - the height.
        `angle1` - the start angle (radians).
        `angle2` - the end angle (radians).
        `inc` - the increment.
        `color` - the color (`null` not permitted).
      Returns:
        A pie segment object.

    - #### createPieLabelMarkers

          public static java.util.List<Object3D> createPieLabelMarkers(double radius,
                                                                       double explodeRadius,
                                                                       double base,
                                                                       double height,
                                                                       double angle1,
                                                                       double angle2)

      Returns two 3D objects (sheets in the y-plane) that can be used as alignment anchors for the labels of a pie segment. One sheet is on the front face of the segment, and the other is on the back face. Depending on the viewing point, only one of the sheets will be showing, and this is the one that the pie segment label will be attached to.
      Parameters:
        `radius` - the pie segment radius (in world units).
        `explodeRadius` - the pie segment explode radius (in world units).
        `base` - the base of the pie segment.
        `height` - the height of the pie segment.
        `angle1` - the start angle of the segment (in radians).
        `angle2` - the end angle of the segment (in radians).
      Returns:
        A list containing the two 3D objects to be used as pie label markers.

    - #### createBar

          public static Object3D createBar(double xWidth,
                                           double zWidth,
                                           double x,
                                           double y,
                                           double z,
                                           double zero,
                                           java.awt.Color barColor,
                                           java.awt.Color baseColor,
                                           java.awt.Color topColor,
                                           boolean inverted)

      Creates a bar with the specified dimensions and color.
      Parameters:
        `xWidth` - the x-width of the bar.
        `zWidth` - the z-width (or depth) of the bar.
        `x` - the x-coordinate for the center of the bar.
        `y` - the y-coordinate for the top of the bar.
        `z` - the z-coordinate for the center of the bar.
        `zero` - the y-coordinate for the bottom of the bar.
        `barColor` - the color for the bar (`null` not permitted).
        `baseColor` - the color for the base of the bar (if `null`, the `color` is used instead).
        `topColor` - the color for the top of the bar (if `null`, the `color` is used instead).
        `inverted` - a flag that determines whether the baseColor and topColor should be swapped in their usage.
      Returns:
        A 3D object that can represent a bar in a bar chart.

    - #### createLabelObject

          public static Object3D createLabelObject(java.lang.String label,
                                                   java.awt.Font font,
                                                   java.awt.Color fgColor,
                                                   java.awt.Color bgColor,
                                                   double x,
                                                   double y,
                                                   double z,
                                                   boolean reversed,
                                                   boolean doubleSided)

      Creates a label object, which has a single transparent face in the Z-plane plus associated label attributes. These faces are used to track the location and visibility of labels in a 3D scene.
      Parameters:
        `label` - the label (`null` not permitted).
        `font` - the font (`null` not permitted).
        `fgColor` - the label foreground color (`null` not permitted).
        `bgColor` - the label background color (`null` not permitted).
        `x` - the x-coordinate in 3D space.
        `y` - the y-coordinate in 3D space.
        `z` - the z-coordinate in 3D space.
        `reversed` - reverse the order of the vertices?
        `doubleSided` - is the face double-sided (visible from either side)?
      Returns:
        A new label object (never `null`).
      Since:
        1.3