com.hedgehog.geo.threed.shapes
Class PlanarCircle3D

java.lang.Object
  com.hedgehog.HObject
      com.hedgehog.geo.GeometricObject
          com.hedgehog.geo.threed.GeometricObject3D
              com.hedgehog.geo.threed.shapes.Shape3D
                  com.hedgehog.geo.threed.shapes.PlanarCircle3D

All Implemented Interfaces:

ModelObject, java.lang.Comparable, java.util.Comparator

public class PlanarCircle3D
extends Shape3D
implements ModelObject

Title: PlanarCircle3D - models a circle lying within a 3D plane.

Description: Models a circle lying in a 3D plane.

Copyright: Copyright (c) Hedgehog Software 2007-2009.

Company: Hedgehog Software

Since:

1.0

Version:

1.1

Field Summary

protected Point3D	mCentre Circle centre.
protected Plane3D	mPlane Circle plane.
protected double	mRadius Circle radius.

Fields inherited from class com.hedgehog.HObject

mID, mName

Constructor Summary

PlanarCircle3D()
Default constructor.

PlanarCircle3D(ID id)
Constructor.

PlanarCircle3D(PlanarCircle3D object)
Copy constructor.

PlanarCircle3D(Point3D centre, double radius, Plane3D plane)
Constructor.

PlanarCircle3D(Point3D centre, double radius, Plane3D plane, java.lang.String name, ID id)
Constructor.

PlanarCircle3D(Point3D p1, Point3D p2, Point3D p3, double tolerance)
Constructor.

PlanarCircle3D(java.lang.String name)
Constructor.

PlanarCircle3D(java.lang.String name, ID id)
Constructor.

PlanarCircle3D(Vector3D n, double d, Point3D centre, double radius)
Constructor.

Method Summary

double	area() Returns the surface area of this circle; ie pir^2.
AxisAlignedBox3D	boundingBox() Returns the axis-aligned bounding of this planar circle.
Point3D	centroid() Returns the centroid of this circle; ie the centre.
java.util.Vector<ModelObject>	childModelObjects() Returns a vector of this object's child ModelObject objects.
double	circumference() Returns the circumference; ie 2pir.
PolyStraightLine3D	circumferencePolyStraightLine3D(int numberPoints, Point3D p, double tolerance) Returns a poly-straight-line representation of a circle.
java.sql.PreparedStatement	databaseInsertStatement(java.sql.Connection connection, int modelID) Returns a prepared statement for inserting (INSERT command) a ModelObject object into a database.
java.sql.PreparedStatement	databaseUpdateStatement(java.sql.Connection connection, int modelID) Returns a prepared statement for updating (UPDATE command) a ModelObject object into a database.
ModelObject	fromDatabase(java.sql.Connection connection, Model model, int modelID, int objectID) Returns a model object from the specified database table.
ModelObject	fromXMLNode(org.w3c.dom.Document document, org.w3c.dom.Node documentRootNode, org.w3c.dom.Node node, Model model) Returns a model object from the specified xml node.
Point3D	getCentre() Returns the circle centre.
Plane3D	getPlane() Returns the circle plane.
double	getRadius() Returns the circle radius.
java.util.Vector<Point3D>	intersection(InfiniteStraightLine3D line, double tolerance) Tests for intersection points between this plane circle and the specified infinite straight line.
java.util.Vector<Point3D>	intersection(PlanarCircle3D circle, double tolerance) Returns the intersection point(s), if any, between two planar circles.
java.util.Vector<Point3D>	intersection(Ray3D ray, double tolerance) Tests for intersection points between this plane circle and the specified ray.
java.util.Vector<Point3D>	intersection(StraightLine3D line, double tolerance) Returns the point/s of intersection between a planar circle and a straight line.
boolean	isSamePlane(PlanarCircle3D circle, double tolerance) Tests whether or not the specified planar circle has the same plane as this circle.
boolean	localAxes(Vector3D lx, Vector3D ly, Vector3D lz, boolean normalise) Returns a set of local axes for this planar circle.
double	perimeter() Returns the perimeter; ie the circumference.
Vector3D	planeNormal(boolean unitNormal) Returns this circle's plane normal.
boolean	pointInside(Point3D p, double tolerance) Tests whether or not the specified point is inside (not including the circumference) this circle.
Point3D	pointOnCircle(double theta, boolean degrees, double tolerance, Vector3D Ip, Vector3D Jq) Returns the point on a circle corresponding to the angle theta (0<=theta<=2pi radians) measured from the local Ip and Jq axes.
boolean	pointOnCirclePlane(Point3D p, double tolerance) Tests whether or not the specified point lies on this circle's plane.
boolean	pointOnCircumference(Point3D p, double tolerance) Tests whether or not the specified point is on the circumference of this circle.
boolean	pointOnSurface(Point3D p, double tolerance) Tests whether or not the specified point is on the surface of this circle; ie on the same plane and either inside or on the crcumference.
java.util.Vector<Point3D>	pointsOnCircle(int numberPoints, Point3D p, double tolerance) Returns a vector of evenly spaced points on this circle.
Point3D	randomPointOnCircumference(double tolerance) Returns a random point on this circle's circumference.
java.util.Vector<Point3D>	randomPointsOnCircumference(int numberPoints, double tolerance) Returns a vector of random points on this circle's circumference.
Shape3D	rotate(double theta, double beta, double gamma, Point3D fixedPoint, boolean degrees) Rotates this shape by the specified angles.
Shape3D	scale(double s, Point3D fixedPoint) Scales this circle about the specified fixed poiint or global origin.
void	setCentre(Point3D centre) Sets the circle centre.
void	setPlane(Plane3D plane) Sets the circle plane.
void	setRadius(double radius) Sets the circle radius.
Circle2D	toCircle2D() Returns a 2D equivalent of this Circle3D object.
java.lang.String	toString() Returns a String representation of an Circle2D object.
X3DNode	toX3DNode(X3DObject x3dObject) X3D support.
org.w3c.dom.Element	toXMLNode(org.w3c.dom.Document document, org.w3c.dom.Element documentRootNode) Returns the xml node of this object.
Shape3D	translate(double tx, double ty, double tz) Translates this shape by the specified vector (tx,ty,tz).
double	volume() Returns the volume of this shape.

