Package org.djutils.draw.point

Class DirectedPoint3d

java.lang.Object
org.djutils.draw.point.Point3d
org.djutils.draw.point.DirectedPoint3d
All Implemented Interfaces:
Serializable, Directed<DirectedPoint3d>, Directed3d<DirectedPoint3d>, Drawable<Point3d>, Drawable3d, Point<Point3d>
Direct Known Subclasses:
OrientedPoint3d, Ray3d
public class DirectedPoint3d extends Point3d implements Directed3d<DirectedPoint3d>
DirectedPoint3d.java.

Copyright (c) 2023-2024 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
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) throws IllegalArgumentException
      Create a new DirectedPoint3d 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
      dirY - double; the complement of the slope
      dirZ - double; the counter-clockwise rotation around the point in radians
      Throws:
      IllegalArgumentException - when x, y, z, dirX, dirY, or dirZ is NaN

    • DirectedPoint3d

      public DirectedPoint3d(double[] xyz, double dirY, double dirZ) throws NullPointerException, IllegalArgumentException
      Create a new DirectedPoint3d with x, y, and z coordinates in a double[] and direction dirY,dirZ.
      Parameters:
      xyz - double[]; the x, y and z coordinates
      dirY - double; the complement of the slope
      dirZ - double; 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(Point3d point, double dirY, double dirZ) throws IllegalArgumentException
      Create a new DirectedPoint3d from another Point3d and and direction dirY,dirZ.
      Parameters:
      point - Point3d; the point from which this OrientedPoint3d will be instantiated
      dirY - double; the complement of the slope
      dirZ - double; the counter-clockwise rotation around the point in radians
      Throws:
      IllegalArgumentException - when dirX, dirY, or dirZ is NaN

    • DirectedPoint3d

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

    • DirectedPoint3d

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

    • DirectedPoint3d

      public DirectedPoint3d(double x, double y, double z, double[] orientation) throws NullPointerException, IllegalArgumentException
      Create a new DirectedPoint3d with x, y and z coordinates and orientation specified using a double array of two elements (containing dirY,dirZ in that order).
      Parameters:
      x - double; the x coordinate
      y - double; the y coordinate
      z - double; the z coordinate
      orientation - double[]; the two direction values (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 orientation is null
      IllegalArgumentException - when the length of the direction array is not 2, or contains a NaN value

    • DirectedPoint3d

      public DirectedPoint3d(double[] xyz, double[] orientation) throws NullPointerException, IllegalArgumentException
      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 - double[]; the x, y and z coordinates in that order
      orientation - double[]; the two orientation angles dirY and dirZ in that order
      Throws:
      NullPointerException - when xyx or orientation is null
      IllegalArgumentException - when the length of the xyx array is not 3 or the length of the orientation array is not 2

    • DirectedPoint3d

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

    • DirectedPoint3d

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

  • Method Details

    • translate

      public DirectedPoint3d 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 Point3d
      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 DirectedPoint3d 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 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 DirectedPoint3d 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 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 DirectedPoint3d 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 Point<Point3d>
      Overrides:
      neg in class Point3d
      Returns:
      Point; 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 and dirZ are copied unchanged.
      Specified by:
      abs in interface Point<Point3d>
      Overrides:
      abs in class Point3d
      Returns:
      Point; a new point with absolute coordinate values

    • normalize

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

    • interpolate

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

    • rotate

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

    • rotate

      public DirectedPoint3d rotate(double rotateY, double rotateZ) throws IllegalArgumentException
      Return a new OrientedPoint3d point with an in-place rotation by the provided rotateY, and rotateZ. The resulting rotations will be normalized between -π and π.
      Parameters:
      rotateY - double; the rotation around the y-axis
      rotateZ - double; the rotation around the z-axis
      Returns:
      DirectedPoint3d; a new point with the same coordinates and applied rotations
      Throws:
      IllegalArgumentException - when any of the rotations is NaN

    • 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>
      Returns:
      double; dirZ

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

    • getPoints

      public Iterator<? extends DirectedPoint3d> 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 Point3d
      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 Point3d
      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 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(DirectedPoint3d other, double epsilonCoordinate, double epsilonRotation) throws NullPointerException, IllegalArgumentException
      Description copied from interface: Directed
      Compare this Directed with another Directed with specified tolerances in the coordinates and the angles.
      Specified by:
      epsilonEquals in interface Directed<DirectedPoint3d>
      Parameters:
      other - D; the Directed to compare to
      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 point 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