/usr/share/doc/libstarlink-ast-doc/node62.html is in libstarlink-ast-doc 8.6.2+dfsg-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 | <!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>Example--the PermMap</TITLE>
<META NAME="description" CONTENT="Example--the PermMap">
<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="previous" HREF="node61.html">
<LINK REL="up" HREF="node51.html">
<LINK REL="next" HREF="node63.html">
</HEAD>
<BODY >
<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html1056"
HREF="node63.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="/usr/share/latex2html/icons/next.png"></A>
<A NAME="tex2html1054"
HREF="node51.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="/usr/share/latex2html/icons/up.png"></A>
<A NAME="tex2html1050"
HREF="node61.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="tex2html1057"
HREF="node63.html">Compound Mappings (CmpMaps)</A>
<B> Up:</B> <A NAME="tex2html1055"
HREF="node51.html">Inter-Relating Coordinate Systems (Mappings)</A>
<B> Previous:</B> <A NAME="tex2html1051"
HREF="node61.html">Example the UnitMap</A>
<BR>
<BR></DIV>
<!--End of Navigation Panel-->
<H2><A NAME="SECTION000511000000000000000"></A><A NAME="ss:permmapexample"></A>
<BR>
Example--the PermMap
</H2>
<P>
The PermMapPermMap is a rather more complicated MappingMapping than we have met
previously. Its purpose is to change the order, or number, of
coordinates. It is also able to substitute fixed values for
coordinates.
<P>
To illustrate its action, suppose our input coordinates are denoted by
(<!-- MATH
$x_1,x_2,x_3,x_4$
-->
<SPAN CLASS="MATH"><IMG
WIDTH="93" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
SRC="img79.png"
ALT="$x_1,x_2,x_3,x_4$"></SPAN>) in a 4-dimensional space and suppose our output
coordinates are to be (<!-- MATH
$x_4,x_1,x_2,x_3$
-->
<SPAN CLASS="MATH"><IMG
WIDTH="93" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
SRC="img80.png"
ALT="$x_4,x_1,x_2,x_3$"></SPAN>). Our PermMap, therefore,
should rotate the coordinate values by one position.
<P>
To create such a PermMap, we first set up two integer arrays. One of
these, ``outperm'', controls the selection of input coordinates for
use in the output and the other, ``inperm'', controls selection of
output coordinates for use in the input:
<P>
<SMALL CLASS="SMALL">
<BR>
<IMG
WIDTH="280" HEIGHT="34" ALIGN="BOTTOM" BORDER="0"
SRC="img81.png"
ALT="\begin{terminalv}
int outperm[ 4 ] = { 4, 1, 2, 3 };
int inperm[ 4 ] = { 2, 3, 4, 1 };
\end{terminalv}">
<BR>
</SMALL>
<P>
Note that the numbers we store in these arrays are the indices of the
coordinates that we want to select. We have chosen these so that the
forward and inverse transformations will perform complementary
permutations on the coordinates.
<P>
The PermMap is then created by passing these arrays to its
constructor, as follows:
<P>
<SMALL CLASS="SMALL">
<BR>
<IMG
WIDTH="465" HEIGHT="91" ALIGN="BOTTOM" BORDER="0"
SRC="img82.png"
ALT="\begin{terminalv}
AstPermMap *permmap;
\par
...
\par
permmap = astPermMap( 4, inperm, 4, outperm, NULL, '''' );
\end{terminalv}">
<BR>
</SMALL>
<P>
Note that we specify the number of input and output coordinates
separately, but set both to 4 in this example. The resulting PermMap
would have the following effect when used to transform coordinates:
<P>
<BR>
<IMG
WIDTH="315" HEIGHT="243" ALIGN="BOTTOM" BORDER="0"
SRC="img83.png"
ALT="\begin{terminalv}
Forward:
(1, 2, 3, 4) --> (4, 1, 2, 3)
(2, 4, 6, 8) --> (8, ...
..., 8, 12) --> (4, 8, 12, 16)
(20, 5, 10, 15) --> (5, 10, 15, 20)
\end{terminalv}">
<BR>
<P>
If the number of input and output coordinates are unequal so, also,
will be the size of the ``outperm'' and ``inperm'' arrays. This means,
however, that we cannot fill them with coordinate indices so that they
perform complementary permutations, because one transformation will
lose information (discard a coordinate) that the other cannot recover.
To give an example, consider the following:
<P>
<SMALL CLASS="SMALL">
<BR>
<IMG
WIDTH="281" HEIGHT="52" ALIGN="BOTTOM" BORDER="0"
SRC="img84.png"
ALT="\begin{terminalv}
int outperm[ 3 ] = { 4, 3, 2 };
int inperm[ 4 ] = { -1, 3, 2, 1 };
double con[ 1 ] = { 99.004 };
\end{terminalv}">
<BR>
</SMALL>
<P>
In this case, the forward transformation will change
(<!-- MATH
$x_1,x_2,x_3,x_4$
-->
<SPAN CLASS="MATH"><IMG
WIDTH="93" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
SRC="img79.png"
ALT="$x_1,x_2,x_3,x_4$"></SPAN>) into (<SPAN CLASS="MATH"><IMG
WIDTH="69" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
SRC="img85.png"
ALT="$x_4,x_3,x_2$"></SPAN>) and will discard <SPAN CLASS="MATH"><IMG
WIDTH="21" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
SRC="img86.png"
ALT="$x_1$"></SPAN>. The
inverse transformation restores the original coordinate order, but has
no value to assign to the first coordinate. In this case, the number
entered in the ``inperm'' array is <SPAN CLASS="MATH"><IMG
WIDTH="19" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
SRC="img87.png"
ALT="$-$"></SPAN>1.
<P>
This negative value indicates that the coordinate value should be
obtained by addressing the first element of the ``con'' array
(<SPAN CLASS="textit">i.e.</SPAN> element zero). This array, ignored in the previous
example, may then be used to supply a value for the missing
coordinate.
<P>
The constructor function:
<P>
<SMALL CLASS="SMALL">
<BR>
<IMG
WIDTH="457" HEIGHT="15" ALIGN="BOTTOM" BORDER="0"
SRC="img88.png"
ALT="\begin{terminalv}
permmap = astPermMap( 4, inperm, 3, outperm, con, '''' );
\end{terminalv}">
<BR>
</SMALL>
<P>
will then create a PermMap with the following effect when used to
transform coordinates:
<P>
<BR>
<IMG
WIDTH="332" HEIGHT="243" ALIGN="BOTTOM" BORDER="0"
SRC="img89.png"
ALT="\begin{terminalv}
Forward:
(1, 2, 3, 4) --> (4, 3, 2)
(2, 4, 6, 8) --> (8, 6, ...
...) --> (99.004, 8, 12, 16)
(20, 15, 10) --> (99.004, 10, 15, 20)
\end{terminalv}">
<BR>
<P>
The ``con'' array may contain more than one value if necessary and may
be addressed by both the ``inperm'' and ``outperm'' arrays using
coordinate indices <SPAN CLASS="MATH"><IMG
WIDTH="19" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
SRC="img87.png"
ALT="$-$"></SPAN>1, <SPAN CLASS="MATH"><IMG
WIDTH="19" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
SRC="img87.png"
ALT="$-$"></SPAN>2, <SPAN CLASS="MATH"><IMG
WIDTH="19" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
SRC="img87.png"
ALT="$-$"></SPAN>3, <SPAN CLASS="textit">etc.</SPAN> to refer to the
first, second, third, <SPAN CLASS="textit">etc.</SPAN> elements.
<P>
If there is no suitable replacement value that can be supplied
<SPAN CLASS="textit">via</SPAN> the ``con'' array, a value of zero may be entered into the
``outperm'' and/or ``inperm'' arrays. This causes the value AST__BAD
to be used for the affected coordinate (as defined in the ``ast.h''
header file), thus indicating a missing coordinate value
(§<A HREF="node60.html#ss:badcoordinates">5.9</A>).
<P>
The principle use for a PermMap lies in matching a coordinate system
to a data array where there is a choice of storage order for the data.
PermMaps are also useful for discarding unwanted coordinates so as to
reduce the number of dimensions, such as when selecting a ``slice''
from a multi-dimensional array.
<P>
<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
<A NAME="tex2html1056"
HREF="node63.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="/usr/share/latex2html/icons/next.png"></A>
<A NAME="tex2html1054"
HREF="node51.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="/usr/share/latex2html/icons/up.png"></A>
<A NAME="tex2html1050"
HREF="node61.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="tex2html1057"
HREF="node63.html">Compound Mappings (CmpMaps)</A>
<B> Up:</B> <A NAME="tex2html1055"
HREF="node51.html">Inter-Relating Coordinate Systems (Mappings)</A>
<B> Previous:</B> <A NAME="tex2html1051"
HREF="node61.html">Example the UnitMap</A></DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
|