STScI Logo

be_ds_rotate xray.xspatial.eintools


NAME · USAGE · DESCRIPTION · WARNINGS · EXAMPLES · TIME_REQUIREMENTS
BUGS · SEE_ALSO

NAME

be_ds_rotate -- rotate IPC bright Earth and deep survey maps using BKFAC table

USAGE

be_ds_rotate qpoefile bkfacfile rbkmap pi_band original_data [defmaps ...]

DESCRIPTION

The task be_ds_rotate will apply the aspect and weights within a background factors table to the input bright Earth and deep survey map to produce a final rotated background map. The rotation and scaling algorithms used are those from the images.geotran task. (See that task for more details on the algorithms.)

The user can create background factors tables from two possible methods. The IPC unscreened CDROM contains a background factors table within the ".bk" FITS file. Using this table as input, this task will recreate the original soft or hard background map from the Level One processing. In this case, the user should use the original bright Earth and deep survey maps.

The other possible method is to use the table generated by the tasks bkfac_make and calc_factors , which calculate the aspects and weights from the QPOE file. The user can use the default bright Earth and deep survey maps if the PI band is one of soft, hard, or broad. Otherwise the user must supply a BEMAP and DSMAP. (See "help making_be_ds_maps".)

PARAMETERS

qpoefile = "" prompt = input QPOE file [root.qp]

The input qpoe file name. The extension ".qp" will be added to the file if there is no extension.

bkfacfile = "." prompt = bkfac table [root_bkfac.tab]

The input background factors table. If no root is given, the file name will be the root of the reference QPOE file followed by the "_bkfac.tab" suffix. If the user supplies a name without an extension, the default extension will be "_bkfac.tab".

rbkmap = "." prompt = output rotated bkgd image [root_bkg.imh]

The output rotated background map. If no root is given, the output file name will be the root of the reference QPOE file followed by the "_bkg.imh" suffix. If the user supplies a name without an extension, the default extension will be "_bkg.imh".

pi_band = "all" prompt = PI band

The PI band to use for the final rotated background map. This can be any of "all", "soft", "hard", "broad", or some range of values, such as "1:5" or "4:6,12:14". The bands correspond to the following ranges: soft=2:4, hard=5:10, broad=2:10, all=0:15. The bands can be abbreviated ("s", "h", etc.).

original_data = yes prompt = recreating original background map?

This should be "yes" if the user is attempting to recover the original Level One processing background map, using the background factors table extracted from the IPC unscreened CDROMs. This task will then use the original soft or hard bright Earth and deep survey maps. This parameter should be "no" if the user ran bkfac_make to create a new BKFAC table.

defmaps = yes prompt = use default BE and DS maps?

[Only prompted for if original_data is "no".]

If the PI band is one of "hard", "soft", or "broad", and if this parameter is "yes", this task will use the appropriate default bright Earth and deep survey maps from the eintoolsdata$ directory. (Note: the default deep survey map is the sum of three maps at different BALs, with an average BAL of 15.2.)

bemap = "" prompt = input bright Earth map

If not using the default bright Earth map, the user must provide the pathname of the appropriate bright Earth map.

dsmap = "" prompt = input deep survey map

If not using the default deep survey map, the user must provide the pathname of the appropriate bright Earth map.

(xscale = 1.0) [double]

Specifies how much the final image should be scaled in the X dimension. If the scaling is above one, the background map will be expanded; less than one, compressed. If xscale is left as 1.0, the final image will be the same size as the QPOE image, i.e. 1024 pixels wide. If xscale=2.0, this task will produce an image twice the width, i.e., 2048 pixels wide.

(yscale = 1.0) [double]

Specifies how much the final image should be scaled in the Y dimension. If the scaling is above one, the background map will be expanded; less than one, compressed. If yscale is left as 1.0, the final image will be the same size as the QPOE image, i.e. 1024 pixels high. If yscale=2.0, this task will produce an image twice the height, i.e., 2048 pixels high.

(def_be_hard = "eintoolsdata$bemaph") [string]

Pathname for the default bright Earth map for the hard band.

(def_ds_hard = "eintoolsdata$dsmaph") [string]

Pathname for the default deep survey map for the hard band.

(def_be_soft = "eintoolsdata$bemaps") [string]

Pathname for the default bright Earth map for the soft band.

(def_ds_soft = "eintoolsdata$dsmaps") [string]

Pathname for the default deep survey map for the soft band.

(def_be_broad = "eintoolsdata$bemapb") [string]

Pathname for the default bright Earth map for the broad band.

(def_ds_broad = "eintoolsdata$dsmapb") [string]