Methods inherited from class com.hedgehog.geo.threed.shapes.Shape3D

is2D, is3D, isCurve, isGrid, isMesh, isPoint, isPointSet, isShape, isSurface, pointInsideOrOnSurface, pointOutside

Methods inherited from class com.hedgehog.geo.GeometricObject

objectDimension

Methods inherited from class com.hedgehog.HObject

clone, compare, compareTo, copy, equals, getID, getName, hashCode, hasID, hasName, setID, setName

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

mCentre

protected Point3D mCentre

Circle centre.

mRadius

protected double mRadius

Circle radius.

mPlane

protected Plane3D mPlane

Circle plane.

Constructor Detail

PlanarCircle3D

public PlanarCircle3D()

Default constructor. Calls Shape3D(). Sets the centre to (0,0,0), the radius to 1 and the default plane of (0,0,0,0).

PlanarCircle3D

public PlanarCircle3D(java.lang.String name)

Constructor. Sets the name of this shape. Calls Shape3D(). Sets the centre to (0,0,0), the radius to 1 and the default plane of (0,0,0,0).

Parameters:

name - Object name.

PlanarCircle3D

public PlanarCircle3D(ID id)

Constructor. Sets the ID of this shape. Calls Shape3D(). Sets the centre to (0,0,0), the radius to 1 and the default plane of (0,0,0,0).

Parameters:

id - Object ID.

PlanarCircle3D

public PlanarCircle3D(java.lang.String name,
                      ID id)

Constructor. Sets both the name and ID of this shape. Calls Shape3D(). Sets the centre to (0,0,0), the radius to 1 and the default plane of (0,0,0,0).

Parameters:

name - Object name.

id - Object ID.

PlanarCircle3D

public PlanarCircle3D(Point3D centre,
                      double radius,
                      Plane3D plane)

Constructor. Sets the centre, radius and plane to the specified objects.

