Extracting Mask Images

We have created a standalone code that serves to both extract masks and as a template library for inclusion in other codes. The code is available as: readAtlasImages-v5_4_11.tar.gz.

Compiling

1. % make clean

2. % make

If you are on a big-endian machine, remove -DSDSS_LITTLE_ENDIAN from CFLAGS in the Makefile.

Using

% read_mask -h

Usage: read_mask [options] input-file hdu output-file
The HDU may be a number (>= 1), or a name such as CR or INTERP
If -p is absent, the output-file will be a 8-bit FITS image;
If -p is specified, the output-file will be a list of vertices.

Your options are:
       -?      This message
       -h      This message
       -p      Calculate polygonal approximations (if so compiled)
       -i      Print an ID string and exit
       -v      Turn up verbosity (repeat flag for more chatter)

To reconstruct the z INTERP mask from run 1336, column 2, field 51 you'd say:

%  read_mask fpM-001336-z2-0051.fit 1 foo.fit 

The resulting file (foo.fit) would be a char FITS file, with a 1 in each pixel that was interpolated. The bitplanes are:

  typedef enum {
      S_MASK_INTERP = 0,           /* pixel's value has been interpolated */
      S_MASK_SATUR,                /* pixel is/was saturated  */
      S_MASK_NOTCHECKED,           /* pixel was NOT examined for an object */
      S_MASK_OBJECT,               /* pixel is part of some object */
      S_MASK_BRIGHTOBJECT,         /* pixel is part of bright object */
      S_MASK_BINOBJECT,            /* pixel is part of binned object */
      S_MASK_CATOBJECT,            /* pixel is part of a cataloged object */
      S_MASK_SUBTRACTED,           /* model has been subtracted from pixel */
      S_MASK_GHOST,                /* pixel is part of a ghost */
      S_MASK_CR,                   /* pixel is part of a cosmic ray */
      S_NMASK_TYPES                /* number of types; MUST BE LAST */
   } S_MASKTYPE;

with HDU _one_ corresponding to plane _zero_ (INTERP). You can specify these HDUs by name (e.g. OBJECT) or number (4). With the -p flag, instead of generating a FITS file, a description of each mask object as a set of convex polygons is written in ascii to the output file; the format should be obvious. One caveat: the vertices of the polygons are the pixel indices, so the boundaries pass _through_ the edge pixels, and the quoted areas are not quite the areas of the polygons that include all of the area.

The current version of this polygonal approximation code in fact generates exactly one polygon per photo object, the convex hull.

Developer Comments

The standalone programs read_atlas_image (reads fpAtlas files) and read_PSF (reads fpField files) are similar. All three are built by the same 'make' command.

I don't expect that many users will actually want to use the read_mask executable (although it is perfectly functional). The main use of the product will probably be to link into custom built executables that need to process atlas image data. I believe that the code should be easily reused for this purpose.