Skip to the navigation links
Last modified: December 2009

AHELP for CIAO 4.2


Context: modules


The S-Lang interface to the CXC pixlib library


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:


Functions provided by the module

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

Function name with arguments
pix_init_pixlib( [String_Type, String_Type])
pix_set_aimpoint(Double_Type, Double_Type, Double_Type)
pix_set_grating(String_Type, Integer_Type)
pix_set_gzo(Double_Type, Double_Type)
pix_set_simoffset(Double_Type, Double_Type, Double_Type [,Double_Type])
Double_Type pix_get_flength()
Double_Type pix_get_fp_scale_in_asec()
Double_Type pix_get_rowland()
Double_Type pix_get_grating_period()
Double_Type pix_get_grating_angle()
Array_Type pix_chip_to_fpc(Integer_Type, Double_Type, Double_Type)
(Integer_Type,Array_Type) pix_fpc_to_chip(Double_Type, Double_Type)
Array_Type pix_chip_to_tdet(Integer_Type, Double_Type, Double_Type)
(Integer_Type, Array_Type) pix_tdet_to_chip(Double_Type, Double_Type)
Array_Type pix_fpc_to_msc(Double_Type, Double_Type)
Array_Type pix_chip_to_gdp (Integer_Type, Double_Type, Double_Type)
Array_Type pix_fpc_to_gdp(Double_Type, Double_Type)
Array_Type pix_gdp_to_gac(Double_Type, Double_Type)
Array_Type pix_gac_to_gdp(Double_Type, Double_Type)
Double_Type pix_get_energy(Double_Type, Double_Type)
Double_Type pix_get_grating_wavelength(Double_Type, Double_Type)
Array_Type pix_apply_aspect(Double_Type, Double_Type, Double_Type, Double_Type, Double_Type )
Array_Type pix_deapply_aspect(Double_Type, Double_Type, Double_Type, Double_Type, Double_Type)
Array_Type pix_dmTanPixToWorld(Array_Type, Array_Type, Array_Type, Array_Type )
Array_Type pix_dmTanWorldToPix(Array_Type, Array_Type, Array_Type, Array_Type )

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").


slsh> require("pixlib");
slsh> pix_init_pixlib();
slsh> pix_disp_config();
****** PIXLIB System Configuration ******
Telescope = flight
Focal Length (mm) = 10070.000
Detector = ACIS
Focal Plane Sys. = FP-1.1
Tiled Detector Plane Sys. = ACIS-2.2
SIM Offset (mm) = (0.684 0.75 236.552)
Aim Point(AI1) (mm) = (-0.782348 0 -237.5)
Grating Arm = HEG
Grating Order = 1
Dispersion Plane Sys. = ASC-GDP-1.1
Rowland Circle (mm) = 8632.48


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

See Also

ardlib, caldb
coords, level, pileup, times
autoname, ciao, ciaorc, parameter, stack, subspace
dm, dmascii, dmbinning, dmfiltering, dmopt, dmregions
pix_apply_aspect, pix_chip_to_fpc, pix_chip_to_gdp, pix_chip_to_tdet, pix_close_pixlib, pix_deapply_aspect, pix_disp_config, pix_dmtanpixtoworld, pix_dmtanworldtopix, pix_fpc_to_chip, pix_fpc_to_gdp, pix_fpc_to_msc, pix_gac_to_gdp, pix_gdp_to_gac, pix_get_energy, pix_get_flength, pix_get_fp_scale_in_asec, pix_get_grating_angle, pix_get_grating_period, pix_get_grating_wavelength, pix_get_rowland, pix_init_pixlib, pix_set_aimpoint, pix_set_detector, pix_set_fpsys, pix_set_gdpsys, pix_set_grating, pix_set_gzo, pix_set_simoffset, pix_set_tdetsys, pix_tdet_to_chip
calindex, calquiz, calvalid

Last modified: December 2009