This is an automated email from the ASF dual-hosted git repository. erans pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-geometry.git
commit ccd1928504fdf4332e1da0f0ee62efc0e7512c05 Author: Matt Juntunen <[email protected]> AuthorDate: Mon Jul 9 22:49:05 2018 -0400 GEOMETRY-7: making PolarCoordinates and SphericalCoordinates final; adding class javadocs --- .../euclidean/threed/SphericalCoordinates.java | 53 +++++++++++++++++++--- .../geometry/euclidean/twod/PolarCoordinates.java | 42 ++++++++++++----- 2 files changed, 77 insertions(+), 18 deletions(-) diff --git a/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/SphericalCoordinates.java b/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/SphericalCoordinates.java index 6b38049..d3b3a25 100644 --- a/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/SphericalCoordinates.java +++ b/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/SphericalCoordinates.java @@ -24,9 +24,49 @@ import org.apache.commons.geometry.core.util.Coordinates; import org.apache.commons.geometry.core.util.SimpleCoordinateFormat; import org.apache.commons.numbers.angle.PlaneAngleRadians; -/** Class representing a set of spherical coordinates in 3 dimensional Euclidean space. +/** Class representing <a href="https://en.wikipedia.org/wiki/Spherical_coordinate_system";>spherical coordinates</a> + * in 3 dimensional Euclidean space. + * + * <p>Spherical coordinates for a point are defined by three values: + * <ol> + * <li><em>Radius</em> - The distance from the point to a fixed referenced point.</li> + * <li><em>Azimuth angle</em> - The angle measured from a fixed reference direction in a plane to + * the orthogonal projection of the point on that plane.</li> + * <li><em>Polar angle</em> - The angle measured from a fixed zenith direction to the point. The zenith + *direction must be orthogonal to the reference plane.</li> + * </ol> + * This class follows the convention of using the origin as the reference point; the positive x-axis as the + * reference direction for the azimuth angle, measured in the x-y plane with positive angles moving counter-clockwise + * toward the positive y-axis; and the positive z-axis as the zenith direction. Spherical coordinates are + * related to Cartesian coordinates as follows: + * <pre> + * x = r cos(θ) sin(Φ) + * y = r sin(θ) sin(Φ) + * z = r cos(Φ) + * + * r = √(x<sup>2</sup>+y<sup>2</sup>+z<sup>2</sup>) + * θ = atan2(y, x) + * Φ = acos(z/r) + * </pre> + * where <em>r</em> is the radius, <em>θ</em> is the azimuth angle, and <em>Φ</em> is the polar angle + * of the spherical coordinates. + * </p> + * + * <p>There are numerous, competing conventions for the symbols used to represent spherical coordinate values. For + * example, the mathematical convention is to use <em>(r, θ, Φ)</em> to represent radius, azimuth angle, and + * polar angle, whereas the physics convention flips the angle values and uses <em>(r, Φ, θ)</em>. As such, + * this class avoids the use of these symbols altogether in favor of the less ambiguous formal names of the values, + * e.g. {@code radius}, {@code azimuth}, and {@code polar}. + * </p> + * + * <p>In order to ensure the uniqueness of coordinate sets, coordinate values + * are normalized so that {@code radius} is in the range {@code [0, +Infinity)}, + * {@code azimuth} is in the range {@code (-pi, pi]}, and {@code polar} is in the + * range {@code [0, pi]}.</p> + * + * @see <a href="https://en.wikipedia.org/wiki/Spherical_coordinate_system";>Spherical Coordinate System</a> */ -public class SphericalCoordinates implements Spatial, Serializable { +public final class SphericalCoordinates implements Spatial, Serializable { /** Serializable version identifier. */ private static final long serialVersionUID = 20180623L; @@ -84,7 +124,7 @@ public class SphericalCoordinates implements Spatial, Serializable { this.polar = polar; } - /** Return the radius value. The value is in the range {@code [0, +infinity)}. + /** Return the radius value. The value is in the range {@code [0, +Infinity)}. * @return the radius value */ public double getRadius() { @@ -152,8 +192,7 @@ public class SphericalCoordinates implements Spatial, Serializable { return toCartesian(Point3D.getFactory()); } - /** - * Get a hashCode for this set of spherical coordinates. + /** Get a hashCode for this set of spherical coordinates. * <p>All NaN values have the same hash code.</p> * * @return a hash code value for this object @@ -207,8 +246,8 @@ public class SphericalCoordinates implements Spatial, Serializable { return SimpleCoordinateFormat.getPointFormat().format(radius, azimuth, polar); } - /** Create a {@link SphericalCoordinates} instance from the given values. The values are normalized - * so that {@code radius} lies in the range {@code [0, +infinity)}, {@code azimuth} lies in the range + /** Return a new instance with the given spherical coordinate values. The values are normalized + * so that {@code radius} lies in the range {@code [0, +Infinity)}, {@code azimuth} lies in the range * {@code (-pi, +pi]}, and {@code polar} lies in the range {@code [0, +pi]}. * @param radius the length of the line segment from the origin to the coordinate point. * @param azimuth the angle in the x-y plane, measured in radians counter-clockwise diff --git a/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/twod/PolarCoordinates.java b/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/twod/PolarCoordinates.java index da80e59..9bc9c96 100644 --- a/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/twod/PolarCoordinates.java +++ b/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/twod/PolarCoordinates.java @@ -24,12 +24,33 @@ import org.apache.commons.geometry.core.util.Coordinates; import org.apache.commons.geometry.core.util.SimpleCoordinateFormat; import org.apache.commons.numbers.angle.PlaneAngleRadians; -/** Class representing a set of polar coordinates in 2 dimensional - * Euclidean space. Coordinates are normalized so that {@code radius} - * is in the range {@code [0, +infinity)} and {@code azimuth} is in the - * range {@code (-pi, pi]}. +/** Class representing <a href="https://en.wikipedia.org/wiki/Polar_coordinate_system";>polar coordinates</a> + * in 2 dimensional Euclidean space. + * + * <p>Polar coordinates are defined by a distance from a reference point + * and an angle from a reference direction. The distance value is called + * the radial coordinate, or <em>radius</em>, and the angle is called the angular coordinate, + * or <em>azimuth</em>. This class follows the standard + * mathematical convention of using the positive x-axis as the reference + * direction and measuring positive angles counter-clockwise, toward the + * positive y-axis. The origin is used as the reference point. Polar coordinate + * are related to Cartesian coordinates as follows: + * <pre> + * x = r * cos(θ) + * y = r * sin(θ) + * + * r = √(x<sup>2</sup> + y<sup>2</sup>) + * θ = atan2(y, x) + * </pre> + * where <em>r</em> is the radius and <em>θ</em> is the azimuth of the polar coordinates. + * </p> + * <p>In order to ensure the uniqueness of coordinate sets, coordinate values + * are normalized so that {@code radius} is in the range {@code [0, +Infinity)} + * and {@code azimuth} is in the range {@code (-pi, pi]}.</p> + * + * @see <a href="https://en.wikipedia.org/wiki/Polar_coordinate_system";>Polar Coordinate System</a> */ -public class PolarCoordinates implements Spatial, Serializable { +public final class PolarCoordinates implements Spatial, Serializable { /** Serializable version UID */ private static final long serialVersionUID = 20180630L; @@ -47,7 +68,7 @@ public class PolarCoordinates implements Spatial, Serializable { /** Radius value */ private final double radius; - /** Azimuth angle in radians. */ + /** Azimuth angle in radians */ private final double azimuth; /** Simple constructor. Input values are normalized. @@ -137,8 +158,7 @@ public class PolarCoordinates implements Spatial, Serializable { return toCartesian(Point2D.getFactory()); } - /** - * Get a hashCode for this set of polar coordinates. + /** Get a hashCode for this set of polar coordinates. * <p>All NaN values have the same hash code.</p> * * @return a hash code value for this object @@ -192,9 +212,9 @@ public class PolarCoordinates implements Spatial, Serializable { return SimpleCoordinateFormat.getPointFormat().format(radius, azimuth); } - /** Return a new polar coordinate instance with the given values. - * The values are normalized so that radius lies in the range {@code [0, +infinity)} - * and azimuth in the range {@code (-pi, pi]}. + /** Return a new instance with the given polar coordinate values. + * The values are normalized so that {@code radius} lies in the range {@code [0, +infinity)} + * and {@code azimuth} in the range {@code (-pi, pi]}. * @param radius Radius value. * @param azimuth Azimuth angle in radians. * @return new {@link PolarCoordinates} instance
