UMASS IMAGE SERVER HOWTO
This page describes a two-part system through which Postgres queries can be used to select and display 2MASS .fits images. The general format of of a select and display comand is:

psql -Atc "SELECT function() FROM table WHERE condition" wsdb | vfits

Vfits, a Pearl script written by Martin Weinberg, pipes a 2MASS image into ds9 for display. Raptor.astro.umass.edu and hawk.astro.umass.edu have the image system installed. In this section it is assumed that the user is at a raptor or hawk local console or has logged on to raptor or hawk with X-forwarding enabled (ssh -X user@raptor for example). In a later section of this document instructions will be given for installing the UMASS image server system on a user's machine. Users should note that the first user of the day may exprience a short delay because the image archive hard disks, which are mounted on on pegasus, are put into a standby state each night.
GET_IMAGE or GET_IMAGEH
The Postgres function get_image is used to select the geometrically best full relolution image from the science scans used in the 2MASS All-Sky data release. The alternate function get_imageh alternately selects the geometrically best h-compressed image for display. The function get_image does not require the use of 2MASS catalogs. It can be used to display the 2MASS sky at locations given in a user loaded table of coordinates. The coordinates will be marked on the DS9 image with a 10" radius circle centered on the coordinates.

Forms:
get_image(ra,decl,band)    
get_image(ra,decl,band,integer)
get_image(ra,decl,band,smallint)
get_image(ra,decl,band,text)

Ra and Decl are floating point coordinates. Band is 'j', 'h', or 'k'. The fourth argument, where present, is used to display information selected by the user at the top of the DS9 image.

Examples of the use of get_image:

psql -Atc "select get_image(0.0,90.0,'k')"  wsdb | vfits

This comand displays the geometrically most favorable k-band full resolution 2MASS All-Sky scan image of the north pole.

psql -Atc "select get_image(ra,decl,'j',pts_key) FROM twomass_psc WHERE j_m BETWEEN 7.0 and 8.0 LIMIT 5" wsdb | vfits

This command displays as many as five j-band images of sources in the All-Sky point-source catalog with j default magnitude between 7.0 and 8.0. The pts_key is displayed by DS9 above the image following the text "Image_Key=". To cycle through the images close the DS9 window.

psql -Atc "select get_image(ra,decl,'k') FROM my_table" wsdb

This command displays the 2MASS k-band sky at locations given in a user loaded table.  

psql -Atc "select get_image(ra,decl,'h',h_m_k20fe::text) FROM twomass_xsc WHERE h_m_k20fe < 10.5 LIMIT 2" wsdb | vfits

This command displays as many as two 2MASS h-band galaxy images with h_m_k20fe < 10.5. The value of h_m_k20fe is displayed in the upper border of the DS9 window. The cast of h_m_k20fe is changed to text to match the function definition. This re-casting may not be necessary in some versions of Postgres.
GET_COADD or GET_COADDH
In certain cases the user may wish to require that an image be located in a specific scan. (Many 2MASS sources have been imaged in more than one scan.) An image is uniquely specified by date, hemis, scan, coadd, and f_type. Therefore the usual application of this function is to view specific sources in 2MASS catalogs. The function always returns only one image. If no ra,decl are provided no locating circle will be plotted in the DS9 window. The alternate form of the function get_coaddh returns an h-compressed image. Note that not all images are available in h-compressed form.

Forms:
get_coadd(date,hemis,scan,coadd,band)
get_coadd(date,hemis,scan,coadd,band,ra,decl)
get_coadd(date,hemis,scan,coadd,band,ra,decl,integer)
get_coadd(date,hemis,scan,coadd,ra,decl,smallint)
get_coadd(date,hemis,scan,coadd,ra,decl,text)

Example of the use of get_coadd:

psql -Atc "SELECT get_coadd(date,hemis,scan,coadd,'j',ra,decl,j_m) FROM twomass_psc WHERE j_m < 0.0 LIMIT 5" wsdb returns

/image_archive/ia_3/000903s/s029/j000903s029M115.fits.bz2 335.006818 -80.439667 -0.081
/image_archive/ia_3/000306s/s116/j000306s116M221.fits.bz2 211.332788 -76.796776 -0.676
/image_archive/ia_3/000418s/s126/j000418s126M139.fits.bz2 252.166231 -69.02774 -0.35
/image_archive/ia_3/000218s/s072/j000218s072M092.fits.bz2 184.392771 -67.960701 -0.163
/image_archive/ia_3/000108s/s082/j000108s082M139.fits.bz2 143.060818 -62.78886 -0.363

