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 2019/12/23 16:49:07 UTC
[commons-geometry] branch master updated: adding back portion of
userguide lost in merge; fixing table of contents link
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
The following commit(s) were added to refs/heads/master by this push:
new 4fafb06 adding back portion of userguide lost in merge; fixing table of contents link
4fafb06 is described below
commit 4fafb06e38d3bf7b7e8066fb774ecdac22da75c6
Author: Matt Juntunen <ma...@hotmail.com>
AuthorDate: Mon Dec 23 10:53:32 2019 -0500
adding back portion of userguide lost in merge; fixing table of contents link
---
src/site/site.xml | 6 +-
src/site/xdoc/userguide/index.xml | 182 ++++++++++++++++++++++++++------------
2 files changed, 126 insertions(+), 62 deletions(-)
diff --git a/src/site/site.xml b/src/site/site.xml
index a404f18..0aa7035 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -36,10 +36,10 @@
</script>
]]>
- <!--
+ <!--
Workaround to get styles for inline code elements. The current version
of the site plugin strips "code" tags out of the content. The following
- style rules are a copy of the Bootstrap rules for "code" elements but
+ style rules are a copy of the Bootstrap rules for "code" elements but
applied to span elements with the class "code".
-->
<![CDATA[
@@ -69,7 +69,7 @@
</menu>
<menu name="User Guide">
- <item name="Contents" href="/userguide/index.html"/>
+ <item name="Contents" href="/userguide/index.html#toc"/>
<item name="Overview" href="/userguide/index.html#overview"/>
<item name="Concepts" href="/userguide/index.html#concepts"/>
<item name="Core Interfaces" href="/userguide/index.html#interfaces"/>
diff --git a/src/site/xdoc/userguide/index.xml b/src/site/xdoc/userguide/index.xml
index 2ff63bd..1bc5f90 100644
--- a/src/site/xdoc/userguide/index.xml
+++ b/src/site/xdoc/userguide/index.xml
@@ -25,8 +25,72 @@
<body>
- <section name="Table of Contents" href="toc">
+ <h1>Commons Geometry User Guide</h1>
+ <section name="Contents" id="toc">
+ <ul>
+ <li>
+ <a href="#overview">Overview</a>
+ </li>
+ <li>
+ <a href="#concepts">Concepts</a>
+ <ul>
+ <li>
+ <a href="#floating_point">Floating Point Math</a>
+ </li>
+ <li>
+ <a href="#transforms">Transforms</a>
+ </li>
+ <li>
+ <a href="#hyperplanes">Hyperplanes</a>
+ </li>
+ <li>
+ <a href="#bsp_trees">BSP Trees</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#interfaces">Core Interfaces</a>
+ </li>
+ <li>
+ <a href="#euclidean">Euclidean Space</a>
+ <ul>
+ <li>
+ <a href="#euclidean_1d">Euclidean 1D</a>
+ </li>
+ <li>
+ <a href="#euclidean_2d">Euclidean 2D</a>
+ </li>
+ <li>
+ <a href="#euclidean_3d">Euclidean 3D</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#euclidean">Spherical Space</a>
+ <ul>
+ <li>
+ <a href="#spherical_1d">Spherical 1D</a>
+ </li>
+ <li>
+ <a href="#spherical_2d">Spherical 2D</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </section>
+
+ <section name="Overview" id="overview">
+ <p>
+ <em>Commons Geometry</em> provides types and utilities for geometric processing. The code originated in the
+ <span class="code">org.apache.commons.math3.geometry</span> package of the
+ <a class="code" href="https://commons.apache.org/proper/commons-math/">commons-math</a> project
+ but was pulled out into a separate project for better maintainability. It has since undergone numerous
+ improvements, including a major refactor of the core interfaces and classes.
+ </p>
+ <p>
+ <em>Commons Geometry</em> is divided into 5 submodules.
+ </p>
<ul>
<li>
<a class="code" href="../commons-geometry-core/index.html">commons-geometry-core</a> - Provides core interfaces
@@ -54,16 +118,16 @@
<section name="Concepts" id="concepts">
<subsection name="Floating Point Math" id="floating_point">
<p>
- All floating point numbers in <em>Commons Geometry</em> are represented using
- <span class="code">double</span>s.
+ All floating point numbers in <em>Commons Geometry</em> are represented using
+ <span class="code">double</span>s.
</p>
<p>
- The concept of a <em>precision context</em> is used in order to avoid issues with floating point errors
- in computations. A precision context is an object that encapsulates floating point comparisons,
- allowing numbers that may not be exactly equal to be considered equal for the
- purposes of a computation. This idea is represented in code with the
+ The concept of a <em>precision context</em> is used in order to avoid issues with floating point errors
+ in computations. A precision context is an object that encapsulates floating point comparisons,
+ allowing numbers that may not be exactly equal to be considered equal for the
+ purposes of a computation. This idea is represented in code with the
<a class="code" href="../commons-geometry-core/apidocs/org/apache/commons/geometry/core/precision/DoublePrecisionContext.html"
- >DoublePrecisionContext</a> interface. The example below uses an epsilon (tolerance) value to compare
+ >DoublePrecisionContext</a> interface. The example below uses an epsilon (tolerance) value to compare
numbers for equality.
</p>
<source>
@@ -82,8 +146,8 @@ precision.compare(1.002, 1.0); // 1
<subsection name="Transforms" id="transforms">
<p>
- A geometric transform is simply a function that maps points from one set to another. Transforms
- in <em>Commons Geometry</em> are represented with the
+ A geometric transform is simply a function that maps points from one set to another. Transforms
+ in <em>Commons Geometry</em> are represented with the
<a class="code" href="../commons-geometry-core/apidocs/org/apache/commons/geometry/core/Transform.html">Transform</a>
interface. Useful implementations of this interface exist for each supported space
and dimension, so users should not need to implement their own. However, it is important to know that
@@ -91,19 +155,19 @@ precision.compare(1.002, 1.0); // 1
</p>
<ol>
<li>
- The transform must be <strong><a href="https://en.wikipedia.org/wiki/Affine_transformation">affine</a></strong>.
+ The transform must be <strong><a href="https://en.wikipedia.org/wiki/Affine_transformation">affine</a></strong>.
In basic terms, this means that the transform must retain the "straightness" and "parallelness" of
- lines and planes (or whatever is an equivalent concept for the space). For example, a translation or
- rotation in Euclidean 3D space meets this requirement because all lines that are parallel before the
- transform remain parallel afterwards. However, a projective transform that causes previously parallel
- lines to meet at a single point does not.
+ lines and planes (or whatever is an equivalent concept for the space). For example, a translation or
+ rotation in Euclidean 3D space meets this requirement because all lines that are parallel before the
+ transform remain parallel afterwards. However, a projective transform that causes previously parallel
+ lines to meet at a single point does not.
</li>
<li>
- The transform must be <strong>inversible</strong>. An inverse transform must exist that will return
- the original point if given the transformed point. In other words, for a transform <var>t</var>, there
- must exist an inverse <var>inv</var> such that <var>inv.apply(t.apply(pt))</var> returns a point equal to
- the input point <var>pt</var>.
- </li>
+ The transform must be <strong>inversible</strong>. An inverse transform must exist that will return
+ the original point if given the transformed point. In other words, for a transform <var>t</var>, there
+ must exist an inverse <var>inv</var> such that <var>inv.apply(t.apply(pt))</var> returns a point equal to
+ the input point <var>pt</var>.
+ </li>
</ol>
<p>
Transforms that do not meet these requirements cannot be expected to produce correct results in
@@ -115,7 +179,7 @@ precision.compare(1.002, 1.0); // 1
<p>
A <em>hyperplane</em> is a subspace of dimension one less than its surrounding space. For example,
the hyperplanes in Euclidean 3D space are 2 dimensional planes. Similarly, the hyperplanes in Euclidean
- 2D space are 1 dimensional lines. Hyperplanes have the property that they partition their surrounding
+ 2D space are 1 dimensional lines. Hyperplanes have the property that they partition their surrounding
space into 3 distinct sets:
</p>
<ul>
@@ -128,21 +192,21 @@ precision.compare(1.002, 1.0); // 1
and the other as the <em>minus</em> side. The <em>offset</em> of a point relative to a hyperplane is the
distance from the point to the closest point on the hyperplane, with the sign of the distance being positive
if the point lies on the plus side of the hyperplane and minus otherwise. Points lying directly on the
- hyperplane have an offset of zero.
+ hyperplane have an offset of zero.
</p>
<p>
A subset of the points in a hyperplane is called a <em>subhyperplane</em>.
A triangular facet of a polyhedron in Euclidean 3D space, for example, is a subhyperplane because its
- interior represents a subset of the plane defined by the three points. Any subset of the points in a
- hyperplane is a subhyperplane; the region does not need to be contiguous or even finite. In fact, a
+ interior represents a subset of the plane defined by the three points. Any subset of the points in a
+ hyperplane is a subhyperplane; the region does not need to be contiguous or even finite. In fact, a
subhyperplane can contain the entire hyperplane itself.
</p>
<p>
Hyperplanes place a key role in <em>Commons Geometry</em> not only because of their importance geometrically but also
because they form the basis for the region classes and algorithms, such as <a href="#bsp_trees">BSP trees</a>.
- Hyperplanes are represented in code with the
+ Hyperplanes are represented in code with the
<a class="code" href="../commons-geometry-core/apidocs/org/apache/commons/geometry/core/partitioning/Hyperplane.html">Hyperplane</a>
- interface, with each space and dimension contains its own custom implementation. Users are not intended to
+ interface, with each space and dimension contains its own custom implementation. Users are not intended to
implement this interface.
</p>
</subsection>
@@ -150,34 +214,34 @@ precision.compare(1.002, 1.0); // 1
<subsection name="BSP Trees" id="bsp_trees">
<p>
Binary Space Partitioning (BSP) trees are an efficient way to represent spatial partitionings. They provide a very
- flexible and powerful geometric data structure that can represent everything from an entire, infinite space
- to simple, convex regions. Numerous algorithms also exist to perform operations on BSP trees, such as
- classifying points, computing the size of a represented region, and performing boolean operations on
+ flexible and powerful geometric data structure that can represent everything from an entire, infinite space
+ to simple, convex regions. Numerous algorithms also exist to perform operations on BSP trees, such as
+ classifying points, computing the size of a represented region, and performing boolean operations on
polytopes (union, intersection, difference, xor, complement).
</p>
<p>
- The main principle in BSP trees is the recursive subdivision of space using
+ The main principle in BSP trees is the recursive subdivision of space using
<a href="#hyperplanes">hyperplanes</a>. The easiest way to understand the data structure is to follow
the steps for creating a tree. When initially created, BSP trees contain a single node: the root node.
- This node is a leaf node and represents the entire space. If one "inserts" a
- hyperplane into the tree at that node, then the hyperplane partitions the node's space into a plus side
- and a minus side. The root node is now "cut", and two new leaf nodes are created for it as children: a plus
- node and a minus node. The plus node represents the half-space on the plus side of the cutting hyperplane
+ This node is a leaf node and represents the entire space. If one "inserts" a
+ hyperplane into the tree at that node, then the hyperplane partitions the node's space into a plus side
+ and a minus side. The root node is now "cut", and two new leaf nodes are created for it as children: a plus
+ node and a minus node. The plus node represents the half-space on the plus side of the cutting hyperplane
and the minus side represents the half-space on the minus side of the cutting hyperplane. These new child
nodes can themselves be cut by other hyperplanes, generating new child leaf nodes, and so on. In this way,
BSP trees can be created to represent any hyperplane-based spatial partitioning.
</p>
<p>
- In their most basic form, BSP trees do not represents polytopes. In order to represent polytopes,
- additional information must be stored with each leaf node, namely whether or not that leaf node lies on the
- inside or outside of the shape. By convention, when a BSP tree node is cut, the child node that lies on the
+ In their most basic form, BSP trees do not represents polytopes. In order to represent polytopes,
+ additional information must be stored with each leaf node, namely whether or not that leaf node lies on the
+ inside or outside of the shape. By convention, when a BSP tree node is cut, the child node that lies on the
minus side of the cutting hyperplane is considered to be inside of the shape, while the child node on the plus
side is considered to be on the outside. For example, in Euclidean 3D space, plane normals point toward the plus
side of the plane. Thus, when splitting a BSP tree node with a plane, the plane normal points outward from
the shape, as one might expect.
</p>
<p>
- One of the main sources for the development of the BSP tree code in this project and the original
+ One of the main sources for the development of the BSP tree code in this project and the original
<span class="code">commons-math</span> project was Bruce
Naylor, John Amanatides and William Thibault's paper <a href="http://www.cs.yorku.ca/~amana/research/bsptSetOp.pdf">Merging
BSP Trees Yields Polyhedral Set Operations</a> Proc. Siggraph '90,
@@ -185,7 +249,7 @@ precision.compare(1.002, 1.0); // 1
Association for Computing Machinery (ACM).
</p>
<p>
- BSP tree data structures in <em>Commons Geometry</em> are represented with the
+ BSP tree data structures in <em>Commons Geometry</em> are represented with the
<a class="code" href="../commons-geometry-core/apidocs/org/apache/commons/geometry/core/partitioning/bsp/BSPTree.html">BSPTree</a>
interface. Implementations of this interface representing regions/polytopes exist for each supported space and dimension.
</p>
@@ -251,8 +315,8 @@ tree.count(); // number of nodes in the tree = 7
<p>
<em>Commons Geometry</em> contains a number of core interfaces that appear throughout the library, generally
- following the same implementation patterns. For each space and dimension, there are interfaces that are always
- implemented with a single class, some that may have more than one implementation, and some that are optional.
+ following the same implementation patterns. For each space and dimension, there are interfaces that are always
+ implemented with a single class, some that may have more than one implementation, and some that are optional.
See the summary below for details.
</p>
@@ -312,17 +376,17 @@ tree.count(); // number of nodes in the tree = 7
<section name="Euclidean Space" id="euclidean">
<p>
- Euclidean space is the space commonly thought of when people think of geometry. It corresponds with the
- common notion of "flat" space or the space that we usually experience in the physical world.
- Distances between points in this space are given by the formula \( \sqrt{(A - B)^2} \),
+ Euclidean space is the space commonly thought of when people think of geometry. It corresponds with the
+ common notion of "flat" space or the space that we usually experience in the physical world.
+ Distances between points in this space are given by the formula \( \sqrt{(A - B)^2} \),
which is also known as the <em>Euclidean norm</em>.
</p>
<h4>Points and Vectors</h4>
<p>
Mathematically, points and vectors are separate, distinct entities. Points represent specific
- locations in space while vectors represent displacements between vectors. However, since the use of these
- types is so closely related and the data structures are so similar, they have been merged into a single set
+ locations in space while vectors represent displacements between vectors. However, since the use of these
+ types is so closely related and the data structures are so similar, they have been merged into a single set
of Euclidean <em>"VectorXD"</em> classes that implement both interfaces using Cartesian coordinates:
<a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/oned/Vector1D.html">Vector1D</a>,
<a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/twod/Vector2D.html">Vector2D</a>, and
@@ -355,7 +419,7 @@ tree.count(); // number of nodes in the tree = 7
Represents arbitrary 1D regions using BSP trees.
</li>
<li>
- <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/oned/Interval.html">Interval</a> -
+ <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/oned/Interval.html">Interval</a> -
Represents a single (possibly infinite), convex interval.
</li>
</ul>
@@ -443,7 +507,7 @@ List<Interval> intervals = tree.toIntervals(); // size = 2
Represents arbitrary areas using BSP trees.
</li>
<li>
- <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/twod/ConvexArea.html">ConvexArea</a> -
+ <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/twod/ConvexArea.html">ConvexArea</a> -
Represents a single (possibly infinite), convex area.
</li>
</ul>
@@ -467,7 +531,7 @@ List<Interval> intervals = tree.toIntervals(); // size = 2
Additional
<ul>
<li>
- <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/twod/Polyline.html">Polyline</a> -
+ <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/twod/Polyline.html">Polyline</a> -
Represents a connected sequence of line segments.
</li>
</ul>
@@ -568,7 +632,7 @@ List<Polyline> boundaries = tree.getBoundaryPaths(); // size = 1
Represents arbitrary volumes using BSP trees.
</li>
<li>
- <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/threed/ConvexVolume.html">ConvexVolume</a> -
+ <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/threed/ConvexVolume.html">ConvexVolume</a> -
Represents a single (possibly infinite), convex volume.
</li>
</ul>
@@ -589,7 +653,7 @@ List<Polyline> boundaries = tree.getBoundaryPaths(); // size = 1
<li>
<a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/threed/rotation/QuaternionRotation.html">QuaternionRotation</a> -
Represents 3D rotations using quaternions. Instances can be converted back and forth between
- <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/threed/rotation/AxisAngleSequence.html">AxisAngleSequence</a>s,
+ <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/threed/rotation/AxisAngleSequence.html">AxisAngleSequence</a>s,
which are used to represent rotations as Euler and/or Tait-Bryan angles.
</li>
</ul>
@@ -598,11 +662,11 @@ List<Polyline> boundaries = tree.getBoundaryPaths(); // size = 1
Additional
<ul>
<li>
- <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/threed/Line3D.html">Line3D</a> -
+ <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/threed/Line3D.html">Line3D</a> -
Represents a line in 3D space.
</li>
<li>
- <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/threed/Segment3D.html">Segment3D</a> -
+ <a class="code" href="../commons-geometry-euclidean/apidocs/org/apache/commons/geometry/euclidean/threed/Segment3D.html">Segment3D</a> -
Represents a line segment in 3D space. Since the segment can extend to infinity in either direction, this
class can also be used to represent rays.
</li>
@@ -708,7 +772,7 @@ List<ConvexSubPlane> minusFacets = minus.getBoundaries(); // size = 4
of points: one representation containing the coordinates given by the user and another, "normalized" representation
that uniquely identifies the location of the point. In 1D, the normalized form is the azimuth angle in the
range \([0, 2\pi)\) (see
- <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/Point1S.html#getNormalizedAzimuth--">Point1S.getNormalizedAzimuth()</a>
+ <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/Point1S.html#getNormalizedAzimuth--">Point1S.getNormalizedAzimuth()</a>
). In 2D, the normalized form is a 3D Euclidean vector indicating the point's location on the unit sphere (see
<a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/twod/Point2S.html#getVector--">Point2S.getVector()</a>
).
@@ -722,7 +786,7 @@ List<ConvexSubPlane> minusFacets = minus.getBoundaries(); // size = 4
where the <em>shortest</em> path between any two points lies entirely within the region. (In cases where
the distances are equal, we also define the region to be convex.) In the 1D case, this means that convex intervals
must either be completely full or have a size less than or equal to \(\pi\) (see
- <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/AngularInterval.Convex.html">AngularInterval.Convex</a>
+ <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/AngularInterval.Convex.html">AngularInterval.Convex</a>
), which implies the same for
<a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/twod/GreatArc.html">GreatArc</a>
instances in 2D.
@@ -741,7 +805,7 @@ List<ConvexSubPlane> minusFacets = minus.getBoundaries(); // size = 4
</li>
<li>
ConvexSubHyperplane -
- <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/CutAngle.SubCutAngle.html">SubCutAngle</a> -
+ <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/CutAngle.SubCutAngle.html">SubCutAngle</a> -
(Stub implementation since no subspace exists.)
</li>
<li>
@@ -752,11 +816,11 @@ List<ConvexSubPlane> minusFacets = minus.getBoundaries(); // size = 4
Represents arbitrary 1D regions using BSP trees.
</li>
<li>
- <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/AngularInterval.html">AngularInterval</a> -
+ <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/AngularInterval.html">AngularInterval</a> -
Represents a single interval, possibly non-convex.
</li>
<li>
- <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/AngularInterval.Convex.html">AngularInterval.Convex</a> -
+ <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/oned/AngularInterval.Convex.html">AngularInterval.Convex</a> -
Represents a single, convex interval.
</li>
</ul>
@@ -836,7 +900,7 @@ List<AngularInterval> intervals = tree.toIntervals(); //size = 2
Represents arbitrary areas using BSP trees.
</li>
<li>
- <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/twod/ConvexArea2S.html">ConvexArea2S</a> -
+ <a class="code" href="../commons-geometry-spherical/apidocs/org/apache/commons/geometry/spherical/twod/ConvexArea2S.html">ConvexArea2S</a> -
Represents a single, convex area.
</li>
</ul>