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:
Iterable<Point3d>, Directed, Directed3d, Drawable<Point3d>, Drawable3d, Oriented3d, Point<Point3d>
public class OrientedPoint3d extends DirectedPoint3d implements Oriented3d
A OrientedPoint3d is a point with an x, y, and z coordinate, 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-2025 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, Wouter Schakel

  • 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)
      Create a new OrientedPoint3d with x, y, and z coordinates and direction 0,0,0.
      Parameters:
      x - the x coordinate
      y - the y coordinate
      z - 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)
      Create a new OrientedPoint3d with x, y, and z coordinates and orientation dirX,dirY,dirZ.
      Parameters:
      x - the x coordinate
      y - the y coordinate
      z - the z coordinate
      dirX - the direction as rotation around the x-axis with the point as the center
      dirY - the direction as rotation around the y-axis with the point as the center
      dirZ - the direction as rotation around the z-axis with the point as the center
      Throws:
      ArithmeticException - when x, y, z, dirX, dirY, or dirZ is NaN

    • OrientedPoint3d

      public OrientedPoint3d(double[] xyz)
      Create a new OrientedPoint3d with x, y, and z coordinates and direction 0,0,0.
      Parameters:
      xyz - the x, y and z coordinates
      Throws:
      NullPointerException - when xyz is null
      IllegalArgumentException - when the length of the xyx array is not 3
      IllegalArgumentException - when the xyx array 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 - the x, y and z coordinates
      dirX - the direction as rotation around the x-axis with the point as the center
      dirY - the direction as rotation around the y-axis with the point as the center
      dirZ - 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
      ArithmeticException - when xyz contains a NaN value, or dirX, dirY, or dirZ is NaN

    • OrientedPoint3d

      public OrientedPoint3d(Point3d point, double dirX, double dirY, double dirZ)
      Create a new OrientedPoint3d from another point and specified orientation dirX,dirY,dirZ.
      Parameters:
      point - the point from which this OrientedPoint3d will be instantiated
      dirX - the direction as rotation around the x-axis with the point as the center
      dirY - the direction as rotation around the y-axis with the point as the center
      dirZ - the direction as rotation around the z-axis with the point as the center
      Throws:
      NullPointerException - when point is null
      ArithmeticException - when dirX, dirY, or dirZ is NaN

    • OrientedPoint3d

      public 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).
      Parameters:
      x - the x coordinate
      y - the y coordinate
      z - the z coordinate
      orientation - 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)
      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 - the x, y and z coordinates in that order
      orientation - 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)
      Description copied from class: Point3d
      Return a new Point3d with a translation by the provided dX and dY and preserved z value.
      Overrides:
      translate in class DirectedPoint3d
      Parameters:
      dX - the x translation
      dY - the y translation
      Returns:
      a new point with the translated coordinates and the same z value

    • translate

      public OrientedPoint3d translate(double dX, double dY, double dZ)
      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 - the x translation
      dY - the y translation
      dZ - the z translation
      Returns:
      a new point with the translated coordinates

    • scale

      public OrientedPoint3d scale(double factor)
      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 - the scale factor
      Returns:
      a new point with the coordinates of this point scaled by the provided factor

    • neg

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

    • normalize

      public OrientedPoint3d normalize() throws IllegalArgumentException
      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:
      the normalized point
      Throws:
      IllegalArgumentException - when point is the origin, and no length can be established for scaling

    • interpolate

      public OrientedPoint3d interpolate(OrientedPoint3d otherPoint, double fraction)
      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 - the other point
      fraction - 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:
      a new OrientedPoint3d at the requested fraction
      Throws:
      NullPointerException - when otherPoint is null
      ArithmeticException - when fraction is NaN

    • rotate

      public OrientedPoint3d rotate(double rotateZ)
      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 - the rotation around the z-axis
      Returns:
      a new point with the same coordinates, dirX and dirY and modified dirZ
      Throws:
      ArithmeticException - when rotateZ is NaN

    • rotate

      public 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. The resulting rotations will be normalized between -π and π.
      Parameters:
      rotateX - the rotation around the x-axis
      rotateY - the rotation around the y-axis
      rotateZ - the rotation around the z-axis
      Returns:
      a new point with the same coordinates and applied rotations
      Throws:
      ArithmeticException - 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
      Returns:
      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 ≤ π/2 indicate above the x-y-plane; positive slope, angles > π/2 indicate angles below this plane; negative slope.
      Specified by:
      getDirY in interface Directed3d
      Overrides:
      getDirY in class DirectedPoint3d
      Returns:
      dirY

    • getDirZ

      public double getDirZ()
      Description copied from interface: Directed
      Retrieve the angle from the positive x-axis. Positive rotates towards the positive y-axis (and beyond).
      Specified by:
      getDirZ in interface Directed
      Overrides:
      getDirZ in class DirectedPoint3d
      Returns:
      the angle from the positive x-axis

    • iterator

      public Iterator<Point3d> iterator()
      Specified by:
      iterator in interface Iterable<Point3d>
      Overrides:
      iterator in class DirectedPoint3d

    • 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:
      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 - a format string (something like "%6.3f") which will be used to render every coordinate value)
      doNotIncludeClassName - 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:
      textual representation of the Drawable

    • epsilonEquals

      public boolean epsilonEquals(OrientedPoint3d other, double epsilonCoordinate, double epsilonRotation) throws NullPointerException, IllegalArgumentException
      Compare this Directed with another Directed with specified tolerances in the coordinates and the angles.
      Parameters:
      other - the Directed to compare to
      epsilonCoordinate - the upper bound of difference for one of the coordinates; use Double.POSITIVE_INFINITY if you do not want to check the coordinates
      epsilonRotation - the upper bound of difference for the rotation(s); use Double.POSITIVE_INFINITY if you do not want to check the angles
      Returns:
      boolean;true if x, y, and possibly z are less than epsilonCoordinate apart, and rotZ and possibly rotX, and possibly rotYare less than epsilonDirection apart, otherwise false
      Throws:
      NullPointerException - when other is null
      ArithmeticException - when epsilonCoordinate or epsilonDirection is NaN
      IllegalArgumentException - epsilonCoordinate or epsilonDirection is negative

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class DirectedPoint3d

    • equals

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