/usr/share/doc/libstarlink-ast-doc/node82.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<!--Converted with LaTeX2HTML 2008 (1.71)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Calculating Distances, Angles and Offsets</TITLE>
<META NAME="description" CONTENT="Calculating Distances, Angles and Offsets">
<META NAME="keywords" CONTENT="sun211">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">

<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="sun211.css">

<LINK REL="next" HREF="node83.html">
<LINK REL="previous" HREF="node81.html">
<LINK REL="up" HREF="node71.html">
<LINK REL="next" HREF="node83.html">
</HEAD>

<BODY >

<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html1277"
  HREF="node83.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="/usr/share/latex2html/icons/next.png"></A> 
<A NAME="tex2html1275"
  HREF="node71.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="/usr/share/latex2html/icons/up.png"></A> 
<A NAME="tex2html1269"
  HREF="node81.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="/usr/share/latex2html/icons/prev.png"></A>   
<BR>
<B> Next:</B> <A NAME="tex2html1278"
  HREF="node83.html">The Domain Attribute</A>
<B> Up:</B> <A NAME="tex2html1276"
  HREF="node71.html">Representing Coordinate Systems (Frames)</A>
<B> Previous:</B> <A NAME="tex2html1270"
  HREF="node81.html">Selecting Frame Axes</A>
<BR>
<BR></DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION000711000000000000000"></A><A NAME="ss:distanceandoffset"></A>
<BR>
Calculating Distances, Angles and Offsets
</H2>
Some complementary
functions
are provided for use with Frames to allow you to perform geometric
operations without needing to know the nature of the coordinate system
represented by the FrameFrame.

<P>
Functions
can be used to find the distance between two points, and to offset a
specified distance along a line joining two points, <SPAN  CLASS="textit">etc.</SPAN> In essence,
these define the metric of the coordinate space which the Frame represents. In
the case of a basic Frame, this is a Cartesian metric.

<P>
The first of these functions, astDistanceastDistance, returns a double distance
value when supplied with the Frame coordinates of two points. For
example:

<P>
<SMALL CLASS="SMALL">
<BR>
<IMG
 WIDTH="365" HEIGHT="129" ALIGN="BOTTOM" BORDER="0"
 SRC="img121.png"
 ALT="\begin{terminalv}
double dist;
double point1[ 2 ] = { 0.0, 0.0 };
double point2[...
....0 };
\par
...
\par
dist = astDistance( frame, point1, point2 );
\end{terminalv}">
<BR>
</SMALL>
<P>
This calculates the distance between the origin (0,0) and a point at
position (1,1). In this case, the result, as you would expect, is
<SPAN CLASS="MATH"><IMG
 WIDTH="29" HEIGHT="35" ALIGN="MIDDLE" BORDER="0"
 SRC="img122.png"
 ALT="$\surd{2}$"></SPAN>. However, this is only true for the Cartesian coordinate
system which a basic Frame represents. In general, astDistance will
calculate the geodesic distance between the two points, so that with a
more specialised Frame (such as a SkyFrameSkyFrame, representing the celestial
sphere) a great-circle distance might be returned.

<P>
The astOffsetastOffset function is really the inverse of astDistance. Given two
points in a Frame, it calculates the coordinates of a third point
which is offset a specified distance away from the first point along
the geodesic joining it to the second one. For example:

<P>
<SMALL CLASS="SMALL">
<BR>
<IMG
 WIDTH="398" HEIGHT="129" ALIGN="BOTTOM" BORDER="0"
 SRC="img123.png"
 ALT="\begin{terminalv}
