Package org.djutils.draw.point

Class OrientedPoint3d

java.lang.Object

org.djutils.draw.point.Point3d

org.djutils.draw.point.OrientedPoint3d

All Implemented Interfaces:

Serializable, Drawable<Point3d>, Drawable3d, Oriented<OrientedPoint3d>, Oriented3d<OrientedPoint3d>, Point<Point3d>

public class OrientedPoint3d
extends Point3d
implements Oriented3d<OrientedPoint3d>

A OrientedPoint3d is an immutable point with an x, y, and z coordinate, stored with double precision plus a 3d orientation. The orientation is specified by the rotations around the x, y, and z-axis. A number of constructors and methods are provided for cases where only the rotation around the z-axis is of importance. Orientation in 3D is stored as three double values dirX,dirY,dirZ. This class does not prescribe a particular order in which these rotations are to be applied. (Applying rotations is not commutative, so this is important.)

Copyright (c) 2020-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See DJUTILS License.

Author:

Alexander Verbraeck, Peter Knoppers

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
final double	dirX	The direction as rotation around the x-axis.
final double	dirY	The direction as rotation around the y-axis.
final double	dirZ	The direction as rotation around the z-axis.

Fields inherited from class org.djutils.draw.point.Point3d

x, y, z

Constructor Summary

Constructors

Constructor	Description
OrientedPoint3d(double[] xyz)	Create a new OrientedPoint3d with x, y, and z coordinates and direction 0,0,0.
OrientedPoint3d(double[] xyz, double[] orientation)	Create a new OrientedPoint3d with x, y, and z coordinates packed in a double array and orientation specified using a double array of three elements (containing dirX,dirY,dirZ in that order).
OrientedPoint3d(double[] xyz, double dirX, double dirY, double dirZ)	Create a new OrientedPoint3d with x, y, and z coordinates, stored with double precision, and orientation dirX,dirY,dirZ.
OrientedPoint3d(double x, double y, double z)	Create a new OrientedPoint3d with x, y, and z coordinates and direction 0,0,0.
OrientedPoint3d(double x, double y, double z, double[] orientation)	Create a new OrientedPoint3d with x, y, and z coordinates and orientation specified using a double array of three elements (containing dirX,dirY,dirZ in that order).
OrientedPoint3d(double x, double y, double z, double dirX, double dirY, double dirZ)	Create a new OrientedPoint3d with x, y, and z coordinates and orientation dirX,dirY,dirZ.
OrientedPoint3d(Point3d point, double dirX, double dirY, double dirZ)	Create a new OrientedPoint3d from another point and specified orientation dirX,dirY,dirZ.

Method Summary

Modifier and Type	Method	Description
OrientedPoint3d	abs()	Return a new Point with absolute coordinate values.
boolean	epsilonEquals(OrientedPoint3d other, double epsilonCoordinate, double epsilonRotation)	Compare this Oriented with another Oriented with specified tolerances in the coordinates and the angles.
boolean	equals(Object obj)
double	getDirX()	Return the rotation around the x-axis in radians.
double	getDirY()	Return the rotation around the y-axis in radians.
double	getDirZ()	Return the rotation around the z-axis in radians.
Iterator<OrientedPoint3d>	getPoints()	Retrieve, or generate all points that make up the object.
int	hashCode()
OrientedPoint3d	interpolate(OrientedPoint3d otherPoint, double fraction)	Interpolate towards another OrientedPoint3d with a fraction.
OrientedPoint3d	neg()	Return a new Point with negated coordinate values.
OrientedPoint3d	normalize()	Return a new Point with a distance of 1 to the origin.
OrientedPoint3d	rotate(double rotateZ)	Return a new OrientedPoint3d with an in-place rotation around the z-axis by the provided delta.
OrientedPoint3d	rotate(double rotateX, double rotateY, double rotateZ)	Return a new OrientedPoint3d point with an in-place rotation by the provided rotateX, rotateY, and rotateZ.
OrientedPoint3d	scale(double factor)	Return a new Point with the coordinates of this point scaled by the provided factor.
String	toString()	Produce a string describing the Drawable using default conversion for the (double) coordinate values.
String	toString(String doubleFormat, boolean doNotIncludeClassName)	Produce a String describing the Drawable.
OrientedPoint3d	translate(double dx, double dy)	Return a new Point with a translation by the provided dx and dy.
OrientedPoint3d	translate(double dx, double dy, double dz)	Return a new Point3d with a translation by the provided dx, dy and dz.

