fflincorr -- Correct an FOC image for flat-field saturation.
fflincorr input output a_file
This program applies the flat-field linearity correction as determined by Robert Jedrzejewski and described in the Instrument Science Report FOC-062.
Each input image is first smoothed by a boxcar filter; this is done in memory, not in the image itself. The intensity transfer function (ITF) is computed at each pixel of the smoothed image. Each pixel of the original image is then multiplied by the ITF factor at the corresponding pixel in order to get the output image. The ITF factor is given by:
ITF = R / Rho = -A * ln (1 - Rho/A) / Rho,
where R is the actual count rate, Rho is the observed count rate, and A is a factor obtained from the a_file parameter. The A value is essentially the maximum possible count rate, which varies inversely with the area of the format and also goes down by about a factor of two in zoom mode.
The header parameter FFLCORR is set to COMPLETE when the task is done, and the task will not process an image that already has FFLCORR = COMPLETE. Two history records are also added to the header, one giving the task name and one giving the names of the A file and the input image.
One significant restriction on an input image is that it may not be a subset of the original image, unless the a_file parameter is just a single number or a file containing just a single value. The task compares the size of the image with the values of SAMPPLN and LINEPFM, corrected for zoom if appropriate, to see if the image is a subset. The reason for this restriction is that with an array of A coefficients, the task must be able to determine where the image is located within that array. This is done by using the header keywords SAMPOFF & LINEOFF. So if you really want to correct just a subset, you can do it if you edit the header to set the values of SAMPOFF, LINEOFF, SAMPPLN and LINEPFM to correspond to the subset. Note, however, that SAMPOFF is in original photocathode coordinates; that is, it is not "flipped" as are the images. SAMPOFF is the pixel offset of the right side of the flipped image from the right side of the flipped photocathode.
A file of A coefficients for each relay is provided in the focphot package directory. If you create your own a_file, however, follow these guidelines. Blank lines and lines beginning with "#" will be ignored. The file is expected to contain eight header parameters followed by a rectangular grid of A coefficients. The table of numerical values (the A coefficients) corresponds to some image format which is described by the header parameters. The eight header parameters (case insensitive) are as follows. RELAY is either 48 or 96. NX and NY give the number of columns and rows respectively in the table of numerical values. NSAMPS is the dezoomed size of the image in the sample (X) direction. NLINES is the size of the image in the line (Y) direction. NX should divide NSAMPS, and NY should divide NLINES. NX and NY may both be one. SAMPOFF is the offset of the format in the sample direction from the beginning of the photocathode. Note that this is in "unflipped" coordinates; that is, SAMPOFF is identical to what one would read from the header of an image in the corresponding format. LINEOFF is the offset of the format in the line direction from the beginning of the photocathode. ZOOM is either 1 or 2, depending on whether the corresponding image format is normal or zoom. This needs to be specified independently of NSAMPS because there is a factor of two penalty in saturation for using zoom mode.
While the input images may be either zoom-format or dezoomed, the A coefficients must be dezoomed values. The top line of data corresponds to the portion of the image with largest line number, and the bottom line of data corresponds to the portion of the image containing line one. The left column of data corresponds to smaller sample numbers. The lower left A value is the average for the rectangle with size NSAMPS/NX by NLINES/NY pixels at the beginning of the image.
- input [file name template]
- The names of the input images.
The correction is best done on uncalibrated images.
If they were taken in zoom format (PXFORMT = ZOOM),
then they do not need to be dezoomed before running fflincorr;
they may be dezoomed, however.
If you need to run this task on a subset of an original image, see the note in the description section.
- output [file name template]
- The names of the output images or a directory name. If the output is not a directory name, the number of input and output names must be the same. As usual, string substitution may be used; for example, if input = "*.d0h", you could use output = "*%%_lc%.d0h" to append the sting "_lc" to the root of each input image.
- a_file = "focphot$a_f96.dat" [file name template]
- The names of text files of A coefficients, or specific numerical values.
If only one name (or one numerical value) is given,
it will be used for all input images; otherwise,
the number of input images and the number of A coefficient files
must be the same.
The files "focphot$a_f48.dat" and "focphot$a_f96.dat" for f/48 and f/96
respectively were provided by Robert Jedrzejewski, and
these files may be used for any FOC format.
When a file name is given, the values of the A coefficients will be scaled depending on the relative sizes of the a_file format and the image format. This allows the same file of A coefficients to be used with any image format that fits within the format of the a_file. When a specific numerical value is given, however, that value is used without any modification, so it must be matched to the format (and zoom) of the image to be corrected.
See the note in the description section about creating your own file of A coefficients.
- (box = 5) [integer, min=1, max=INDEF]
- Size of smoothing box; this must be an ODD integer.
The ITF factor will be computed from a boxcar smoothed copy of the input image, using a box of this size in each dimension. For a zoom-format image (that has not been dezoomed), the width of the smoothing box is given by the xbox parameter, while only the height is given by box.
- (xbox = 3) [integer, min=1, max=INDEF]
- Width of smoothing box for a zoom-format image that has not been dezoomed. This must be an odd integer. For a non-zoom image or a zoom-format image that has been dezoomed, xbox is ignored, and the width as well as the height are given by the value of box.
- (boundary = nearest) [string]
- Allowed values: constant | nearest | reflect | wrap
Type of boundary extension for boxcar smoothing.
- (b_const = 0.) [real]
- Value to use for boundary extension if boundary = "constant".
- (verbose = yes) [boolean]
- Print file names?
If verbose = yes, the names of the input and output files as well as the a_file will be written to the standard output.
1. Correct all raw images beginning with "x0st580" in the current directory; the output root names will be the same as the input except that they will have "_ffl" appended. The A coefficient 0.73 will be used for all images.
fo> fflincorr x0st580*.d0h x0st580*%%_ffl%.d0h 0.73
2. Correct all raw images in the current directory, putting the output images in the subdirectory "ffl" (which must already exist). In this example we run the task twice to correct both the f/48 images and the f/96 images. The files "a_f48.dat" and "a_f96.dat" in the focphot package directory will be used as the source of A values for f/48 and f/96 respectively. When we use "a_f48.dat", only the f/48 images will be corrected, and a warning message will be printed for each f/96 image to say that it is being skipped. Similarly, when we use "a_f96.dat" only f/96 images will be corrected.
fo> fflincorr *.d0h ffl focphot$a_f48.dat fo> fflincorr *.d0h ffl focphot$a_f96.dat
Note that this procedure would be slower than running fflincorr separately for the f/48 and f/96 images.
This task was written by Phil Hodge based on the Instrument Science Report FOC-062 by Robert Jedrzejewski.