/usr/share/doc/libstarlink-ast-doc/node185.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>Writing a Transformation Function</TITLE>
<META NAME="description" CONTENT="Writing a Transformation Function">
<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="node186.html">
<LINK REL="previous" HREF="node184.html">
<LINK REL="up" HREF="node181.html">
<LINK REL="next" HREF="node186.html">
</HEAD>

<BODY >

<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html2376"
  HREF="node186.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="/usr/share/latex2html/icons/next.png"></A> 
<A NAME="tex2html2374"
  HREF="node181.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="/usr/share/latex2html/icons/up.png"></A> 
<A NAME="tex2html2368"
  HREF="node184.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="tex2html2377"
  HREF="node186.html">Registering a Transformation Function</A>
<B> Up:</B> <A NAME="tex2html2375"
  HREF="node181.html">Creating Your Own Private</A>
<B> Previous:</B> <A NAME="tex2html2369"
  HREF="node184.html">Limitations of IntraMaps</A>
<BR>
<BR></DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION000204000000000000000"></A><A NAME="ss:transformationfunctions"></A>
<BR>
Writing a Transformation Function
</H2>

<P>
The first stage in creating an IntraMapIntraMap is to write the coordinate
transformation function. This should have a calling interface like the
astTranPastTranP function provided by AST (<SPAN  CLASS="textit">q.v.</SPAN>). Here is a simple
example of a suitable transformation function which transforms
coordinates by squaring them:
SqrTran

<P>
<SMALL CLASS="SMALL">
<BR>
<IMG
 WIDTH="640" HEIGHT="547" ALIGN="BOTTOM" BORDER="0"
 SRC="img279.png"
 ALT="\begin{terminalv}
...">
<BR>
</SMALL>
<P>
As you can see, the function comes in two halves which implement the
forward and inverse coordinate transformations. The number of points
to be transformed (``npoint'') and the numbers of input and output
coordinates per point (``ncoord_in'' and ``ncoord_out''--in this
case both are assumed equal) are passed to the function. A pair of
loops then accesses all the coordinate values.  Note that it is
legitimate to omit one or other of the forward/inverse transformations
and simply not to implement it, if it will not be required. It is also
permissible to require that the numbers of input and output
coordinates be fixed (<SPAN  CLASS="textit">e.g.</SPAN> at 2), or to write the function so
that it can handle arbitrary dimensionality, as here.

<P>
Before using an incoming coordinate, the function must first check
that it is not set to the value AST__BAD, which indicates missing
data (&#167;<A HREF="node60.html#ss:badcoordinates">5.9</A>). If it is, the same value is also
assigned to any affected output coordinates. The value AST__BAD is
also generated if any coordinates cannot be transformed. In this
example, this can happen with the inverse transformation if negative
values are encountered, so that the square root cannot be taken.

<P>
There are very few restrictions on what a coordinate transformation
function may do. For example, it may freely perform I/O to access any
external data needed, it may invoke other AST facilities (but beware
of unwanted recursion), <SPAN  CLASS="textit">etc.</SPAN> Typically, you may also want to
pass information to it <SPAN  CLASS="textit">via</SPAN> global variables. Remember,
however, that whatever facilities the transformation function requires
must be available in every program which uses it.

<P>
Generally, it is not a good idea to retain context information within
a transformation function. That is, it should transform each set of
coordinates as a single point and retain no memory of the points it
has transformed before. This is in order to conform with the AST model
of a MappingMapping.

<P>
If an error occurs within a transformation function, it should use the
astSetStatusastSetStatus function (&#167;<A HREF="node49.html#ss:errordetection">4.15</A>) to set the AST
status to an error value before returning. This will alert AST to the
error, causing it to abort the current operation. The error value
AST__ITFER is available for this purpose, but other values may also
be used (<SPAN  CLASS="textit">e.g.</SPAN> if you wish to distinguish different types of
error).

<P>

<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
<A NAME="tex2html2376"
  HREF="node186.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="/usr/share/latex2html/icons/next.png"></A> 
<A NAME="tex2html2374"
  HREF="node181.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="/usr/share/latex2html/icons/up.png"></A> 
<A NAME="tex2html2368"
  HREF="node184.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="tex2html2377"
  HREF="node186.html">Registering a Transformation Function</A>
<B> Up:</B> <A NAME="tex2html2375"
  HREF="node181.html">Creating Your Own Private</A>
<B> Previous:</B> <A NAME="tex2html2369"
  HREF="node184.html">Limitations of IntraMaps</A></DIV>
<!--End of Navigation Panel-->

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