artofillusion.object
Class ImplicitObject

java.lang.Object
  extended by artofillusion.object.Object3D
      extended by artofillusion.object.ImplicitObject
Direct Known Subclasses:
CompoundImplicitObject, ImplicitSphere

public abstract class ImplicitObject
extends Object3D

This abstract class represents an object whose surface is defined as an isosurface of a 3D field function. Subclasses define the function and isosurface value used to generate a particular surface. More precisely, the interior of the object is defined to consist of all points which satisfy the following conditions:

  1. The value of the field at that point is greater than the cutoff value.
  2. The point is inside the bounding box returned by getBounds().
In general, an implicit surface can be rendered in two different ways: by triangulating the surface, or by directly evaluating the field function (e.g. raymarching). Some renderers do not have the ability to visualize implicit surfaces directly, and therefore must use triangulation. When direct visualization is supported, the object can specify which is the preferred method to use. It does this by implementing getPreferDirectRendering().


Field Summary
 
Fields inherited from class artofillusion.object.Object3D
APPROXIMATELY, CANT_CONVERT, EXACTLY
 
Constructor Summary
ImplicitObject()
          The default constructor does nothing.
ImplicitObject(java.io.DataInputStream in, Scene theScene)
          Subclasses should invoke this method in their own constructors for loading from a file.
 
Method Summary
 int canConvertToTriangleMesh()
          Tells whether the object can be converted to a TriangleMesh.
 TriangleMesh convertToTriangleMesh(double tol)
          Return a TriangleMesh which reproduces the shape of this object.
 void generateMesh(double tol, java.util.List<Vec3> vertices, java.util.List<int[]> faces)
          Construct a mesh from the implicit function.
 double getCutoff()
          Get the cutoff value which defines the surface of the object.
 void getFieldGradient(double x, double y, double z, double size, double time, Vec3 grad)
          Get the gradient of the field function at a point specified in object coordinates.
abstract  double getFieldValue(double x, double y, double z, double size, double time)
          Get the value of the field function at a point specified in object coordinates.
 double getMaxGradient()
          Get the maximum value which can ever occur for the absolute value of the field gradient.
abstract  boolean getPreferDirectRendering()
          Get the preferred rendering method to use when this object is rendered by a renderer that supports direct evaluation of the field.
 RenderingMesh getRenderingMesh(double tol, boolean interactive, ObjectInfo info)
          Objects which can be rendered as part of a scene should override this method to return a RenderingMesh which describes the appearance of the object.
 WireframeMesh getWireframeMesh()
          Every object should override this method to return a WireframeMesh.
 void sceneChanged(ObjectInfo info, Scene scene)
          This will be called whenever this object is moved, or the time changes.
 void writeToFile(java.io.DataOutputStream out, Scene theScene)
          Subclasses should invoke this method in their own writeToFile() methods.
 
Methods inherited from class artofillusion.object.Object3D
applyPoseKeyframe, canConvertToActor, canSetMaterial, canSetTexture, configurePoseTrack, copyObject, copyTextureAndMaterial, duplicate, edit, editGesture, editKeyframe, getAverageParameterValues, getBounds, getMaterial, getMaterialMapping, getParameters, getParameterValue, getParameterValues, getPosableObject, getPoseKeyframe, getProperties, getPropertyValue, getSkeleton, getTexture, getTextureMapping, isClosed, isEditable, readParameterValue, renderObject, setMaterial, setParameters, setParameterValue, setParameterValues, setPropertyValue, setSize, setTexture
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ImplicitObject

public ImplicitObject()
The default constructor does nothing.


ImplicitObject

public ImplicitObject(java.io.DataInputStream in,
                      Scene theScene)
               throws java.io.IOException,
                      java.io.InvalidObjectException
Subclasses should invoke this method in their own constructors for loading from a file.

Throws:
java.io.IOException
java.io.InvalidObjectException
Method Detail

getFieldValue

public abstract double getFieldValue(double x,
                                     double y,
                                     double z,
                                     double size,
                                     double time)
Get the value of the field function at a point specified in object coordinates.

Parameters:
x - the x coordinate of the location at which to evaluate the function
y - the y coordinate of the location at which to evaluate the function
z - the z coordinate of the location at which to evaluate the function
size - the width of the region over which to average the function for antialiasing
time - the time at which the function is being evaluated
Returns:
the value of the field function at the specified location

getFieldGradient

public void getFieldGradient(double x,
                             double y,
                             double z,
                             double size,
                             double time,
                             Vec3 grad)
Get the gradient of the field function at a point specified in object coordinates.