Pathname for the default deep survey map for the broad band.

(orig_be_hard = "eintoolsdata$bemapho") [string]

Pathname for the original bright Earth map for the hard band.

(orig_ds_hard = "eintoolsdata$dsmapho") [string]

Pathname for the original deep survey map for the hard band.

(orig_be_soft = "eintoolsdata$bemapso") [string]

Pathname for the original bright Earth map for the soft band.

(orig_ds_soft = "eintoolsdata$dsmapso") [string]

Pathname for the original deep survey map for the soft band.

(br_edge_reg = "box 256.256.5 226 226") [string]

The bright edge region to be applied to BE and DS images. This is meant to screen out the bright edges in unscreened data. If the user modifies this region, the user should also modify the bright edge filter in any other tasks run. (The filter must describe the same area as the bright edge region.)

(xsample = 1.0, ysample = 1.0) [real]

[FOR ROTATION AND SCALING:]

The coordinate surface subsampling factors. The coordinate surfaces are evaluated at every xsample-th pixel in x and every ysample-th pixel in y. Transformed coordinates at intermediate pixel values are determined by bilinear interpolation in the coordinate surfaces. If the coordinate surface is of high order setting these numbers to some reasonably high value is strongly recommended.

(interpolant = "linear") [string]

[FOR ROTATION AND SCALING:]

The interpolant used for rebinning the image. The choices are the following.

nearest
Nearest neighbour.
linear
Bilinear interpolation in x and y.
poly3
Third order polynomial in x and y.
poly5
Fifth order polynomial in x and y.
spline3
Bicubic spline.
(boundary = "constant") [string]

[FOR ROTATION AND SCALING:]

The choices are:

nearest
Use the value of the nearest boundary pixel.
constant
Use a user supplied constant value.
(constant = 0.0) [real]

[FOR ROTATION AND SCALING:]

The value of the constant for boundary extension.

(nxblock = 256, nyblock = 256) [int]

[FOR ROTATION AND SCALING:]

If the size of the output image is less than nxblock by nyblock then the entire image is transformed at once. Otherwise the output image is computed in blocks nxblock by nyblock pixels.

(clobber = no) [boolean]

OK to overwrite the existing output file?

(display = 1) [int]

The display level. A setting of 0 should output no display (besides warnings), while settings above 3 are only useful for debugging.

WARNINGS

This task may produce warnings about the BKFAC table and the BE and DS maps.

"WARNING: BKFAC table PI band differs"

The PI band used to create the BKFAC table differs from the one requested.

"WARNING: Bright Earth PI band differs"

The bright Earth map is for a different PI band than the one used to make the BKFAC table.

"WARNING: Deep Survey Earth PI band differs"

The deep survey map is for a different PI band than the one used to make the BKFAC table.

"WARNING: Bright Earth map counts differs"

The number of counts in the bright Earth map differs than the number of counts found when the BKFAC table was created. This suggests that a different BE map was used to make the BKFAC table.

"WARNING: Deep survey map counts differs"

The number of counts in the deep survey map differs than the number of counts found when the BKFAC table was created. This suggests that a different DS map was used to make the BKFAC table.

"WARNING: Deep survey livetime differs"

The livetime of the deep survey map differs than the livetime found when the BKFAC table was created. This suggests that a different DS map was used to make the BKFAC table.

"WARNING: Nominal RA & DEC don't match between BKFAC & QPOE"

The QPOE used to make the BKFAC table had a different nominal RA & DEC than the current QPOE file.

EXAMPLES

1. Use be_ds_rotate to create a background map given a BKFAC table from bkfac_make.

ei> bkfac_make
input QPOE file [root.qp]: xdata$snr.qp
output background factor table [root_bkfac.tab] (.): 
PI band (all): broad

Created bkfac table ./snr_bkfac.tab with 1 row(s).
ei> calc_factors
input QPOE file [root.qp]: xdata$snr.qp
background factor table [root_bkfac.tab] (.): 
PI band (all): broad
input source counts: 3691.25
use default bright Earth and deep survey maps? (yes): 

WARNING: Total counts in the background factors table (20417.00000)
do not match the number of counts in the qpoe file (20420.00000).

Added background factors to table ./snr_bkfac.tab.
ei> be_ds_rotate
input QPOE file [root.qp]: xdata$snr.qp
input background factor table file [root_bkfac.tab] (.): 
output rotated background image [root_bkg.imh] (.): 
PI band (all): broad
recreating original background map? (yes): no
use default bright Earth and deep survey maps? (yes): 

This task will be rotating 1 image(s).

Rotating image # 1...

