com.hedgehog.geo.threed.shapes
Class Sphere3D

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.Sphere3D

All Implemented Interfaces:

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

Direct Known Subclasses:

AbstractPlanet, Moon

public class Sphere3D
extends Shape3D
implements ModelObject

Title: Sphere3D - models a 3D sphere as a centre and radius.

Description: Models a 3D sphere.

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

Company: Hedgehog Software

Since:

1.0

Version:

1.1

Field Summary

protected Point3D	mCentre Sphere centre.
protected double	mRadius Sphere radius.

Fields inherited from class com.hedgehog.HObject

mID, mName

Constructor Summary

Sphere3D()
Constructor.

Sphere3D(double radius)
Creates a new sphere of the specified radius with centre at (0,0,0).

Sphere3D(ID id)
Constructor.

Sphere3D(Point3D centre, double radius)
Creates a new sphere of the specified radius and specified centre.

Sphere3D(Point3D centre, double radius, java.lang.String name, ID id)
Creates a new sphere of the specified radius and specified centre.

Sphere3D(Point3D p1, Point3D p2, Point3D p3, Point3D p4, double tolerance)
Constructor.

Sphere3D(Sphere3D object)
Copy constructor.

Sphere3D(java.lang.String name)
Constructor.

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

Sphere3D(java.util.Vector<Point3D> points, int maxIterations, double tolerance)
Constructor.

Method Summary

