NAME

USAGE

DESCRIPTION

The coordpnt task is a mission-independent tool for transforming either a single coordinate point or a region file from one coordinate system to another. The input is either a pair of numbers (single point mode) or a file name (region file mode).

This task converts either from a lower to a higher coordinate system (e.g., RAW to SKY) or from a higher to a lower coordinate system (e.g., SKY to RAW), including conversions that require intermediate steps through multiple coordinate systems (e.g., ACT, DET, and FOC).

The coordpnt task supports all region shapes supported by the CFITSIO regfilter routine. Details about the region file format, with a description of some existing variations, can be found at http://ds9.si.edu/doc/ref/region.html. Most of the region shapes are described, with examples, in http://hea-www.harvard.edu/RD/funtools/reggeometry.html.

The region shapes supported by coordpnt are listed below. The lower-case shape names (point, line, etc.) and hash symbols appear in the region files exactly as shown below, in order to facilitate use of the files by other software. The words in parentheses, e.g., x, y, and number, denote parameters of the shape that must be specified as numbers in the actual file. For coordpnt, the region specification must include the parentheses and commas:

Point:

point(x, y) # point=circle

Line:

line(x1, y2, x2, y2) # line 0 0

Circle:

circle(x, y, radius)

Annulus:

annulus(x, y, inner, outer)

Ellipse:

ellipse(x, y, radius, radius, angle)

Elliptical annulus:

ellipse(x, y, rx1, ry1, rx2, ry2, angle)

Box:

box(x, y, width, height, angle)

Box annulus:

box(x, y, width1, height1, width2, height2, angle)

Rectangle:

rectangle(x, y, x, y, angle, length, length)

Diamond:

diamond(x, y, length, length, angle)

Sector:

sector(x, y, number, number)

Polygon:

polygon(x1, y1, x2, y2, x3, y3, x4, y4, x5, y5)

Panda (pie and annulus):

panda(x, y, startangle, stopangle, nangle, inner, outer, nradius)

Epanda (elliptical panda):

epanda(x, y, startangle, stopangle, nangle, widthinner, heightinner, widthouter, heightouter, nradius, angle)

Bpanda (box panda):

bpanda(x, y, startangle, stopangle, nangle, widthinner, heightinner, widthouter, heightouter, nradius, angle)

In order to transform a region, all parameters are transformed so that in both the destination and origin system, the region covers the equivalent 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 two parameter sets 'ra/dec/roll', and 'ranom/decnom/rollnom'

The transformations that involve SKY coordinates are controlled by two sets of pointing parameters. One is the actual pointing of the satellite, supplied by the parameters 'ra', 'dec', and 'roll', and the other is the nominal pointing, supplied by the parameters 'ranom', 'decnom', and 'rollnom'. The nominal pointing simply defines the center of the SKY system and the transformation from the SKY coordinate system to the RA/DEC coordinate system does not depend on the actual pointing of the satellite. The actual pointing represents the primary aim point in the instrument field of view, which is also the center of the FOC coordinate system. The transformation between FOC and SKY coordinates depends on the difference between the actual and nominal pointing. The two sets of pointing parameters (actual and nominal) correspond to two different quaternions maintained internally by coordpnt. The quaternion corresponding to the actual pointing corresponds to the time-dependent spacecraft attitude.

By default, the coordinates of the nominal pointing are set to be the same as those of the actual pointing; i.e., 'ranom' = 'ra', and 'decnom' = 'dec'. Also by default, 'rollnom' is zero, which means that the SKY positive Y-axis points toward the North Celestial Pole. It follows that if the default parameter settings are used for 'ranom', 'decnom', and 'rollnom', then the transformation from FOC to SKY is only a rotation, determined by the 'roll' parameter.

If the user varies 'ranom' and 'decnom' separately from 'ra' and 'dec', then the transformation results a linear shift in X and Y. If the user chooses non-zero values for 'rollnom', then the applied rotation differs from the default one by the value of 'rollnom'.

Hitomi and XRISM parameters 'multiseg' and 'winoffset'

The parameter 'multisegpar' contains a set of values to be used when the input teldef file contains a transformation described by a keyword of the form TRTYPEn=MULTISEG. This type of transformation involves an initial coordinate system that is multiplexed in some way (e.g., input coordinates x0, y0 could transform to multiple different outputs xi, yi). The 'multisegpar' parameters determine the specific transformation to be applied by indexing a MULTISEGn_COEFF table in the teldef file. The coordpnt task retrieves the proper coefficients from the table with 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.

For Hitomi 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 identifier is written to the data stream. For segment AB, SEGMENT=0, and for segment CD, SEGMENT=1.
2. READNODE: Each segment has two readout nodes, A and B for segment AB, and C and D for segment CD. The choice of read-out node is commandable 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 commandable window modes, wherein a specified part of a chip is read out multiple times during a readout interval. The WINOPT property is set to WINOPT=0 if windowing is not used (full chip readout) 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 commandable size of the window is written to the data stream with one of four possible values: WIN_SIZE=640 for full chip readout, 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 values 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 set 'multisegpar="0,1,1,80"', for SEGMENT=0, READNODE=1, WINOPT=1, and 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 lead to an error, e.g., 'multisegpar="2,0,0,640"' (out of range) or 'multisegpar="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 the Hitomi 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. if WIN_SIZE=640, winoffsety=1
2. if WIN_SIZE=160, winoffsety=415
3. if WIN_SIZE=80, winoffsety=455
4. if WIN_SIZE=40, winoffsety=475.

PARAMETERS

input = region.reg [filename]

