NAME

USAGE

DESCRIPTION

It converts in both directions (RAW to SKY and SKY to RAW) and through multiple sets of coordinates. See also the help file for the 'coordevt' tool.

'Coordpnt' supports all region shapes supported by the cfitsio 'regfilter' routine. Details about various region shapes can be found at http://ds9.si.edu/doc/ref/region.html.

The regions shapes supported by 'coordpnt' are listed below:

1. Circle: circle x y radius

2. Annulus: annulus x y inner outer n=# / annulus x y r1 r2 r3...

3. Ellipse: ellipse x y radius radius angle

4. Ellipse Annulus: ellipse x y r11 r12 r21 r22 n=# [angle] / ellipse x y r11 r12 r21 r22 r31 r32 ... [angle]

5. Box/Rectangle: box x y width height angle

6. Diamond: diamond point x y

7. PIE/Sector: xcenter ycenter angle1 angle2

8. Polygon: x1 y1 x2 y2 ... xn yn

9. Point: point x y # point=[circle|box|diamond|cross|x|arrow|boxcircle] [size] / circle point x y

10. Line: line x1 y1 x2 y2 # line=[0|1] [0|1]

11. Panda: panda x y startangle stopangle nangle inner outer nradius

12. Epanda: epanda x y startangle stopangle nangle inner outer nradius [angle]

13. Bpanda: bpanda x y startangle stopangle nangle inner outer nradius [angle]

When a region is transformed, all region descriptors (center, dimensions, rotations) are transformed so that in both the destination and origin system, the region covers the same part of the coordinate space. If there are multiple regions within a single input region file, then all regions are transformed to the final coordinate system.

Using the ra/dec/roll and ranom/decnom/rollnom parameters

'coordpnt' may be used to simulate deviations from the nominal pointing to mimic the effects in flight of any imperfections in the attitude control. This is done by adjusting the ranom/decnom/rollnom parameters separately from the ra/dec/roll of the actual pointing. By default, the 'ranom' and 'decnom' are set to the same value that of the pointing, and rollnom is set to 0.

These groups of parameters are used only in conversions that include the SKY coordinate system. 'coordpnt' maintains and uses two attitude quaternions. One for the nominal pointing, and the other for the actual pointing. The actual pointing, given by the parameters ra/dec/roll, represents the center of the field of view of the instrument, or the center of the FOC coordinate system. It corresponds to the time-dependent attitude in 'coordevt'. The nominal pointing, given by the parameters ranom/decnom/rollnom, represents the center of the SKY coordinate system and the orientation of the SKY system with respect to the Celestial coordinates. By default the positive SKY-Y axis points toward the North Celestial Pole ('rollnom=0.0').

The transformation between SKY and RADEC coordinates depends only on the nominal pointing ranom/decnom/rollnom and not on ra/dec/roll. The transformation between the focal plane (FOC) coordinates and SKY coordinates depends on the difference between the actual and nominal pointing. If the default parameter settings are used for ranom/decnom/rollnom, then this transformation is only a roll, determined by the 'roll' parameter. If the user chooses to vary 'ranom' and 'decnom' separately from 'ra' and 'dec', then the transformation includes a linear shift in X and Y in addition to a roll.

Hitomi specific configuration: Multiseg and winoffset parameters

The following parameters multisegpar', 'winoffsetx' and 'winoffsety' are used in the transformation and currently set at default values appropriate for one of the Hitomi/SXI mode. To modify them, users are advised to read the documentation on coordinate system relative to the mission. Below is a short summary for Hitomi.

The 'multisegpar' parameters are used when the input teldeffile contains a 'TRTYPEn = MULTISEG' transformation. This type of transformation involves an initial coordinate system that is multiplexed in some way (e.g. origin X0, Y0 could transform to multiple different destination Xi, Yi). The 'multisegpar' parameters determine the specific transformation to be applied by indexing a MULTISEGn_COEFF table in the teldef file. 'Coordpnt' retrieves the proper coefficients from the table based on the values of the 'multisegpar' parameters and uses these coefficients to build the appropriate transformation based on a hard-coded algebraic formula. This formula also uses the values of two other parameters 'winoffsetx' and 'winoffsety', which are supplied as separate parameters. Below is an example from the Hitomi/SXI.

In the SXI, there are four 'multiseg' properties, which are used to decode the event data in the transformation from the RAW to the ACT coordinates. The properties are listed in the order in which they appear in the SXI TelDef file, which is the order in which the 'multisegpar' parameters must be given.