double	arcDistanceBetween(Point3D p, Point3D q) Returns the distance along a great circular arc between the two specified points.
double	area() Returns the surface area of this sphere; ie 4PIr^2.
Point3D	axisXPoint() Returns the point where the x-axis intersects the sphere.
Vector3D	axisXVector() Returns the vector from the sphere centre to axisXPoint().
Point3D	axisYPoint() Returns the point where the y-axis intersects the sphere.
Vector3D	axisYVector() Returns the vector from the sphere centre to axisYPoint().
Point3D	axisZPoint() Returns the point where the z-axis intersects the sphere.
Vector3D	axisZVector() Returns the vector from the sphere centre to axisZPoint().
AxisAlignedBox3D	boundingBox() Returns the axis-aligned bounding box of this sphere.
Point3D	centroid() Returns the centroid of this sphere; ie its centre.
java.util.Vector<ModelObject>	childModelObjects() Returns a vector of this object's child ModelObject objects.
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.
double	diameter() Returns the sphere diameter; ie 2r.
Point3D	diametricallyOppositePoint(Point3D p, double tolerance) Returns the point diametrically opposite the specified point.
double	distanceToSphere(Point3D p) Returns the distance from the specfied point to the sphere surface.
static Sphere3D	enclosingSphere(Sphere3D sphere0, Sphere3D sphere1) Returns the sphere that encloses the two specified spheres.
static Sphere3D	enclosingSphereAverageCentre(java.util.Vector<Point3D> points) Returns the smallest sphere whose centre is the average of the input points.
PlanarCircle3D	equatorCircle() Returns the planar great circle passing through the centre, axisXPoint() and axisYPoint().
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	furthestPoint(Point3D q, double tolerance) Returns the furthest point on this sphere's circumference from the specified point.
double	gaussCurvature() Returns the Gauss curvature; ie k=1/r^2.
Point3D	getCentre() Returns the sphere centre.
double	getRadius() Returns the sphere radius.
PlanarCircle3D	greatCircle(double pPhi, double pTheta, double qPhi, double qTheta, boolean degrees) Returns a great circle passing through this sphere's centre and the two specified points p(pPhi,pTheta) and q(qPhi,qTheta).
PlanarCircle3D	greatCircle(Point3D p, Point3D q) Returns a great circle passing through the points p and q.
Intersection3D	intersection(Plane3D plane, double tolerance) Tests for intersection between the specified plane and this sphere.
Intersection3D	intersection(Ray3D ray, double tolerance) Returns the intersection object between a sphere and a ray.
Intersection3D	intersection(Sphere3D sphere, double tolerance) Tests for intersection between this sphere and the specified sphere.
Intersection3D	intersection(StraightLine3D line, double tolerance) Returns the intersection object between a sphere and a straight line segment.
double	intersectionVolume(Sphere3D sphere) Returns the volume of intersection between this sphere and the specified sphere; ie the volume of the resulting lens shape.
int	kissingNumber() The "kissing number" is the maximum number of times a sphere can touch a central sphere, with all spheres having same size and without intersecting other spheres.
double	latitude(Point3D p, boolean degrees) Returns the latitude of point p in the range [-90:+90] degrees where -90 degrees is the south pole and +90 degrees is the north pole.
double	longitude(Point3D p, boolean degrees) Returns the longitude of point p in the range [0:+360] degrees where 0 degrees is zero longitude (x-axis) and +360 is a full revolution and also corresponds to zero longitude.
double	meanCurvature() Returns the mean curvature; ie h=1/r.
Point3D	nearestPoint(Point3D q, double tolerance) Returns the nearest point on this sphere's surface to the specified point.
Point3D	northPole() Returns the north pole point; ie (cx,cy,cz+r).
Vector3D	outwardNormal(Point3D p, boolean normalise) Returns the outward normal at the specified point.
PairDouble	phiAndThetaFromPoint(Point3D p, boolean degrees) Returns the phi and theta values corresponding to point p.
boolean	pointInside(Point3D p, double tolerance) Tests whether or not the specified point is inside this sphere.
boolean	pointInsideOrOnSurface(Point3D p, double tolerance) Tests whether or not the specified point is either inside or on the surface of this sphere.
Point3D	pointOnSphere(double phiRadians, double thetaRadians) Returns the point on a sphere corresponding to the angles phi (-pi/2<=phi<=pi/2) and theta (-pi<=theta<=pi), (both in radians).
boolean	pointOnSurface(Point3D p, double tolerance) Tests whether or not the specified point is on the surface of this sphere.
boolean	pointOutside(Point3D p, double tolerance) Tests whether or not the specified point is outside this sphere.
java.util.Vector<Point3D>	randomPointsInsideSphere(int no_of_random_points) Returns a vector of random points inside a sphere.
java.util.Vector<Point3D>	randomPointsOnSphere(int no_of_random_points) Returns a vector of random points on the surface of a sphere.
Shape3D	rotate(double theta, double beta, double gamma, Point3D fixedPoint, boolean degrees) Rotates this sphere angle theta about z, beta about y and gamma about x.
Shape3D	scale(double s, Point3D fixedPoint) Scales this sphere by multiplying the radius by the specified scaling factor.
void	setCentre(Point3D centre) Sets the centre.
void	setRadius(double radius) Sets the radius.
Point3D	southPole() Returns the north pole point; ie (cx,cy,cz-r).
PlanarCircle3D	sphereCircle(double phi_theta_radians, boolean const_phi) Returns a circle on this sphere.
QuadraticSurface3D	toQuadraticSurface3D() Returns the quadratic surface equation equivalent of this sphere; ie Q=(Gz^2+Hxz+Iyz+Jz)+(Ax^2+Bxy+Cy^2+Dx+Ey+F)=0.
java.lang.String	toString() Returns a String representation of a Sphere3D 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.
void	transform(Matrix4x4 matrix) Applies the specified transformation matrix to this polygon.
Shape3D	translate(double tx, double ty, double tz) Translates this sphere by the specified translate vector (tx,ty,tz).
double	volume() Returns the volume of this sphere; ie (4/3)PI.r^3.
HDouble	xValue(HDouble phiRadians, HDouble thetaRadians) Returns the x-coordinate of a point on a sphere's surface specified by the (phi,theta) values.
HDouble	yValue(HDouble phiRadians, HDouble thetaRadians) Returns the y-coordinate of a point on a sphere's surface specified by the (phi,theta) values.
HDouble	zValue(HDouble phiRadians, HDouble thetaRadians) Returns the z-coordinate of a point on a sphere's surface specified by the (phi,theta) values.

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

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

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

Sphere centre.

mRadius

protected double mRadius

Sphere radius.

Constructor Detail

Sphere3D

public Sphere3D()

Constructor. Creates a new sphere of unit radius with centre at (0,0,0).

Sphere3D

public Sphere3D(double radius)