The default implementation of this method estimates the gradient by evaluating the field function at several closely spaced points. In many cases, it is possible to calculate the gradient both more quickly and more accurately by analytical means. Whenever possible, this method should be overridden to calculate the gradient directly.

Parameters:
x - the x coordinate of the location at which to evaluate the function
y - the y coordinate of the location at which to evaluate the function
z - the z coordinate of the location at which to evaluate the function
size - the width of the region over which to average the function for antialiasing
time - the time at which the function is being evaluated
grad - on exit, this should be set equal to the gradient of the field function at the specified location

getMaxGradient

public double getMaxGradient()
Get the maximum value which can ever occur for the absolute value of the field gradient. The default implementation returns Double.MAX_VALUE. If you can guarantee that the gradient will never be larger than some fixed value, overriding this method to return it may allow faster rendering.


getCutoff

public double getCutoff()
Get the cutoff value which defines the surface of the object. Points for which the field value is greater than the cutoff are inside the object.

The default implementation returns 1.0. It may be overridden to return a different value.


getPreferDirectRendering

public abstract boolean getPreferDirectRendering()
Get the preferred rendering method to use when this object is rendered by a renderer that supports direct evaluation of the field.

Returns:
true if direct evaluation is preferred, false if it is preferable to triangulate the surface by calling getRenderingMesh()

writeToFile

public void writeToFile(java.io.DataOutputStream out,
                        Scene theScene)
                 throws java.io.IOException
Subclasses should invoke this method in their own writeToFile() methods.

Overrides:
writeToFile in class Object3D
Throws:
java.io.IOException

canConvertToTriangleMesh

public int canConvertToTriangleMesh()
Description copied from class: Object3D
Tells whether the object can be converted to a TriangleMesh. It should return one of the following values: CANT_CONVERT: The object cannot be converted to a TriangleMesh. EXACTLY: The object can be represented exactly by a TriangleMesh. APPROXIMATELY: The object can be converted to a TriangleMesh. However, the resulting mesh will not be exactly the same shape as the original object. If a class overrides this method, it must also override convertToTriangleMesh().

Overrides:
canConvertToTriangleMesh in class Object3D

convertToTriangleMesh

public TriangleMesh convertToTriangleMesh(double tol)
Description copied from class: Object3D
Return a TriangleMesh which reproduces the shape of this object. If canConvertToTriangleMesh() returned APPROXIMATELY, this method should return a TriangleMesh which reproduces the object to within the specified tolerance. That is, no point on the mesh should be further than tol from the corresponding point on the original surface. If canConvertToTriangleMesh() returned EXACTLY, then tol should be ignored. If canConvertToTriangleMesh() return CANT_CONVERT, this method returns null.

Overrides:
convertToTriangleMesh in class Object3D

getRenderingMesh

public RenderingMesh getRenderingMesh(double tol,
                                      boolean interactive,
                                      ObjectInfo info)
Description copied from class: Object3D
Objects which can be rendered as part of a scene should override this method to return a RenderingMesh which describes the appearance of the object. All points on the RenderingMesh should be within a distance tol of the true surface. The interactive flag tells whether the resulting Mesh will be rendered in interactive mode. When interactive is set to true, the RenderingMesh should be cached for future use, so that it may be rendered repeatedly without needing to be regenerated.

The ObjectInfo contains additional information which may affect how the object is rendered, such as it location in the scene, texture parameters, etc.

Objects which cannot be rendered directly (lights, cameras, curves, etc.) do not need to override this method.

Overrides:
getRenderingMesh in class Object3D

getWireframeMesh

public WireframeMesh getWireframeMesh()
Description copied from class: Object3D
Every object should override this method to return a WireframeMesh. This will be used for drawing the object in wireframe mode, and also for drawing "nonrenderable" objects in other rendering modes.

Specified by:
getWireframeMesh in class Object3D

sceneChanged

public void sceneChanged(ObjectInfo info,
                         Scene scene)
Description copied from class: Object3D
This will be called whenever this object is moved, or the time changes. Most objects will do nothing here, and do not need to override this. It is available for those cases where an object's internal properties depend explicitly on time or on the object's position within the scene.

Overrides:
sceneChanged in class Object3D

generateMesh

public void generateMesh(double tol,
                         java.util.List<Vec3> vertices,
                         java.util.List<int[]> faces)
Construct a mesh from the implicit function.

Parameters:
tol - the surface error tolerance
vertices - the coordinates of mesh vertices will be added to this List
faces - an int[3] will be added to this List containing the vertex indices for each mesh face


Copyright © 1999-2011 by Peter Eastman.