The following examples illustrate the use of get_coadd with vfits:

psql -Atc "select get_coadd(date,hemis,scan,coadd,'j',ra,decl) FROM twomass_psc where pts_key=40" wsdb | vfits

Displays the an image of the point source with pts_key=40 in the scan in which it is located. A 10" radius circle marks the source in the DS9 window.

psql -Atc "select get_coadd(date,hemis,scan,coadd,'j',ra,decl,pts_key) FROM twomass_psc where pts_key=40" wsdb | vfits

 Displays the an image of the point source with pts_key=40 in the scan in which it is located. A 10" radius circle marks the source in the DS9 window. The value of pts_key is shown on the upper border of the DS9 window.
COUNT_IMAGES
The function count_images returns an integer which is the number of images in the archive in which the coordinates entered in the argument are visible.

Forms:
count_images(ra,decl,s_type,f_type,cat)
count_images(ra,decl,s_type,f_type)

Examples of the use of count_images:

psql -Atc "select count_images(0.0,90.0,'sci','M','y')" wsdb
Returns the number of full resolution science scan images in which the north pole is visible in scans present in the All-Sky data release. (311)

psql -Atc "select count_images(0.0,90.0,'sci','M')" wsdb
Returns the number of full resolution science scan images in which the north pole is visible. (682)
GET_ALL_IMAGES
The SQL function distance(ra1,decl1,ra2,decl2) which returns the unsigned distance between two points 1 and 2 on the sphere in arc secods is used in the queries that follow. This function is valid for all points on the sphere including the poles. This function as well as the functions described in the previous section must be created in the database to permit spatial image queries.

The bash script get_all_images returns all UMASS modified All Sky Catalog images contaiing the point (ra,decl) in the specified band. This task can not be coded as a SQL function because a SQL function returns only one result.

Example:  ./get_all_images 276.0 -88.0 k returns:

/image_archive/ia_3/000422s/s103/k000422s103M186.fits.bz2 276.0 -88.0 224.12
/image_archive/ia_3/000422s/s105/k000422s105M186.fits.bz2 276.0 -88.0 170.24
/image_archive/ia_3/000422s/s104/k000422s104M186.fits.bz2 276.0 -88.0 136.91
/image_archive/ia_3/000422s/s112/k000422s112M186.fits.bz2 276.0 -88.0 276.99

The bold-italic numbers in the above table are the distance between the point ( 276.0, - 88.0 ) and the center of the coadd. These numbers are not returned by the function get_all_images but will be used here to illustrate the get_image function.

The best image of a position on the sky is the coadd whose center is closest to the reference point provided that the coadd contains the reference point. The postgres function get_image ( ra, decl, band ) discussed above returns the best UMASS modified All Sky Catalog image.

Example: psql -Atc "select get_image( 276, -88.0, 'k' )" wsdb returns:

 /image_archive/ia_3/000422s/s104/k000422s104M186.fits.bz2 276 -88
SETTING UP A 2MASS POSTGRES IMAGE SERVER ON A USER MACHINE

Create the following directories on the user machine:

/image_archive/ia_1
/image_archive/ia_2
/image_archive/ia_3

Within the astro.umass.edu domain the 2MASS image archive disks may be NFS mounted from pegasus by executing the mount_nfs command. The directories may be umounted by executing the umount_nfs command. Outside the astro.umass.edu domain the user will have to obtain and mount the three 750GB hard disks that comprise the 2MASS mage archive.

Install Postgres and create a database with the name wsdb.
load the images table into wsdb.  Analyze the table.
Execute the following bash scripts (the order matters) to create the postgres image server functions.

create_function_distance
create_function_get_coadd
create_function_get_coaddh
create_function_get_image
create_function_get_imageh
create_function_count_images

Download, un-tar, and place the i_386 or x86_64 version of DS9 in the user path. In SuSE Linux put executables in /usr/local/bin. Download and place vfits in the user path. Download and compile H-Compress executables. Put hdecomp in the user path. Download get_all_images and get_all_imagesh and put them in the user path. Note that the executables used in this section apart from H-Compress may be conveniently created by downloading the file all_files.tar.gz to a temporary directory and executing the command tar -zxvf all_files.tar.gz.
Edited by R. Stiening on May 8, 2007