You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by er...@apache.org on 2018/07/21 10:07:46 UTC
[commons-geometry] 08/15: GEOMETRY-7: making PolarCoordinates and
SphericalCoordinates final; adding class javadocs
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 <ma...@hotmail.com>
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