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 <[email protected]>
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>