Scaling background map to (1.00,1.00)...

Created rotated background map ./snr_bkg.imh.
ei> imhead snr_bkg.imh l+
snr_bkg.imh[1024,1024][real]: 
    No bad pixels, no histogram, min=unknown, max=unknown
    Line storage mode, physdim [1024,1024], length of user area 2714 s.u.
    Created Fri 16:26:00 08-Apr-94, Last modified Fri 16:26:03 08-Apr-94
    Pixel file 'HDR$snr_bkg.pix' [ok]
    be_ds_rotate: ./snr_bkfac.tab -> ./snr_bkg.imh
    WCSDIM  =                    2
    CTYPE1  = 'RA---TAN'
    CTYPE2  = 'DEC--TAN'
    CRVAL1  =             344.7319
    CRVAL2  =             58.61319
    CRPIX1  =                 512.
    CRPIX2  =                 513.
    CDELT1  =         -0.002222222
    CDELT2  =          0.002222222
    CD1_1   =         -0.002222222
    CD2_2   =          0.002222222
    LTM1_1  =                   1.
    LTM2_2  =                   1.
    WAT0_001= 'system=image                                                        '
    WAT1_001= 'system=world wtype=tan axtype=ra                                    '
    WAT2_001= 'wtype=tan axtype=dec                                                '
    OBJECT  = 'CTB 109 '
    TELESCOP= 'EINSTEIN'
    INSTRUME= 'IPC-1   '
    RADECSYS= 'FK4     '
    EQUINOX =                1950.
    MJD-OBS =             44427.98
    DATE-OBS= '07/07/80'
    TIME-OBS= '23:26:57'
    DATE-END= '08/07/80'
    TIME-END= '01:37:20'
    OBS_ID  = '8102    '
    OBSERVER= '        '
    ROR_NUM =                  563
    ORIGIN  = 'USA     '
    FILTER  = 'NONE    '
    OBS_MODE= 'POINTING'
    TIMEREF = 'LOCAL   '
    TIMESYS = 'UNKNOWN '
    POISSERR=                    T
    MJDREFI =                43508
    MJDREFF =                   0.
    XS-EVREF=                    0
    XS-TBASE=     79486834.1453091
    ONTIME  =     4440.95999999344
    LIVETIME=     4255.77856097547
    DTCOR   =            0.9583015
    RA_NOM  =             344.7319
    DEC_NOM =             58.61319
    ROLL_NOM=            -51.30594
    XS-XPT  =                  512
    XS-YPT  =                  512
    XS-XDET =                 1024
    XS-YDET =                 1024
    XS-FOV  =                    0
    XS-INPXX=          0.002222222
    XS-INPXY=          0.002222222
    OPTAXISX=                514.5
    OPTAXISY=                499.3
    PHACHANS=                   16
    PICHANS =                   16
    MINPI   =                    0
    MAXPI   =                    0
    MINPHA  =                    0
    MAXPHA  =                    0
    FORMAT  =                    1
    REVISION=                    0
    CRETIME =            422632833
    MODTIME =            422632833
    PIBAND  = '2:10    '
    XS-NHIST=                    1
    XS-HIS01= 'be_ds_rotate: ./snr_bkfac.tab -> ./snr_bkg.imh'

2. Use be_ds_rotate to create a soft background map given an original BKFAC table and a Revision 1 IPC QPOE file.

im> be_ds_rotate
input QPOE file [root.qp]: i8703
input background factor table file [root_bkfac.tab]: i8703BKWCS.tab
output rotated background image [root_bkg.imh]: 
PI band (all): soft
recreating original background map? (yes): 

This task will be rotating 2 image(s).

Rotating image # 1...
Rotating image # 2...

Scaling background map to (1.00,1.00)...

Created rotated background map i8703_bkg.imh.

TIME REQUIREMENTS

This task takes under 2 minutes on a Sparc for a background factors table with one row. It takes under 10 minutes for a table with 14 rows.

BUGS

The WCS information in the final background map depends on the WCS information in the QPOE file. If this file has had its WCS information altered (i.e., with qplintran or wcsqpedit ) the constant aspect table may be inaccurate.

SEE ALSO

See bkfac_make and calc_factors for information on how the background factors table is generated.

See ecd2pros for information on how to retrieve the original BKFAC table from an IPC unscreened CDROM.

See rbkmap_make to see how this task is used to generate rotated background maps from a QPOE file.

Use "help making_be_ds_maps" for more information on creating deep survey and bright Earth maps for a specified band.

Use "help explain_bkfac" for more details on the contents of the BKFAC table.


Source Code · Search Form · STSDAS