com.hedgehog.geo.twod.curves
Class StraightLine2D

java.lang.Object
  com.hedgehog.HObject
      com.hedgehog.geo.GeometricObject
          com.hedgehog.geo.twod.GeometricObject2D
              com.hedgehog.geo.twod.curves.Curve2D
                  com.hedgehog.geo.twod.curves.StraightLine2D

All Implemented Interfaces:

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

Direct Known Subclasses:

HorizontalLine2D, VerticalLine2D

public class StraightLine2D
extends Curve2D
implements ModelObject

Title: StraightLine2D - represents a straight line segment of finite length.

Description: Models a 2D straight line segment of finite length and terminated by two end-points.

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

Company: Hedgehog Software

Since:

1.0

Version:

1.1

Field Summary

Fields inherited from class com.hedgehog.geo.twod.curves.Curve2D

mp0, mp1

Fields inherited from class com.hedgehog.HObject

mID, mName

Constructor Summary

StraightLine2D()
Default constructor.

StraightLine2D(ID id)
Constructor.

StraightLine2D(Point2D p0, Point2D p1)
Constructor.

StraightLine2D(Point2D p0, Point2D p1, java.lang.String name, ID id)
Constructor.

StraightLine2D(StraightLine2D object)
Copy constructor.

StraightLine2D(java.lang.String name)
Constructor.

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

