Package org.djutils.draw.point

Class OrientedPoint3d

java.lang.Object
org.djutils.draw.point.Point3d
org.djutils.draw.point.DirectedPoint3d
org.djutils.draw.point.OrientedPoint3d
All Implemented Interfaces:
Serializable, Directed<DirectedPoint3d>, Directed3d<DirectedPoint3d>, Drawable<Point3d>, Drawable3d, Oriented<OrientedPoint3d>, Oriented3d<OrientedPoint3d>, Point<Point3d>
public class OrientedPoint3d extends DirectedPoint3d 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:

  • Field Details

    • dirX

      public final double dirX
      The direction as rotation around the x-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 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 xyz 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
      Description copied from class: Point3d
      Return a new Point3d with a translation by the provided dx and dy.
      Overrides:
      translate in class DirectedPoint3d
      Parameters:
      dx - double; the x translation
      dy - double; the y 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
      Description copied from class: Point3d
      Return a new Point3d with a translation by the provided dx, dy and dz.
      Overrides:
      translate in class DirectedPoint3d
      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
      Description copied from interface: Point
      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 DirectedPoint3d
      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()
      Description copied from interface: Point
      Return a new Point with negated coordinate values. If this is a DirectedPoint, dirY and dirZ are negated.
      Specified by:
      neg in interface Directed<DirectedPoint3d>
      Specified by:
      neg in interface Oriented<OrientedPoint3d>
      Specified by:
      neg in interface Point<Point3d>
      Overrides:
      neg in class DirectedPoint3d
      Returns:
      Point; a new point with negated coordinate values

    • abs

      public OrientedPoint3d abs()
      Description copied from interface: Point
      Return a new Point with absolute coordinate values. If this is a DirectedPoint, dirY and dirZ are copied unchanged.
      Specified by:
      abs in interface Point<Point3d>
      Overrides:
      abs in class DirectedPoint3d
      Returns:
      Point; a new point with absolute coordinate values

    • normalize

      public OrientedPoint3d normalize() throws DrawRuntimeException
      Description copied from interface: Point
      Return a new Point with a distance of 1 to the origin.
      Specified by:
      normalize in interface Point<Point3d>
      Overrides:
      normalize in class DirectedPoint3d
      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 otherPoint 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 rotateZ. The resulting rotation will be normalized between -π and π.
      Overrides:
      rotate in class DirectedPoint3d
      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()
      Description copied from interface: Oriented3d
      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()
      Description copied from interface: Directed3d
      Retrieve the angle from the positive z axis to the direction. Normally these are values between [0:π]. Angles less than π/2 indicate above the x-y-plane; positive slope, angles > π/2 indicate angles below this plane; negative slope.
      Specified by:
      getDirY in interface Directed3d<DirectedPoint3d>
      Specified by:
      getDirY in interface Oriented3d<OrientedPoint3d>
      Overrides:
      getDirY in class DirectedPoint3d
      Returns:
      double; dirY

    • getDirZ

      public double getDirZ()
      Description copied from interface: Directed3d
      Retrieve the angle from the positive x-axis to the projection of the direction in the x-y-plane. Positive values rotate towards the positive y-axis (and beyond).
      Specified by:
      getDirZ in interface Directed3d<DirectedPoint3d>
      Specified by:
      getDirZ in interface Oriented<OrientedPoint3d>
      Overrides:
      getDirZ in class DirectedPoint3d
      Returns:
      double; dirZ

    • getPoints

      public Iterator<OrientedPoint3d> getPoints()
      Description copied from interface: Drawable
      Retrieve, or generate all points that make up the object.
      Specified by:
      getPoints in interface Drawable<Point3d>
      Overrides:
      getPoints in class DirectedPoint3d
      Returns:
      Iterable<Point2d>; an iterator that generates all points that make up the object

    • toString

      public String toString()
      Description copied from interface: Drawable
      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 DirectedPoint3d
      Returns:
      String; a string describing the Drawable

    • toString

      public String toString(String doubleFormat, boolean doNotIncludeClassName)
      Description copied from interface: Drawable
      Produce a String describing the Drawable.
      Specified by:
      toString in interface Drawable<Point3d>
      Overrides:
      toString in class DirectedPoint3d
      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
      Description copied from interface: Oriented
      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 Oriented 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 DirectedPoint3d

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class DirectedPoint3d