Telescope Pointing Utilities

jwst.lib.set_telescope_pointing Module

Set Telescope Pointing from Observatory Engineering Telemetry

Calculate and update the pointing-related and world coordinate system-related keywords. Given a time period, usually defined by an exposure, the engineering mnemonic database is queried for observatory orientation. The orientation defines the sky coordinates a particular point on the observatory is pointed to. Then, using a set of matrix transformations, the sky coordinates of the reference pixel of a desired aperture is calculated.

The transformations are defined by the Technical Reference JWST-STScI-003222, SM-12. This document has undergone a number of revisions. The current version implemented is based on an internal email version Rev. C, produced 2021-11.

There are a number of algorithms, or methods, that have been implemented. Most represent the historical refinement of the algorithm. Until the technical reference is finalized, all methods will remain in the code. The default, state-of-the art algorithm is represented by method OPS_TR_202111, implemented by calc_transforms_ops_tr_202111.


The primary usage is through the command line interface Operating on a list of JWST Level 1b exposures, this command updates the world coordinate system keywords with the values necessary to translate from aperture pixel to sky coordinates.

Access to the JWST Engineering Mnemonic database is required. See the Engineering Database Interface for more information.

Programmatically, the command line is implemented by the function add_wcs, which calls the basic function calc_wcs. The available methods are defined by Methods.

There are two data structures used to maintain the state of the transformation. TransformParameters contains the parameters needed to perform the transformations. Transforms contains the calculated transformation matrices.

Transformation Matrices

All the transformation matrices, as defined by Transforms, are Direction Cosine Matrices (DCM). A DCM contains the Euler rotation angles that represent the sky coordinates for a particular frame-of-reference. The initial DCM is provided through the engineering telemetry and represents where in the sky either the Fine Guidance Sensor (FGS) or star tracker is pointed to. Then, through a set of transformations, the DCM for the reference point of the target aperture is calculated.


add_wcs(filename[, allow_any_file, ...])

Add WCS information to a JWST DataModel.


Calculate transforms which determine reference point celestial WCS


Calculate transforms in OPS using TR 2021-11


Given observatory orientation and target aperture, calculate V1 and Reference Pixel sky coordinates

calc_wcs_over_time(obsstart, obsend, t_pars)

Calculate V1 and WCS over a time period

update_wcs(model[, default_pa_v3, ...])

Update WCS pointing information



Available methods to calculate V1 and aperture WCS information

TransformParameters([allow_default, ...])

Parameters required the calculations

Transforms([m_eci2fgs1, m_eci2gs, m_eci2j, ...])

The matrices used in calculation of the M_eci2siaf transformation

WCSRef(ra, dec, pa)

Create new instance of WCSRef(ra, dec, pa)

jwst.lib.v1_calculate Module

V1 Calculation based on time and engineering database info


v1_calculate_from_models(sources[, siaf_path])

Calculate V1 over the time period for the given models

v1_calculate_over_time(obsstart, obsend[, ...])

Calculate V1 over the given time period


Available commands are as follows. Use the -h option for more details.

Update basic WCS information in JWST exposures from the engineering database.


Summarize various pointing information in a table.


Calculate V1 over a time period.