identify images
images
List of images in which to identify features and fit coordinate functions.
section = middle line
If an image is not one dimensional or given as a one dimensional image
section then the image section given by this parameter is used. The
section is used to define the initial vector and the direction (columns,
lines, or "z") of the image vectors to be fit. The image is still considered
to be two or three dimensional and it is possible to change the data vector
within the program.
The section parameter may be specified directly as an image section or in one of the following forms
line|column|x|y|z first|middle|last|# [first|middle|last|#]] first|middle|last|# [first|middle|last|#] line|column|x|y|z
where each field can be one of the strings separated by | except for # which is an integer number. The field in [] is a second designator which is used with 3D data. See the example section for examples of this syntax. Abbreviations are allowed though beware that 'l' is not a sufficient abbreviation.
database = database
Database in which the feature data and coordinate functions are recorded.
coordlist = linelists$idhenear.dat
User coordinate list consisting of an ordered list of line coordinates.
Some standard line lists are available in the directory "linelists$":
cl> dir linelists cl> page linelists$README.le
match = 5.
The maximum difference for a match between the feature coordinate function
value and a coordinate in the coordinate list. The unit of this parameter
is that of the user coordinates.
maxfeatures = 50
Maximum number of the strongest features to be selected automatically from
the coordinate list (function 'l') or from the image data (function 'y').
zwidth = 100.
Width of graphs, in user coordinates, when in zoom mode (function 'z').
The following parameters are used in determining feature positions.
ftype = emission
Type of features to be identified. The possibly abbreviated choices are
"emission" and "absorption".
fwidth = 4.
Width in pixels of features to be identified.
cradius = 5.
The maximum distance, in pixels, allowed between a feature position
and the initial estimate when defining a new feature.
threshold = 10.
In order for a feature center to be determined the range of pixel intensities
around the feature must exceed this threshold.
minsep = 2.
The minimum separation, in pixels, allowed between feature positions
when defining a new feature.
The following parameters are used to fit a function to the user coordinates.
The icfit package is used and further descriptions about these parameters
may be found under that package.
function = spline3
The function to be fit to the user coordinates as a function of the pixel
coordinate. The choices are "chebyshev", "legendre", "spline1", or "spline3".
order = 1
Order of the fitting function. The order is the number of polynomial terms
or number of spline pieces.
sample = *
Sample regions for fitting. This is in pixel coordinates and not the user
coordinates.
niterate = 0
Number of rejection iterations.
low_reject = 3.0, high_reject = 3.0
Lower and upper residual rejection in terms of the RMS of the fit.
grow = 0
Distance from a rejected point in which additional points are automatically
rejected regardless of their residuals.
The following parameters control the input and output.
autowrite = no
Automatically write or update the database? If no then attempting to
exit the program if the feature data and fit have been modified results
in a query. If yes exiting the program automatically updates the database.
graphics = stdgraph
Graphics device. The default is the standard graphics device which is
generally a graphics terminal.
cursor =
Cursor input file. If a cursor file is not given then the standard graphics
cursor is read.
?
Clear the screen and print a menu of options.
a
Apply next (c)enter or (d)elete operation to (a)ll features
c
(C)enter the feature nearest the cursor. Used when changing the position
finding parameters or when features are defined from a previous feature list.
d
(D)elete the feature nearest the cursor. (D)elete all features when preceded
by the (a)ll key. This does not affect the dispersion function.
f
(F)it a function of the pixel coordinates to the user coordinates. This enters
the interactive function fitting package.
g
Fit a zero point shift to the user coordinates by minimizing the difference
between the user and fitted coordinates. The coordinate function is
not changed.
i
(I)nitialize (delete features and coordinate fit).
j
Go to the preceding line, column, or band in a 2D/3D or multispec image.
k
Go to the next line, column, or band in a 2D/3D or multispec image.
l
(L)ocate features in the coordinate list. A coordinate function must be
defined or at least two features must have user coordinates from which a
coordinate function can be determined.
m
(M)ark a new feature using the cursor position as the initial position
estimate.
n
Move the cursor or zoom window to the (n)ext feature (same as +).
o
Go to the specified line, column, or band in a 2D/3D or multispec image.
For 3D images two numbers are specified.
p
(P)an to the original window after (z)ooming on a feature.
q
(Q)uit and continue with next image.
r
(R)edraw the graph.
s
(S)hift the fit coordinates relative to the pixel coordinates. The
user specifies the desired fit coordinate at the position of the cursor
and a zero point shift to the fit coordinates is applied. If features
are defined then they are recentered and the shift is the average shift.
The shift in pixels, user coordinates, and z (fractional shift) is printed.
t
Reset the current feature to the position of the cursor. The feature
is not recentered. This is used to mark an arbitrary position.
u
Enter a new (u)ser coordinate for the current feature.
When (m)arking a new feature the user coordinate is also requested.
w
(W)indow the graph. A window prompt is given and a number of windowing
options may be given. For more help type '?' to the window prompt or
see help under gtools.
x
Crosscorrelate features with the data peaks and reregister. This is generally
used with a feature list from a different image.
The mean shift in user coordinates, mean shift in pixels, and the fractional
shift in user coordinates is printed.
y
Up to maxfeatures emission peaks are found automatically (in order of
peak intensity) and, if a dispersion solution is defined, the peaks are
identified from the coordinate list.
z
(Z)oom on the feature nearest the cursor. The width of the zoom window
is determined by the parameter zwidth.
.
Move the cursor or zoom window to the feature nearest the cursor.
4 +
Move the cursor or zoom window to the (n)ext feature.
4 -
Move the cursor or zoom window to the previous feature.
Parameters are shown or set with the following "colon commands", which may be
abbreviated. To show the value of a parameter type the parameter name alone
and to set a new value follow the parameter name by the value.
:show file
Show the values of all the parameters. If a file name is given then the
output is appended to that file. If no file is given then the terminal
is cleared and the output is sent to the terminal.
:features file
Print the feature list and the fit rms. If a file name is given then the
output is appended to that file. If no file is given then the terminal
is cleared and the output is sent to the terminal.
:coordlist file
Set or show the coordinate list file.
:cradius value
Set or show the centering radius in pixels.
:threshold value
Set or show the detection threshold for centering.
:database name
Set or show the database for recording feature records.
:ftype value
Set or show the feature type (emission or absorption).
:fwidth value
Set or show the feature width in pixels.
:image imagename
Set a new image or show the current image.
:labels value
Set or show the feature label type (none, index, pixel, coords, user, or both).
None produces no labeling, index labels the features sequentially in order
of pixel position, pixel labels the features by their pixel coordinates,
coords labels the features by their user coordinates (such as wavelength),
user labels the features by the user or line list supplied string, and
both labels the features by both the user coordinates and user strings.
:match value
Set or show the coordinate list matching distance.
:maxfeatures value
Set or show the maximum number of features automatically found.
:minsep value
Set or show the minimum separation allowed between features.
:read name ap
Read a record from the database. The record name defaults to the image name
and, for 1D spectra, the aperture number defaults to aperture of
the current image.
:write name ap
Write a record to the database. The record name defaults to the image name
and, for 1D spectra, the aperture number defaults to aperture of
the current image.
:add name ap
Add features from a database record. The record name defaults to the image name
and, for 1D spectra, the aperture number defaults to aperture of
the current image. Only the features are added to any existing list
of features. The dispersion function is not read.
:zwidth value
Set or show the zoom width in user units.
:/help
Print additional help for formatting graphs. See help under "gtools".
Features in the input images are identified interactively and assigned user coordinates. A "coordinate function" mapping pixel coordinates to user coordinates may be determined from the identified features. A user coordinate list may be defined to automatically identify additional features. This task is used to measure positions of features, determine dispersion solutions for spectra, and to identify features in two and three dimensional images for mapping a two or three dimensional coordinate transformation.
Each image in the input list is considered in turn. If the image is not one dimensional or a one dimensional section of an image then the image section given by the parameter section is used. This parameter may be specified in several ways as described in the parameter and examples sections. The image section is used to select a starting vector and image axis.
If the image is not one dimensional or in multispec format then the number of lines, columns, or bands given by the parameter nsum are summed. The one dimensional image vector is graphed. The initial feature list and coordinate function are read from the database if an entry exists. The features are marked on the graph. The image coordinates are in pixels unless a coordinate function is defined, in which case they are in user coordinate units. The pixel coordinate, coordinate function value, and user coordinate for the current feature are printed.
The graphics cursor is used to select features and perform various functions. A menu of the keystroke options and functions is printed with the key '?'. The cursor keys and their functions are defined in the CURSOR KEYS section and described further below. The standard cursor mode keys are also available to window and redraw the graph and to produce hardcopy "snaps".
There are two types of feature selection functions; defining new features and selecting previously defined features. The key 'm' marks a new feature nearest the cursor position. The feature position is determined by the feature centering algorithm (see help for center1d). If the new position is within a distance given by the parameter minsep of a previous feature it is considered to be the same feature and replaces the old feature. Normally the position of the new feature will be exactly the same as the original feature. The coordinate list is searched for a match between the coordinate function value (when defined) and a user coordinate in the list. If a match is found it becomes the default user coordinate which the user may override. The new feature is marked on the graph and it becomes the current feature. The redefinition of a feature which is within the minimum separation may be used to set the user coordinate from the coordinate list. The key 't' allows setting the position of a feature to other than that found by the centering algorithm.
The 'y' key applies a peak finding algorithm to the one dimensional image vector. Up to the maximum number of features (maxfeatures) are found. If there are more peaks only the strongest are kept. The peaks are then matched against the coordinate list to find user coordinate values.
To select a different feature as the current feature the keys '.', 'n', '+', and '-' are used. The '.' selects the feature nearest the cursor, the 'n' and '+' select the next feature, and the '-' selects the previous feature relative to the current feature in the feature list as ordered by pixel coordinate. These keys are useful when redefining the user coordinate with the 'u' key and when examining features in zoom mode.
If two or more features are identified spanning the range of the data or if a coordinate function is defined then the 'l' key may be used to identify additional features from a coordinate list. If a coordinate function is not defined the default function is fit to the user coordinates of the currently defined features. Then for each coordinate value in the coordinate list the pixel coordinate is determined and a search for a feature at that point is made. If a feature is found (based on the parameters ftype, fwidth, cradius, and threshold) its user coordinate value based on the coordinate function is determined. If the coordinate function value matches the user coordinate from the coordinate list within the error limit set by the parameter match then the new feature is entered in the feature list. Up to a maximum number of features, set by the parameter maxfeatures, may be defined in this way. A new user coordinate function is fit to all the located features. Finally, the graph is redrawn in user coordinates with the additional features found from the coordinate list marked.
A minimum of two features must be defined for this algorithm to work. However, three or more features are preferable to determine changes in the dispersion as a function of position.
The key 'f' fits a function of the pixel coordinates to the user
coordinates. The type of function, order and other fitting parameters
are initially set with the parameters function, order, sample,
niterate, low_reject, high_reject and grow.. The value of the
function for a particular pixel coordinate is called the function
coordinate and each feature in the feature list has a function
coordinate value. The fitted function also is used to convert pixel
coordinates to user coordinates in the graph. The fitting is done
within the interactive curve fitting package which has its own set of
interactive commands. For further information on this package see the
help material under icfit.
If a zero point shift is desired without changing the coordinate function
the user may specify the coordinate of a point in the spectrum with
the 's' key from which a shift is determined. The 'g' key also
determines a shift by minimizing the difference between the user
coordinates and the fitted coordinates. This is used when a previously
determined coordinate function is applied to a new spectrum having
fewer or poorer lines and only a zero point shift can reasonably be
determined. Note that the zero point shift is in user coordinates.
This is only an approximate correction for shifts in the raw spectra
since these shifts are in pixels and the coordinate function should
also be appropriately shifted.
Features may be deleted with the key 'd'. All features are deleted
when the 'a' key immediately precedes the delete key. Deleting the
features does not delete the coordinate function. Features deleted in the
curve fitting package also are removed from the feature list upon
exiting the curve fitting package.
It is common to transfer the feature identifications and coordinate function
from one image to another. When a new image without a database entry
is examined, such as when going to the next image in the input list,
changing image lines or columns with 'j', 'k' and 'o', or selecting
a new image with the ":image" command, the current feature list and coordinate
function are kept. Alternatively, a database record from a different
image may be read with the ":read" command. When transfering feature
identifications between images the feature coordinates will not agree exactly
with the new image feature positions and several options are available to
reregister the feature positions. The key 'c' centers the feature nearest
the cursor using the current position as the starting point. When preceded
with the 'a' key all the features are recentered (the user must refit
the coordinate function if desired). As an aside, the recentering
function is also useful when the parameters governing the feature
centering algorithm are changed. An additional options is the ":add"
command to add features from a database record. This does not overwrite
previous features (or the fitting functions) as does ":read".
The (c)entering function is applicable when the shift between the
current and true feature positions is small. Larger shifts may be
determined automatically with the 'x' function which correlates
features in the image with the feature list. The features are then
recentered. A zero point shift may also be given interactively with
the 's' key by using the cursor to indicate the coordinate of a point
in the spectrum. If there are no features then the shift is exactly as
marked by the cursor but if there are features the approximate shift is
applied and then the features are recentered. The shift is then the
mean shift of the features after recentering. The shift is used as a
zero point offset added to the dispersion function. The shift is
in user coordinates.
In addition to the single keystroke commands there are commands initiated
by the key ':' (colon commands). As with the keystroke commands there are
a number of standard graphics features available begining with ":."
(type ":.help" for these commands). The identify colon commands
allow the task parameter values to be listed and to be reset
within the task. A parameter is listed by typing its name. The colon command
":show" lists all the parameters. A parameter value is reset by
typing the parameter name followed by the new value; for example
":match 10". Other colon commands display the feature list (:features),
control reading and writing records to the database (:read and :write),
and set the graph display format.
The feature identification process for an image is completed by typing
'q' to quit. Attempting to quit an image without explicitly
recording changes in the feature database produces a warning message
unless the autowrite parameter is set. If this parameter is
not set a prompt is given asking whether to save the results otherwise
the results are automatically saved. Also
the reference spectrum keyword REFSPEC is added to the image header at
this time. This is used by refspectra and dispcor.
As an immediate exit the 'I' interrupt key may be used. This does not save
the feature information and may leave the graphics in a confused state.
The database specified by the parameter database is a directory of
simple text files. The text files have names beginning with 'id' followed
by the entry name, usually the name of the image. The database text files
consist of a number of records. A record begins with a line starting with the
keyword "begin". The rest of the line is the record identifier. Records
read and written by identify have "identify" as the first word of the
identifier. Following this is a name which may be specified following the
":read" or ":write" commands. If no name is specified then the image name
is used. For 1D spectra the database entry includes the aperture number
and so to read a solution from a aperture different than the current image
and aperture number must be specified. For 2D/3D images the entry name
has the 1D image section which is what is specified to read the entry.
The lines following the record identifier contain
the feature information and dispersion function coefficients.
The dispersion function is saved in the database as a series of
coefficients. The section containing the coefficients starts with the
keyword "coefficients" and the number of coefficients.
The first four coefficients define the type of function, the order
or number of spline pieces, and the range of the independent variable
(the line or column coordinate along the dispersion). The first
coefficient is the function type code with values:
The second coefficient is the order (actually the number of terms) of
the polynomial or the number of pieces in the spline.
The next two coefficients are the range of the independent variable over
which the function is defined. These values are used to normalize the
input variable to the range -1 to 1 in the polynomial functions. If the
independent variable is x and the normalized variable is n, then
where xmin and xmax are the two coefficients.
The spline functions divide the range into the specified number of
pieces. A spline coordinate s and the nearest integer below s,
denoted as j, are defined by
where npieces are the number of pieces.
The remaining coefficients are those for the appropriate function.
The number of coefficients is either the same as the function order
for the polynomials, npieces+1 for the linear spline, or npieces + 3
for the cubic spline.
1. Chebyshev Polynomial
The polynomial can be expressed as the sum
where the the c_i are the coefficients and the z_i are defined
interatively as:
2. Legendre Polynomial
The polynomial can be expressed as the sum
where the the c_i are the coefficients and the z_i are defined
interatively as:
3. Linear Spline
The linear spline is evaluated as
where j is as defined earlier and a and b are fractional difference
between s and the nearest integers above and below
4. Cubic Spline
The cubic spline is evaluated as
where j is as defined earlier. The term z_i are computed from
a and b, as defined earlier, as follows
EXAMPLES
1. Because this task is interactive and has many possible applications
it is difficult to provide actual examples. Instead some uses of the task
are described.
2. For images which are two or three dimensional it is necessary to
specify the image axis for the data vector and the number of pixels at each
point across the vector direction to sum. One way specify a vector is to
use an image section to define a vector. For example, to select column
20:
The alternative is to use the section parameter. Below are some examples
of the section parameter syntax for an image "im2d" which is 100x200
and "im3d" which is 100x200x50. On the left is the section string syntax
and on the right is the image section
The most common usage should be "middle line", "middle column" or "middle z".
The summing factors apply to the axes across the specified vector. For
3D images there may be one or two values. The following shows which axes
are summed, the second and third columns, when the vector axis is that shown
in the first column.
The coordinates and image data are double precision.
The double precision curve fitting procedures are used.
center1d,
gtools,
icfit,
reidentify,
DATABASE RECORDS
Code Type
1 Chebyshev polynomial
2 Legendre polynomial
3 Cubic spline
4 Linear spline
n = (2 * x - (xmax + xmin)) / (xmax - xmin)
s = (x - xmin) / (xmax - xmin) * npieces
j = integer part of s
y = sum from i=1 to order {c_i * z_i}
z_1 = 1
z_2 = n
z_i = 2 * n * z_{i-1} - z_{i-2}
y = sum from i=1 to order {c_i * z_i}
z_1 = 1
z_2 = n
z_i = ((2*i-3) * n * z_{i-1} - (i-2) * z_{i-2}) / (i-1)
y = c_j * a + c_{j+1} * b
a = (j + 1) - s
b = s - j
y = sum from i=0 to 3 {c_{i+j} * z_i}
z_0 = a**3
z_1 = 1 + 3 * a * (1 + a * b)
z_2 = 1 + 3 * b * (1 + a * b)
z_3 = b**3
EXAMPLES
o
For defining distortions in the slit dimension as a function of
wavelength the positions of objects are marked at some wavelength.
The task reidentify is then used to trace the features to other
wavelengths.
o
For determining dispersion solutions in a one dimensional
spectrum an arc calibration is used. Three emission features are marked
and the (l)ocate key is used to find additional features from a
coordinate list of arc lines. The dispersion solution is fit interactively
and badly determined or misidentified lines are deleted. The
solution may be written to the database or transfered to the object
spectrum by reading the object image and deleting all the features.
Deleting the features does not delete the coordinate function.
o
For determining a two or three dimensional coordinate transformation the a
dispersion solution is determined at one slit position in a long slit arc
spectrum or one spatial position in a Fabry-Perot spectrum as in the
previous example. The features are then traced to other positions with the
task reidentify.
cl> identify obj[20,*]
Section parameter | Image section | Description
------------------|---------------------|---------------------
first line | im2d[*,1] | First image line
middle column | im2d[50,*] | Middle image column
last z | im3d[100,200,*] | Last image z vector
middle last y | im3d[50,*,50] | Image y vector
line 20 | im2d[*,20] | Line 20
column 20 | im2d[20,*] | Column 20
x 20 | im2d[*,20] | Line 20
y 20 | im2d[20,*] | Column 20
y 20 30 | im2d[20,*,30] | Column 20
z 20 30 | im3d[20,30,*] | Image z vector
x middle | im3d[*,100,25] | Middle of image
y middle | im3d[50,*,25] | Middle of image
z middle | im3d[50,100,*] | Middle of image
Vector axis | Sum axis in 2D | Sum axes in 3D
------------------|---------------------|--------------------
1 | 2 | 2 3
2 | 1 | 1 3
3 | - | 1 2
REVISIONS
IDENTIFY V2.10.3
The section and nsum parameter syntax was extended to apply to 3D
images. The previous values and defaults may still be used.
IDENTIFY V2.10
The principle revision is to allow multiple aperture images and long slit
spectra to be treated as a unit. New keystrokes allow jumping or scrolling
within multiple spectra in a single image. For aperture spectra the
database entries are referenced by image name and aperture number and not
with image sections. Thus, IDENTIFY solutions are not tied to specific
image lines in this case. There is a new autowrite parameter which may
be set to eliminate the save to database query upon exiting. The new
colon command "add" may be used to add features based on some other
spectrum or arc type and then apply the fit to the combined set of features.
NOTES
SEE ALSO
This page automatically generated from the iraf .hlp file. If you
would like your local iraf package .hlp files converted into HTML
please contact Dave Mills at NOAO.dmills@noao.edu