1. SEGMENT. Each SXI CCD chip has two independent segments, called AB and CD. A photon can land on either segment and the segment ID, 'SEGMENT=0' for segment AB or SEGMENT=1 for segment CD is written to the data stream.

2. READNODE. Each segment has two read-out nodes, A and B for segment AB and C and D for segment CD. The choice of read-out node is commendable in the flight software. The choice of readout nodes is written to the data stream, where 'READNODE=0' denotes node A or C and 'READNODE=1' denotes node B or D.

3. WINOPT. The SXI chips can be operated in commendable "window" modes, wherein a specified part of a chip is read out multiple times during a read out interval. The WINOPT property is set to 'WINOPT=0' if windowing is not used (full chip read out) or to 'WINOPT=1' if windowing is used.

4. WIN_SIZE. There are four possible sizes of the window that can be read out in windowing mode, including full chip readout. The commendable size of the window is written to the data stream with one of four possible values: 'WIN_SIZE=640' for full chip read out, 'WIN_SIZE=160' for 1/4 chip read out, 'WIN_SIZE=80' for 1/8 chip read out and 'WIN_SIZE=40' for 1/16 chip read out. These are not independent of WINOPT; 'WIN_SIZE=640' only applies for 'WINOPT=0', the other values of WIN_SIZE can apply when 'WINOPT=1'.

The SEGMENT, READNODE and WIN_SIZE properties are all set independently, yielding a total of 16 (2 x 2 x 4) possible combinations.

As an example, to simulate a situation where a photon is read out in segment AB, read node B, with 1/8 windowing mode, one would provide multisegpar parameters "0,1,1,80", for 'SEGMENT=0, READNODE=1, WINOPT=1, WIN_SIZE=80'. Similarly setting multisegpar="1,0,0,640" would mean segment CD, node C, full windowing mode. Any out of range or incompatible parameters leads to an error, like for example multisegpar="2,0,0,640" (out of range) or "1,0,1,640" ('WINOPT' and 'WIN_SIZE' options incompatible).

The 'winoffsetx' and 'winoffsety' parameters are related to the windowing mode, but are set independently. For SXI, 'winoffsetx' should always be zero (it is in fact ignored in the SXI TelDef), and 'winoffsety' can vary, but is nominally linked to WIN_SIZE:

1. WIN_SIZE=640, winoffsety=1
2. WIN_SIZE=160, winoffsety=415
3. WIN_SIZE=80, winoffsety=455
4. WIN_SIZE=40, winoffsety=475

Currently The Hitomi/SXI is the only instrument to use the MULTISEG capabilities.

PARAMETERS

input [string]

Input point or region to be transformed. The input string can be one of the following.

1) A pair of numbers separated by a comma, representing a single point in the coordinate system specified by the startsys parameter. The default is the lowest-level coordinate system defined in the teldef file.

2) A single pixel number in the case where the startsys coordinate system is represented by pixel numbers, as opposed to positions in a coordinate grid.

3) The name of an ASCII region file containing at least one standard format region defined in the startsys coordinate system.

outfile [filename]

This parameter should be set to "NONE" except when the input parameter is a name of a file. Then it is set to the name of the output file that contains the regions transformed from the startsys to the stopsys coordinate system.

telescop [string]

The name of the telescope for which the coordinate systems in the transformation are defined. The value of telescop must be the name of a valid mission (e.g. Swift, Suzaku, Hitomi) and must match the TELESCOP keyword in the teldef file.

instrume [string]

The name of the instrument for which the coordinate systems in the transformation are defined. The value of instrume must be the name of a valid instrument on the mission given by telescop and must match the INSTRUME keyword in the teldef file.

ra = -999.000 [real]

The Right Ascension in decimal degrees of the actual pointing, representing the center of the field of view of the instrument. This must be a value between 0 and 360.

dec = -999.000 [real]

The declination in decimal degrees of the actual pointing, representing the center of the field of view of the instrument. This must be a value between -90 and +90.

roll = 0.0 [real]

The roll angle in decimal degrees between the SKY coordinate system and the FOC coordinate system. The roll angle is about the center of the SKY system and is measured counterclockwise from the positive SKY Y axis to the positive FOC Y axis.

(ranom = -999.000) [real]

The Right Ascension in decimal degrees of the nominal pointing, representing the center of the SKY coordinate system. When set to -999.000 (the default), 'ranom' is identical to 'ra'. Otherwise, this must be a value between 0 and 360.

