Commons Math example source code file (geometry.xml)
The Commons Math geometry.xml source code<?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: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $ -->
<document url="geometry.html">
<properties>
<title>The Commons Math User Guide - Geometry
</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 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,
null vector, and special vectors with infinite or NaN coordinates).
</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>
<p>
<a href="../apidocs/org/apache/commons/math/geometry/Vector3DFormat.html">
org.apache.commons.math.geometry.Vector3DFormat</a> is a specialized format
for formatting output or parsing input with text representation of 3D vectors.
</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
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);
<p>
Focus is oriented on what a rotation <em>does rather than on its
underlying representation. Once it has been built, and regardless of
its internal representation, a rotation is an <em>operator 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 a 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 or
<code>computeTransformedDirection. It provides simpler and more
generic methods: <code>applyTo(Vector3D) and
<code>applyInverseTo(Vector3D).
</p>
<p>
Since a rotation is basically a vectorial operator, several
rotations can be composed together and the composite operation
<code>r = r1 o r2 (which means that for each
vector <code>u,
Other Commons Math examples (source code examples)Here is a short list of links related to this Commons Math geometry.xml source code file: |
The search page
Other Commons Math source code examples at this package level
Click here to learn more about this project
