BAD PIXEL MASKING FAQ

How do I mask out bad pixel regions in GALFIT?

To exclude pixels from the fit, GALFIT can read in an ASCII text file or a FITS image in option ``F''. The formats are the following:

Text File: If the input file is in ASCII (i.e. text), all coordinates listed in the file are ignored during the fit. The format is simply a list of ``x y'' coordinates (with no comma separator).

FITS Image: If the bad pixel input file is a FITS image, all non-zero valued pixels would be ignored during the fit. Note that one can also use the SExtractor segmentation map in GALFIT. Except, be sure to ``zero-out'', from that map, pixel values of the object that one is trying to fit to allow GALFIT to ``see'' it.

Masking out pixels one by one is tedious, how do I mask out a region more easily?

Sometimes you may come across a situation where you need to mask out a whole lot of pixels, but the region you're trying to mask has a complex shape. In that situation, it would be nice if one can draw some shape around that region. That is possible, as shown in the following figure:

Above: an example of an image mask. The green outline is the polygon drawn into SAOimage DS9, and the filling is done by the ``fillpoly'' program.

The easiest way to mask out a large region interactively is to use SAOimage DS9 in conjunction of two algorithms ``ds9poly.c'' and ``fillpoly.f'' that I provide, with instructions below. The steps look long, but once everything is set up, the only steps to remember are: draw polygon, run ``ds9poly'', and run``fillpoly''.

Download ds9poly.c: First, download my ds9poly.c program. I will explain how to use this below. But, first compile it by doing:

cc -o ds9poly ds9poly.c

Download fillpoly.f: Next, download my fillpoly.f program. I will explain how to use this below. But, first compile it by doing:

f77 -o fillpoly fillpoly.f

Download SAOimage DS9: Now download SAOimage DS9. This will let you draw polygons over the region you want to mask out without having to guess.

Drawing a polygon into DS9: Click on the "Region" button, then the "Poly" button. Create a polygon by click-dragging (don't just click -- you'll have to drag too) a square box in the image. You start out with a square, but you can add vertices by clicking and dragging on the green border. You can also delete vertices by putting your cursor carefully on a vertex and hitting the ``Backspace''key (if you delete the polygon by accident, go to the ``Edit'' menu and hit ``undo'').

Saving the polygon: Once you have a polygon to your liking, output the polygon file. To do so, click on a button on the lower right hand corner, which might also be called ``region'' or (in newer version of DS9) ``more''. Select, ``Save''. Note: Do not save more than one polygon if you want to use my task below. If ``ds9poly'' freezes, it could be because of this. Below, I'll call the output file ``ds9out.''

Run ds9poly: From the DS9 output in the previous step, run ds9poly you compiled above by doing:

ds9poly ds9out > vertices

Take a look at the ``vertices'' file. You'll notice that ``ds9poly'' only parses the output ``ds9out'' into 2 columns. You can now use ``vertices'' directly in ``fillpoly'' above.

If your polygon is superposed on a GALFIT image block (such as the residual image), make sure to add back the appropriate pixel offsets if you're only working on a subregion. A simple way is to type on the Linux/Unix command line (where xmin and ymin are from Parameter H in the GALFIT input file):

awk '{print $1 + (xmin-1), $2 + (ymin-1)}' vertices > new_vertices

* If ds9poly ``hangs'', there's a problem with the DS9 file. Take a look at it to make sure there's not more than one polygon listed in the file. If this is not a problem then....

* Note that some versions of DS9 do not have the same output format, which may give ``ds9poly'' some trouble. If so, feel free to email me (and attach the DS9 file), or fix ds9poly.c if you know how.

Run fillpoly: ``fillpoly'' is a program that produces a list of pixels inside a polygon region. The input file is a coordinate list of polygon vertices, again, in 2 column format (x y, no comma separator). The coordinates only have to be in consecutive order around a polygon, and the directionality (clock-wise or counterclock-wise) doesn't matter. To run fillpoly, simply type on the command line:

fillpoly

Then give the polygon input file and the name of the output file. Or, you can do it all on the command line:

fillpoly vertices.txt mask.txt

You can now use the output file directly in Option F in GALFIT.

Oh, one more thing: ``fillpoly'' appends to an output file rather than overwrites it. This saves an extra step of having to concatenate multiple masks if you want to do so. So please keep this in mind in case something funny happens. Always examine what you created (using the following step) if you're not sure.

Examining what you think you've created: You're officially done at this point. But, if you're like me, then a list of pixels is not exactly a confidence builder that such a complex polygon filling scheme has worked right. To see, as an image, what exactly you had created and masked out, you can use a handy-dandy task called ``badpiximage'' in IRAF/imred/ccdred package. To generate an image from the pixel list (which I'll call polygon.txt) that you created using ``fillpoly'' in the previous step, do the following:

badpiximage polygon.txt data_image.fits newmask.fits goodval=0 badval=1

where, data_image.fits is the image that you're asking GALFIT to fit, *not* the output image block (there may be an offset due to the fitting region used -- see two bullet points above). You can now display newmask.fits to see if the masking has been done correctly. Incidentally, you can also feed this image into GALFIT (in Option F) instead of the ASCII file. If ``fillpoly'' did not work correctly, send me an email, providing me the DS9 polygon file, and I'll check to see what the problem may be.