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
|
.help transform Sep87 noao.twodspec.longslit
.ih
NAME
transform -- Transform longslit images to user coordinates
.ih
USAGE
transform input output fitnames
.ih
PARAMETERS
.ls input
List of input images to be transformed.
.le
.ls output
List of output images. The number of output images in the list must
match the number of input images.
.le
.ls minput = ""
List of input masks or references. This mask is used to create an output
mask and is currently not used in the calculation of the output pixel
values. The list may be empty, a single element to apply to all input
images, or a list that matches the input list. A element in the list
may be "BPM" to use the mask referenced by the standard bad pixel mask
keyword "BPM", "!<keyword>" to use another header keyword pointing to a
mask, or a mask filename. The mask file is typically a pixel list file
but it may also be an image. The mask values are interpreted as zero and
greater than zero with the actual values ignored. The mask is assumed to
be registered with the input and no coordinate system matching is used.
The mask maybe smaller or larger than the input image with non-overlapping
pixels ignored and missing pixels assumed to be zero valued. The mask
.le
.ls moutput = ""
List of output masks to be created. The list may be empty or must match
the input list. Output masks may be specified even if no input mask is
specified, in which case the output mask will identify pixels which map
to regions outside the input images (also see the \fIblank\fR parameter).
If an explicit extension is not specified a FITS mask is extension is
created unless the environment variable "masktype" is set to "pl".
.le
.ls fitnames
Names of the user coordinate maps in the database to be used in the transform.
If no names are specified, using the null string "", the world coordinate
system (WCS) of the image is used. This latter case may be used to
resample previously WCS calibrated images to a different linear range
or sampling.
.le
.ls database = "database"
Database containing the coordinate map to be used in transforming the images.
.le
.ls interptype = "spline3"
Image interpolation type. The allowed types are "nearest" (nearest neighbor),
"linear" (bilinear), "poly3" (bicubic polynomial), "poly5" (biquintic
polynomial), and "spline3" (bicubic polynomial).
.le
.ls flux = yes
Conserve flux per pixel? If "no" then each output pixel is simply interpolated
from the input image. If "yes" the interpolated output pixel value is
multiplied by the Jacobean of the transformation (essentially the ratio of
pixel areas between the output and input images).
.le
.ls x1 = INDEF, y1 = INDEF
User coordinates of the first output column and line. If INDEF then the
smallest value corresponding to a pixel from the image used to create the
coordinate map is used. These values are in user units regardless of whether
logarithmic intervals are specified or not.
.le
.ls x2 = INDEF, y2 = INDEF
User coordinates of the last output column and line. If INDEF then the
largest value corresponding to a pixel from the image used to create the
coordinate map is used. These values are in user units regardless of whether
logarithmic intervals are specified or not.
.le
.ls dx = INDEF, dy = INDEF
Output pixel intervals. If INDEF then the interval is set to yield the
specified number of pixels. Note that for logarithmic intervals the
interval must be specified as a base 10 logarithm (base 10) and not in
user units.
.le
.ls nx = INDEF, ny = INDEF
Number of output pixels. If INDEF and if the pixel interval is also INDEF then
the number of output pixels is equal to the number of input pixels.
.le
.ls xlog = no, ylog = no
Convert to logarithmic intervals? If "yes" the output pixel intervals
are logarithmic.
.le
.ls blank = INDEF
Value to put in the output transformed image when it transforms to regions
outside the input image. The special value INDEF will use the nearest
input pixel which is the behavior before the addition of this parameter.
Using special blank values allows other software to identify such out
of input pixels. See also the \fImoutput\fR parameter to identify
out of input pixels in pixel masks.
.le
.ls logfiles = "STDOUT,logfile"
List of files in which to keep a log. If null, "", then no log is kept.
.le
.ih
DESCRIPTION
The coordinate maps U(X,Y) and V(X,Y), created by the task \fBfitcoords\fR,
are read from the specified database coordinate fits or from the
world coordinate system (WCS) of the image. X and Y are the original
untransformed pixel coordinates and U and V are the desired output user or
world coordinates (i.e. slit position and wavelength). If a coordinate map
for only one of the user coordinates is given then a one-to-one mapping
is assumed for the other such that U=X or V=Y. The coordinate maps are
inverted to obtain X(U,V) and Y(U,V) on an even subsampled grid of U and
V over the desired output image coordinates. The X and Y at each output
U and V used to interpolate from the input image are found by linear
interpolation over this grid. X(U,V) and Y(U,V) are not determined at
every output point because this is quite slow and is not necessary since
the coordinate surfaces are relatively slowly varying over the subsampling
(every 10th output point).
The type of image interpolation is
selected by the user. Note that the more accurate the interpolator the
longer the transformation time required. The parameter \fIflux\fR selects
between direct image interpolation and a flux conserving interpolation.
Flux conservation consists of multiplying the interpolated pixel value by
the Jacobean of the transformation at that point. This is essentially
the ratio of the pixel areas between the output and input images. Note
that this is not exact since it is not an integral over the output pixel.
However, it will be very close except when the output pixel size is much
greater than the input pixel size. A log describing the image transformations
may be kept or printed on the standard output.
The output coordinate grid may be defined by the user or allowed to
default to an image of the same size as the input image spanning the
full range of user coordinates in the coordinate transformation maps.
When the coordinate maps are created by the task \fBfitcoords\fR the
user coordinates at the corners of the image are recorded in the
database. By default these values are used to set the limits of the
output grid. If a pixel interval is not specified then an interval
yielding the specified number of pixels is used. The default number of
pixels is that of the input image. Note that if a pixel interval is
specified then it takes precedence over the number of pixels.
The pixel intervals may also be logarithmic if the parameter \fIxlog\fR or
\fIylog\fR is "yes". Generally, the number of output pixels is specified
in this case . However, if the interval is specified it must be a base
10 logarithmic interval and not in units of the x and y limits which are
specified in user units.
The transformation from the desired output pixel to the input image may
fall outside of the input image. In this case the output pixel may be
set to the nearest pixel value in the input image or to a particular value
using the \fIblank\fR parameter. Also if an output mask is created this
pixels will have a value of one in the mask.
The parameters \fIminput\fR and \fImoutput\fR provide for input and output
pixel masks. An input mask is not used in calculating the transformed
pixel value but is used to identify the output pixels in the output mask
which make a significant contribution to the interpolated value. The
significance is determined as follows. The input mask values above zero
are converted to one hundred. The mask is then interpolated in the same
way as the input image. Any interpolated value of ten or greater is then
given the value one in the output mask. This means if all the input pixels
had mask values of zero a result of zero means no bad pixels were used.
If all the input pixels had values of 100 then the result will be 100 and
the output mask will flag this as a bad pixel. Other values are produced
by a mixture of good and bad pixels weighted by the interpolation kernel.
The choice of 10% is purely empirical and gives an approximate identification
of significant affected pixels.
zero and
is created with values of 100
.ih
EXAMPLES
Arc calibration images were used to determine a two dimensional dispersion
map called dispmap. Stellar spectra were used to determine a two dimensional
distortion map call distort. These maps where made using the task
\fBfitcoords\fR. To transform a set of input images into linear wavelength
between 3800 and 6400 Angstroms (the user coordinate units) with a dispersion
of 3 Angstroms per pixel:
.nf
cl> transform obj001,obj002 out001,out002 dispmap,distort \
>>> y1=3800 y2=6400 dy=3
.fi
To use logarithmic intervals in the wavelength to yield the same number of
pixels in the output images as in the input images:
.nf
cl> transform obj001,obj002 out001,out002 dispmap,distort \
>>> y1=3800 y2=6400 ylog=yes
.fi
.ih
TIMINGS
The following timings were obtained for transforming a 511x512 real
image to another 511x512 real image using two Chebyshev transformation
surface functions (one for the dispersion axis, "henear", and one in
spatial axis, "object") of order 6 in both dimensions created with the
task \fBfitcoords\fR. The times are for a UNIX/VAX 11/750.
.nf
cl> $transform input output henear,object interp=linear
TIME (transform) 173.73 5:13 55%
cl> $transform input output henear,object interp=poly3
TIME (transform) 266.63 9:17 42%
cl> $transform input output henear,object interp=spline3
TIME (transform) 309.05 6:11 83%
cl> $transform input output henear,object interp=spline3
TIME (transform) 444.13 9:44 76%
cl> $transform input output henear interp=linear
TIME (transform) 171.32 7:24 38%
cl> $transform input output henear interp=spline3
TIME (transform) 303.40 12:17 41%
cl> $transform input output henear,object interp=spline3 flux=no
TIME (transform) 262.42 10:42 40%
.fi
The majority of the time is due to the image interpolation and not evaluating
the transformation functions as indicated by the last three examples.
.ih
NOTES
.ls TRANSFORM: V2.12.2
The use of bad pixel masks, a specified "blank" value, and use of a WCS
to resample a WCS calibrated image was added.
.le
.ls TRANSFORM: V2.6
With Version 2.6 of IRAF the algorithm used to invert the user
coordinate surfaces, U(X,Y) and V(X,Y) to X(U,V) and Y(U,V), has been
changed. Previously surfaces of comparable order to the original
surfaces were fit to a grid of points, i.e. (U(X,Y), V(X,Y), X) and
(U(X,Y), V(X,Y), Y), with the same surface fitting routines used in
\fBfitcoords\fR to obtain the input user coordinate surfaces. This
method of inversion worked well in all cases in which reasonable
distortions and dispersions were used. It was selected because it was
relatively fast. However, it cannot be proved to work in all cases; in
one instance in which an invalid surface was used the inversion was
actually much poorer than expected. Therefore a more direct iterative
inversion algorithm is now used. This is guaranteed to give the
correct inversion to within a set error (0.05 of a pixel in X and Y).
It is slightly slower than the previous algorithm but it is still not
as major a factor as the image interpolation itself.
.le
.ih
SEE ALSO
fitcoords
.endhelp
|
