STScI Logo

resfind stsdas.foc.focgeom



resfind -- Accurately locate reseau marks in images.


resfind input outres entry


This program will accurately locate reseau marks in images, given the approximate location of one mark and one or more model templates for the marks. The task will try to find marks near their approximate positions using the following method. For each reseau mark, the reseau model is selected that fits that reseau mark best, and the position of that mark is determined using that model. To determine the best fit and the position, each model template is scaled to the mean image value near the reseau, and the sum of the squared deviations from the image is calculated for different positions around the reseau mark. The position is found by quadratic fitting near the minimum of the sums of squared deviations, and the model with the lowest minimum is chosen as the best fit. The positions are written out to a reseau table.

This task uses the reseau-finding algorithm from rfindx, but the estimated positions are extrapolated from an initial position using a subroutine written by Dave Baxter. Reseaux are found from the middle outward, starting with an estimated position specified by the user. The starting position may be taken from the resinit pset, which contains different positions and spacings for each relay, for several different formats, and for either raw or geometrically corrected images. As an alternative, the approximate location of one reseau mark may be given using parameters x0 and y0. After finding an N by N grid of reseau positions near the middle, positions are linearly extrapolated to get estimated positions for the row or column bordering each side of the N by N grid, and this procedure is repeated until the full image is covered.

When using x0 and y0 as the starting reseau position, it sometimes happens that resfind is off by one grid position when placing the set of observed reseau positions within the grid. To work around this, one can trim off one row and/or column of the resfind output using rsubset and then extrapolate the opposite sides using rextrap.


input [file name template]
Names of the input images. Since all reseaux positions are written to the same reseau table, all input images must be the same size. Image section notation may be used.

If the input list includes more than one image, it may be useful to set entry to null ("") in order to use the image root names as entry names.

A zoom mode image (PXFORMT = "ZOOM") must be dezoomed before it can be passed as input to resfind.

outres [file name]
File name for the reseau table produced by resfind. If this table already exists, the new entry will be appended to it, and the grid size will be the same as previous entries. If the table does not exist it will be created. In this case the grid size will either be taken from the values of ncols and nrows, or it will be calculated by the task based on the size of the first input image if either ncols and nrows is INDEF.
entry [string]
Entry name for the output reseau marks written to outres. If no value is provided for this parameter, then the entry will take the name of the image header keyword "ROOTNAME" from input; if that name cannot be determined, the entry name will be the image name. If more than one input image is specified, but entry is not null, then the output reseau table will have multiple entries with the same name. It makes more sense in this case to set entry = "".
rmodel = "focgeom$reseau.dat" [file name]
The name of a text file containing up to 20 model templates, represented as free-format integers. For each model, the first two numbers give the size of the model in number of pixels and lines, maximum 50 x 50, followed by the model data itself--which is assumed to be normalized to a surrounding image mean of 100. The models must be symmetrical about their center point, or else there will be a systematic bias in locations.
(search= 11) [integer, min=3, max=INDEF]
Number of pixels to search in each line; the search will be centered on the approximate location of each reseau mark.
(search= 11) [integer, min=3, max=INDEF]
Number of lines to search for each pixel coordinate; the search will be centered on the approximate location of each reseau mark.
(depth = 50.0) [real, min=0., max=100.]
The percentage depth of the correlation matrix, 100*(max-min)/max, which must be exceeded for a mark to be located. The value of depth should be in the range of 50.0 to 100.0. A value of 100 is a perfect match between the mark template and the reseau mark, that is, the fit must be exact. Higher values of depth mean that model must more closely fit the data. However, spurious data points within the search area can lead to a spuriously large maximum value in the correlation matrix, and therefore, a spuriously good fit of a model to the data for any particular mark.
(x= INDEF) [real]
The task needs the approximate position of one reseau mark to get started. If that mark cannot be found the task will fail. The approximate position may be specified in one of two ways. The better way, normally, is to leave x0 and y0 INDEF, so that the initial position will be taken from the values in the resinit pset. This is discussed below.

