Package org.djutils.draw.point

Class DirectedPoint3d

java.lang.Object
org.djutils.draw.point.Point3d
org.djutils.draw.point.DirectedPoint3d
All Implemented Interfaces:
Serializable, Iterable<Point3d>, Directed, Directed3d, Drawable<Point3d>, Drawable3d, Point<Point3d>
Direct Known Subclasses:
OrientedPoint3d, Ray3d
public class DirectedPoint3d extends Point3d implements Directed3d
A DirectedPoint3d is a point in 3d space that additionally carries a direction in 3d i.c. dirY (similar to tilt; measured as an angle from the positive z-direction) and dirZ (similar to pan; measured as an angle from the positive x-direction).

Copyright (c) 2023-2025 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djutils.org. The DJUTILS project is distributed under a three-clause BSD-style license, which can be found at https://djutils.org/docs/license.html.

Author:
Alexander Verbraeck, Peter Knoppers, Wouter Schakel
See Also:

  • Field Details

    • dirY

      public final double dirY
      The direction as rotation around the x-axis.

    • dirZ

      public final double dirZ
      The direction as rotation from the positive z-axis towards the x-y plane.

  • Constructor Details

    • DirectedPoint3d

      public DirectedPoint3d(double x, double y, double z, double dirY, double dirZ)
      Create a new DirectedPoint3d with x, y, and z coordinates and direction dirY,dirZ.
      Parameters:
      x - the x coordinate
      y - the y coordinate
      z - the z coordinate
      dirY - the complement of the slope
      dirZ - the counter-clockwise rotation around the point in radians
      Throws:
      ArithmeticException - when x, y, z, dirY, or dirZ is NaN

    • DirectedPoint3d

      public DirectedPoint3d(double x, double y, double z, double[] directionVector)
      Create a new DirectedPoint3d with x, y and z coordinates and direction specified using a double array of two elements (containing dirY,dirZ in that order).
      Parameters:
      x - the x coordinate
      y - the y coordinate
      z - the z coordinate
      directionVector - the two direction angles (dirY and dirZ) in a double array containing dirY and dirZ in that order. DirY is the rotation from the positive z-axis to the direction. DirZ is the angle from the positive x-axis to the projection of the direction in the x-y-plane.
      Throws:
      NullPointerException - when directionVector is null
      ArithmeticException - when x, y, z is NaN, or directionVector contains a NaN value
      IllegalArgumentException - when the length of the directionVector array is not 2, or contains a NaN value

    • DirectedPoint3d

      public DirectedPoint3d(double x, double y, double z, Direction3d dir)
      Create a new DirectedPoint3d with x, y, and z coordinates and Direction3d.
      Parameters:
      x - the x coordinate
      y - the y coordinate
      z - the z coordinate
      dir - the direction
      Throws:
      NullPointerException - when dir> is null
      ArithmeticException - when x, y, z, dirY, or dirZ is NaN

    • DirectedPoint3d

      public DirectedPoint3d(double x, double y, double z, double throughX, double throughY, double throughZ)
      Construct a new DirectedPoint3d from three coordinates and the coordinates of a point that the direction goes through.
      Parameters:
      x - the x coordinate of the new DirectedPoint
      y - the y coordinate of the new DirectedPoint
      z - the z coordinate of the new DirectedPoint
      throughX - the x-coordinate of a point that the direction goes through
      throughY - the y-coordinate of a point that the direction goes through
      throughZ - the z-coordinate of a point that the direction goes through
      Throws:
      ArithmeticException - when z, y, z, throughX, throughY, or throughZ is NaN
      IllegalArgumentException - when throughX == x and throughY == y and throughZ == z

    • DirectedPoint3d

      public DirectedPoint3d(double x, double y, double z, Point3d throughPoint)
      Construct a new DirectedPoint3d from x, y and z coordinates and a point that the direction goes through.
      Parameters:
      x - the x coordinate of the new DirectedPoint3d
      y - the y coordinate of the new DirectedPoint3d
      z - the z coordinate of the new DirectedPoint3d
      throughPoint - a point that the direction goes through
      Throws:
      NullPointerException - when throughPoint is null
      ArithmeticException - when x, y, or z is NaN
      IllegalArgumentException - when throughPoint is exactly at (x y,z)

    • DirectedPoint3d

      public DirectedPoint3d(double[] xyz, double dirY, double dirZ)
      Create a new DirectedPoint3d with x, y, and z coordinates in a double[] and direction dirY,dirZ.
      Parameters:
      xyz - the x, y and z coordinates
      dirY - the complement of the slope
      dirZ - the counter-clockwise rotation around the point in radians
      Throws:
      NullPointerException - when xyx is null
      IllegalArgumentException - when the length of the xyz array is not 3, or contains a NaN value, or dirY, or dirZ is NaN

    • DirectedPoint3d

      public DirectedPoint3d(double[] xyz, double[] directionVector)
      Create a new OrientedPoint3d from x, y and z coordinates packed in a double array of three elements and a direction specified using a double array of two elements.
      Parameters:
      xyz - the x, y and z coordinates in that order
      directionVector - the two direction angles dirY and dirZ in that order
      Throws:
      NullPointerException - when xyz, or directionVector is null
      ArithmeticException - when xyz, or directionVector contains a NaN value
      IllegalArgumentException - when the length of the xyx is not 3 or the length of the directionVector is not 2

    • DirectedPoint3d

      public DirectedPoint3d(double[] xyz, Direction3d dir)
      Create a new DirectedPoint3d with x, y, and z coordinates in a double[] and a Direction3d.
      Parameters:
      xyz - the x, y and z coordinates
      dir - the direction
      Throws:
      NullPointerException - when xyx is null, or dir is null
      IllegalArgumentException - when the length of the xyz array is not 3, or contains a NaN value

    • DirectedPoint3d

      public DirectedPoint3d(Point3d point, double dirY, double dirZ)
      Create a new DirectedPoint3d from another Point3d and and direction dirY,dirZ.
      Parameters:
      point - the point from which this OrientedPoint3d will be instantiated
      dirY - the complement of the slope
      dirZ - the counter-clockwise rotation around the point in radians
      Throws:
      ArithmeticException - when dirY, or dirZ is NaN

    • DirectedPoint3d

      public DirectedPoint3d(Point3d point, Direction3d direction)
      Create a new DirectedPoint3d from another Point3d and a Direction3d.
      Parameters:
      point - the point from which this OrientedPoint3d will be instantiated
      direction - the direction
      Throws:
      NullPointerException - when point, or direction is null

    • DirectedPoint3d

      public DirectedPoint3d(Point3d point, double throughX, double throughY, double throughZ)
      Construct a new DirectedPoint3d form a Point3d and the coordinates that the direction goes through.
      Parameters:
      point - the point
      throughX - the x coordinate of a point that the direction goes through
      throughY - the y coordinate of a point that the direction goes through
      throughZ - the z coordinate of a point that the direction goes through
      Throws:
      NullPointerException - when point is null
      ArithmeticException - when throughX, or throughY, or throughZ is NaN
      IllegalArgumentException - when throughX == point.x and throughY == point.y and throughZ == point.z

    • DirectedPoint3d

      public DirectedPoint3d(Point3d point, Point3d throughPoint)
      Construct a new DirectedPoint3d.
      Parameters:
      point - the location of the new DirectedPoint3d
      throughPoint - another point that the direction goes through
      Throws:
      NullPointerException - when point is null or throughPoint is null
      IllegalArgumentException - when throughPoint is exactly at point

  • Method Details

    • translate

      public DirectedPoint3d 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 Point3d
      Parameters:
      dX - the x translation
      dY - the y translation
      Returns:
      a new point with the translated coordinates and the same z value

    • translate

      public DirectedPoint3d 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 Point3d
      Parameters:
      dX - the x translation
      dY - the y translation
      dZ - the z translation
      Returns:
      a new point with the translated coordinates

    • scale

      public DirectedPoint3d 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 Point3d
      Parameters:
      factor - the scale factor
      Returns:
      a new point with the coordinates of this point scaled by the provided factor

    • neg

      public DirectedPoint3d 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 Point3d
      Returns:
      a new point with negated coordinate values

    • abs

      public DirectedPoint3d 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 Point3d
      Returns:
      a new point with absolute coordinate values

    • normalize

      public DirectedPoint3d 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 Point3d
      Returns:
      the normalized point
      Throws:
      IllegalArgumentException - when point is the origin, and no length can be established for scaling

    • interpolate

      public DirectedPoint3d interpolate(DirectedPoint3d otherPoint, double fraction)
      Interpolate towards another DirectedPoint3d 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. 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 DirectedPoint3d at the requested fraction
      Throws:
      NullPointerException - when otherPoint is null
      ArithmeticException - when fraction is NaN

    • rotate

      public DirectedPoint3d rotate(double rotateZ)
      Return a new DirectedPoint3d with an in-place rotation around the z-axis by the provided rotateZ. The resulting rotation will be normalized between -π and π.
      Parameters:
      rotateZ - the rotation around the z-axis
      Returns:
      a new point with the same coordinates, dirY and modified dirZ
      Throws:
      ArithmeticException - when rotateZ is NaN

    • rotate

      public DirectedPoint3d rotate(double rotateY, double rotateZ)
      Return a new DirectedPoint3d point with an in-place rotation by the provided rotateY, and rotateZ. The resulting rotations will be normalized between -π and π.
      Parameters:
      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 rotateY, or rotateZ is NaN

    • 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
      Returns:
      the angle from the positive x-axis

    • 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
      Returns:
      dirY

    • iterator

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

    • 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 Point3d
      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 Point3d
      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(DirectedPoint3d other, double epsilonCoordinate, double epsilonDirection) 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
      epsilonDirection - 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 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 Point3d

    • equals

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