commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r517837 - /jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml
Date Tue, 13 Mar 2007 20:02:29 GMT
Author: luc
Date: Tue Mar 13 13:02:28 2007
New Revision: 517837

added a section for the geometry package in the user guide

    jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml   (with props)

Added: jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml
--- jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml (added)
+++ jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml Tue Mar 13 13:02:28 2007
@@ -0,0 +1,136 @@
+<?xml version="1.0"?>
+   Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+  -->
+<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
+<!-- $Revision: 480435 $ $Date: 2006-11-29 08:06:35 +0100 (mer., 29 nov. 2006) $ -->
+<document url="geometry.html">
+  <properties>
+    <title>The Commons Math User Guide - Geometry</title>
+  </properties>
+  <body>
+    <section name="11 Geometry">
+      <subsection name="11.1 Overview" href="overview">
+        <p>
+           The geometry package provides classes useful for many physical simulations
+           in the real 3D space, namely vectors and rotations.
+        </p>
+      </subsection>
+      <subsection name="11.2 Vectors" href="vectors">
+        <p>
+          <a href="../apidocs/org/apache/commons/math/geometry/Vector3D.html">
+          org.apache.commons.math.geometry.Vector3D</a> provides a simple vector
+          type. One important feature is that instances of this class are guaranteed
+          to be immutable, this greatly simplifies modelization of 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
+          azimuthal coodinates 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 and
+          null vector).
+        </p>
+        <p>
+          The generic vectorial space operations are available including dot product,
+          normalization, orthogonal vector finding and angular separation computation
+          which have a specific meaning in 3D. The 3D geometry specific cross product
+          is of course also implemented.
+        </p>
+      </subsection>
+      <subsection name="11.3 Rotations" href="rotations">
+        <p>
+          <a href="../apidocs/org/apache/commons/math/geometry/Rotation.html">
+          org.apache.commons.math.geometry.Rotation</a> represents 3D rotations.
+          Rotation instances are also immutable objects, as Vector3D instances.
+        </p>
+        <p>
+          Rotations can be represented by several different mathematical
+          entities (matrices, axe and angle, Cardan or Euler angles,
+          quaternions). This class presents an higher level abstraction, more
+          user-oriented and hiding this implementation details. Well, for the
+          curious, we use quaternions for the internal representation. The user
+          can build a rotation from any of these representations, and any of
+          these representations can be retrieved from a <code>Rotation</code>
+          instance (see the various constructors and getters). In addition, a
+          rotation can also be built implicitely from a set of vectors and their
+          image.
+        </p>
+        <p>
+          This implies that this class can be used to convert from one
+          representation to another one. For example, converting a rotation
+          matrix into a set of Cardan angles can be done using the
+          following single line of code:
+        </p>
+        <source>double[] angles = new Rotation(matrix, 1.0e-10).getAngles(RotationOrder.XYZ);</source>
+        <p>
+          Focus is oriented on what a rotation <em>do</em> rather than on its
+          underlying representation. Once it has been built, and regardless of
+          its internal representation, a rotation is an <em>operator</em> which
+          basically transforms three dimensional vectors into other three
+          dimensional vectors. Depending on the application, the meaning of
+          these vectors may vary as well as the semantics of the rotation.
+        </p>
+        <p>
+          For example in an spacecraft attitude simulation tool, users will
+          often consider the vectors are fixed (say the Earth direction for
+          example) and the rotation transforms the coordinates coordinates of
+          this vector in inertial frame into the coordinates of the same vector
+          in satellite frame. In this case, the rotation implicitely defines the
+          relation between the two frames (we have fixed vectors and moving frame).
+          Another example could be a telescope control application, where the
+          rotation would transform the sighting direction at rest into the desired
+          observing direction when the telescope is pointed towards an object of
+          interest. In this case the rotation transforms the direction at rest in
+          a topocentric frame into the sighting direction in the same topocentric
+          frame (we have moving vectors in fixed frame). In many case, both
+          approaches will be combined, in our telescope example, we will probably
+          also need to transform the observing direction in the topocentric frame
+          into the observing direction in inertial frame taking into account the
+          observatory location and the Earth rotation.
+        </p>
+        <p>
+          These examples show that a rotation means what the user wants it to
+          mean, so this class does not push the user towards one specific
+          definition and hence does not provide methods like
+          <code>projectVectorIntoDestinationFrame</code> or
+          <code>computeTransformedDirection</code>. It provides simpler and more
+          generic methods: <code>applyTo(Vector3D)</code> and
+          <code>applyInverseTo(Vector3D)</code>.
+        </p>
+        <p>
+          Since a rotation is basically a vectorial operator, several
+          rotations can be composed together and the composite operation
+          <code>r = r<sub>1</sub> o r<sub>2</sub></code>
(which means that for each
+          vector <code>u</code>, <code>r(u) = r<sub>1</sub>(r<sub>2</sub>(u))</code>)
+          is also a rotation. Hence we can consider that in addition to vectors, a
+          rotation can be applied to other rotations as well (or to itself). With our
+          previous notations, we would say we can apply <code>r<sub>1</sub></code>
+          <code>r<sub>2</sub></code> and the result we get is <code>r
+          r<sub>1</sub> o r<sub>2</sub></code>. For this purpose,
the class
+          provides the methods: <code>applyTo(Rotation)</code> and
+          <code>applyInverseTo(Rotation)</code>.
+        </p>
+      </subsection>
+     </section>
+  </body>

Propchange: jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml
    svn:eol-style = native

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message