Creating Postage Stamp Request Files

up to PostageStampServer

Note: This page has not been updated to include the request version 2 features.

Postage Stamp request files are FITS tables.

We expect that various science servers and other users will have their own programs for building request files.

To help with testing the postage stamp server we have written a simple script called pstamp_request_file, which is installed as part of the standard IPP installation. It may be found in the IPP source tree in the directory pstamp/scripts.

This script has no IPP dependencies but does use the perl module Astro::FITS::CFITSIO.

The input to this program is a text file. For example

# test2.txt

# A sample Postage stamp request description file
# This can be parsed by the program pstamp_req_create to build a 
# PS1_PSTAMP_REQUEST fits binary table.

# First line of data is for the extension header
#
# Note that value for REQ_NAME may be overriden by the pstamp_req_create
# command line argument --req_name
# Blank and comment lines (like this one) are ignored

# REQ_NAME   EXTVER ACTION email
CHANGEME     2 PROCESS myemail@myinstitution.edu

# subsequent lines define the rows in the table

# If ROWNUM is set to zero, pstamp_request_file will set insert a value for
# each row beginning with 1

# Fields are separated by spaces. Text after the | character is saved in the
# request table in the column comment

#
# ID    |     ROI Specification                   |  JOB Specification |  Images of interest specification
# ROWNUM CENTER_X    CENTER_Y  WIDTH HEIGHT COORD_MASK JOB_TYPE OPTION_MASK PROJECT SURVEY_NAME IPP_RELEASE REQ_TYPE IMG_TYPE    ID   TESS_ID COMPONENT DATA_GROUP  REQFILT MJD_MIN MJD_MAX RUN_TYPE FWHM_MIN FWHM_MAX | COMMENT
#
1       18.876667     -0.861489 100    100      2        stamp       1        gpc1 3PI            3PI.PV3 bycoord   chip       null    null   null           null        null 55249   0   null 0 0 |search by coords
# just change the coordinates for the next request keep other params the same
2       18.87         -0.8616  100    100      2  | different coords in same images of interest

The columns in the request file have three purposes

  • Define the "Region of Interest"
  • Define the "Images of Interest"
  • Specify what the job does

The region of interest has a center and width and height. The center may be given in either sky coordinates (RA and DEC) or in pixels. How these columns are interpreted depends on the value of the COORD_MASK. The usage of COORD_MASK is described in detail in the ICD. Currently

0 center in RA/DEC; width & height in arc seconds
1 center in pixel coordinates; width and height in arc seconds
2 center in RA/DEC; width and height in pixels
3 center x/y, width, and height in pixel coordinates

These sample requests all use the most commononly used mode (COORD_MASK = 2). This means that center is specified in sky coordinates while width and height are in pixels.

The images of interest may be selected in many ways. The REQ_TYPE column has the following values

  • byid
  • byexp
  • byskycell
  • bydiff
  • bycoord

The first two rows are bycoord requests. Requests of this type are currently quite expensive for the postage stamp server to process. Depending on the field they can generate a large number of images of interest (many which are probably not available).

The other rows use the REQ_TYPE byid. This specified the chip_id and class_id of the image of interest.

Many of the other columns apply cuts to the images of interest. In the first request MJD_MIN and MJD_MAX are set restricting the look ups to a given date range If a column with string type is not needed for a given request specification it may be given the value 'null'. In the first row ID, TESS_ID, COMPONENT, DATA_GROUP, and REQFILT are null.

For the second row we want to just change the coordinates so we just provide the ROI specification. The other parameters will be copied from the previous row.

OPTION_MASK is used to select which data products are returned. This value is a bitwise or of the following values

  • PSTAMP_SELECT_IMAGE = 1;
  • PSTAMP_SELECT_MASK = 2;
  • PSTAMP_SELECT_VARIANCE = 4;
  • PSTAMP_SELECT_CMF = 8;
  • PSTAMP_SELECT_PSF = 16;
  • PSTAMP_SELECT_BACKMDL = 32;
  • PSTAMP_SELECT_JPEG = 64
  • PSTAMP_SELECT_UNCOMPRESSED = 512
  • PSTAMP_SELECT_INVERSE = 1024;
  • PSTAMP_SELECT_UNCONV = 2048;
  • PSTAMP_RESTORE_BACKGROUND = 4096
  • PSTAMP_NO_WAIT_FOR_UPDATE = 32768

Row 1 selects stamps from the image. Row 3 also requests stamps from the mask and variance images. Row 5 requests that the sources (cmf), psf, and background model files from the chipRun be included in the results file set. Note that the region of interest has no effect on these data products. They are returned in full.

ndeacon- I've written a very simple bit of c code that takes an input filename, a name for the request and a filter request (ie. y,z,null etc) and writes a table (or several tables of up to 1000 objects for large requests) for putting in to pstamp_request_file. It only gives a 100*100 pixel stamp image although feel free to edit it to do more stuff. The file is attached.

Attachments