Module org.bzdev.graphics
Package org.bzdev.geom

Class Paths3D

java.lang.Object
org.bzdev.geom.Paths3D
public class Paths3D extends Object
Utility class to create various 3D paths. This class consists of static methods, and is analogous to the class Paths2D but for 3D paths instead of 2D paths. It also includes methods for creating unit vectors.

The operations include creating arcs and reversing existing paths.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Path3D
    alignClosedPaths(Path3D target, Path3D path)
    Shift a path, possibly reversing it, so that its start is as close as possible to the start of a target path.
    static Path3D
    alignClosedPaths(Path3D target, Path3D path, double limit)
    Shift a path, possibly reversing it, so that its start is as close as possible to the start of a target path, with a limit on how much tangent vectors can diverge.
    static Path3D
    createArc(double startx, double starty, double startz, double[] tangent, double[] normal, double radius, double theta)
    Create a 3D arc.
    static Path3D
    createArc(double startx, double starty, double startz, double[] tangent, double[] normal, double radius, double theta, double maxDelta)
    /** Create a 3D arc, specifying a maximum angular extent for each path segment.
    static Path3D
    reverse(Path3D path)
    Reverse a path.
    static Path3D
    shiftClosedPath(Path3D path, double x, double y, double z)
    Find the first closed component of a path that goes through a point (x, y, z) and shift that path component so it starts at (x, y, z); The point (x, y, z) must be the last point in a segment (including a MOVE_TO segment).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • createArc

      public static Path3D createArc(double startx, double starty, double startz, double[] tangent, double[] normal, double radius, double theta)
      Create a 3D arc. The normal vector must be perpendicular to the tangent vector and must point towards the center of the circle that contains the arc.
      Parameters:
      startx - the starting X coordinate
      starty - the starting Y coordinate
      startz - the starting Z coordinate
      tangent - the tangent vector at the start of the arc
      normal - the normal vector at the start of the arc
      radius - the radius of the arc
      theta - the angular extent of the arc in radians
      Returns:
      the new arc

    • createArc

      public static Path3D createArc(double startx, double starty, double startz, double[] tangent, double[] normal, double radius, double theta, double maxDelta)
      /** Create a 3D arc, specifying a maximum angular extent for each path segment. The normal vector must be perpendicular to the tangent vector and must point towards the center of the circle that contains the arc.
      Parameters:
      startx - the starting X coordinate
      starty - the starting Y coordinate
      startz - the starting Z coordinate
      tangent - the tangent vector at the start of the arc
      normal - the normal vector at the start of the arc
      radius - the radius of the arc
      theta - the angular extent of the arc in radians
      maxDelta - the maximum angular extent of an arc segment with allowed values in the range (0, 2π/3]
      Returns:
      the new arc

    • reverse

      public static Path3D reverse(Path3D path) throws IllegalArgumentException
      Reverse a path. For a path to be reversible, each PathIterator3D.SEG_CLOSE segment that does not end a path must be followed by a PathIterator3D.SEG_MOVETO segment.

      Reversing a path can be useful when a path is an outer boundary of one surface and an inner boundary of another.

      Parameters:
      path - the path to reverse
      Returns:
      the reversed path
      Throws:
      IllegalArgumentException - the path cannot be reversed

    • alignClosedPaths

      public static Path3D alignClosedPaths(Path3D target, Path3D path) throws IllegalArgumentException
      Shift a path, possibly reversing it, so that its start is as close as possible to the start of a target path. The argument path or a new path based on it, generated by shifting path and possibly reversing path or the shifted path will be returned.

      To determine if the returned path is reversed, the normalized tangent vectors at the start of the target path is compared to the normalized tangent vector of the shifted path and its reversed path by computing their dot products. The one with the largest dot product is chosen.

      Parameters:
      target - the target path
      path - the path to shift
      Returns:
      the path if its starting point is the closest one to the start of the target path; a new path otherwise
      Throws:
      IllegalArgumentException - if either path is not closed, or if the number of segments for each path differ

    • alignClosedPaths

      public static Path3D alignClosedPaths(Path3D target, Path3D path, double limit) throws IllegalArgumentException, IllegalStateException
      Shift a path, possibly reversing it, so that its start is as close as possible to the start of a target path, with a limit on how much tangent vectors can diverge. The argument path or a new path based on it, generated by shifting path and possibly reversing path or the shifted path will be returned.

      To determine if the returned path is reversed, the normalized tangent vectors at the start of the target path is compared to the normalized tangent vector of the shifted path and its reversed path by computing their dot products. The one with the largest dot product is chosen. If the absolute value of the difference in dot products is less than the limit, an exception is thrown.

      Parameters:
      target - the target path
      path - the path to shift
      limit - a non-negative limit on the absolute value of the difference in dot products of the normalized starting tangent vector of the target path with the normalized start tangent vector of the shifted path and the reverse of the shifted path
      Returns:
      the path if its starting point is the closest one to the start of the target path; a new path otherwise
      Throws:
      IllegalArgumentException - if either path is not closed, if the first argument is out of range, or if the number of segments for each path differ
      IllegalStateException - if the dot-product test failed

    • shiftClosedPath

      public static Path3D shiftClosedPath(Path3D path, double x, double y, double z)
      Find the first closed component of a path that goes through a point (x, y, z) and shift that path component so it starts at (x, y, z); The point (x, y, z) must be the last point in a segment (including a MOVE_TO segment).
      Parameters:
      path - the path
      x - the X coordinate of a point on the path
      y - the Y coordinate of a point on the path
      z - the Z coordinate of a point on the path
      Returns:
      the path component with a segment starting or ending at (x, y, z), with its segments shifted cyclically so that the returned path starts at the point (x, y, z); null if no segment starts or ends with the point (x, y, z).
      Throws:
      IllegalArgumentException - an argument was illegal