Creates a new sphere of the specified radius with centre at (0,0,0).

Parameters:

radius - Sphere radius.

Sphere3D

public Sphere3D(Point3D centre,
                double radius)

Creates a new sphere of the specified radius and specified centre.

Parameters:

centre - Sphere centre.

radius - Sphere radius.

Sphere3D

public Sphere3D(Point3D centre,
                double radius,
                java.lang.String name,
                ID id)

Creates a new sphere of the specified radius and specified centre.

Parameters:

centre - Sphere centre.

radius - Sphere radius.

name - Object name.

id - Object ID.

Sphere3D

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

Constructor. Sphere defined by four points. Ensure that the 4 points are not co-planar.

Parameters:

p1 - Point 1.

p2 - Point 2.

p3 - Point 3.

p4 - Point 4.

tolerance - Required tolerance.

Throws:

java.lang.IllegalArgumentException - Thrown if either p1, p2, p3 or p4 are null. Also thrown if the 4 points are co-planar.

Sphere3D

public Sphere3D(java.util.Vector<Point3D> points,
                int maxIterations,
                double tolerance)
         throws java.lang.IllegalArgumentException

Constructor. Constructs a sphere from the specified vector of points. Uses the method of least-squares to generate a best-fit sphere.

Parameters:

points - Vector of points. must be at least 4 points in order to fit a sphere.

maxIterations - Maximum number of iterations used to generate a sphere from the specified vector of points. A value of 100 with a tolerance of 1e-03 is suitable for most cases.

tolerance - Required tolerance.

Throws:

java.lang.IllegalArgumentException - Thrown if points is null, points has less than 4 elements or the method did not converge in generating a sphere that passes through the points vector.

Sphere3D

public Sphere3D(java.lang.String name)

Constructor. Creates a new sphere of unit radius with centre at (0,0,0).

Parameters:

name - Sphere name.

Sphere3D

public Sphere3D(ID id)

Constructor. Creates a new sphere of unit raius with centre at (0,0,0).

Parameters:

id - Sphere ID.

Sphere3D

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

Constructor. Creates a new sphere of unit raius with centre at (0,0,0).

Parameters:

name - Sphere name.

id - Sphere ID.

Sphere3D

public Sphere3D(Sphere3D object)

Copy constructor.

Parameters:

object - Object to copy.

Method Detail

getCentre

public Point3D getCentre()

Returns the sphere centre.

Returns:

Sphere centre.

getRadius

public double getRadius()

Returns the sphere radius.

Returns:

Sphere radius.

setCentre

public void setCentre(Point3D centre)

Sets the centre.

Parameters:

centre - New centre.

setRadius

public void setRadius(double radius)

Sets the radius.

Parameters:

radius - New radius.

diameter

public double diameter()

Returns the sphere diameter; ie 2r.

Returns:

Sphere diameter.

distanceToSphere

public double distanceToSphere(Point3D p)

Returns the distance from the specfied point to the sphere surface. The returned distance is to the sphere surface and caters for points inside, on the surface and outside.

Parameters:

p - Point from which to find distance.

Returns:

The straight-line distance from p to sphere surface.

nearestPoint

public Point3D nearestPoint(Point3D q,
                            double tolerance)

Returns the nearest point on this sphere's surface to the specified point. Note that if q is at the sphere centre then the nearest point is undefined and a copy of q is returned.

Parameters:

q - Point to find nearest point.

tolerance - Required tolerance.

Returns:

Nearest sphere surface point to the specified point.

furthestPoint

public Point3D furthestPoint(Point3D q,
                             double tolerance)

Returns the furthest point on this sphere's circumference from the specified point. Note that if q is at the sphere centre then the nearest point is undefined and a copy of q is returned.

Parameters:

q - Point to find furthest point.

tolerance - Required tolerance.

Returns:

Furthest sphere point to the specified point. Returns null if unable to determine the furthest point.

diametricallyOppositePoint

public Point3D diametricallyOppositePoint(Point3D p,
                                          double tolerance)
                                   throws java.lang.IllegalArgumentException

Returns the point diametrically opposite the specified point.

Parameters:

p - Point on surface.