(decnom = -999.000) [real]

The declination in decimal degrees of the nominal pointing, representing the center of the SKY coordinate system. When set to -999.000 (the default), 'ranom' is identical to 'dec'. Otherwise, this must be a value between -90 and +90.

(rollnom = 0.0) [real]

The roll angle in decimal degrees between the SKY coordinate system and the Celestial coordinates. The roll angle is about the center of the SKY system and is measured counterclockwise from the North celestial axis to the positive SKY Y axis. By default, 'rollnom' is set to zero, which aligns the SKY system with the Celestial system.

(teldeffile = CALDB) [filename]

Name of the Telescope Definition (TelDef) file, which specifies the coordinate systems and transformation properties. If the parameter is set to CALDB, the default, the file is read from the calibration database. If a file name is provided, then the TELESCOP and INSTRUME keywords in the file must match exactly the values of the telescop and instrume parameters. The tool supports TelDef file format versions 0. through 0.2.

(startsys = LOWEST) [string]

The name of the starting coordinate system of the requested conversion. When startsys is set to 'LOWEST', the default, the conversion begins with the lowest level system present in the teldef file as identified by the parameter 'COORD0', usually 'RAW'. Setting startsys=HIGHEST and stopsys to LOWEST, the task converts the top-level coordinates into all the other coordinate systems. In addition to the coordinate systems defined in the teldef file, 'startsys' can be set to 'RADEC', which indicates that the output coordinates are the pair (ra,dec) in decimal degrees.

(stopsys = HIGHEST) [string]

The name of the ending coordinate system of the conversion. If stopsys is set to HIGHEST, then the coordinate transformation chain ends with the highest-level system, usually 'SKY'. In addition to the coordinate systems defined in the teldef file, 'stopsys' can be set to 'RADEC', which indicates that the output coordinates are the pair (ra,dec) in decimal degrees.

(multisegpar = NULL) [string]

The values of the multi-segment parameters, which are required when the teldef file contains a 'TRTYPEn = MULTISEG' transformation (e.g. Hitomi SXI). These parameters must be specified as a list of numbers separated by a comma in with the following way: a) There must be one number for each parameter. b) The numbers must be in the same order as in the teldef. c) The numbers must be within their allowed range (see the example given above).

EXAMPLES

1. Basic transformation from RAW to SKY coordinates, using the teldef file from the calibration database for the Suzaku XIS0.

coordpnt input="51,51" outfile="NONE" telescop="Suzaku" instrume="XIS0" \
ra=0.0 dec=90.0 roll=90.0 teldeffile="CALDB" 

2. Transformation from RAW to SKY coordinates of a region file, using the teldef file from the calibration database for the Suzaku XIS0.

    
coordpnt input="region.ds9" outfile="region-out.ds9" telescop="Suzaku" \
instrume="XIS0" ra=0.0 dec=90.0 roll=90.0 teldeffile="CALDB" 

3. Transformation of a region file from ACT to FOC coordinates, using a user-specified teldef file for the Swift XRT

    
coordpnt input="region.ds9" outfile="region-out.ds9" telescop="Swift" \
instrume="XRT" ra=187.413 dec=-62.998 roll=216.38 teldeffile="swxrt-teldef.fits" \
startsys=ACT stopsys=FOC clobber=yes

4. Transformation from RAW to SKY coordinates for the Hitomi SXS, using the teldef file from the calibration database. The input is a single pixel number.

coordpnt input=15 outfile="NONE" telescop="HITOMI" instrume="SXS" \
ra=0.0 dec=90.0 roll=90.0 teldeffile="CALDB" 

5. Transformation for the Hitomi SXI, where multiseg parameters are set on the command line to specify segment CD, read node C, and 1/8 windowing mode (see Description above for more details on the meanings of these parameters).

coordpnt input="124,56" outfile="NONE" telescop="HITOMI" \
instrume="SXI" ra=50.0 dec=-32.45 roll=85.88 teldeffile="CALDB" \
multisegpar="1,0,1,80" rawtodetseg=2 winoffsetx=0 winoffsety=455

coordpnt input="124,56" outfile="NONE" telescop="HITOMI" \
instrume="SXI" ra=50.0 dec=-32.45 roll=85.88 teldeffile="CALDB" \
multisegpar="0,0,0,640" rawtodetseg=2 winoffsetx=0 winoffsety=1

SEE ALSO

The design of this task is based on coordevt in the ftools package.

LAST MODIFIED