Author: luc
Date: Wed Jan 22 15:55:03 2014
New Revision: 1560390

URL: http://svn.apache.org/r1560390
Log:
Updated user guide for geometry.

Modified:
    commons/proper/math/trunk/src/site/xdoc/userguide/geometry.xml
    commons/proper/math/trunk/src/site/xdoc/userguide/index.xml

Modified: commons/proper/math/trunk/src/site/xdoc/userguide/geometry.xml
URL: 
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/geometry.xml?rev=1560390&r1=1560389&r2=1560390&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/geometry.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/geometry.xml Wed Jan 22 
15:55:03 2014
@@ -30,50 +30,64 @@
       <subsection name="11.1 Overview" href="overview">
         <p>
            The geometry package provides classes useful for many physical 
simulations
-           in Euclidean spaces, like vectors and rotations in 3D, as well as a 
general
-           implentation of Binary Space Partitioning Trees (BSP trees).
+           in Euclidean spaces, like vectors and rotations in 3D, as well as 
on the
+           sphere. It also provides a general implementation of Binary Space 
Partitioning
+           Trees (BSP trees).
+        </p>
+        <p>
+           All supported type of spaces (Euclidean 3D, Euclidean 2D, Euclidean 
1D, 2-Sphere
+           and 1-Sphere) provide dedicated classes that represent complex 
regions of the
+           space as shown in the following table:
+        </p>
+        <p>
+          <table border="1" align="center">
+          <tr BGCOLOR="#CCCCFF"><td colspan="2"><font 
size="+1">Regions</font></td></tr>
+          <tr BGCOLOR="#EEEEFF"><font 
size="+1"><td>Space</td><td>Region</td></font></tr>
+          <tr><td>Euclidean 1D</td><td><a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/oned/IntervalsSet.html">IntervalsSet</a></td></tr>
+          <tr><td>Euclidean 2D</td><td><a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/twod/PolygonsSet.html">PolygonsSet</a></td></tr>
+          <tr><td>Euclidean 3D</td><td><a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/threed/PolyhedronsSet.html">PolyhedronsSet</a></td></tr>
+          <tr><td>1-Sphere</td><td><a 
href="../apidocs/org/apache/commons/math3/geometry/spherical/oned/ArcsSet.html">ArcsSet</a></td></tr>
+          <tr><td>2-Sphere</td><td><a 
href="../apidocs/org/apache/commons/math3/geometry/spherical/twod/SphericalPolygonsSet.html">SphericalPolygonsSet</a></td></tr>
+          </table>
+        </p>
+        <p>
+          All these regions share common features. Regions can be defined from 
several non-connected parts.
+          As an example, one PolygonsSet instance in Euclidean 2D (i.e. one 
the plane) can represent a region composed
+          of several separated polygons separate from each other. They also 
support regions containing holes. As an example
+          a SphericalPolygonsSet on the 2-Sphere can represent a land mass on 
the Earth with an interior sea, where points
+          on this sea would not be considered to belong to the land mass. Of 
course more complex models can also be represented
+          and it is possible to define for example one region composed of 
several continents, with interior sea containing
+          separate islands, some of which having lakes, which may have smaller 
island ... In the infinite Euclidean spaces,
+          regions can have infinite parts. for example in 1D (i.e. along a 
line), one can define an interval starting at
+          abscissa 3 and extending up to infinity. This is also possible in 2D 
and 3D. For all spaces, regions without any
+          boundaries are also possible so one can define the whole space or 
the empty region. The classical set operations
+          are available in all cases: union, intersection, symmetric 
difference (exclusive or), difference, complement.
+          There are also region predicates (point inside/outside/on boundary, 
emptiness, other region contained). For some
+          regions, they can be constructed directly from a boundary 
representation (for example vertices in the case of 2D
+          polygons, both on the Euclidean space or on the 2-Sphere). Some 
geometric properties like size, or boundary size
+          can be computed, as well as barycenters on the Euclidean space. 
Another important feature available for all these
+          regions is the projection of a point to the closest region boundary 
(if there is a boundary). The projection provides
+          both the projected point and the signed distance between the point 
and its projection, with the convention distance
+          to boundary is considered negative if the point is inside the 
region, positive if the point is outside the region
+          and of course 0 if the point is already on the boundary. This 
feature can be used for example as the value of a
+          function in a root solver to determine when a moving point crosses 
the region boundary.
         </p>
       </subsection>
