SCLEAN-Interactive patching of images, especially SCUBA data.

Description:

SCLEAN is an interactive routine for marking and fixing bad pixels, rows and columns in two dimensional images. It has all the facilities of CLEAN, plus some additional ones suitable for use with files generated by the SCUBA instrument.

The principal advantages for SCUBA users of SCLEAN over CLEAN are that this application marks bad pixels by setting one of the bits (specified by the parameter BITNUM) of the quality array, rather than simply setting the data value to the magic bad value, and that an additional viewing mode is available which enables a plot of the values for a given bolometer to be seen easily.

In interactive mode, an image is displayed and operations are specified using the cursor and keyboard. In batch mode, the program will read a file of instructions and perform the operations without user intervention. SCLEAN will also optionally write a log file of the operations it has performed in the batch file format, so that a set of operations can be performed interactively, and then reperformed on the same or a different NDF by writing to the log file in the first instance and using that as a batchfile for subsequent runs.

Parameters:

IMAGE

IMAGE is the image - usually a SCUBA NDF - that is to be cleaned of bad pixels.

OUTPUT

OUTPUT is the name of the image that results from the cleaning process.

IDEV

IDEV is the name of the image device to use for display. In batch mode (i.e. if BATCHFILE is non-null) it defaults to null, in which case no graphic display is performed. It is an error for IDEV to be null in interactive mode.

QUIT

Used to confirm quitting the application.

DEG

Degree of fit to use for interpolation.

XSIZE

Size of interpolation box in X.

YSIZE

Size of interpolation box in Y.

HIGH

Highest displayed data value.

LOW

Lowest displayed data value.

BITNUM

Bit number of quality mask to modify for bad pixels.

ZOOM

Minimum pixel magnification factor in Expanded and SCUBA mode.

LOGFILE

Name of a file to log to. If null, no logging is performed. The log file begins with comment lines naming the IMAGE and OUTPUT NDFs, and continues with one line per cleaning operation, consisting of the command letter followed by zero, one or two arguments. This log file is understood if read by a subsequent invocation of the program as the BATCHFILE parameter.

BATCHFILE

Name of a file from which to read batch input. If null (the default) the program will run in interactive mode, but if this parameter has a value the named file will be read to determine the cleaning operations to be performed so that no user intervention is requested.

If a line is encountered which cannot be executed (e.g. it contains an invalid command or refers to a region outside the image) the user is notified and the line is ignored. No other attempt is made to verify that the commands in the batch file are appropriate for the particular image being examined.