Method Summary

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	ellipticDistance(Point2D p) Returns the distance (bc+ca) of a point at c to line ab.
Point2D	extrapolatedPoint(double c1, double c2) Returns an extrapolated point which divides a straight line in the ratio p0-p:p-p1 is c1:c2.
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.
double	interpolation(double p0_value, double p1_value, double u) Returns the interpolated value at the parametric point u from the end-point values p0_value and p1_value.
Intersection2D	intersection(Ray2D ray, double tolerance) Intersects the specified ray with this straight-line.
Intersection2D	intersection(StraightLine2D line, double tolerance) Intersects the specified straight-line with this straight-line.
java.util.Vector<Point2D>	intersectionPoints(StraightLine2D line, double tolerance) Tests whether or not the specified line intersects with this line and returns the vector of intersection points, if any.
boolean	isHorizontal(double tolerance) Tests whether or not this line segment is horizontal.
boolean	isOrthogonal(StraightLine2D l, double tolerance) Returns logical-true if two lines are orthogonal/perpendicular.
boolean	isValid(double tolerance) Tests whether or not this line is valid.
boolean	isVertical(double tolerance) Tests whether or not this line segment is vertical.
double	length() Returns the length of this straight line.
Point2D	maximumPointFromGloablOrigin() Returns the furthest end-point with respect to the global origin.
double	maximumX(double tolerance) Returns the maximum x-value of this curve.
double	maximumY(double tolerance) Returns the minimum y-value of this curve.
Point2D	midPoint() Returns the mid-point of this line.
double	minimumDistance(Point2D p, double tolerance) Returns the minimum distance (i.e.
Point2D	minimumPointFromGloablOrigin() Returns the closet end-point with respect to the global origin.
double	minimumX(double tolerance) Returns the minimum x-value of this curve.
double	minimumY(double tolerance) Returns the minimum y-value of this curve.
Point2D	nearestEndPoint(Point2D p, double tolerance) Returns the nearest end-point to the specified point, p.
double	parametricVariable(Point2D p, double tolerance) Returns the value of the parametric variable, u, corresponding to the specified point.
InfiniteStraightLine2D	perpendicularStraightLineThroughPoint(Point2D p, double tolerance) Returns an infinite straight-line which is perpendicular to the operated-on straight-line and passes through point p.
Point2D	pointOnCurve(double u, double tolerance) Returns a point on a straight-line which corresponds to the specified parametric variable, u.
boolean	pointOnCurve(Point2D p, double tolerance) Tests whether or not the specified point is on this curve.
boolean	pointOnLeft(Point2D p, double tolerance) Tests whether or not the specified point is on the lhs of this line, with the line's sense from p0 to p1.
boolean	pointOnRight(Point2D p, double tolerance) Tests whether or not the specified point is on the lhs of this line, with the line's sense from p0 to p1.
boolean	pointsOnSameSide(Point2D p, Point2D q) Tests whether or not the specified points are on the same side of this line.
Vector2D	tangent() Returns the tangent vector of this straight line from p0 to p1.
Vector2D	tangent(double u) Returns the tangent vector at point u.
Vector2D	tangent(Point2D p) Returns the tangent vector at point u.
InfiniteStraightLine2D	toInfiniteStraightLine2D() Returns the InfiniteStraightLine2D object passing through the two points of this line.
LinearLine2D	toLinearLine2D() Returns the infinite LinearLine2D object passing through the two points of this line.
Ray2D	toRay2D() Returns the Ray2D object with p0 as origin and vector [p0-->p1] as direction.
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.

Methods inherited from class com.hedgehog.geo.twod.curves.Curve2D

commonEndPoint, curvature, curvePoints, distanceBetweenTwoPointsAlongCurve, distanceBetweenTwoPointsAlongCurve, equals, evenlySpacedIntermediatePoints, getP0, getP1, interpolation, is2D, is3D, isCurve, isEndPoint, isEndPointP0, isEndPointP1, isGrid, isMesh, isOpen, isP0Set, isP1Set, isPoint, isPointSet, isShape, isSurface, isValid, jacobianDeterminant, length, lengthCoordinates, lengthFunction, nearestEndPoint, nearestEndPoint, nearestPoint, nearestPointApprox, otherEndPoint, pointOfCurve, pointXOnCurve, pointYOnCurve, randomPoint, reverse, sameCurve, sameEndPoints, secondDerivative, setP0, setP1, shapeFunctions, shapeFunctions, shapeFunctionsDerivatives, shareEndPoint, toPolyStraightLine2D, toString, trihedron, unitBiNormalVector, unitPrincipalNormalVector

Methods inherited from class com.hedgehog.geo.GeometricObject

objectDimension

Methods inherited from class com.hedgehog.HObject

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

Methods inherited from class java.lang.Object

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

Constructor Detail

StraightLine2D

public StraightLine2D()

Default constructor. Initialises both end-points to null.

StraightLine2D

public StraightLine2D(Point2D p0,
                      Point2D p1)

Constructor. Initialises both end-points to the specified points.

Parameters:

p0 - End-point p0.

p1 - End-point p1.

StraightLine2D

public StraightLine2D(Point2D p0,
                      Point2D p1,
                      java.lang.String name,
                      ID id)

Constructor. Initialises both end-points to the specified points.

Parameters:

p0 - End-point p0.

p1 - End-point p1.

name - Straight-line name.

id - Straight-line ID.

StraightLine2D

public StraightLine2D(java.lang.String name)

Constructor. Initialises both end-points to null.

Parameters:

name - Straight-line name.

StraightLine2D

public StraightLine2D(ID id)

Constructor. Initialises both end-points to null.

Parameters:

id - Straight-line ID.

StraightLine2D

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

Constructor. Initialises both end-points to null.

Parameters:

name - Straight-line name.

id - Straight-line ID.

StraightLine2D

public StraightLine2D(StraightLine2D object)

Copy constructor.

Parameters:

object - Object to copy.

Method Detail

length

public double length()

Returns the length of this straight line.

Overrides:

length in class Curve2D

Returns:

The length of this straight line.

midPoint

public Point2D midPoint()

Returns the mid-point of this line.

Overrides:

midPoint in class Curve2D

Returns:

Mid-point of this straight-line segment.

pointsOnSameSide

public boolean pointsOnSameSide(Point2D p,
                                Point2D q)

Tests whether or not the specified points are on the same side of this line.

Parameters:

p - Point 1.

q - Point 2.

Returns:

Logical-true if p and q are on same side of line, else logical-false.

parametricVariable

public double parametricVariable(Point2D p,
                                 double tolerance)
                          throws java.lang.IllegalArgumentException

Returns the value of the parametric variable, u, corresponding to the specified point. Ensure that the point lies on the straight-line.

Overrides:

parametricVariable in class Curve2D

Parameters:

p - Point to determine parametric variable value.

tolerance - Required tolerance.

Returns:

Parametric variable distance of end-point p0 to the specified point, p. If an error occurs in OneVariableFunction.optimisationBFGS() then a value of -1.0 is returned. For example, with overridden StraightLine2D.parametricVariable() removed this method gives: StraightLine2D sline = new StraightLine2D(new Point2D(1,0),new Point2D(5,0)); Point2D p = new Point2D(2.0,0.0); double u = sline.parametricVariable(p,1e-03); java.lang.System.out.println("sline p u: " + u); with output: sline p u: 0.25000017446238687 with the exact answer being 0.25.

Throws:

java.lang.IllegalArgumentException - Thrown if p is not on the operated-on straight-line.

perpendicularStraightLineThroughPoint

public InfiniteStraightLine2D perpendicularStraightLineThroughPoint(Point2D p,
                                                                    double tolerance)

Returns an infinite straight-line which is perpendicular to the operated-on straight-line and passes through point p.

Parameters:

p - Point from which to form straight-line that is perpendicular to this straight-line.

tolerance - Required tolerance.

Returns:

Infinite straight line that is perpendicular to this line and passing through p.

pointOnCurve

public Point2D pointOnCurve(double u,
                            double tolerance)
                     throws java.lang.IllegalArgumentException

Returns a point on a straight-line which corresponds to the specified parametric variable, u. The returned point is newly created (even if coincides with an end-point) and can therefore subsequently be deleted. Note: ensure that u is within the range [0:1].

Specified by:

pointOnCurve in class Curve2D

Parameters:

u - Parametric variable value.

tolerance - Required tolerance.

Returns:

Point at specified parametric distance from p0.

Throws:

java.lang.IllegalArgumentException - Thrown if u is out of range [0:1].

pointOnCurve

public boolean pointOnCurve(Point2D p,
                            double tolerance)

Tests whether or not the specified point is on this curve.

Specified by:

pointOnCurve in class Curve2D

Parameters:

p - Point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p is on this curve, else logicl-false.

pointOnLeft

public boolean pointOnLeft(Point2D p,
                           double tolerance)

Tests whether or not the specified point is on the lhs of this line, with the line's sense from p0 to p1.

Specified by:

pointOnLeft in class Curve2D

Parameters:

p - point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p on the left of this line, else logical-false.

pointOnRight

public boolean pointOnRight(Point2D p,
                            double tolerance)

Tests whether or not the specified point is on the lhs of this line, with the line's sense from p0 to p1.

Specified by:

pointOnRight in class Curve2D

Parameters:

p - point to test.

tolerance - Required tolerance.

Returns:

Logical-true if p on the left of this line, else logical-false.

intersectionPoints

public java.util.Vector<Point2D> intersectionPoints(StraightLine2D line,
                                                    double tolerance)
                                             throws java.lang.IllegalArgumentException

Tests whether or not the specified line intersects with this line and returns the vector of intersection points, if any. Note1: If the specified line lies entirely on this line then it is assumed there are two intersection points; ie the end-points of line. For details about line-line intersection refer to MathWorld.

Parameters:

line - Line to test for intersection with this line.

tolerance - Required tolerance.

Returns:

Set upon return to the intersection points, if any. If no intersections occur then the returned vector will be empty.

Throws:

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

intersection

public Intersection2D intersection(StraightLine2D line,
                                   double tolerance)

Intersects the specified straight-line with this straight-line.

Parameters:

line - Straight line to test.

tolerance - Required tolerance.

Returns:

Intersection object. Thrown if line is null.

Throws:

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

intersection

public Intersection2D intersection(Ray2D ray,
                                   double tolerance)
                            throws java.lang.IllegalArgumentException

Intersects the specified ray with this straight-line.

Parameters:

ray - Ray.

tolerance - Required tolerance.

Returns:

Intersection object.

Throws:

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

minimumX

public double minimumX(double tolerance)
                throws FunctionEvaluationException

Returns the minimum x-value of this curve.

Overrides:

minimumX in class Curve2D

Parameters:

tolerance - Required tolerance.

Returns:

Minimum x-value of this curve.

Throws:

FunctionEvaluationException - Not thrown.

minimumY

public double minimumY(double tolerance)
                throws FunctionEvaluationException

Returns the minimum y-value of this curve.

Overrides:

minimumY in class Curve2D

Parameters:

tolerance - Required tolerance.

Returns:

Minimum y-value of this curve.

Throws:

FunctionEvaluationException - Not thrown.

maximumX

public double maximumX(double tolerance)
                throws FunctionEvaluationException

Returns the maximum x-value of this curve. Uses OneVariableFunction.optimisationBFGS() and pointXOnCurve() to find the minimum x-value for a general 2D curve. Uses end-point p0.x as the initial minimum value.

Overrides:

maximumX in class Curve2D

Parameters:

tolerance - Required tolerance.

Returns:

Minimum x-value of this curve.

Throws:

FunctionEvaluationException - Not thrown.

maximumY

public double maximumY(double tolerance)
                throws FunctionEvaluationException

Returns the minimum y-value of this curve. Uses OneVariableFunction.optimisationBFGS() and pointXOnCurve() to find the minimum y-value for a general 2D curve. Uses end-point p0.y as the initial minimum value.

Overrides:

maximumY in class Curve2D

Parameters:

tolerance - Required tolerance.

Returns:

Minimum y-value of this curve.

Throws:

FunctionEvaluationException - Not thrown.

minimumPointFromGloablOrigin

public Point2D minimumPointFromGloablOrigin()

Returns the closet end-point with respect to the global origin.

Returns:

Minimum end-point with respect to the global origin.

maximumPointFromGloablOrigin

public Point2D maximumPointFromGloablOrigin()

Returns the furthest end-point with respect to the global origin.

Returns:

Maximum end-point with respect to the global origin.

minimumDistance

public double minimumDistance(Point2D p,
                              double tolerance)

Returns the minimum distance (i.e. perpendicular) between the point and the straight-line. If the projection of p falls outside this line then the minimum distane is from p to one of the line's end points.

Overrides:

minimumDistance in class Curve2D

Parameters:

p - Point from which to determine the minimum distance between and dthis curve.

tolerance - Required tolerance.

Returns:

Minimum distance between specified point and this curve.

nearestEndPoint

public Point2D nearestEndPoint(Point2D p,
                               double tolerance)
                        throws java.lang.IllegalArgumentException

Returns the nearest end-point to the specified point, p. If p lies exactly mid way between p0 and p1 then p0 is returned.

Parameters:

p - Point to test.

tolerance - Required tolerance used for testing p lies on this curve.

Returns:

Nearest end-point.

Throws:

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

ellipticDistance

public double ellipticDistance(Point2D p)

Returns the distance (bc+ca) of a point at c to line ab. (bc+ca) provides a measure of point c to ab.

Parameters:

p - Point to fidn elliptic distance.

Returns:

Elliptic distance.

extrapolatedPoint

public Point2D extrapolatedPoint(double c1,
                                 double c2)
                          throws java.lang.IllegalArgumentException

Returns an extrapolated point which divides a straight line in the ratio p0-p:p-p1 is c1:c2. If c1>c2 then p0p1p, else if c1

Parameters:

c1 - Length ratio p0-p.

c2 - Length ratio p-p1.

Returns:

Extrapolated point.

Throws:

java.lang.IllegalArgumentException - Thrown if c1 and c2 are equivalent.

interpolation

public double interpolation(double p0_value,
                            double p1_value,
                            double u)
                     throws java.lang.IllegalArgumentException

Returns the interpolated value at the parametric point u from the end-point values p0_value and p1_value.

Parameters:

p0_value - Value at p0.

p1_value - Value at p1.

u - Parametric coordinate along line.

Returns:

Interpolated value at parametric point u.

Throws:

java.lang.IllegalArgumentException - Thrown if u out of range [0:1].

isOrthogonal

public boolean isOrthogonal(StraightLine2D l,
                            double tolerance)

Returns logical-true if two lines are orthogonal/perpendicular.

Parameters:

l - Line to test against this line.

tolerance - Required tolerance.

Returns:

Logical-true if the two lines are orthogonal, else logical-false.

isHorizontal

public boolean isHorizontal(double tolerance)

Tests whether or not this line segment is horizontal.

Parameters:

tolerance - Required tolerance.

Returns:

Logical-true if this line is horizontal, else logical-false.

isVertical

public boolean isVertical(double tolerance)

Tests whether or not this line segment is vertical.

Parameters:

tolerance - Required tolerance.

Returns:

Logical-true if this line is vertical, else logical-false.

isValid

public boolean isValid(double tolerance)

Tests whether or not this line is valid. Tests that both mp0 and mp1 are non-null and not the same point.

Parameters:

tolerance - Required tolerance.

Returns:

Logical-true if this is a valid line, else logical-false.

tangent

public Vector2D tangent(double u)
                 throws java.lang.IllegalArgumentException

Returns the tangent vector at point u. Independent of u for a straight-line as the tangent vector is simply p0-p1.

Overrides:

tangent in class Curve2D

Parameters:

u - Parametric variable u.

Returns:

Tangent vector at u.

Throws:

java.lang.IllegalArgumentException - Throws exception if u is outside the range [0:1].

tangent

public Vector2D tangent(Point2D p)
                 throws java.lang.IllegalArgumentException

Returns the tangent vector at point u. Independent of p for a straight-line as the tangent vector is simply p0-p1.

Overrides:

tangent in class Curve2D

Parameters:

p - Parametric variable u.

Returns:

Tangent vector at u.

Throws:

java.lang.IllegalArgumentException - Throws exception if u is outside the range [0:1].

tangent

public Vector2D tangent()

Returns the tangent vector of this straight line from p0 to p1.

Returns:

Tangent vector (p0,p1).

toLinearLine2D

public LinearLine2D toLinearLine2D()

Returns the infinite LinearLine2D object passing through the two points of this line. Uses the two-point line formula; ie A=-(p1.y-p0.y), B=p1.x-p0.x and C=p0.x*p1.y-p1.x*p0.y.

Returns:

LinearLine2D object representation of this line.

toInfiniteStraightLine2D

public InfiniteStraightLine2D toInfiniteStraightLine2D()

Returns the InfiniteStraightLine2D object passing through the two points of this line. Uses (p0,p1) to define the line.

Returns:

InfiniteStraightLine2D object representation of this line.

toRay2D

public Ray2D toRay2D()

Returns the Ray2D object with p0 as origin and vector [p0-->p1] as direction.

Returns:

Ray2D object representation of this line.

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 consisting of this object's two Point2D end-points.

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 updating 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 model to which this 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.

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.