+
       <subsection name="11.2 Euclidean spaces" href="euclidean">
-      <p>
-          <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/oned/Interval.html">
-          Interval</a> and <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/oned/IntervalsSet.html">
-          IntervalsSet</a> represent one dimensional regions. All classical 
set operations are available
-          for intervals sets: union, intersection, symmetric difference 
(exclusive or), difference, complement,
-          as well as region predicates (point inside/outside/on boundary, 
emptiness, other region contained).
-          It is also possible to compute geometrical properties like size, 
barycenter or boundary size.
-          Intervals sets can be built by constructive geometry (union, 
intersection ...) or from a boundary
-          representation.
-      </p>
-      <p>
-          <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/twod/PolygonsSet.html">
-          PolygonsSet</a> represent two dimensional regions. All classical set 
operations are available
-          for polygons sets: union, intersection, symmetric difference 
(exclusive or), difference, complement,
-          as well as region predicates (point inside/outside/on boundary, 
emptiness, other region contained).
-          It is also possible to compute geometrical properties like size, 
barycenter or boundary size and
-          to extract the vertices. Polygons sets can be built by constructive 
geometry (union, intersection ...)
-          or from a boundary representation.
-      </p>
-      <p>
-          <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/threed/PolyhedronsSet.html">
-          PolyhedronsSet</a> represent three dimensional regions. All 
classical set operations are available
-          for polyhedrons sets: union, intersection, symmetric difference 
(exclusive or), difference, complement,
-          as well as region predicates (point inside/outside/on boundary, 
emptiness, other region contained).
-          It is also possible to compute geometrical properties like size, 
barycenter or boundary size and
-          to extract the vertices. Polyhedrons sets can be built by 
constructive geometry (union, intersection ...)
-          or from a boundary representation.
-      </p>
-        <p>
-          <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/threed/Vector3D.html">
-          Vector3D</a> provides a simple vector type. One important feature is
-          that instances of this class are guaranteed
+        <p>
+          <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/oned/Vector1D.html">
+          Vector1D</a>, <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/twod/Vector2D.html">
+          Vector2D</a> and <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/threed/Vector3D.html">
+          Vector3D</a> provide simple vector types. One important feature is
+          that instances of these classes are guaranteed
           to be immutable, this greatly simplifies modelling dynamical systems
           with changing states: once a vector has been computed, a reference 
to it
           is known to preserve its state as long as the reference itself is 
preserved.
         </p>
         <p>
           Numerous constructors are available to create vectors. In addition 
to the
-          straightforward cartesian coordinates constructor, a constructor 
using
+          straightforward Cartesian coordinates constructor, a constructor 
using
           azimuthal coordinates can build normalized vectors and linear 
constructors
           from one, two, three or four base vectors are also available. 
