Module org.jfree.chart3d
Package org.jfree.chart3d.graphics3d

# Class Object3D

java.lang.Object
org.jfree.chart3d.graphics3d.Object3D

Direct Known Subclasses:
  `Dot3D`, `LineObject3D`

public class Object3D extends 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
Description
`static final String`
`CLASS_KEY`
The key for storing the object class as an optional property for this object.
`static final String`
`COLOR_PREFIX`
A prefix used for setting color properties for an object.
`static final String`
`ITEM_KEY`
The key for storing item keys as property values.

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`void`
`addDoubleSidedFace(int[] vertices)`
Adds a double-sided face for the given vertices (specified by index value) and color.
`void`
`addFace(int[] vertices)`
Adds a face for the given vertices (specified by index value).
`void`
`addFace(int[] vertices, String tag)`
Adds a tagged face for the given vertices (specified by index value).
`void`
`addFace(Face face)`
Adds a face for this object.
`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.
`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, Color barColor, Color baseColor, 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, 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, Color color)`
Creates a cube centered on `(x, y, z)` with the specified `size`.
`static Object3D`
`createLabelObject(String label, Font font, Color fgColor, 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, Color color)`
Creates an octahedron.
`static 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, Color color)`
Creates a pie segment with the specified attributes.
`static Object3D`
`createSphere(double radius, int n, double x, double y, double z, Color extColor, Color intColor)`
Creates an approximation of a sphere.
`static Object3D`
`createTetrahedron(double size, double xOffset, double yOffset, double zOffset, Color color)`
Creates a tetrahedron.
`static Object3D`
`createYSheet(double size, double x, double y, double z, 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, Color color)`
Creates a square flat surface in the x-y plane (constant z).
`Color`
`getColor()`
Returns the default face color as specified in the constructor.
`Color`
`getColor(Face face)`
Returns the color for a specific face.
`int`
`getFaceCount()`
Returns the number of faces.
`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.
`Object`
`getProperty(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(String key, 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 Details

### CLASS_KEY

public static final 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 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 String COLOR_PREFIX
A prefix used for setting color properties for an object.

Since:
  1.3
See Also:
  - Constant Field Values

## Constructor Details

### Object3D

public Object3D(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(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 Details

### getColor

public 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 Object getProperty(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(String key, 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 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, 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 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 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, 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, 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, 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, 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, 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, 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, Color extColor, 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, 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 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, Color barColor, Color baseColor, 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(String label, Font font, Color fgColor, 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