geometry-doc.sgml

机器人开源项目orocos的源代码

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
	"docbook/dtd/4.1/docbook.dtd" [
<!ENTITY orocos "<acronym>Orocos</acronym>">
]>

<article>

<articleinfo>
  <title>
    Geometry: primitives, database and engine
  </title>
  <author>
    <firstname>Herman</firstname>
    <surname>Bruyninckx</surname>
    <affiliation>
      <address>
        [e-mail]
      </address>
    </affiliation>
  </author>
 <copyright>
  <year>2003</year>
  <holder>Herman Bruyninckx &mdash;
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU General Public License
(<ulink
 url="http://www.fsf.org/copyleft/gpl.html">http://www.fsf.org/copyleft/gpl.html</ulink>), 
where the <emphasis>source code</emphasis> of the document is the 
<ulink url="geometry-doc.xml">XML file</ulink>.
</holder>
 </copyright>


 <abstract>
 <para>
 <emphasis role="strong">Abstract</emphasis>
 </para>
 <para>
This document presents the class hierarchy design for the 
<emphasis role="strong">primitive geometric objects</emphasis> that
are needed in robotics, machine tool control, computer animation and
games: points, frames,
lines, &hellip; It also describes how to represent a <emphasis
role="strong">geometric database</emphasis>, <emphasis>i.e.</emphasis>
the interconnection information between a set of geometric primitives.
The geometric database of an application is constantly updated and
queried on-line, and all this functionality is called a
<emphasis role="strong">geometric engine</emphasis>.
 </para>
 </abstract>

 <revhistory>
  <revision>
    <revnumber>0.01</revnumber>
    <date>July 13, 2003</date>
    <authorinitials>HB</authorinitials>
	 <revremark>
Started this document by extracting the section on geometric classes
from the documentation on kinematics and dynamics.  Added more
extensive discussion about generic (conceptual and concrete) APIs and
representations.
    </revremark> 
  </revision>
  <revision>
    <revnumber>0.02</revnumber>
    <date>August 11, 2003</date>
    <authorinitials>HB</authorinitials>
	 <revremark>
Removed the RigidBody class, because it is not a purely geometric
thing. Small additions and corrections to all other sections.
    </revremark> 
  </revision>
  <revision>
    <revnumber>0.03</revnumber>
    <date>November 1, 2003</date>
    <authorinitials>HB</authorinitials>
	 <revremark>
Added polyhedron, mesh, geometric database and engine.
    </revremark> 
  </revision>
  <revision>
    <revnumber>0.04</revnumber>
    <date>November 18, 2003</date>
    <authorinitials>HB</authorinitials>
	 <revremark>
Added physical methods. Added motion, position and orientation methods
for frames.
    </revremark> 
  </revision>
  <revision>
    <revnumber>0.05</revnumber>
    <date>January 4, 2004</date>
    <authorinitials>HB</authorinitials>
	 <revremark>
Overall overhaul of the text. More concrete class descriptions.
Clarified relationships between geometric class, symbolic class, and
physical property. Added Displacement.
    </revremark> 
  </revision>
 </revhistory>

</articleinfo>

<section id="overview">
<title> Introduction </title>
<para>
This document describes the classes for the 
<emphasis role="strong">
 <link linkend="geometric-classes">basic geometric primitives</link>
</emphasis>
that are relevant to robotics, machine tools and computer animation:
<link linkend="point">points</link>, 
<link linkend="vector">vectors</link>, 
<link linkend="line">lines</link>,
<link linkend="plane">planes</link>, 
<link linkend="polyhedron">polyhedrons</link>, 
<link linkend="mesh">meshes</link>, 
<link linkend="screw">screws</link>, 
<link linkend="orientation">orientations</link>, 
and
<link linkend="frame">frames</link>.
In general, all these primitives exist in
<emphasis role="strong">linear</emphasis> (&ldquo;1D&rdquo;),
<emphasis role="strong">planar</emphasis> (&ldquo;2D&rdquo;), and
<emphasis role="strong">spatial</emphasis> (&ldquo;3D&rdquo;)
versions.
</para>
<note>
<para>
The goal of this document is to describe the design of a set of
<emphasis>small libraries</emphasis>, which can be combined together to
model not only the most complex systems, but from which application
developers can also choose only the subset that offers them the most
efficient solution for their particular goals.
</para>
<para>
The design keeps in mind that the same library
<emphasis role="strong">interfaces</emphasis> can be used for
&ldquo;all&rdquo; possible robot and machine tool devices. Hence, much
attention is paid to find the most appropriate 
<ulink url="decoupling.html">decoupling</ulink> between the
required functionalities, and the best trade-off between generality
and complexity of the interfaces.
</para>
</note>
<para>
Many <emphasis>implementations</emphasis> for all geometric primitives
exist already.  But almost invariably, the implementations only cover
<emphasis>mathematical (<emphasis>i.e.</emphasis> coordinate)
representations</emphasis>, and much less explicitly
<link linkend="symbolic-class">symbolic</link> or 
<link linkend="physical-properties">physical</link> properties. Adding
the latter types of information incurs some storage overhead, but it
is mandatory in <emphasis>complex</emphasis> systems: these need more
functionality than just fast calculation of always the same hard-coded
algorithms, and they must integrate software components from different
sources so they must be able to check on line their compatibility and
the correctness of service calls.
</para>
<para>
In real-world applications, geometric objects do often not exist
just on their own, but form
<emphasis role="strong">interconnected sets</emphasis>, such as
robots; the real world is also <emphasis
role="strong">dynamic</emphasis>, in the sense that objects come and
go, they move with respect to each other, and the user is interested
in new relationships between geometric objects, in different
representations, or in new substructures of the database.  So, the
representation of these time-varying interconnections requires a
<emphasis role="strong">
 <link linkend="geometric-database">geometric database</link>
</emphasis> instead of a simple static data structure. The database
keeps track of where every geometric feature
(<emphasis>i.e.</emphasis> (a part of) a geometric primitive) in the
world is located, how motions of one object influence the relative
locations of all other geometric features, and which
<link linkend="geometric-classes">geometric</link>,
<link linkend="symbolic-class">symbolic</link> and/or
<link linkend="physical-properties">physical</link> properties are
linked to each other. So, different applications can use a different
number of objects to represent the same robot or machine tool: one
application can prefer to use more symbolic information, while another
application needs multiple shapes to visualize the same geometric
primitive.
</para>
<para>
The geometric database must faithfully represent the
<emphasis>dynamic</emphasis> nature of the world, so it needs a
<emphasis>programming interface</emphasis>.
The database and its programming interface are called a
<emphasis role="strong">geometric engine</emphasis>.
</para>
<para>
This text describes the basic geometric classes in more
detail. These descriptions are not complete, for example, the
following methods are not described explicitly:
<itemizedlist>

<listitem>
<para>
Constructors and destructors.
</para>
</listitem>

<listitem>
<para>
<function>Set_&hellip;()</function> and
<function>Get_&hellip;()</function> methods, to write or read all the
data stored in one object of a particular class.
</para>
</listitem>

<listitem>
<para>
&ldquo;Factory&rdquo; methods to construct complex geometric
objects by interconnection, or by &ldquo;derivation&rdquo;
(<emphasis>e.g.</emphasis>
<function>perpendicularLineToPlane()</function>, etc.).
</para>
</listitem>

<listitem>
<para>
&ldquo;Analysis&rdquo; methods to investigate existing geometric
constructions; <emphasis>e.g.</emphasis>
<function>isPartOf()</function> returns a Boolean value indicating
whether a given geometric object is a part of another object.
</para>
</listitem>

</itemizedlist>
</para>
<note>
<para>
Developers of geometric libraries or framework can decide to implement
only parts of all the presented classes; they also have many choices
for the implementation of the geometric engine; for example, not all
<link linkend="symbolic-port">Ports</link> are needed in all
applications.
</para>
</note>

</section>


<section id="symbolic-class">
<title>Symbolic class</title>
<para>
All geometric classes have some symbolic properties in common. These
are assembled in a <emphasis>symbolic class</emphasis> with the
following <emphasis>data structures</emphasis>:
<variablelist>
 <varlistentry>
 <term>
  <anchor id="symbolic-name">
  <parameter>name</parameter>:
 </term>
  <listitem>
  <para>
A symbolic description (<emphasis>e.g.</emphasis> a string) that
serves as a unique identifier of an object instantiation of the class.
Such a <parameter>name</parameter> is certainly needed in distributed
software systems; in a centralized system, the software components can
get direct access to the binary objects, but there is also a need to
describe objects by their symbolic name, <emphasis>e.g.</emphasis> in
a graphical user interface, or a scripting program.
  </para>
  <para>
Giving unique names is very difficult, especially in dynamic systems
where one doesn't know in advance how many objects will exist.
Therefore, the symbolic names are often only to be interpreted in a
specific context, or <emphasis role="strong">name space</emphasis>.
For example, a kinematic structure of a robot contains a line for each
joint, and the name of that line should only be unique in the context
of that robot.
  </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="symbolic-dimension">
  <parameter>dimension</parameter>:
 </term>
  <listitem>
  <para>
<parameter>1D</parameter>, <parameter>2D</parameter>, or
<parameter>3D</parameter>. It indicates whether the object lives on a
line, in a plane or in the space.
  </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="symbolic-port">
  <anchor id="geometric-port">
  <parameter>geometricPorts</parameter>:
 </term>
  <listitem>
  <para>
This is a <emphasis>list</emphasis> of 
<ulink url="decoupling.html#INTER-CONNECTION-DECOUPLING">Ports</ulink>:
each geometric object can be
<emphasis role="strong">connected</emphasis> to various other
geometric objects, and a <parameter>geometricPort</parameter> is the
place that allows for this interconnection between geometric objects.
For example, a <link linkend="point">point</link>
can be defined as the intersection of two
<link linkend="line">lines</link> (and hence is interconnected with
both lines), or belong to a
plane, a frame or a surface.
(<ulink url="general-dynamics-doc.html">Another document</ulink>
has a more detailed description of complex interconnected systems.)
Therefore, most of the objects described in this document have
<ulink url="decoupling.html#INTER-CONNECTION-DECOUPLING">Ports</ulink>
of various types.
  </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="symbolic-coordinates">
  <parameter>coordinatePorts</parameter>:
 </term>
  <listitem>
  <para>
Another list of
<ulink url="decoupling.html#INTER-CONNECTION-DECOUPLING">Ports</ulink>,
each with a different mathematical representation of the object. So, this
list doesn't directly give numerical values, but objects that contain
the symbolic information about one particular mathematical
representation: the <emphasis role="strong">type</emphasis> of the
coordinates; the
<emphasis role="strong">reference <link linkend="frame">frame</link></emphasis>
with respect to which the coordinates are expressed (this is nothing
else than the Port connection to the geometric object that encodes the
frame!), and the
<emphasis role="strong">physical units</emphasis> of the coordinates.
  </para>
  <para>
(IDEA: The Object connected to the Port has a type that encodes the physical
units and the type of the coordinates? And the Connector contains the
numerical values?)
  </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="symbolic-visualisation">
  <parameter>visualisationPorts</parameter>:
 </term>
  <listitem>
  <para>
very often, the geometric objects are visualised in one way or
another. This list of 
<ulink url="decoupling.html#INTER-CONNECTION-DECOUPLING">Ports</ulink>
gives access to the various visualisation objects of this
geometric object.
  </para>
  </listitem>
 </varlistentry>

</variablelist>
The Ports are the mechanism <emphasis>to interconnect</emphasis>
objects in a
<link linkend="geometric-database">geometric database</link>.
However, a Port is more than just a pointer to a database table: it is
part of the
<ulink url="decoupling.html#INTER-CONNECTION-DECOUPLING">Object-Port-Connector</ulink>
software pattern, that brings some added value over bare pointers.
</para>
<para>
Each Port has a specific <emphasis>type</emphasis>, such that it can
be made impossible to connect Ports of different types.  A symbolic
object also has <function>Set_&hellip;()</function> and
<function>Get_&hellip;()</function> <emphasis>methods</emphasis> for
each of the above-mentioned <emphasis>data structures</emphasis>.
<anchor id="symbolic-iterate-ports">
A <parameter>Ports</parameter> class has methods to get to
its components; <emphasis>e.g.</emphasis> the
<parameter>iteratePorts</parameter> method call returns the object