Constants have
           been defined for the most commons vectors (plus and minus canonical 
axes,
@@ -86,9 +100,11 @@
           is of course also implemented.
         </p>
         <p>
-          <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/threed/Vector3DFormat.html">
-          Vector3DFormat</a> is a specialized format for formatting output or 
parsing
-          input with text representation of 3D vectors.
+          <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/oned/Vector1DFormat.html">
+          Vector1DFormat</a>, <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/twod/Vector2DFormat.html">
+          Vector2DFormat</a> and <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/threed/Vector3DFormat.html">
+          Vector3DFormat</a> are specialized classes for formatting output or 
parsing
+          input with text representation of vectors.
         </p>
         <p>
           <a 
href="../apidocs/org/apache/commons/math3/geometry/euclidean/threed/Rotation.html">
@@ -163,7 +179,18 @@
           <code>applyInverseTo(Rotation)</code>.
         </p>
       </subsection>
-      <subsection name="11.3 Binary Space Partitioning" href="partitioning">
+      <subsection name="11.3 n-Sphere" href="sphere">
+        <p>
+          The Apache Commons Math library provides a few classes dealing with 
geometry
+          on the 1-sphere (i.e. the one dimensional circle corresponding to 
the boundary of
+          a two-dimensional disc) and the 2-sphere (i.e. the two dimensional 
sphere surface
+          corresponding to the boundary of a three-dimensional ball). The main 
classes in
+          this package corresopnd to the region explained above, i.e.
+          <a 
href="../apidocs/org/apache/commons/math3/geometry/spherical/oned/ArcsSet.html">ArcsSet</a>
+          and <a 
href="../apidocs/org/apache/commons/math3/geometry/spherical/twod/SphericalPolygonsSet.html">SphericalPolygonsSet</a>.
+        </p>
+      </subsection>
+      <subsection name="11.4 Binary Space Partitioning" href="partitioning">
         <p>
           <a 
href="../apidocs/org/apache/commons/math3/geometry/partitioning/BSPTree.html">
           BSP trees</a> are an efficient way to represent space partitions and
@@ -177,12 +204,21 @@
           The main use of such partitions is to use a boolean attribute to
           define an inside/outside property, hence representing arbitrary
           polytopes (line segments in 1D, polygons in 2D and polyhedrons in
-          3D) and to operate on them.
+          3D) and to operate on them. This is how the regions explained above 
in the Euclidean
+          and Sphere spaces are implemented. The partitioning package provides 
the engine to do the
+          computation, but not the dimension-specific implementations. The
+          various interfaces in this package (hyperplane, sub-hyperplane, 
embedding,
+          and even region) are therefore not considered to be reusable public
+          interface, they are private interface. They may change and users are 
not expected to
+          rely directly on them. What users can rely on is the BSP tree class 
itself, and the
+          space-specific implementations of the interfaces (i.e. Plane in 3D 
as the implementation
+          of hyperplane, or S2Point on the 2-Sphere as the implementation of 
Point).
         </p>
 
         <p>
-          Another example would be to represent Voronoi tesselations, the
-          attribute of each cell holding the defining point of the cell.
+          Another example of BST tree use would be to represent Voronoi 
tesselations, the
+          attribute of each cell holding the defining point of the cell. This 
is not
+          available yet.
         </p>
 
         <p>

Modified: commons/proper/math/trunk/src/site/xdoc/userguide/index.xml
URL: 
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/index.xml?rev=1560390&r1=1560389&r2=1560390&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/index.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/index.xml Wed Jan 22 
15:55:03 2014
@@ -117,8 +117,9 @@
         <li><a href="geometry.html">11. Geometry</a>
                 <ul>
                 <li><a href="geometry.html#a11.1_Overview">11.1 
Overview</a></li>
-                <li><a href="geometry.html#a11.2_Vectors">11.2 Vectors</a></li>
-                <li><a href="geometry.html#a11.3_Rotations">11.3 
Rotations</a></li>
+                <li><a href="geometry.html#a11.2_Euclidean_spaces">11.2  
Euclidean spaces</a></li>
+                <li><a href="geometry.html#a11.3_n-Sphere">11.3 
n-Sphere</a></li>
+                <li><a 
href="geometry.html#a11.4_Binary_Space_Partitioning">11.4 Binary Space 
Partitioning</a></li>
                 </ul></li>                                 
         <li><a href="optimization.html">12. Optimization</a>
                 <ul>


Reply via email to