Description

The pixlib module is the interface between the S-Lang interpreter (see "ahelp slang") and the CXC pixlib library (see "ahelp dmcoords" for the more-limited tool-based interface to the pixlib library). This document provides an overview of the features of the pixlib module, and tips for using it efficiently in a S-Lang program. Detailed descriptions of each function are provided by individual ahelp entries.

The pixlib module is not available by default; to use it in a S-Lang program, it must be loaded using the S-Lang require() function:

  require("pixlib");

Functions provided by the module

The following functions are provided by the module; use "ahelp <function>" to get a detailed description of a function:

Pixlib and Chandra Coordinate Systems

A number of coordinate systems have been defined for use with Chandra. The pixlib module makes conversion between these systems much easier, but the user must first familiarize themselves with the various systems, which are described in Coordinate Systems Paper I: Imaging.

Setting up pixlib geometry

The pixlib module must be initialized, after it is loaded, with the pix_init_pixlib call. This sets the default geometry for Chandra in flight. Most of these values (those set by the pix_set_tdetsys, pix_set_fpsys, or pix_set_gdpsys calls) should not be changed. The Science Instrument Module (SIM) position, however, must be set correctly for each observation and aspect solution in order to properly convert between sky and detector coordinates. This is done using the pix_set_aimpoint() call (see example below) which uses the nominal SIM_X, SIM_Y, and SIM_Z values (available in the event file header) and the aspect solution DY and DZ values as inputs.

Restarting pixlib

Pixlib should not be closed and re-initialized within a single session, as this causes internal variables to be mis-set and incorrect results produced. This bug will be addressed in a future release; the simple workaround is to call pix_init_pixlib only once, immediately after the call to require("pixlib").