Package org.djutils.draw.line

Class Ray3d

java.lang.Object
org.djutils.draw.point.Point3d
org.djutils.draw.point.DirectedPoint3d
org.djutils.draw.line.Ray3d
All Implemented Interfaces:
Serializable, Iterable<Point3d>, Directed<DirectedPoint3d>, Directed3d<DirectedPoint3d>, Drawable<Point3d>, Drawable3d, Project<Point3d>, Ray<Ray3d,DirectedPoint3d,Point3d>, Point<Point3d>
public class Ray3d extends DirectedPoint3d implements Drawable3d, Ray<Ray3d,DirectedPoint3d,Point3d>
Ray3d is a half-line in 3d; it has one end point with non-infinite coordinates; the other end point is infinitely far away.

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
See Also:

  • Constructor Details

    • Ray3d

      public Ray3d(double x, double y, double z, double dirY, double dirZ)
      Construct a new Ray3d.
      Parameters:
      x - the x coordinate of the finite end point of the ray
      y - the y coordinate of the finite end point of the ray
      z - the z coordinate of the finite end point of the ray
      dirY - the angle from the positive Z axis direction in radians (the complement of the slope)
      dirZ - the angle from the positive X axis direction in radians
      Throws:
      IllegalArgumentException - when dirY, or dirZ is NaN (should be impossible)

    • Ray3d

      public Ray3d(double x, double y, double z, double[] directionVector)
      Create a new Ray3d 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
      directionVector - the two direction angles 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 direction is null
      ArithmeticException - when the directionVector array contains a NaN value
      IllegalArgumentException - when the length of the directionVector array is not 2

    • Ray3d

      public Ray3d(double x, double y, double z, Direction3d dir)
      Construct a new Ray3d.
      Parameters:
      x - the x coordinate of the finite end point of the ray
      y - the y coordinate of the finite end point of the ray
      z - the z coordinate of the finite end point of the ray
      dir - the direction
      Throws:
      IllegalArgumentException - when dirY, or dirZ is NaN (should be impossible)

    • Ray3d

      public Ray3d(double x, double y, double z, double throughX, double throughY, double throughZ)
      Construct a new Ray3d.
      Parameters:
      x - the x coordinate of the finite end point of the ray
      y - the y coordinate of the finite end point of the ray
      z - the z coordinate of the finite end point of the ray
      throughX - the x coordinate of another point on the ray
      throughY - the y coordinate of another point on the ray
      throughZ - the z coordinate of another point on the ray
      Throws:
      ArithmeticException - when throughX, or throughY, or throughZ is NaN
      IllegalArgumentException - when throughX> == x and throughY == y and throughZ == z

    • Ray3d

      public Ray3d(double x, double y, double z, Point3d throughPoint)
      Construct a new Ray3d.
      Parameters:
      x - the x coordinate of the finite end point of the ray
      y - the y coordinate of the finite end point of the ray
      z - the z coordinate of the finite end point of the ray
      throughPoint - another point on the ray
      Throws:
      NullPointerException - when throughPoint is null
      ArithmeticException - when x, y, or z is NaN
      IllegalArgumentException - when throughPoint is exactly at (x, y)

    • Ray3d

      public Ray3d(double[] xyz, double dirY, double dirZ)
      Create a new Ray3d from x, y, and z coordinates packed in a double array of three elements and direction dirY,dirZ.
      Parameters:
      xyz - the x, y and z coordinates in that order
      dirY - the angle from the positive Z axis direction in radians (the complement of the slope)
      dirZ - the angle from the positive X axis direction 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

    • Ray3d

      public Ray3d(double[] xyz, double[] directionVector)
      Create a new Ray3d from x, y, and z coordinates packed in a double array of three elements and direction dirY,dirZ.
      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

    • Ray3d

      public Ray3d(double[] xyz, Direction3d dir)
      Create a new Rayt3d 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
      dir - the direction
      Throws:
      NullPointerException - when xyx array or dir is null
      ArithmeticException - when the xyz arraycontains a NaN value
      IllegalArgumentException - when the length of the xyx array is not 3

    • Ray3d

      public Ray3d(Point3d point, double dirY, double dirZ)
      Construct a new Ray3d.
      Parameters:
      point - the finite end point of the ray
      dirY - the angle from the positive Z axis direction in radians (the complement of the slope)
      dirZ - the angle from the positive X axis direction in radians
      Throws:
      NullPointerException - when point is null
      IllegalArgumentException - when dirY, or dirZ is NaN

    • Ray3d

      public Ray3d(Point3d point, Direction3d dir)
      Construct a new Ray3d.
      Parameters:
      point - the finite end point of the ray
      dir - the direction
      Throws:
      NullPointerException - when point is null, or dir is null

    • Ray3d

      public Ray3d(Point3d point, double throughX, double throughY, double throughZ)
      Construct a new Ray3d.
      Parameters:
      point - the finite end point of the ray
      throughX - the x coordinate of another point on the ray
      throughY - the y coordinate of another point on the ray
      throughZ - the z coordinate of another point on the ray
      Throws:
      NullPointerException - when point is null
      ArithmeticException - when throughX, or throughY, or throughZ is NaN
      IllegalArgumentException - when throughX == x and throughY == y and throughZ == z

    • Ray3d

      public Ray3d(Point3d point, Point3d throughPoint) throws NullPointerException, IllegalArgumentException
      Construct a new Ray3d.
      Parameters:
      point - the finite end point of the ray
      throughPoint - another point on the ray
      Throws:
      NullPointerException - when point is null or throughPoint is null
      IllegalArgumentException - when throughPoint is exactly at point

    • Ray3d

      public Ray3d(DirectedPoint3d directedPoint)
      Construct a new Ray3d.
      Parameters:
      directedPoint - point and direction of the new Ray3d
      Throws:
      NullPointerException - when directedPoint is null

  • Method Details

    • getDirY

      public final 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<DirectedPoint3d>
      Overrides:
      getDirY in class DirectedPoint3d
      Returns:
      dirY

    • getDirZ

      public final 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 Ray<Ray3d,DirectedPoint3d,Point3d>
      Overrides:
      getDirZ in class DirectedPoint3d
      Returns:
      dirZ

    • getEndPoint

      public DirectedPoint3d getEndPoint()
      Description copied from interface: Ray
      Get the finite end point of this Ray.
      Specified by:
      getEndPoint in interface Ray<Ray3d,DirectedPoint3d,Point3d>
      Returns:
      the finite end point of this Ray

    • size

      public int size()
      Description copied from interface: Drawable
      Retrieve the number of points that make up the object.
      Specified by:
      size in interface Drawable<Point3d>
      Overrides:
      size in class Point3d
      Returns:
      the number of points that make up the object

    • iterator

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

    • getBounds

      public Bounds3d getBounds()
      Description copied from interface: Drawable3d
      Retrieve the bounding box of the object.
      Specified by:
      getBounds in interface Drawable3d
      Overrides:
      getBounds in class Point3d
      Returns:
      the bounding box of the object

    • neg

      public Ray3d 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 Directed<DirectedPoint3d>
      Specified by:
      neg in interface Point<Point3d>
      Overrides:
      neg in class DirectedPoint3d
      Returns:
      a new point with negated coordinate values

    • flip

      public Ray3d flip()
      Description copied from interface: Ray
      Flip the direction of the Ray (creates and returns a new Ray instance).
      Specified by:
      flip in interface Ray<Ray3d,DirectedPoint3d,Point3d>
      Returns:
      Ray at the same location, but with dirZ (in case of a Ray3d) incremented by π and dirY subtracted from π

    • getLocationExtended

      public Ray3d getLocationExtended(double position) throws ArithmeticException, IllegalArgumentException
      Description copied from interface: Ray
      Get the location at a position on the line, with its direction. Position must be a finite value
      Specified by:
      getLocationExtended in interface Ray<Ray3d,DirectedPoint3d,Point3d>
      Parameters:
      position - the position on the line for which to calculate the point on the line
      Returns:
      a ray with the same direction as this ray
      Throws:
      ArithmeticException - when position is NaN
      IllegalArgumentException - when position infinite

    • closestPointOnRay

      public Point3d closestPointOnRay(Point3d point) throws NullPointerException
      Description copied from interface: Ray
      Project a Point on a Ray. If the the projected points lies outside the ray, the start point of the ray is returned. Otherwise the closest point on the ray is returned.
      Adapted from example code published by Paul Bourke.
      Specified by:
      closestPointOnRay in interface Ray<Ray3d,DirectedPoint3d,Point3d>
      Parameters:
      point - the point to project onto the segment
      Returns:
      either the start point, or DirectedPoint that lies somewhere on this Ray
      Throws:
      NullPointerException - when point is null

    • projectOrthogonal

      public Point3d projectOrthogonal(Point3d point) throws NullPointerException
      Description copied from interface: Project
      Project a point onto this object. For PolyLines and Polygons, there may be multiple valid solutions. In that case the solution that lies on the closest segment is returned. If there is no valid solution on the closest segment, null is returned.
      Specified by:
      projectOrthogonal in interface Project<Point3d>
      Parameters:
      point - the point
      Returns:
      the projection of the point (may be null if no sensible projection is possible). If the result is not null; the result lies somewhere on this object.
      Throws:
      NullPointerException - when point is null

    • projectOrthogonalExtended

      public Point3d projectOrthogonalExtended(Point3d point)
      Description copied from interface: Project
      Project a point onto this object. For PolyLines and Polygons, there may be multiple valid solutions. In that case the solution that lies on the closest segment is returned.
      Specified by:
      projectOrthogonalExtended in interface Project<Point3d>
      Parameters:
      point - the point
      Returns:
      the projection of the point. This result cannot be null, but it may not lie on this object, but, in stead, lie on a line, or plane that extends this object

    • projectOrthogonalFractional

      public double projectOrthogonalFractional(Point3d point) throws NullPointerException
      Description copied from interface: Project
      Project a point onto this object. For PolyLines and Polygons, there may be multiple valid solutions. In that case the solution that lies on the closest segment is returned. If there is no valid solution on the closest segment, NaN is returned.
      Specified by:
      projectOrthogonalFractional in interface Project<Point3d>
      Parameters:
      point - the point
      Returns:
      the fractional position of the projection of the point (may be NaN if no sensible projection is possible). If the result is not NaN; the result lies somewhere on this object.
      Throws:
      NullPointerException - when point is null

    • projectOrthogonalFractionalExtended

      public double projectOrthogonalFractionalExtended(Point3d point) throws NullPointerException
      Description copied from interface: Project
      Project a point onto this object. For PolyLines and Polygons, there may be multiple valid solutions. In that case the solution that lies on the closest segment is returned.
      Specified by:
      projectOrthogonalFractionalExtended in interface Project<Point3d>
      Parameters:
      point - the point
      Returns:
      the fractional position of the projection of the point. This result cannot be NaN, but it may be outside the range 0.0 .. 1.0.
      Throws:
      NullPointerException - when point is null

    • 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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class DirectedPoint3d

    • equals

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