tolerance - Required tolerance.

Returns:

Diametrically opposite point.

Throws:

java.lang.IllegalArgumentException - Thrown if p is not on the surface of this sphere.

outwardNormal

public Vector3D outwardNormal(Point3D p,
                              boolean normalise)
                       throws java.lang.IllegalArgumentException

Returns the outward normal at the specified point.

Parameters:

p - Point at which to find the outward normal.

normalise - Specifies whether or not the returned normal is normalised.

Returns:

Outward normal acting from the sphere centre, through p.

Throws:

java.lang.IllegalArgumentException - Thrown if p is not on this sphere.

northPole

public Point3D northPole()

Returns the north pole point; ie (cx,cy,cz+r).

Returns:

North pole point.

southPole

public Point3D southPole()

Returns the north pole point; ie (cx,cy,cz-r).

Returns:

North pole point.

pointOnSphere

public Point3D pointOnSphere(double phiRadians,
                             double thetaRadians)
                      throws java.lang.IllegalArgumentException

Returns the point on a sphere corresponding to the angles phi (-pi/2<=phi<=pi/2) and theta (-pi<=theta<=pi), (both in radians). In other words, this method provides a mapping from (latitude,longitude) coordinates to Cartesian coordinates.

Parameters:

phiRadians - The latitude angle phi in radians [-PI/2:+PI/2].

thetaRadians - The longitude angle theta in radians [-PI:+PI].

Returns:

The (px,py,pz) point on the sphere surface corresponding to the specified phi and theta angles.

Throws:

java.lang.IllegalArgumentException - Thrown if phi_radians or theta_radians are out of range.

phiAndThetaFromPoint

public PairDouble phiAndThetaFromPoint(Point3D p,
                                       boolean degrees)

Returns the phi and theta values corresponding to point p. The latitude (phi) is in the range [-90:+90] degrees and the longitude (theta) is in the range [-180:180]. The range of the longitude differs from the [0:360] range for conventional longitude values; if this is required then use the longitude() method. Ensure that p does lie on the sphere surface.

Parameters:

p - Point to map to latitude, longitude coordinates.

degrees - If logical-true then the returned pair of angles will be in degrees, else in radians.

Returns:

Pair of (phi,theta) values of the point p.

randomPointsInsideSphere

public java.util.Vector<Point3D> randomPointsInsideSphere(int no_of_random_points)
                                                   throws java.lang.IllegalArgumentException

Returns a vector of random points inside a sphere.

Parameters:

no_of_random_points - Number of random points.

Returns:

Vector of random points inside this sphere.

Throws:

java.lang.IllegalArgumentException - Thrown if no_of_random_points is <=0.

randomPointsOnSphere

public java.util.Vector<Point3D> randomPointsOnSphere(int no_of_random_points)
                                               throws java.lang.IllegalArgumentException

Returns a vector of random points on the surface of a sphere.

Parameters:

no_of_random_points - Number of random points.

Returns:

Vector of points.

Throws:

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

axisXPoint

public Point3D axisXPoint()

Returns the point where the x-axis intersects the sphere.

Returns:

The point where the x-axis intersects the sphere.

axisYPoint

public Point3D axisYPoint()

Returns the point where the y-axis intersects the sphere.

Returns:

The point where the y-axis intersects the sphere.

axisZPoint

public Point3D axisZPoint()

Returns the point where the z-axis intersects the sphere.

Returns:

The point where the z-axis intersects the sphere.

axisXVector

public Vector3D axisXVector()

Returns the vector from the sphere centre to axisXPoint().

Returns:

The vector from the sphere centre to axisXPoint().

axisYVector

public Vector3D axisYVector()

Returns the vector from the sphere centre to axisYPoint().

Returns:

The vector from the sphere centre to axisYPoint().

axisZVector

public Vector3D axisZVector()

Returns the vector from the sphere centre to axisZPoint().

Returns:

The vector from the sphere centre to axisZPoint().

arcDistanceBetween

public double arcDistanceBetween(Point3D p,
                                 Point3D q)

Returns the distance along a great circular arc between the two specified points. For details about the method used refer to the article in EPE Dec '04.

Parameters:

p - Point p on sphere surface.

q - Point q on sphere surface.

Returns:

Returns the distance between the two points measured along a great circular arc.

longitude

public double longitude(Point3D p,
                        boolean degrees)

Returns the longitude of point p in the range [0:+360] degrees where 0 degrees is zero longitude (x-axis) and +360 is a full revolution and also corresponds to zero longitude.

Parameters:

p - Point in which latitude is required.

degrees - Specifies whether degrees or radians is required.

Returns:

The latitude of point p.

latitude

public double latitude(Point3D p,
                       boolean degrees)

Returns the latitude of point p in the range [-90:+90] degrees where -90 degrees is the south pole and +90 degrees is the north pole.

Parameters:

p - Point in which latitude is required.

degrees - Specifies whether degrees or radians is required.

Returns:

The latitude of point p.

xValue

public HDouble xValue(HDouble phiRadians,
                      HDouble thetaRadians)
               throws java.lang.IllegalArgumentException

Returns the x-coordinate of a point on a sphere's surface specified by the (phi,theta) values. The signature of this method is HDouble f(HDouble,HDouble) and can be used by the 2-variable optimisers.

Parameters:

phiRadians - phi value of point on surface. Must be in range [-PI/2:PI/2].

thetaRadians - theta value of point on surface. Must be in range [-PI:PI].

Returns:

x-coordinate of point (phi,theta).

Throws:

java.lang.IllegalArgumentException - Thrown if phiRadians or thetaRadians are out of range.

yValue

public HDouble yValue(HDouble phiRadians,
                      HDouble thetaRadians)
               throws java.lang.IllegalArgumentException

Returns the y-coordinate of a point on a sphere's surface specified by the (phi,theta) values. The signature of this method is HDouble f(HDouble,HDouble) and can be used by the 2-variable optimisers.

Parameters:

phiRadians - phi value of point on surface. Must be in range [-PI/2:PI/2].

thetaRadians - theta value of point on surface. Must be in range [-PI:PI].

Returns:

y-coordinate of point (phi,theta).

Throws:

java.lang.IllegalArgumentException - Thrown if phiRadians or thetaRadians are out of range.

zValue

public HDouble zValue(HDouble phiRadians,
                      HDouble thetaRadians)
               throws java.lang.IllegalArgumentException

Returns the z-coordinate of a point on a sphere's surface specified by the (phi,theta) values. The signature of this method is HDouble f(HDouble,HDouble) and can be used by the 2-variable optimisers.

Parameters:

phiRadians - phi value of point on surface. Must be in range [-PI/2:PI/2].

thetaRadians - theta value of point on surface. Must be in range [-PI:PI].

Returns:

z-coordinate of point (phi,theta).

Throws:

java.lang.IllegalArgumentException - Thrown if phiRadians or thetaRadians are out of range.

kissingNumber

public int kissingNumber()

The "kissing number" is the maximum number of times a sphere can touch a central sphere, with all spheres having same size and without intersecting other spheres. For an interesting discussion refer to Paul Bourke.

Returns:

A value of 12.

toString

public java.lang.String toString()

Returns a String representation of a Sphere3D object.

Overrides:

toString in class java.lang.Object

Returns:

A String representation of a Sphere3D object.

toQuadraticSurface3D

public QuadraticSurface3D toQuadraticSurface3D()

Returns the quadratic surface equation equivalent of this sphere; ie Q=(Gz^2+Hxz+Iyz+Jz)+(Ax^2+Bxy+Cy^2+Dx+Ey+F)=0.

Returns:

This sphere expressed as a QuadraticSurface3D object.

toX3DNode

public X3DNode toX3DNode(X3DObject x3dObject)
                  throws InvalidObjectException

X3D support. Attributes are handled in the order ColourAttribute, MaterialNode and AppearanceNode. If a ColourAttribute is associated with this object's ID then a MaterialNode is generated from the colour attribute. If a MaterialNode is associated with this object's ID then it is added to the shape node's Appearance node. If no MaterialNode is found then AppearanceNode is tested for association and if so then added.

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.

greatCircle

public PlanarCircle3D greatCircle(Point3D p,
                                  Point3D q)
                           throws java.lang.IllegalArgumentException