Parameters:

centre - Circle centre.

radius - Circle radius.

plane - Circle plane.

PlanarCircle3D

public PlanarCircle3D(Point3D centre,
                      double radius,
                      Plane3D plane,
                      java.lang.String name,
                      ID id)

Constructor. Sets the centre, radius and plane to the specified objects.

Parameters:

centre - Circle centre.

radius - Circle radius.

plane - Circle plane.

name - Object name.

id - Objetc ID.

PlanarCircle3D

public PlanarCircle3D(Vector3D n,
                      double d,
                      Point3D centre,
                      double radius)

Constructor. Creates a new plane circle from the specified plane normal and distance (n,d) and the circle centre and radius.

Parameters:

n - Plane normal.

d - Plane distance to oriign.

centre - Circle centre.

radius - Circle radius.

PlanarCircle3D

public PlanarCircle3D(Point3D p1,
                      Point3D p2,
                      Point3D p3,
                      double tolerance)
               throws java.lang.IllegalArgumentException

Constructor. Creeates a new plane circle object from the specified three points.

Parameters:

p1 - Point 1.

p2 - Point 2.

p3 - Point 3.

tolerance - Required tolerance.

Throws:

java.lang.IllegalArgumentException - Thrown if the three points are collinear/coincident.

PlanarCircle3D

public PlanarCircle3D(PlanarCircle3D object)

Copy constructor.

Parameters:

object - Object to copy.

Method Detail

getCentre

public Point3D getCentre()

Returns the circle centre.

Returns:

Circle centre.

getRadius

public double getRadius()

Returns the circle radius.

Returns:

Circle radius.

getPlane

public Plane3D getPlane()

Returns the circle plane.

Returns:

circle plane.

setCentre

public void setCentre(Point3D centre)
               throws java.lang.IllegalArgumentException

Sets the circle centre.

Parameters:

centre - New circle centre.

Throws:

java.lang.IllegalArgumentException - Thrown if centre is null.

setRadius

public void setRadius(double radius)
               throws java.lang.IllegalArgumentException

Sets the circle radius.

Parameters:

radius - New circle radius.

Throws:

java.lang.IllegalArgumentException - Thrown if radius<0.0.

setPlane

public void setPlane(Plane3D plane)
              throws java.lang.IllegalArgumentException

Sets the circle plane.

Parameters:

plane - New circle plane.

Throws:

java.lang.IllegalArgumentException - Thrown if plane is null.

planeNormal

public Vector3D planeNormal(boolean unitNormal)

Returns this circle's plane normal.

Parameters:

unitNormal - Specifies whether or not the returned vector is to be normalised.

Returns:

Circle plane normal.

pointOnCirclePlane

public boolean pointOnCirclePlane(Point3D p,
                                  double tolerance)

Tests whether or not the specified point lies on this circle's plane.

Parameters:

p - point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p lies on this circle's plane, else logical-false.

isSamePlane

public boolean isSamePlane(PlanarCircle3D circle,
                           double tolerance)

Tests whether or not the specified planar circle has the same plane as this circle.

Parameters:

circle - Circle to compare.

tolerance - Required tolerance.

Returns:

Logical-true if the specified circle has the same plane as this circle, else logical-false.

pointOnCircle

public Point3D pointOnCircle(double theta,
                             boolean degrees,
                             double tolerance,
                             Vector3D Ip,
                             Vector3D Jq)
                      throws java.lang.IllegalArgumentException

Returns the point on a circle corresponding to the angle theta (0<=theta<=2pi radians) measured from the local Ip and Jq axes.

Parameters:

theta - Angle or rotation in radians measured in counterclockwise direction from Ip.

degrees - Specifies whether or not theta is in radians or degrees.

tolerance - Required tolerance.

Ip - Local x-axis.

Jq - Local y-axis.

Returns:

Point on circle circumference corresponding to the specified angle.

Throws:

java.lang.IllegalArgumentException - Thrown if theta is out of range [0:2pi] or if either Ip or Jq are not within the base circle plane.

localAxes