Methods inherited from class org.djutils.draw.point.Point3d

closestPointOnLine, closestPointOnLine, closestPointOnLine, closestPointOnSegment, closestPointOnSegment, distance, distanceSquared, epsilonEquals, fractionalPositionOnLine, getBounds, getX, getY, getZ, horizontalDirection, horizontalDirection, horizontalDistance, horizontalDistanceSquared, interpolate, project, size, verticalDirection

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.djutils.draw.Drawable

getPointList, toString, toString

Methods inherited from interface org.djutils.draw.Drawable3d

getDimensions

Field Details

dirX

public final double dirX

The direction as rotation around the x-axis.

dirY

public final double dirY

The direction as rotation around the y-axis.

dirZ

public final double dirZ

The direction as rotation around the z-axis.

Constructor Details

OrientedPoint3d

public OrientedPoint3d(double x,
 double y,
 double z)
                throws IllegalArgumentException

Create a new OrientedPoint3d with x, y, and z coordinates and direction 0,0,0.

Parameters:

x - double; the x coordinate

y - double; the y coordinate

z - double; the z coordinate

Throws:

IllegalArgumentException - when x, y, or z is NaN

OrientedPoint3d

public OrientedPoint3d(double x,
 double y,
 double z,
 double dirX,
 double dirY,
 double dirZ)
                throws IllegalArgumentException

Create a new OrientedPoint3d with x, y, and z coordinates and orientation dirX,dirY,dirZ.

Parameters:

x - double; the x coordinate

y - double; the y coordinate

z - double; the z coordinate

dirX - double; the direction as rotation around the x-axis with the point as the center

dirY - double; the direction as rotation around the y-axis with the point as the center

dirZ - double; the direction as rotation around the z-axis with the point as the center

Throws:

IllegalArgumentException - when x, y, z, dirX, dirY, or dirZ is NaN

OrientedPoint3d

public OrientedPoint3d(double[] xyz)
                throws NullPointerException,
IllegalArgumentException

Create a new OrientedPoint3d with x, y, and z coordinates and direction 0,0,0.

Parameters:

xyz - double[]; the x, y and z coordinates

Throws:

NullPointerException - when xyx is null

IllegalArgumentException - when the length of the xyx array is not 3, or contains a NaN value

OrientedPoint3d

public OrientedPoint3d(double[] xyz,
 double dirX,
 double dirY,
 double dirZ)
                throws NullPointerException,
IllegalArgumentException

Create a new OrientedPoint3d with x, y, and z coordinates, stored with double precision, and orientation dirX,dirY,dirZ.

Parameters:

xyz - double[]; the x, y and z coordinates

dirX - double; the direction as rotation around the x-axis with the point as the center

dirY - double; the direction as rotation around the y-axis with the point as the center

dirZ - double; the direction as rotation around the z-axis with the point as the center

Throws:

NullPointerException - when xyx is null

IllegalArgumentException - when the length of the xyx array is not 3, or contains a NaN value, or dirX, dirY, or dirZ is NaN

OrientedPoint3d

public OrientedPoint3d(Point3d point,
 double dirX,
 double dirY,
 double dirZ)
                throws IllegalArgumentException

Create a new OrientedPoint3d from another point and specified orientation dirX,dirY,dirZ.

Parameters:

point - Point3d; the point from which this OrientedPoint3d will be instantiated

dirX - double; the direction as rotation around the x-axis with the point as the center

dirY - double; the direction as rotation around the y-axis with the point as the center

dirZ - double; the direction as rotation around the z-axis with the point as the center

Throws:

IllegalArgumentException - when dirX, dirY, or dirZ is NaN

OrientedPoint3d

