Author: luc
Date: Tue Mar 13 13:02:28 2007
New Revision: 517837
URL: http://svn.apache.org/viewvc?view=rev&rev=517837
Log:
added a section for the geometry package in the user guide
Added:
jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml (with props)
Added: jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml?view=auto&rev=517837
==============================================================================
 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
+
+ http://www.apache.org/licenses/LICENSE2.0
+
+ 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.
+ >
+
+<?xmlstylesheet type="text/xsl" href="./xdoc.xsl"?>
+<! $Revision: 480435 $ $Date: 20061129 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
+ useroriented 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.0e10).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>
to
+ <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>
+</document>
Propchange: jakarta/commons/proper/math/trunk/xdocs/userguide/geometry.xml

svn:eolstyle = native

To unsubscribe, email: commonsdevunsubscribe@jakarta.apache.org
For additional commands, email: commonsdevhelp@jakarta.apache.org
