commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From l..@apache.org
Subject svn commit: r1560390 - in /commons/proper/math/trunk/src/site/xdoc/userguide: geometry.xml index.xml
Date Wed, 22 Jan 2014 15:55:04 GMT
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>



Mime
View raw message