Input point or name of a region file to be transformed. The input filename or string of coordinates 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 = region_out.reg[string NONE|file name]

This parameter should be set to NONE, except when the input parameter is the name of a file. For this case, the parameter is set to the name of the output file that contains the regions transformed from the 'startsys' to the 'stopsys' coordinate system.

telescop [string]

Name of the mission 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]

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.0 [double]

The right ascension [degrees] of the actual pointing, representing the center or aim point of the field of view of the instrument. This must be a value between 0 and 360.

dec = -999.0 [double]

The declination [degrees] of the actual pointing, representing the center or aim point of the field of view of the instrument. This must be a value between -90 and +90.

roll = 0.0 [double]

The roll angle [degrees] between the SKY coordinate system and the FOC coordinate system. The roll angle center of rotation is defined to be the center of the SKY system and is measured counterclockwise from the positive SKY Y axis to the positive FOC Y axis.

(ranom = -999.0) [double]

The right ascension [degrees] of the nominal pointing, representing the center of the SKY coordinate system. When set to -999.000, 'ranom' is identical to 'ra'. Otherwise, this must be a value between 0 and 360.

(decnom = -999.0) [double]

The declination [degrees] of the nominal pointing, representing the center of the SKY coordinate system. When set to -999.000, 'decnom' is identical to 'dec'. Otherwise, this must be a value between -90 and +90.

(rollnom = 0.0) [double]

The roll angle [degrees] between the SKY coordinate system and the Celestial coordinate system. The roll angle center of rotation is defined to be the center of the SKY system and is measured counterclockwise from the North celestial axis to the positive SKY Y axis. When 'rollnom' is set to zero, the SKY system is aligned with the Celestial system.

(teldeffile = CALDB) [filename CALDB|file name]

Name of the teldef file, which specifies the coordinate systems and transformation properties. If the parameter is set to CALDB, the file is read from the calibration database. If a file name is provided, the TELESCOP and INSTRUME keywords in the file must match exactly the values of the 'telescop' and 'instrume' input parameters. The task supports teldef file format versions 0.0 through 0.2.

(startsys = LOWEST) [string]

Name of the starting coordinate system of the requested conversion. When 'startsys' is set to LOWEST, the conversion begins with the lowest level system present in the teldef file as identified by the parameter COORD0, usually RAW. When 'startsys=HIGHEST' and 'stopsys=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]

Name of the ending coordinate system of the conversion. If 'stopsys' is set to HIGHEST, 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 multisegment parameters, which are required when the teldef file contains a TRTYPEn=MULTISEG transformation (e.g. Hitomi/SXI). These parameters must be specified as a comma-separated list of numbers in the following way:

1. There must be one number for each parameter.
2. The numbers must be in the same order as in the teldef file.
3. The numbers must be within their allowed range (see the example given above).

If there is a MULTISEG transformation for the given instrument, but the 'multisegpar' parameter has its default NULL value, the code assumes the properties listed in the first row of the teldef MULTISEGn_COEFF table. If there is no MULTISEG transformation for the given instrument, this parameter is ignored.

(rawtodetseg = -1) [string]

The value of the segment, which is required when the teldef file contains a RAWTODET type transformation governed by segments (e.g., Hitomi SXI), as opposed to a PIXEL_MAP (e.g., Hitomi SXS). This transformation is multiplexed and the value of 'rawtodetseg' determines the transformation. If the value of this parameter is out of range, the code exits with an error.

(pixeltest = CENTER) [string CENTER|PARTIAL|TOTAL]

This parameter determines how to handle the extent of overlap between a region file and pixels, when saving pixels in a pixel list. When 'pixeltest=CENTER', the center of the pixel must be within the region. When 'pixeltest=PARTIAL', at least one corner of the pixel must be within the region. When 'pixeltest=TOTAL', all corners of the pixel must be within the region. Note that a very small region that does not include any of points that are tested for any pixel is legal input and produces an empty pixel list.

(winoffsetx = 0) [integer]

The value of the windowing offset parameter in the x direction, which is required when the teldef file contains a TRTYPEn = MULTISEG transformation. This parameter value is used, along with the 'multisegpar' parameters, to determine the formula for the MULTISEG transformation. Since it is an additive parameter in the transformation formula, when 'winoffsetx=0.0', the parameter is effectively ignored.

(winoffsety = 0) [integer]

The value of the windowing offset parameter in the y direction, which is required when the teldef file contains a TRTYPEn = MULTISEG transformation. The value is used, along with the 'multisegpar' parameters to determine the formula for the MULTISEG transformation. Since it is an additive parameter in the transformation formula, when 'winoffsety=0.0', the parameter is effectively ignored.

(outx = INDEF) [double]

(Output parameter.) The value of the output x coordinate when the input is a coordinate point or pixel number. This number is also written to stdout. When 'stopsys' is the lowest level coordinate system and pixel numbers define that system, 'outx' represents the pixel number and 'outy' is set to zero. This parameter is set to 0.0 when 'input' is a region file.

(outy = INDEF) [double]

(Output parameter.) The value of the output y coordinate when the input is a coordinate point or pixel number. This number is also written to stdout. When 'stopsys' is the lowest level coordinate system and that system is defined by pixel numbers, 'outy' is set to zero and 'outx' represents the pixel number. This parameter is set to 0.0 when 'input' is a region file.

(buffer = -1) [integer -1|0|N]

Rows to buffer (-1=auto, 0=none, N>0=number of rows).

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records tool parameters in HISTORY.

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=DET stopsys=SKY 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

LAST MODIFIED