public boolean localAxes(Vector3D lx,
                         Vector3D ly,
                         Vector3D lz,
                         boolean normalise)

Returns a set of local axes for this planar circle. The x'-axis is formed by generating a random point on the circumference and then passing a vector from the centre through the circumferential point. The z'-axis is equal to the plane normal and y' is equal to x' x z'.

Parameters:

lx - Set to the local x'-axis.

ly - Set to the local y'-axis.

lz - Set to the local z'-axis.

normalise - Specifies whether or not the returned axes are normalised.

Returns:

Logical-true if the axes are set, else logical-false.

intersection

public java.util.Vector<Point3D> intersection(Ray3D ray,
                                              double tolerance)
                                       throws java.lang.IllegalArgumentException

Tests for intersection points between this plane circle and the specified ray.

Parameters:

ray - Ray to test for intersections.

tolerance - Required tolerance.

Returns:

Vector of intersection points,if any. If the ray is parallel to this plane then there are no zero intersection points. If the ray is not parallel to the circle plane and lies outside the circle plane then the plane-ray intersection point is found and tested to see if it falls inside or on the circumference of this circle; at most 1 intersection point. If the ray is within the circle plane then the problem effectively reduces to a local 2D problem with at most 2 intersection points.

Throws:

java.lang.IllegalArgumentException - Thrown if ray is null.

intersection

public java.util.Vector<Point3D> intersection(InfiniteStraightLine3D line,
                                              double tolerance)
                                       throws java.lang.IllegalArgumentException

Tests for intersection points between this plane circle and the specified infinite straight line.

Parameters:

line - Infinite straight line to test for intersections.

tolerance - Required tolerance.

Returns:

Vector of intersection points,if any. If the line is parallel to this plane then there are no zero intersection points. If the line is not parallel to the circle plane and lies outside the circle plane then the plane-ray intersection point is found and tested to see if it falls inside or on the circumference of this circle; at most 1 intersection point. If the line is within the circle plane then the problem effectively reduces to a local 2D problem with at most 2 intersection points.

Throws:

java.lang.IllegalArgumentException - Thrown if line is null.

intersection

public java.util.Vector<Point3D> intersection(StraightLine3D line,
                                              double tolerance)
                                       throws java.lang.IllegalArgumentException

Returns the point/s of intersection between a planar circle and a straight line.

Parameters:

line - Straight line to test for intersection with this planar circle.

tolerance - Required tolerance.

Returns:

Vector of point(s) of intersection, if any.

Throws:

java.lang.IllegalArgumentException - Thrown if line is null.

intersection

public java.util.Vector<Point3D> intersection(PlanarCircle3D circle,
                                              double tolerance)
                                       throws java.lang.IllegalArgumentException

Returns the intersection point(s), if any, between two planar circles. Note that if the two circles are in different planes then it is assumed that no intersection occurs.

Parameters:

circle - Other circle to test for intersection.

tolerance - Required tolerance.

Returns:

Vector of intersection point(s), if any.

Throws:

java.lang.IllegalArgumentException - Thrown if circle is null.

randomPointOnCircumference

public Point3D randomPointOnCircumference(double tolerance)
                                   throws InvalidObjectException

Returns a random point on this circle's circumference.

Parameters:

tolerance - Required tolerance.

Returns:

Random point on this circle's circumference.

Throws:

InvalidObjectException - Thrown if internal problem generating local x'-axis in circle plane.

randomPointsOnCircumference

public java.util.Vector<Point3D> randomPointsOnCircumference(int numberPoints,
                                                             double tolerance)
                                                      throws java.lang.IllegalArgumentException

Returns a vector of random points on this circle's circumference. Ensures that the returned vector of points is unique, although enforcing uniquness may mean that there are fewer points than requested.

Parameters:

numberPoints - Number of points.

tolerance - Required tolerance.

Returns:

Vector of random points on this circle's circumference. Returns an empty vector if an internal error occurred.

Throws:

java.lang.IllegalArgumentException - Thrown if numberPoints<=0.

pointsOnCircle

public java.util.Vector<Point3D> pointsOnCircle(int numberPoints,
                                                Point3D p,
                                                double tolerance)
                                         throws java.lang.IllegalArgumentException

