pypixlib

Synopsis

Provides a Python interface to the CXC coordinates library: pixlib

>>> from pixlib import Pixlib

Description

The CXC coordinates library (pixlib) encodes all knowledge of the geometry of the Chandra telescope and specifically all information related to the detector geometry. The Python pixlib module provides access to the same coordinate system conversion routines used by the compiled C/C++ tools.

Most users will not need to access the coordinate information at this level. Most users can get what is needed using the dmcoords tool or using one of the coords.chandra or coords.grating modules available in the ciao-contrib package.

Pixlib object

The Pixlib constructor takes two optional arguments: the telescope (default is 'chandra'), and the name of the geometry parameter file: geom.par. Most users will only need to use the defaults and create the Pixlib object as:

>>> my_pix = Pixlib()

Note: It is **ESSENTIAL** that one, and only one Pixlib object exists. The underlying C code uses global variables to store state information, which means that only one Pixlib object can exist. The Python wrapper does not enforce this, so users need to take responsibility.

attributes

There are several attributes that should be set to match an observation including things like detector, aimpoint, and mirror. For grating observations, the zeroth order location must also be set before doing any coordinate conversions. The full list of the Pixlib object's parameters is below:

aimcoord

Get/Set 3-D aimpoint position as a tuple. Units are mm. These are the SIM_X, SIM_Y, and SIM_Z keyword values in a standard Chandra file

>>> my_pix.aimcoord
(-0.782348198338433, 0.0, -237.49970907005604)

aimpoint

Get/Set aimpoint name in string or set 3-D aimpoint position. This is the same as aimcoord except that users can specify the aimpoint location by name in addition to by coordinates

>>> my_pix.aimpoint
'AI1'

close

Close the current pixlib interface session. The object cannot be used after the close attribute has been accessed. This is non-standard Python as it should be a method, not an attribute.

detector

Get/Set detector name in string. Note: There is no such thing as 'ACIS-I' and 'ACIS-S', only 'ACIS'. The "-I" and "-S" only refer to default aimpoints.

>>> my_pix.detector
'ACIS'
>>> my_pix.detector = 'ACIS-I'
>>> my_pix.detector
'ACIS'

flength

Get telescope focal length [mm].

>>> my_pix.flength
10070.0

fp_scale

Get FP scale [arcsecs].

>>> my_pix.fp_scale
0.492

fpsys

Get/Set FP system in string.

>>> my_pix.fpsys
'FP-1.1'

gdpsys

Get/Set Grating Dispersion Plane (GDP) system in string.

>>> my_pix.gdpsys
'ASC-GDP-1.1'

grating

Get/Set grating arm. This must be one of HEG, MEG, or LEG.

>>> my_pix.grating
'HEG'
>>> my_pix.grating = 'HETG'
"ERROR: Unsupported grating arm name, at 'HETG'."

grt_order

Get/Set grating order in integer.

>>> my_pix.grt_order
>>> my_pix.grt_order = 1
>>> my_pix.grt_order
1

grt_prop

Get grating properties: (period[Angstrom], angle[degree]).

>>> my_pix.grating = 'HEG'
>>> my_pix.grt_prop
(2000.81, -5.205)

grt_zo

Get/Set 3-D Grating Zero Order coordinates [mm]. The grating zeroth order coordinates need to be specified in the 3D fc focus coordinate system.

>>> my_pix.grt_zo
(None, None, None)
...
>>> my_pix.grt_zo = my_pix.fpc2fc( zero_order_detx_y )

isokay

Get/Set error status. isokay will be 1 if there is no error, 0 if there is an error, and -1 if there is a warning. The isokay value can be set to 1 to clear the error stack. This method of error handling is highly non-standard in Python.

>>> my_pix.grating = 'LETG'
"ERROR: Unsupported grating arm name, at 'LETG'."
>>> my_pix.isokay
0
>>> my_pix.grating = 'HEG'
>>> my_pix.isokay
1

mirror

Get/Set 3-D stage position [mm] and stage angle theta [arcsecs]. These values typically come from the "DY_AVG", "DZ_AVG", and "DTH_AVG" keywords in a standard Chandra file. Note: "DX_AVG" is always set to 0 as there is no independent way to measure it; "DY_AVG" and "DZ_AVG" are defined in the opposite directions, so they need to be multiplied by -1.

>>> from pycrates import read_file
>>> tab = read_file("/export/img.fits")
>>> dy = tab.get_key_value("DY_AVG")
>>> dz = tab.get_key_value("DZ_AVG")
>>> dtheta = tab.get_key_value("DTH_AVG")
>>> my_pix.mirror = ((0.0, -1.0*dy, -1.0*dz), dtheta)
>>> my_pix.mirror
((0.0, -0.045452498327, -0.2133308158), -0.0021552640335)

tdetsys

Get/Set Tiled-Detector system name in string.

>>> my_pix.tdetsys
'ACIS-2.2'

telescope

Get/Set the telescope name

>>> my_pix.telescope
'chandra'

methods

Most of the Pixlib object's methods perform coordinate transformation from one coordinate system to another. The list of methods includes:

• chip2fpc
• chip2gdp
• chip2lsi
• chip2tdet
• fc2fpc
• fc2gzo
• fpc2chip|fpc2chipCoords
• fpc2fc
• fpc2gdp
• fpc2mnc
• fpc2msc
• gac2gdp
• gac2gzo
• gdp2gac
• gzo2fc
• gzo2gac
• lsi2chip
• mnc2fpc
• msc2fpc
• tdet2chip

In addition, there are a few utilities to convert from physical units (celestial coordinates and wavelength) to/from Chandra coordinates. These include:

• app_aspect
• deapp_aspect
• grt_energy
• grt_wavelen

Below is a list of the various coordinate systems. For details about each system see the Chandra Data Analysis Coordinate Systems memo.

Bugs

See the bugs page for the pypixlib library on the CIAO website for an up-to-date listing of known bugs.

Refer to the CIAO bug pages for an up-to-date listing of known issues.

See Also

calibration

ardlib, caldb

chandra

coords, level, pileup, times

concept

autoname, ciao, ciao-install, history, parameter, stack, subspace

dm

dm, dmascii, dmbinning, dmfiltering, dmmasks, dmopt, dmregions

paramio

paramio

tools::caldb

calindex, calmerge, calquiz, calvalid

tools::utilities

check_ciao_caldb