SECCHI_PREP User Guide
$Id: secchi_prep.html,v 1.18 2012/06/26 22:19:17 nathan Exp $

Overview

SECCHI_PREP is the IDL routine to read in and perform the latest calibration and image correction procedures for all SECCHI instruments. SECCHI_PREP calibrates the raw images, level 0.5, into level 1.0 and level 2.0 images suitable for quantitative photometric analysis. SECCHI_PREP is intended to be the single routine that the user would interact with to calibrate images.

Inputs to SECCHI_PREP are a string array of filenames or a single filename and optional parameters that allow the user to control which procedures are applied. It then calls correct prep programs for each instrument. SECCHI_PREP returns an array of images and an array of header structures in the output variables.

IDL>  SECCHI_PREP, filenames, headers, images

If SECCHI_PREP is called without any keywords then default processing is applied for each instrument. Each instrument has a set of programs that preform the calibration, corrections and image processing. There are also many general programs that are used by all the instruments. Since the prep procedures for COR1 and COR2 are similar there is one set of programs for both detector. The same is true for HI1 and HI2. A full description of the default and optional processing for each instrument is described in the page linked below.

General Examples

To process multiple files with the default procedures and return them to memory:
IDL> SECCHI_PREP, filenames, headers, images

To return a reduced resolution image; decreases processing time and memory usage :
IDL> SECCHI_PREP, filenames, headers, images, outsize=(1024 or 512)
note: the default value of outsize is the largest image processed; outsize must be an integer factor of 2048


To return 512x512 images corrected only for exposure duration and Binning, and data values in header not updated (quicker):
IDL> SECCHI_PREP, filenames, headers, images, OUTSIZE=512, /NOCALFAC, /CALIMG_OFF, /UPDATE_HDR_OFF, /EXPTIME_OFF

To save the images to disk while processing the them in SECCHI_PREP :
IDL> SECCHI_PREP, filenames, headers, images, /write_fts, savepath = path
note: if savepath is not set then the images are written to the current IDL directory

or to save the image to disk without returning them to memory :
IDL> SECCHI_PREP, filenames, /write_fts, savepath = path
Using SECCHI_PREP with :
COR1 & COR2 EUVI HI1 & HI2
Feedback

General SECCHI_PREP Programs

The instrument programs call many of the same subprograms to preform general task such as getting the bias and exposure time. The filename of any program that is specific to an instrument begins with the instrument name. Programs which are general to the SECCHI instruments have filenames that begin with either 'get' or 'scc'.
GET_BIASMEAN
GET_CALFAC
GET_CALIMG
GET_EXPTIME
GET_SMASK		 SCC_GET_MISSING
SCC_IMG_STATS
SCC_IMG_TRIM
SCC_PUTIN_ARRAY
 SCC_SEBIP
SCC_UPDATE_COMMENTS
SCC_UPDATE_HDR

GET_BIASMEAN

The GET_BIASMEAN function returns the corrected mean bias from a headers. The program corrects the mean bias for SEB IP bias subtraction and SEB IP image summing.
Syntax
result = GET_BIASMEAN(header)
Return Value
Returns the corrected mean bias.
back
GET_CALFAC

The GET_CALFAC function returns the calibration factor for each image.  The program corrects the calibration factor for SEB IP image summing.
Syntax
results = GET_CALFAC(header)
Return Value
Returns the correct calibration factor for each image.
back

GET_CALIMG

The GET_CALIMG function returns the latest calibration image for each instrument.  The function crops, scales and rectifies the calibration image array to match the data image.
Syntax
result = GET_CALIMG(header [,CALIMG_FILENAME=variable] [,/NEW_CALIMG])
Return Value
Returns the calibration image corrected to match the data image.
Keywords
CALIMG_FILENAME - set this keyword to a string variable containing the filename of an alternative FITS calibration image. Allows the user to open a calibration image other then the default.

NEW_CALIMG  - if set will force the program to open the calibration image from the disk instead of using the image in memory. 
back

GET_EXPTIME

The GET_EXPTIME function returns the correct exposure time for each image from a header.
Syntax
result = GET_EXPTIME(header)
Return Value
Returns the correct exposure time.
back

GET_SMASK