double point1[ 2 ] = { 0.0, 0.0 };
double point2[ 2 ] = { 1.0,...
...;
\par
...
\par
astOffset( frame, point1. point2, 0.5, point3 );
\end{terminalv}">
<BR>
</SMALL>
<P>
This would fill the ``point3'' array with the coordinates of a point
which is offset 0.5 units away from the origin (0,0) in the direction
of the position (1,1). Again, this is a simple result in a Cartesian
Frame, as varying the offset will trace out a straight line. On the
celestial sphere, however (<SPAN  CLASS="textit">e.g.</SPAN> using a SkyFrame), it would
trace out a great circle.

<P>
The functions astAxDistanceastAxDistance and astAxOffsetastAxOffset are similar to astDistance
and astOffset, except that the curves which they use as ``straight
lines'' are not geodesics, but curves parallel to a specified axis<A NAME="tex2html30"
  HREF="footnode.html#foot1563"><SUP><IMG  ALIGN="BOTTOM" BORDER="1" ALT="[*]"
 SRC="/usr/share/latex2html/icons/footnote.png"></SUP></A>. One
reason for using these functions is to deal with the cyclic ambiguity of
longitude and latitude axes.

<P>
The astOffset2astOffset2 function is similar to astOffset, but instead of using the
geodesic which passes through two positions, it uses the geodesic which
passes at a given position angle through the starting position.

<P>
Position angles are always measured from the positive direction of the
second Frame axis to the required line, with positive angles being in the
same sense as rotation from the positive direction of the second axis to
the positive direction of the first Frame axis. This definition applies
to all classes of Frame, including SkyFrame. The default ordering of axes
in a SkyFrame makes the second axis equivalent to north, and so the
definition of position angle given above corresponds to the normal
astronomical usage, ``from north, through east''. However, it should be
remembered that it is possible to permute the axes of a SkyFrame (or
indeed any Frame), so that north becomes axis 1. In this case, an AST
``position angle'' would be the angle ``from east, through north''.
Always take the axis ordering into account when deriving an astronomical
position angle from an AST position angle.

<P>
Within a Cartesian coordinate system, the position angle of a geodesic
(<SPAN  CLASS="textit">i.e.</SPAN> a straight line) is constant along its entire length, but
this is not necessarily true of other coordinate systems. Within a
spherical coordinate system, for instance, the position angle of a geodesic
will vary along its length (except for the special cases of a meridian and
the equator). In addition to returning the required offset position, the
astOffset2 function
returns the position angle of the geodesic at the
offset position. This is useful if you want to trace out a path which
involves turning through specified angles. For instance, tracing out a
rectangle in which each side is a geodesic involves turning through 90
degrees at the corners. To do this, use astOffset2 to calculate the
position of each corner, and then add (or subtract) 90 degrees from the
position angle returned by astOffset2.

<P>
The astAngleastAngle function
calculates the angle subtended by two points, at a third point.
If used with a 2-dimensional Frame the returned angle
is signed to indicate the sense of rotation (clockwise or anti-clockwise)
in taking the ``shortest route'' from the first point to the second.
If the Frame has more than 2 axes, the result is un-signed and is always
in the range zero to <SPAN CLASS="MATH"><IMG
 WIDTH="18" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
 SRC="img124.png"
 ALT="$\pi$"></SPAN>.

<P>
The astAxAngleastAxAngle function is similar to astAngle,
but the ``reference direction'', from which angles are measured, is
a specified axis.

<P>
The astResolveastResolve function
resolves a given displacement within a Frame into two components, parallel and
perpendicular to a given reference direction.

<P>
The displacement is specified by two positions within the Frame; the
starting and ending positions. The reference direction is defined by the
geodesic curve passing through the starting position and a third specified
position. The lengths of the two components are returned, together with
the position on the reference geodesic which is closest to the third
supplied point.

<P>

<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
<A NAME="tex2html1277"
  HREF="node83.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="/usr/share/latex2html/icons/next.png"></A> 
<A NAME="tex2html1275"
  HREF="node71.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="/usr/share/latex2html/icons/up.png"></A> 
<A NAME="tex2html1269"
  HREF="node81.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="/usr/share/latex2html/icons/prev.png"></A>   
<BR>
<B> Next:</B> <A NAME="tex2html1278"
  HREF="node83.html">The Domain Attribute</A>
<B> Up:</B> <A NAME="tex2html1276"
  HREF="node71.html">Representing Coordinate Systems (Frames)</A>
<B> Previous:</B> <A NAME="tex2html1270"
  HREF="node81.html">Selecting Frame Axes</A></DIV>
<!--End of Navigation Panel-->

</BODY>
</HTML>
libstarlink-ast-doc 8.6.2+dfsg-2 / usr / share / doc / libstarlink-ast-doc / node82.html