Returns a vector of evenly spaced points on this circle.

Parameters:

numberPoints - Number of points.

p - Start point from which other points are generated. If null then a random point on the circumference is selected.

tolerance - Required tolerance.

Returns:

A vector of points on this circle's circumference. Returns an empty vector if an internal error occurred.

Throws:

java.lang.IllegalArgumentException - Thrown if numberPoints<=0 or p (if not null) does not lies on this circle's circumference.

toCircle2D

public Circle2D toCircle2D()

Returns a 2D equivalent of this Circle3D object. Sets the 2D origin at (0,0) and the same radius. It will still be necessary to setup local axes, maybe using PlaneWithLocalAxes.

Returns:

Circle2D equivalent.

toString

public java.lang.String toString()

Returns a String representation of an Circle2D object.

Overrides:

toString in class java.lang.Object

Returns:

A String representation of an Circle2D object.

circumferencePolyStraightLine3D

public PolyStraightLine3D circumferencePolyStraightLine3D(int numberPoints,
                                                          Point3D p,
                                                          double tolerance)
                                                   throws java.lang.IllegalArgumentException

Returns a poly-straight-line representation of a circle.

Parameters:

numberPoints - The number of points on the polyline.

p - Start point. Must be on the circle circumference.

tolerance - Required tolerance.

Returns:

Polyline representation of this circle.

Throws:

java.lang.IllegalArgumentException - Thrown if p is not on the circle circumference.

pointOnCircumference

public boolean pointOnCircumference(Point3D p,
                                    double tolerance)

Tests whether or not the specified point is on the circumference of this circle.

Parameters:

p - Point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p is on the circumference of this circle, else logical-false.

perimeter

public double perimeter()

Returns the perimeter; ie the circumference.

Returns:

The circumference.

circumference

public double circumference()

Returns the circumference; ie 2pir.

Returns:

The circumference.

area

public double area()

Returns the surface area of this circle; ie pir^2.

Specified by:

area in class Shape3D

Returns:

Surface area of this circle.

boundingBox

public AxisAlignedBox3D boundingBox()

Returns the axis-aligned bounding of this planar circle. A box centred at the circle centre of x, y and z widths equal to 2r is returned. Not a particularly tight bbox but fast to compute.

Specified by:

boundingBox in class Shape3D

Returns:

Axis-aligned bounding box.

centroid

public Point3D centroid()

Returns the centroid of this circle; ie the centre.

Specified by:

centroid in class Shape3D

Returns:

Centroid.

pointInside

public boolean pointInside(Point3D p,
                           double tolerance)

Tests whether or not the specified point is inside (not including the circumference) this circle.

Specified by:

pointInside in class Shape3D

Parameters:

p - Point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p is inside this circle, else logical-false.

pointOnSurface

public boolean pointOnSurface(Point3D p,
                              double tolerance)

Tests whether or not the specified point is on the surface of this circle; ie on the same plane and either inside or on the crcumference.

Specified by:

pointOnSurface in class Shape3D

Parameters:

p - Point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p is on the circumference of this circle, else logical-false.

rotate

public Shape3D rotate(double theta,
                      double beta,
                      double gamma,
                      Point3D fixedPoint,
                      boolean degrees)
               throws java.lang.IllegalArgumentException

Rotates this shape by the specified angles.

Specified by:

rotate in class Shape3D

Parameters:

theta - Angle about x-axis; in range [0:360] degrees or [0:2pi] radians.

beta - Angle about y-axis; in range [0:360] degrees or [0:2pi] radians.

gamma - Angle about z-axis; in range [0:360] degrees or [0:2pi] radians.

fixedPoint - Rotationa fixed point or global origin is null.

degrees - Specifies whether or not the anhles are in degrees or radians.

Returns:

Rotated shape.

Throws:

java.lang.IllegalArgumentException - Thrown if angles are out of range.

scale

public Shape3D scale(double s,
                     Point3D fixedPoint)

Scales this circle about the specified fixed poiint or global origin. Note that fixedPoint is not used for scaling planar circles. only the radius is scaled.