If both x0 and y0 are not INDEF, these values will be taken as the pixel coordinates of one reseau mark. The designated position should be within about 300 pixels of the image center. If the input image is not full format, or if an image section was specified, it is important to note that x0 and y0 are so-called logical coordinates; that is, they range from one to the width or height of the image. This is in contrast to photocathode coordinates which range from one to 1024.

If either x0 or y0 is INDEF, the position will be taken from parameters in the resinit pset. The parameter names for X and Y will be constructed based on the relay (f/48 or f/96), the image size, and whether geometric correction has been done. If the format of your image is not included in resinit, then you must use x0 and y0 to give a starting location. Note that these parameters in the resinit pset are in photocathode coordinates. The offsets to logical coordinates are determined from the values of SAMPOFF & LINEOFF from the image header plus the offset from an image section, if one was specified.

If the default resinit parameters are used, and if no image section was specified, then the initial coordinates will be those of the central reseau mark for the given image format. There is a major advantage to this, especially for a full format f/96 image. Not all of the rows and columns of reseau marks are visible on the photocathode. Without additional information, resfind determines where the observed reseau positions fall within the full 17 by 17 grid based on the number of marks found around the edges, and this method is not entirely reliable. If resfind knows that the initial reseau position is for the central mark, however, the task can place the observed positions correctly within the grid.

(y= INDEF) [real]
See the description for x0.
(resinit) [pset]
This pset contains parameters giving the location of one reseau mark and the offsets in X and Y to two adjacent reseau marks. There are separate parameters for f/96 and f/48. The task selects which parameters to use based on the values of keywords OPTCRLY and GEOCORR in the input image header. For the initial position of the central reseau mark, keywords PXFORMT, SAMPPLN and LINEPFM are also used. See the help for x0 or type "help resinit" for further details.
(ncols = INDEF) [integer]
Number of columns in the reseau grid. The parameters ncols and nrows are ignored if the output reseau table already exists. If the output reseau table does not exist, the reseau grid size may be specified explicitly using these parameters. If either ncols or nrows is INDEF or less than one, an appropriate value is calculated based on the size of the input image and the nominal spacing of the reseau marks. It is possible to specify one of the parameters and leave the other INDEF.
(nrows = INDEF) [integer]
Number of rows in the reseau grid. See the description of ncols.
(verbosity = 1) [int, min=0, max=2]
Display all text output on the terminal screen? Note that if verbosity = 2, a great deal of information about the fitting process is written to the screen. If verbosity = 1, a limited amount of information will be printed, such as the name of the image and how many reseaux were found. A pattern will also be printed to the screen to show which reseaux were found. An "x" indicates the mark was found, while a space is printed if it was not found. If a reseau mark was found outside the range of rows and columns indicated by nrows and ncols, an "o" will be printed instead of an "x". If verbosity = 0, only error messages will be printed.
(noindefs = no) [boolean]
Prohibit input coordinates from being changed to INDEF coordinates? If a mark cannot be located, the estimated coordinate will be copied to the output.


1. Locate reseau marks in an image called "x14q0107t.d0h". The output reseau grid will be written to the table "outres" with entry name "respos". Send diagnostic log output to the file x14q0107t.log.

  fo> resfind x14q0107t.d0h outres respos verb=2 > x14q0107t.log

2. Find reseau marks in all images with extension "cbh" in the default directory. Use the rootname of each image as its entry name in the output reseau table.

  fo> resfind *.cbh outres ""



The gridextrap subroutine was written by David Baxter, and the rfindx set of subroutines were written by David Giaretta. These were combined into the current task by Phil Hodge.


resinit, rfindx, rgenx, rprintx, rplotx

Type "help focgeom opt=sys" for a higher-level description of the focgeom package.

Type "help reseau" for more information about reseau tables.

Source Code · Package Help · Search Form · STSDAS