Returns a great circle passing through the points p and q.

Parameters:

p - Point p through which the great circle passes.

q - Point q through which the great circle passes.

Returns:

Planar circle representing the great circle through points p and q.

Throws:

java.lang.IllegalArgumentException - Thrown if p or q are null.

greatCircle

public PlanarCircle3D greatCircle(double pPhi,
                                  double pTheta,
                                  double qPhi,
                                  double qTheta,
                                  boolean degrees)
                           throws java.lang.IllegalArgumentException

Returns a great circle passing through this sphere's centre and the two specified points p(pPhi,pTheta) and q(qPhi,qTheta). A convenience method of greatCircle(Point3D,Point3D) in that internally it generates two points corresponding to the specified angles and then calls greatCircle(Point3D,Point3D).

Parameters:

pPhi - The latitude angle phi in radians [-PI/2:+PI/2] of point p.

pTheta - The longitude angle theta in radians [-PI:+PI] of point p.

qPhi - The latitude angle phi in radians [-PI/2:+PI/2] of point q.

qTheta - The longitude angle theta in radians [-PI:+PI] of point q.

degrees - Specifies whether or not the specified angles are in degrees (true) or radians (false).

Returns:

Planar circle representing the great circle through points p and q.

Throws:

java.lang.IllegalArgumentException - Thrown if (pPhi,pTheta) or (qPhi,qTheta) are out of range.

intersection

public Intersection3D intersection(Sphere3D sphere,
                                   double tolerance)

Tests for intersection between this sphere and the specified sphere.

Parameters:

sphere - Other sphere.

tolerance - Required tolerance.

Returns:

Intersection object. Sets to NONE if no intersection, POINT if a single tangential intersection point and CIRCLE if intersection occurs on a PlanarCircle3D circle.

intersection

public Intersection3D intersection(Ray3D ray,
                                   double tolerance)

Returns the intersection object between a sphere and a ray.

Parameters:

ray - The ray to test for intersection with this sphere.

tolerance - Required tolerance.

Returns:

Intersection object. The object can consist of no intersection points (NONE), 1 Point3D intersection point (POINT) or 2 Point3D intersection points (POINTS).

intersection

public Intersection3D intersection(StraightLine3D line,
                                   double tolerance)

Returns the intersection object between a sphere and a straight line segment.

Parameters:

line - The straight line to test for intersection with this sphere.

tolerance - Required tolerance.

Returns:

Intersection object. The object can consist of no intersection points (NONE), 1 Point3D intersection point (POINT) or 2 Point3D intersection points (POINTS).

intersection

public Intersection3D intersection(Plane3D plane,
                                   double tolerance)

Tests for intersection between the specified plane and this sphere.

Parameters:

plane - Plane to test for intersection.

tolerance - Required tolerance.

Returns:

Intersection object. Set to NONE if no intersection, POINT if a single Point3D tangential intersection and CIRCLE if a PlanarCircle3D intersection.

intersectionVolume

public double intersectionVolume(Sphere3D sphere)

Returns the volume of intersection between this sphere and the specified sphere; ie the volume of the resulting lens shape. For details about the evaluation refer to MathWorld

Parameters:

sphere - Other sphere.

Returns:

Volume of intersection or 0.0 if no overlap.

sphereCircle

public PlanarCircle3D sphereCircle(double phi_theta_radians,
                                   boolean const_phi)
                            throws java.lang.IllegalArgumentException

Returns a circle on this sphere.

Parameters:

phi_theta_radians - Theta or phi angle in radians.

const_phi - If logical-true then an angle phi is specified, else an angle theta is specified.

Returns:

The PlanarCircle object representing the great circle at the specified angle.

Throws:

java.lang.IllegalArgumentException - Thrown if phi_theta_radians is out of range.

equatorCircle

public PlanarCircle3D equatorCircle()

Returns the planar great circle passing through the centre, axisXPoint() and axisYPoint().

Returns:

The equator circle.

gaussCurvature

public double gaussCurvature()

Returns the Gauss curvature; ie k=1/r^2. The curvature is constant over the entire surface. For further details refer to MathWorld.

