137 lines
7.2 KiB
XML
137 lines
7.2 KiB
XML
<?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/LICENSE-2.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.
|
|
-->
|
|
|
|
<?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 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
|
|
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 a higher level abstraction, more
|
|
user-oriented and hiding 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>does</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 implicitly 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>
|