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. Examples of the region file format, with a description of some existing variations, can be found at http://ds9.si.edu/doc/ref/region.html. Many region shapes are described, with examples, in https://github.com/Smithsonian/si_funtools/blob/master/doc/reggeometry.html. Be warned, however, that the exact set of regions supported varies between software packages, and sometimes individual parameters for regions with the same name can be defined differently, as well.

The region shapes supported by coordpnt are listed below together with an indication of the region parameters. 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. In this context, nangle refers to a number of evenly-spaced angle bins between starting and stopping values, and nradius to a number of evenly-spaced radial bins between inner and outer values. For coordpnt, the region specification must include the parentheses and commas:

Point:

point(x, y) # point=circle

Line:

line(x1, y1, 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(x1, y1, x2, y2, angle)

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'

A pointing on the sky consists of three values: right ascension (RA), declination (Dec), and roll (phi). The transformations that involve SKY coordinates are controlled by two pointings. One is the actual spacecraft pointing at some particular time, as determined from the attitude file. The other is the nominal pointing, which is the tangent point of the SKY coordinate plane in RA and Dec, together with a set value of phi, usually zero.

To convert a photon event location between SKY coordinates and one of the coordinate systems fixed to the spacecraft, both the actual pointing at the event time and the nominal pointing must be specified explicitly. The actual pointing at the event time is given by 'ra', 'dec', and 'roll', and the nominal pointing is given by 'ranom', 'decnom', and 'rollnom'.

For some use cases, the time-dependent spacecraft pointing may be approximated by the nominal pointing. For example, the user may wish to compute a region for display in DET coordinates for an entire exposure, starting from world coordinates (RA and Dec). In this case, the parameters 'ra', 'dec', and 'roll' should be set to the nominal pointing, while the hidden parameters 'ranom', 'decnom', and 'rollnom' are left at their default values.

Hitomi and XRISM parameters 'multisegpar' and 'winoffsetx/y'

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 given as separate parameters.

For XRISM Xtend and Hitomi SXI, there are four properties used for indexing the MULTISEGn_COEFF table, listed here in the order in which they appear in the teldef file. This order is the same order in which the individual 'multisegpar' parameters must be given:

1. SEGMENT: Each 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 D and READNODE=1 denotes node B or C.
3. WINOPT. The four 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.

Note that in an event file context, some of these parameters appear as event table columns, and others as FITS header keywords. This task, coordpnt, does not process event files, and the user must figure out the values to be supplied. The default 'multisegpar' values select SEGMENT=0, READNODE=0, WINOPT=0, and WIN_SIZE=640, for both Hitomi SXI and XRISM Xtend. For this case, the appropriate values for 'winoffsetx' and 'winoffsety' are the defaults, 0 and 1, respectively.

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. Normally, for both XRISM Xtend and the Hitomi SXI, following the standard teldef files, 'winoffsetx' should be set to 0. By contrast, 'winoffsety' can vary, but is linked to WIN_SIZE. For both Hitomi SXI and XRISM Xtend, it is given in event files by the WIN_ST keyword.

Currently, XRISM Xtend and Hitomi SXI are the only instruments to use the multiseg capability.

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, effectively the tangent point of the FOC coordinate system at a given instant. This must be a value between 0 and 360. Note the distinction between the parameters 'ra' and 'dec', and the right ascension and declination of a point on the sky to be converted to other coordinate systems; such coordinates are specified by the 'input' parameter with 'startsys=RADEC'.

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, effectively the tangent point of the FOC coordinate system at a given instant. This must be a value between -90 and +90. Note the distinction between the parameters 'ra' and 'dec', and the right ascension and declination of a point on the sky to be converted to other coordinate systems; such coordinates are specified by the 'input' parameter with 'startsys=RADEC'.

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 input 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 overall coordinate transformation includes a step of the RAWTODET type, as determined by the teldef file. A RAWTODET transformation is multiplexed like the MULTISEG type (see above), but in a much simpler way, with only one parameter, supplied to coordpnt as 'rawtodetseg'. This parameter is ignored if no RAWTODET transformation is required in the calculation. For Hitomi and XRISM, the valid values of 'rawtodetseg' are nonnegative; therefore, the the default value of -1 for 'rawtodetseg' will cause an error. For Hitomi SXI and XRISM Xtend, 'rawtodetseg' is a CCD identifier, and for Hitomi SXS and XRISM Resolve, it is a pixel number.

(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 the 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. 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 'winoffsetx=0', the parameter is effectively ignored. If there is no MULTISEG transformation for the given instrument, this parameter is ignored.

(winoffsety = 1) [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. For the default value 1, see the general discussion of MULTISEG parameters above. If there is no MULTISEG transformation for the given instrument, this parameter is 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 INDEF 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 INDEF 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

For all examples with teldeffile=CALDB, the remote HEASARC calibration database was set up using instructions here: https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_remote_access.html. File versions current as of 2026-06-16 were used.

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

Result:

coordpnt: OUTX OUTY= 1217.50000000   848.50000000

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

Input file region.ds9:

box(100,500,25,51,0)

Output file region-out.ds9:

# Region file written by coordpnt.
# Comments and global records not copied from input.
physical
+box(768.50000000,799.50000000,25.00000000,51.00000000,270.00000000)

3. Transformation of a region file from DET to SKY coordinates, using an explicitly specified teldef file for the Swift XRT that exists in the working directory:

coordpnt input="region.ds9" outfile="region-out.ds9" telescop=Swift \
instrume=XRT ra=187.413 dec=-62.998 roll=216.38 \
teldeffile=swx20230701v001.teldef startsys=DET stopsys=SKY clobber=yes

Input file region.ds9:

box(100,500,25,51,0)

Output file region-out.ds9:

# Region file written by coordpnt.
# Comments and global records not copied from input.
physical
+box(780.25373752,458.80651918,25.00000000,51.00000000,216.38000000)

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

Result:

coordpnt: OUTX OUTY= 1244.29777711  1204.34728702

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). The values of 'multisegpar' and 'winoffsety' are from row 15 of the MULTISEG_COEFF0 table, together with associated descritive comments, in the Hitomi teldef file. The value 2 for 'rawtodetseg' means that the photon event is on the CCD denoted by CCD_ID=2:

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

Result:

coordpnt: OUTX OUTY=  987.82430029  1497.33583015

6. Transformation for XRISM Xtend, where multiseg parameters are set on the command line to specify segment AB, read node A, and full windowing mode. This information is in the first row of the MULTISEG_COEFF0 table extension of the teldef file. This teldef file also specifies that WIN_ST is the header keyword carrying the 'winoffsety' information in the event file, and for this observing configuration, the value would be as shown here. The value 2 for 'rawtodetseg' specifies one of the four Xtend CCDs by its CCD_ID, which may be 0, 1, 2, or 3:

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

Result:

coordpnt: OUTX OUTY=  532.80716202  1577.13061363

7. This series of runs illustrates the differences between the spacecraft orientation parameters 'ra', 'dec', and 'roll', the nominal orientation parameters 'ranom', 'decnom', and 'rollnom', and input coordinates on the sky given in the 'RADEC' system.

7a. Transformation from RADEC to rectangular SKY coordinates for XRISM Xtend, assuming a constant spacecraft pointing (i.e., 'ranom' and 'decnom' are taken by default from 'ra' and 'dec'); the place of interest on the sky is specified by the 'input' parameter to be exactly at the pointing axis:

coordpnt input="192.196382996526,-41.3004292247674" outfile=NONE telescop=XRISM \
instrume=XTEND ra=192.196382996526 dec=-41.3004292247674 roll=106.673603601569 teldeffile=CALDB \
startsys=RADEC stopsys=SKY

Result is exactly at the tangent point of the SKY system:

coordpnt: OUTX OUTY= 1215.50000000  1215.50000000

7b. This example repeats the previous one, except that the transformation is to FOC coordinates:

coordpnt input="192.196382996526,-41.3004292247674" outfile=NONE telescop=XRISM \
instrume=XTEND ra=192.196382996526 dec=-41.3004292247674 roll=106.673603601569 teldeffile=CALDB \
startsys=RADEC stopsys=FOC

Result is exactly at the tangent point of the FOC system:

coordpnt: OUTX OUTY= 1215.50000000  1215.50000000

7c. This example is similar to the previous one, except that the actual orientation ('ra','dec','roll') has a different pointing axis from the nominal one. However, the source coordinates ('input') remain on the nominal pointing axis. Note that the resulting FOC coordinates change:

coordpnt input="192.196382996526,-41.3004292247674" outfile=NONE telescop=XRISM \
instrume=XTEND ra=192.196410557481 dec=-41.3006759601926 roll=106.673603601569 teldeffile=CALDB \
ranom=192.196382996526 decnom=-41.3004292247674 rollnom=0.0 \
startsys=RADEC stopsys=FOC

Result:

coordpnt: OUTX OUTY= 1215.96918644  1215.31546170

7d. This example is like the previous one, except that the SKY coordinates are computed instead of FOC. The output coordinates are again at the SKY tangent point because the actual spacecraft orientation is ignored in converting from RADEC to SKY:

coordpnt input="192.196382996526,-41.3004292247674" outfile=NONE telescop=XRISM \
instrume=XTEND ra=192.196410557481 dec=-41.3006759601926 roll=106.673603601569 teldeffile=CALDB \
ranom=192.196382996526 decnom=-41.3004292247674 rollnom=0.0 \
startsys=RADEC stopsys=SKY

Result:

coordpnt: OUTX OUTY= 1215.50000000  1215.50000000

7e. This example computes FOC coordinates for an off-axis point on the sky, using the same orientation parameters as the previous example:

coordpnt input="192.0,-41.1" outfile=NONE telescop=XRISM \
instrume=XTEND ra=192.196410557481 dec=-41.3006759601926 roll=106.673603601569 teldeffile=CALDB \
ranom=192.196382996526 decnom=-41.3004292247674 rollnom=0.0 \
startsys=RADEC stopsys=FOC

Result:

coordpnt: OUTX OUTY= 1520.14443872   809.64923746

7f. This example computes SKY coordinates using the same orientation parameters and source coordinates as the previous example:

coordpnt input="192.0,-41.1" outfile=NONE telescop=XRISM \
instrume=XTEND ra=192.196410557481 dec=-41.3006759601926 roll=106.673603601569 teldeffile=CALDB \
ranom=192.196382996526 decnom=-41.3004292247674 rollnom=0.0 \
startsys=RADEC stopsys=SKY

Result:

coordpnt: OUTX OUTY= 1516.83604458  1623.27966825

SEE ALSO

LAST MODIFIED