Returns:

The Gauss curvature.

meanCurvature

public double meanCurvature()

Returns the mean curvature; ie h=1/r. The curvature is constant over the entire surface. For further details refer to MathWorld.

Returns:

The mean curvature.

area

public double area()

Returns the surface area of this sphere; ie 4PIr^2.

Specified by:

area in class Shape3D

Returns:

Surface area of this sphere.

boundingBox

public AxisAlignedBox3D boundingBox()

Returns the axis-aligned bounding box of this sphere.

Specified by:

boundingBox in class Shape3D

Returns:

The axis-aligned bounding box of this sphere.

centroid

public Point3D centroid()

Returns the centroid of this sphere; ie its centre.

Specified by:

centroid in class Shape3D

Returns:

Sphere centroid/centre.

pointInside

public boolean pointInside(Point3D p,
                           double tolerance)

Tests whether or not the specified point is inside this sphere.

Specified by:

pointInside in class Shape3D

Parameters:

p - Point to test.

tolerance - Required tolerance.

Returns:

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

pointOutside

public boolean pointOutside(Point3D p,
                            double tolerance)

Tests whether or not the specified point is outside this sphere.

Overrides:

pointOutside in class Shape3D

Parameters:

p - Point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p is outside, else logical-false.

pointOnSurface

public boolean pointOnSurface(Point3D p,
                              double tolerance)

Tests whether or not the specified point is on the surface of this sphere.

Specified by:

pointOnSurface in class Shape3D

Parameters:

p - Point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p is on the surface, else logical-false.

pointInsideOrOnSurface

public boolean pointInsideOrOnSurface(Point3D p,
                                      double tolerance)

Tests whether or not the specified point is either inside or on the surface of this sphere.

Overrides:

pointInsideOrOnSurface in class Shape3D

Parameters:

p - Point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p is inside or on the surface of this sphere, else logical-false.

rotate

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

Rotates this sphere angle theta about z, beta about y and gamma about x. Simply returns a copy of this sphere as a Sphere object is defined as a centre and radius and does not encapsulate local axes.

Specified by:

rotate in class Shape3D

Parameters:

theta - Angle of rotation in xy-plane about z-axis.

beta - Angle of rotation in zx-plane about y-axis.

gamma - Angle of rotation with respect to yz-plane about x-axis.

fixedPoint - Fixed point. If null then rotation is with respect to centre.

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

Returns:

This sphere rotated. A copy of this sphere is returned as the rotated object is identical to this object.

Throws:

java.lang.IllegalArgumentException - Thrown if (theta,beta,gamma) are out of range.

scale

public Shape3D scale(double s,
                     Point3D fixedPoint)

Scales this sphere by multiplying the radius by the specified scaling factor.

Specified by:

scale in class Shape3D

Parameters:

s - Scaling factor.

fixedPoint - Fixed point. Not used in scaling this sphere.

Returns:

Scaled sphere.

translate

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

Translates this sphere by the specified translate 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 sphere.

volume

public double volume()

Returns the volume of this sphere; ie (4/3)PI.r^3.

Specified by:

volume in class Shape3D

Returns:

Volume of this sphere.

enclosingSphereAverageCentre

public static Sphere3D enclosingSphereAverageCentre(java.util.Vector<Point3D> points)

Returns the smallest sphere whose centre is the average of the input points.

Parameters:

points - Vector of points.

Returns:

The smallest sphere whose centre is the average of the input points.

enclosingSphere

public static Sphere3D enclosingSphere(Sphere3D sphere0,
                                       Sphere3D sphere1)

Returns the sphere that encloses the two specified spheres.

Parameters:

sphere0 - Sphere 0.

sphere1 - Sphere 1.

Returns:

Enclosing sphere.

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 the single element of the centre point.

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 - Document 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 - The modelt to which the returned object is associated.

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.

transform

public void transform(Matrix4x4 matrix)

Applies the specified transformation matrix to this polygon. Refer to the static methods of Matix4x4 for standard transformation matrices. Note that the transformation is applied to this sphere's centre point only. If a transformation of the sphere's radius is required then this must be done separately.

Parameters:

matrix - Transformation matrix.