The GET_SMASK function returns and image containing a smooth mask for each instrument.  The mask image is a binary array with values 1 or 0. The function crops and scales mask image to match the data image.
Syntax
result = GET_SMASK(header)
Return Value
Returns the mask image corrected to match the data image.
back

SCC_GET_MISSING

The SCC_GET_MISSING function returns the subscript of pixels that have either missing or corrupted data due to transmission loses.  The function uses the header values in MISSLIST to find the missing or corrupted image pixels.
Syntax
result = SCC_GET_MISSING(header)
Return Value
Returns a longword vector containing the subscripts of the missing or corrupted image pixels.
back

SCC_IMG_STATS

The SCC_IMG_STATS procedure calculates the image statistics of the input image and returns the values in the output variables. The keyword MISSING allows the specification of which pixels are missing data in the image and thus are not to be included in the image statistic.
Syntax
SCC_IMG_STATS image, mn ,mx, zeros, nsat, mxval, mnval, nsatmin, men, sig,percentile, [,SATMAX=value]  [,SATMIN=value] [,missing=value]
Return Value
mn - the minimum value of the image; header keyword DATAMIN
mx - the  maximum value of the image; header keyword DATAMAX
zeros - the number of zero pixels in the image; header keyword DATAZER
nsat - the number of saturated pixels
mxval - Value used as saturated
mnval - Minimum value in scaled image
nsatmin - Number of pixels cut off on lower end
men - Mean of Image before BSCALE
sig - Standard Deviation of Image before BSCALE
percentile - Percentile Values [1%,10%,25%,75%,90%,95%,98%,99%]
Arguments
Keywords
back

SCC_IMG_TRIM

The SCC_IMG_TRIM function removes the over/under scan region from the data and updates the effected header keyword values. Some SECCHI images include an over and under scan region in the image. These regions are used to calculate the mean bias and other calibrations factors. The over/under scan regions do not contain solar data. By default, SECCHI_PREP trims off the over/under scan regions of the image array. The images will not be trimmed if the keyword TRIM_OFF is set in SECCHI_PREP.
Syntax
result = SCC_IMG_TRIM(image, header)
Return Value
Returns the trimmed image.  The updated header is returned in place.
back

SCC_PUTIN_ARRAY

The SCC_PUTIN_ARRARY function resizes images to the output array. The function will positions subfield images in a blank full field, rebins the images to the size given in the SECCHI_PREP keyword OUTSIZE and updates the effected header values.
Syntax
result = SCC_PUTIN_ARRAY(image, header, outsize)
Return Value
Returns an image of the same size as the output image array of SECCHI_PREP.
Arguments
outsize - by default the size of the largest input image; the value can be set by using the keyword OUTSIZE in SECCHI_PREP
back

SCC_SEBIP

 The SCC_SEBIP function returns the image corrected for any SEB Image Processing not associated with image compression.  The SEB IP can be set to take the square root of the image or divide the image by a factor of 2, 3, or 4 multiple times. The numerical codes for the SEB IP functions are in the 0.5 header (IP_00_19). The descriptions of the IP functions by number are in Science Operations Manual (MSWord).
Syntax
result = SCC_SEBIP( image, header, [IPFLAG = variable])
Return Value
Returns the image corrected for any SEB Image Processing not associated with image compression.
Keywords
IPFLAG - if set returns 1 if any correction was applied; else 0.
back

SCC_UPDATE_COMMENTS

The SCC_UPDATE_COMMENTS  function updates any header keyword comments that change as a result of the calibration. Only used to write FITS files.
Syntax
result = SCC_UPDATE_COMMENTS(comments, header)
Return Value
Returns header keyword commnents updated with change that result from calibration.
Arguments
comments - string array of header keyword comment (e.g. result from GET_FITSCOMMENTS function)
back

SCC_UPDATE_HDR

The SCC_UPDATE_HDR  function updates any header keyword values that change as a result of the calibration. It calls the SCC_IMG_STATS procedure to calculate the image statistics.
Syntax
result = SCC_UPDATE_HDR(image, header, [,FILENAME=variable]  [,/UPDATE_HDR_OFF] )
Return Value
Returns header with updated keyword values that change as a result of calibration.
Keywords
FILENAME -A named variable to receive the value of the new level 1.0 filename. See data naming conventions in the SECCHI FITS Header Keyword Definition.

UPDATE_HDR_OFF - Set this keyword to prevent the calculation the image statistics which is time consuming.
back