| identify | noao.onedspec | identify |
identify -- Identify features in one dimensional image vectors
Features are interactively marked in one dimensional image vectors. The features may be spectral lines when the vector is a spectrum or profile positions when the vector is a spatial cut. A function may be fit to the user coordinates as a function of pixel coordinates. This is primarily used to find dispersion functions for spectra such as arc-line calibration spectra. The profile position measurements are generally used for geometric calibrations.
identify images
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 three dimensional data. See the example section for examples of this syntax. Abbreviations are allowed though beware that l is not a sufficient abbreviation.
cl> help onedspec.package section=units
If no units are specified and a coordinate list is used then the units of the coordinate list are selected. If a database entry exists then the units defined there override both this parameter and the coordinate list.
The following parameters are used in determining feature positions.
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.
The following parameters control the input and output.
The following parameters are queried when the b key is used.
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.
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. Because of this dual use the terms vector and feature are used rather than spectrum and spectral line.
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 PARAMETERS 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 a number of ways of defining features. They fall into two categories; interactively defining features with the cursor and using automatic algorithms.
The m key is the principle interactive feature marking method. Typing m near the position of a feature applies a feature centering algorithm (see center1d ) and, if a center is found, the feature is entered in the feature list and marked on the spectrum. 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 a 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 t key allows setting the position of a feature to other than that found by the centering algorithm.
The principle automatic feature identification algorithm is executed with the b key. The user is queried for an approximate coordinate value and coordinate interval per pixel. The coordinate value is for the center of the spectrum by default though this may be changed with the aidpars parameters. Only the magnitude of the coordinate interval per pixel is used by default though this also may be changed. Either value may be given as INDEF to do an unconstrained search, however, this will be much slower and more likely to fail. The algorithm searches for matches between the strong lines in the spectrum and lines in the coordinate list. The algorithm is described in the documentation for aidpars .
The b key works with no predefined dispersion solution or features. If two or more features are identified, with m, spanning the range of the data or if a coordinate function is defined, from a previous solution, then the e, l, and y keys may be used to identify additional features from a coordinate list. The e key only adds features at the coordinates of the line lists if the centering algorithm finds a feature at that wavelength (as described below). The y key works in reverse by finding the prominent features using a peak finding algorithm and then looking in the coordinate list for entries near the estimated position. Up to a maximum number of features (maxfeatures ) will be selected. If there are more peaks only the strongest are kept. In either of these cases there is no automatic fitting and refitting of the dispersion function.
The l key combines automatic fits with locating lines from the coordinate list. If two or more features are defined an initial fit is made. 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 the l key algorithm to work. However, three or more features are preferable to determine changes in the dispersion as a function of position.
The f key 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.
One a set of features is defined one may select features for various operations. To select 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, changing the fitting weight of a feature with v, and when examining features in zoom mode.
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 transferring 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 s or x keys.
A zero point shift is specified 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. If there are features the specified shift is applied, the features are recentered, and the mean shift for all the features is determined.
The x key uses the automatic line identification algorithm (see aidpars ) with the constraint that the dispersion is nearly the same and the is primarily a shift in the coordinate zero point. If features are defined, normally by inheritance from another spectrum, then a first pass is done to identify those features in the spectrum. Since this only works when the shifts are significantly less than the dispersion range of the spectrum (i.e. a significant number of features are in common) a second pass using the full coordinate line list is performed if a shift based on the features is not found. After a shift is found any features remaining from the original list are recentered and a mean shift is computed.
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 beginning 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:
Code Type 1 Chebyshev polynomial 2 Legendre polynomial 3 Cubic spline 4 Linear spline
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
n = (2 * x - (xmax + xmin)) / (xmax - xmin)
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
s = (x - xmin) / (xmax - xmin) * npieces j = integer part of s
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
y = sum from i=1 to order {c_i * z_i}
where the the c_i are the coefficients and the z_i are defined interactively as:
z_1 = 1
z_2 = n
z_i = 2 * n * z_{i-1} - z_{i-2}
2. Legendre Polynomial
The polynomial can be expressed as the sum
y = sum from i=1 to order {c_i * z_i}
where the the c_i are the coefficients and the z_i are defined interactively as:
z_1 = 1
z_2 = n
z_i = ((2*i-3) * n * z_{i-1} - (i-2) * z_{i-2}) / (i-1)
3. Linear Spline
The linear spline is evaluated as
y = c_j * a + c_{j+1} * b
where j is as defined earlier and a and b are fractional difference between s and the nearest integers above and below
a = (j + 1) - s b = s - j
4. Cubic Spline
The cubic spline is evaluated as
y = sum from i=0 to 3 {c_{i+j} * z_i}
where j is as defined earlier. The term z_i are computed from a and b, as defined earlier, as follows
z_0 = a**3 z_1 = 1 + 3 * a * (1 + a * b) z_2 = 1 + 3 * b * (1 + a * b) z_3 = b**3
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:
cl> identify obj[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
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
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.
Vector axis | Sum axis in 2D | Sum axes in 3D
------------------|---------------------|--------------------
1 | 2 | 2 3
2 | 1 | 1 3
3 | - | 1 2
A new key, e, has been added to add features from a line list without doing any fits. This is like the l but without the automatic fitting before and after adding new features.
A new key, b, has been added to apply an automatic line identification algorithm.
The x key has been changed to use the automatic line identification algorithm. The allows finding much larger shifts.
The match parameter may now be specified either in user coordinates or in pixels. The default is now 3 pixels.
The default threshold value has been changed to 0.
The v key was added to allow assigning weights to features.
autoidentify, reidentify, aidpars, center1d, linelists, fitcoords, icfit, gtools