Normally the batchfile will have been written by a previous invocation of SCLEAN using the LOGFILE parameter, but it can in principle be modified or written by hand. The format of the file is plain text consisting of one single letter command in column one followed by zero, one or two numeric arguments. Anything after a hash (#), and blank lines, are ignored.

Commands:

The following keys are recognised -

W - display Whole image E - Expand image around cursor position B - SCUBA type display for cursor column R - delete indicated Row (horizontal line) & fix it C - delete indicated Column (vertical line) & fix it X - delete indicated area and fix by interpolation in the x direction Y - like X, but uses vertical interpolation L - delete indicated line, but don't fix K - delete indicated column, but don't fix A - delete pixel at cursor, but don't fix G - mark as Good pixel at cursor S - set stretch, ie High & low limits for display D - set degree of fit used for interpolation N - set size of deleted area for "X" and "Y" P - indicate current cursor position T - test area to see what BCLEAN might find there U - Undo last operation - replace with original image data Q - Quit program

H

H - help

A summary of available commands is displayed.

W

W - display Whole image

The whole image is displayed, stretched or compressed in both directions to fit the available plotting surface.

E

E - Expand image around cursor position

A section of the image around the cursor position is displayed with ZOOM * ZOOM display pixels representing each image pixel.

B

B - SCUBA type display for cursor column

A special display mode is used suitable for NDFs from the SCUBA instrument. Each image pixel is at least ZOOM display pixels in X and Y directions, although it will be displayed larger if there is space. Additionally, on one half of the screen is displayed a line plot of one column (the column the cursor was on when 'B' was selected). If the cursor is on the graph half of the screen it is considered to be on the column plotted.

R

R - delete indicated Row (horizontal line) & fix it

The row of pixels at the cursor is replaced by interpolation.

C

C - delete indicated Column (vertical line) & fix it

The column of pixels at the cursor is replaced by interpolation.

X

X - delete indicated area and fix by interpolation in X direction

The XSIZE * YSIZE region at the cursor is replaced by a horizontal interpolation using a polynomial fit of degree DEG.

Y

Y - delete indicated area and fix by interpolation in Y direction

The XSIZE * YSIZE region at the cursor is replaced by a vertical interpolation using a polynomial fit of degree DEG.

S

S - set stretch, ie high & low limits for display

The user is queried for the parameters HIGH and LOW, the highest and lowest values of pixel to be represented in the colour mapping.

L

L - delete indicated line, but don't fix

The row at the cursor is marked as bad.

K

K - delete indicated column, but don't fix

The column at the cursor is marked as bad.

A

A - delete pixel at cursor, but don't fix

The pixel at the cursor is marked as bad.

G

G - mark as Good pixel at cursor

The pixel at the cursor is marked as good (In fact the bit BITNUM in the quality byte is set to zero. If other bits in the quality byte are set, or if the data value itself is flagged bad, the pixel may still be bad.)

D

D - set degree of fit used for interpolation

The user is prompted for the parameter DEG, the degree of the polynomial used for interpolation by the X and Y commands.

N

N - set size of deleted area for "X" and "Y"

The user is prompted for the values of the parameters XSIZE and YSIZE, the dimensions of the box used for interpolation by the X and Y commands.

P

P - indicate current cursor position

The current cursor position is printed.

T

T - test area to see what BCLEAN might find there

The algorithm used by the BCLEAN application is run and the user is informed what spikes it would identify.

U

U - Undo last operation - replace with original image data

The last operation which modified the data is undone. Until the undo buffer fills up (usually it does not) all cleaning operations back to the start of the session can be undone in a Last In First Out fashion.

Q

Q - Quit program

The program is exited following a prompt for confirmation.

[See also:] FIGARO: BCLEAN, CLEAN, COSREJ, MEDFILT, MEDSKY, TIPPEX.
KAPPA: FFCLEAN, CHPIX, FILLBAD, GLITCH, MEDIAN, MSTATS, ZAPLIN.

[Source comments:]

 S C L E A N

 Main routine for the Figaro 'SCLEAN' command.  Displays
 a CCD image and then allows the user to move around it with
 the cursor, selecting rows and columns to be corrected and
 cosmic rays to be zapped.  The idea is that this routine can
 be used to fix up any areas in an image that were not fixed
 automatically by the non-interactive version ('BCLEAN').  It
 may also give a better idea of the best settings for the
 BCLEAN parameters.  A mode is provided especially suited for
 examination of SCUBA data files.

 The task works internally with a quality array, setting the
 bit specified by the parameter BITNUM to mark pixels as bad,
 but if the input NDF uses flagged bad values and no quality
 array, the output NDF will represent quality information in
 the same way.

 Variances are propagated, but if any changes are made to the
 data array, the corresponding element of the variance array
 is set to zero.  This is intended to mark it as a bad value,
 since Figaro does not support explicitly flagged bad values
 in the variance array.  If this has been done, the user is
 warned at the end of processing.

 Command parameters -

 IMAGE      (Character) The name of the image to be displayed.
 OUTPUT     (Character) The name of the resulting cleaned image.
            If the same as IMAGE, the image is cleaned in situ.
 QUIT       (Logical) Used to confirm quitting the application.
 DEG        (Integer) Degree of fit to use for interpolation.
 XSIZE      (Integer) Size of deletion box in X.
 YSIZE      (Integer) Size of deletion box in Y.
 HIGH       (Real) Highest displayed data value.
 LOW        (Real) Lowest displayed data value.
 BITNUM     (Integer) Number of quality bit to modify.
 ZOOM       (Integer) Minimum pixel zoom factor.
 LOGFILE    (Character) The name of a file to log to.  If null,
            no logging is performed.
 BATCHFILE  (Character) The name of a file (in SCLEAN log file
            format) to draw batch input from.  If null (default),
            run in interactive mode.

 User variables -  ("<" output, "!" modified)

 (!) IMARRAY (Numeric array) Contains current image display
             parameters.
 (<) IMFILE  (Character) Contains name of currently displayed
             image file.
 (>) IDEV    (Character) Contains name of display device.

                                    MBT / IoA 29th July 1998