Specified by:

scale in class Shape3D

Parameters:

s - Scalaing factor.

fixedPoint - Scaling fixed point or global origin if null.

Returns:

Scaled circle.

translate

public Shape3D translate(double tx,
                         double ty,
                         double tz)

Translates this shape by the specified vector (tx,ty,tz).

Specified by:

translate in class Shape3D

Parameters:

tx - Translation in x-direction.

ty - Translation in y-direction.

tz - Translation in z-direction.

Returns:

Translated shape.

volume

public double volume()

Returns the volume of this shape.

Specified by:

volume in class Shape3D

Returns:

The volume of this shape.

childModelObjects

public java.util.Vector<ModelObject> childModelObjects()

Returns a vector of this object's child ModelObject objects.

Specified by:

childModelObjects in interface ModelObject

Returns:

A vector with the 2 elements of the centre and plane.

databaseInsertStatement

public java.sql.PreparedStatement databaseInsertStatement(java.sql.Connection connection,
                                                          int modelID)
                                                   throws java.sql.SQLException

Returns a prepared statement for inserting (INSERT command) a ModelObject object into a database.

Specified by:

databaseInsertStatement in interface ModelObject

Parameters:

connection - Database connection.

modelID - Model ID.

Returns:

A prepared statement for inserting a ModelObject object into a database.

Throws:

java.sql.SQLException - Thrown if an SQL exception occurs.

databaseUpdateStatement

public java.sql.PreparedStatement databaseUpdateStatement(java.sql.Connection connection,
                                                          int modelID)
                                                   throws java.sql.SQLException

Returns a prepared statement for updating (UPDATE command) a ModelObject object into a database.

Specified by:

databaseUpdateStatement in interface ModelObject

Parameters:

connection - Database connection.

modelID - Model ID.

Returns:

A prepared statement for inserting a ModelObject object into a database.

Throws:

java.sql.SQLException - Thrown if an SQL exception occurs.

toXMLNode

public org.w3c.dom.Element toXMLNode(org.w3c.dom.Document document,
                                     org.w3c.dom.Element documentRootNode)
                              throws InvalidObjectException

Returns the xml node of this object.

Specified by:

toXMLNode in interface ModelObject

Parameters:

document - XML document.

documentRootNode - Douument root node.

Returns:

The xml node of this object.

Throws:

InvalidObjectException - Thrown if this object's ID is equal to the default ID of -1.

fromXMLNode

public ModelObject fromXMLNode(org.w3c.dom.Document document,
                               org.w3c.dom.Node documentRootNode,
                               org.w3c.dom.Node node,
                               Model model)
                        throws InvalidObjectException

Returns a model object from the specified xml node.

Specified by:

fromXMLNode in interface ModelObject

Parameters:

document - XML document.

documentRootNode - Document root node; ie Model node.

node - XML node.

model - Model to which node object is added.

Returns:

ModelObject corresponding to the specified node. A null value is returned if an error occurred building the object.

Throws:

InvalidObjectException - Thrown if an error occurred building the object.

fromDatabase

public ModelObject fromDatabase(java.sql.Connection connection,
                                Model model,
                                int modelID,
                                int objectID)
                         throws java.sql.SQLException

Returns a model object from the specified database table.

Specified by:

fromDatabase in interface ModelObject

Parameters:

connection - Database connection.

modelID - Model ID.

objectID - Object ID in associated ModelObjects table.

model - Model built from database.

Returns:

ModelObject corresponding to the specified db connection, model ID and obect ID. A null value is returned if no match found.

Throws:

java.sql.SQLException - Thrown if an SQL exception occurs.

toX3DNode

public X3DNode toX3DNode(X3DObject x3dObject)
                  throws InvalidObjectException

X3D support. Renders as an IndexedFaceSet node with a set of triangles focued at the centre.

Specified by:

toX3DNode in interface ModelObject

Parameters:

x3dObject - X3D object.

Returns:

X3D object or null if object has no visualisation.

Throws:

InvalidObjectException - Thrown if this object is invalid.