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:
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 '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. 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=4556. Transformation for the Hitomi SXI, where multiseg parameters are set on the command line to specify segment AB, read node A, and full 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="0,0,0,640" rawtodetseg=2 winoffsetx=0 winoffsety=1
The design of this task is based on coordevt in the ftools package.