public OrientedPoint3d(double x,
 double y,
 double z,
 double[] orientation)
                throws NullPointerException,
IllegalArgumentException

Create a new OrientedPoint3d with x, y, and z coordinates and orientation specified using a double array of three elements (containing dirX,dirY,dirZ in that order).

Parameters:

x - double; the x coordinate

y - double; the y coordinate

z - double; the z coordinate

orientation - double[]; the three orientation values as rotations around the x,y,z-axes in a double array containing dirX,dirY,dirZ in that order

Throws:

NullPointerException - when rotation is null

IllegalArgumentException - when the length of the direction array is not 3

OrientedPoint3d

public OrientedPoint3d(double[] xyz,
 double[] orientation)
                throws NullPointerException,
IllegalArgumentException

Create a new OrientedPoint3d with x, y, and z coordinates packed in a double array and orientation specified using a double array of three elements (containing dirX,dirY,dirZ in that order).

Parameters:

xyz - double[]; the x, y and z coordinates in that order

orientation - double[]; the three orientation values as rotations around the x,y,z-axes in a double array containing dirX,dirY,dirZ in that order

Throws:

NullPointerException - when xyx or direction is null

IllegalArgumentException - when the length of the xyx array or the length of the orientation array is not 3

Method Details

translate

public OrientedPoint3d translate(double dx,
 double dy)
                          throws IllegalArgumentException

Return a new Point with a translation by the provided dx and dy.

Overrides:

translate in class Point3d

Parameters:

dx - double; the horizontal translation

dy - double; the vertical translation

Returns:

Point3D; a new point with the translated coordinates

Throws:

IllegalArgumentException - when dx, or dy is NaN

translate

public OrientedPoint3d translate(double dx,
 double dy,
 double dz)
                          throws IllegalArgumentException

Return a new Point3d with a translation by the provided dx, dy and dz.

Overrides:

translate in class Point3d

Parameters:

dx - double; the x translation

dy - double; the y translation

dz - double; the z translation

Returns:

Point3d; a new point with the translated coordinates

Throws:

IllegalArgumentException - when dx, dy, or dz is NaN

scale

public OrientedPoint3d scale(double factor)
                      throws IllegalArgumentException

Return a new Point with the coordinates of this point scaled by the provided factor.

Specified by:

scale in interface Point<Point3d>

Overrides:

scale in class Point3d

Parameters:

factor - double; the scale factor

Returns:

Point; a new point with the coordinates of this point scaled by the provided factor

Throws:

IllegalArgumentException - when factor is NaN

neg

public OrientedPoint3d neg()

Return a new Point with negated coordinate values.

Specified by:

neg in interface Oriented<OrientedPoint3d>

Specified by:

neg in interface Point<Point3d>

Overrides:

neg in class Point3d

Returns:

Point; a new point with negated coordinate values

abs

public OrientedPoint3d abs()

Return a new Point with absolute coordinate values.

Specified by:

abs in interface Point<Point3d>

Overrides:

abs in class Point3d

Returns:

Point; a new point with absolute coordinate values

normalize

public OrientedPoint3d normalize()
                          throws DrawRuntimeException

Return a new Point with a distance of 1 to the origin.

Specified by:

normalize in interface Point<Point3d>

Overrides:

normalize in class Point3d

Returns:

Point; the normalized point

Throws:

DrawRuntimeException - when point is the origin, and no length can be established for scaling

interpolate

public OrientedPoint3d interpolate(OrientedPoint3d otherPoint,
 double fraction)
                            throws NullPointerException,
IllegalArgumentException

Interpolate towards another OrientedPoint3d with a fraction. It is allowed for fraction to be less than zero or larger than 1. In that case the interpolation turns into an extrapolation. DirX, dirY and dirZ are interpolated/extrapolated using the interpolateShortest method.

Parameters:

otherPoint - OrientedPoint3d; the other point

fraction - double; the factor for interpolation towards the other point. When <code>fraction</code> is between 0 and 1, it is an interpolation, otherwise an extrapolation. If fraction is 0; this Point is returned; if fraction is 1, the other point is returned

Returns:

OrientedPoint3d; a new OrientedPoint3d at the requested fraction

Throws:

NullPointerException - when otherPoint is null

IllegalArgumentException - when fraction is NaN

rotate

public OrientedPoint3d rotate(double rotateZ)
                       throws IllegalArgumentException

Return a new OrientedPoint3d with an in-place rotation around the z-axis by the provided delta. The resulting rotation will be normalized between -π and π.

Parameters:

rotateZ - double; the rotation around the z-axis

Returns:

OrientedPoint3d; a new point with the same coordinates, dirX and dirY and modified dirZ

Throws:

IllegalArgumentException - when rotateZ is NaN

rotate

public OrientedPoint3d rotate(double rotateX,
 double rotateY,
 double rotateZ)
                       throws IllegalArgumentException

Return a new OrientedPoint3d point with an in-place rotation by the provided rotateX, rotateY, and rotateZ. The resulting rotations will be normalized between -π and π.

Parameters:

rotateX - double; the rotation around the x-axis

rotateY - double; the rotation around the y-axis

rotateZ - double; the rotation around the z-axis

Returns:

OrientedPoint3d; a new point with the same coordinates and applied rotations

Throws:

IllegalArgumentException - when any of the rotations is NaN

getDirX

public double getDirX()

Return the rotation around the x-axis in radians.

Specified by:

getDirX in interface Oriented3d<OrientedPoint3d>

Returns:

double; the rotation around the x-axis in radians

getDirY

public double getDirY()

Return the rotation around the y-axis in radians.

Specified by:

getDirY in interface Oriented3d<OrientedPoint3d>

Returns:

double; the rotation around the y-axis in radians

getDirZ

public double getDirZ()

Return the rotation around the z-axis in radians.

Specified by:

getDirZ in interface Oriented<OrientedPoint3d>

Returns:

double; the rotation around the z-axis in radians

getPoints

public Iterator<OrientedPoint3d> getPoints()

Retrieve, or generate all points that make up the object.

Specified by:

getPoints in interface Drawable<Point3d>

Overrides:

getPoints in class Point3d

Returns:

Iterable<Point2d>; an iterator that generates all points that make up the object

toString

public String toString()

Produce a string describing the Drawable using default conversion for the (double) coordinate values. Regrettably, it is not allowed to provide a default implementation here.

Specified by:

toString in interface Drawable<Point3d>

Overrides:

toString in class Point3d

Returns:

String; a string describing the Drawable

toString

public String toString(String doubleFormat,
 boolean doNotIncludeClassName)

Produce a String describing the Drawable.

Specified by:

toString in interface Drawable<Point3d>

Overrides:

toString in class Point3d

Parameters:

doubleFormat - String; a format string (something like "%6.3f") which will be used to render every coordinate value)

doNotIncludeClassName - boolean; if true; the output of toString is not prefixed by the class name. This is useful for concatenating the textual representation of lots of Drawables (e.g. an array, or a List).

Returns:

String; textual representation of the Drawable

epsilonEquals

public boolean epsilonEquals(OrientedPoint3d other,
 double epsilonCoordinate,
 double epsilonRotation)
                      throws NullPointerException,
IllegalArgumentException

Compare this Oriented with another Oriented with specified tolerances in the coordinates and the angles.

Specified by:

epsilonEquals in interface Oriented<OrientedPoint3d>

Parameters:

other - O; the point to compare with

epsilonCoordinate - double; the upper bound of difference for one of the coordinates; use Double.POSITIVE_INFINITY if you do not want to check the coordinates

epsilonRotation - double; the upper bound of difference for the direction(s); use Double.POSITIVE_INFINITY if you do not want to check the angles

Returns:

boolean; true if x, y, and z are less than epsilonCoordinate apart, and rotX, rotY and rotZ are less than epsilonRotation apart, otherwise false

Throws:

NullPointerException - when other is null

IllegalArgumentException - epsilonCoordinate or epsilonRotation is NaN or negative

hashCode

public int hashCode()

Overrides:

hashCode in class Point3d

equals

public boolean equals(Object obj)

Overrides:

equals in class Point3d