Last modified: April 2023

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/sso_freeze.html
AHELP for CIAO 4.16

sso_freeze


Synopsis

Reproject sky x and y coordinates into a Solar System Object centered reference frame.

Syntax

sso_freeze  infile scephemfile ssoephemfile outfile [asolfile]
[ocsolfile] [logfile] [scale] [lookuptab] [clobber] [verbose]

Description

sso_freeze reprojects sky x and y coordinates from the nominal coordinate frame fixed to the celestial sphere to a reference frame which is fixed to the moving solar system object (SSO) target. The result is that the new event list table columns ocx and ocy display events as seen from an observer moving with the SSO, eliminating the "blurring" seen in the sky x and y events. Along with the event file, primary input data are the spacecraft ephemeris and SSO ephemeris. Multiple input event files spanning several obsid's can be combined into a single object centered output file, and output object centered coordinates can be either spherical or linear.

Note that it is recommended that linear output object-centered coordinates be chosen instead of angular when combining several ObsID's widely spaced in time. This will avoid the problem of different apparent angular sizes in the object, which occurs when the Chandra-to-object distance has changed significantly. Also note that although X-rays emitted by the SSO may be affected by either SSO rotation or large changes in the sun illumination angle of the SSO, neither effect is taken into account by sso_freeze.

For some applications, creating an aspect solution in object-centered coordinates is useful. This may be done at the same time as creating the object-centered event file by supplying a standard RA,Dec aspect solution to the tool.

For a detailed example, see the Reprojecting Coordinates of a Solar System Object thread.


Examples

Example 1

sso_freeze planet.fits sc_ephemeris.fits sso_ephemeris.fits
sso_freeze_evt.fits

Create an event file with object-centered coordinate and distance-to-object data columns from an input event file, "planet.fits".

Example 2

sso_freeze @evt.lis sc_ephemeris.fits sso_ephemeris.fits
sso_freeze_evt.fits scale=2000

Create the object-centered event file from a stack of input files. Linear output coordinates for ocx and ocy are selected, with a scale of 2000 km/pixel.

Example 3

sso_freeze acis3726.fits orbitf160142700N001_eph0.fits
jupiterf162475200N001_eph1.fits outfile=acis3726_oc.fits
asolfile=pcadf162488590N002_asol1.fits ocsolfile=ocsol3726.fits

Create an object-centered aspect solution file in addition to the event file.


Parameters

name type ftype def min max reqd
infile file input       yes
scephemfile file input       yes
ssoephemfile file input       yes
outfile file output       yes
asolfile file input       no
ocsolfile file output       no
logfile file output STDOUT     no
scale real input 0     no
lookuptab file input       no
clobber boolean input no     no
verbose integer input 0 0 5 no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input event file or stack.

Multiple input event files can be specified by a stack list file and will produce a single output file.

Parameter=scephemfile (file required filetype=input)

Input spacecraft geocentric ephemeris file or stack.

The time of the initial ephemeris record must be equal to or less than the earliest event record time, and the time of the last ephemeris record must be equal or greater than the time of the last event record. Multiple files can be specified in a stack list file, but must be in ascending time order. Overlapping time records in multiple files are allowed (subsequent ephemeris data at an earlier time is ignored).

Parameter=ssoephemfile (file required filetype=input)

Input solar system object geocentric ephemeris file or stack.

The time of the initial ephemeris record must be equal to or less than the earliest event record time, and the time of the last ephemeris record must be equal or greater than the time of the last event record. Multiple files can be specified in a stack list file, but must be in ascending time order. Overlapping time records in multiple files are allowed (subsequent ephemeris data at an earlier time is ignored).

Parameter=outfile (file required filetype=output)

Output event file name.

Only a single filename is allowed. Multiple input files are combined into a single output file.

Parameter=asolfile (file not required filetype=input)

Aspect solution file. Used if OC-coordinate aspect solution is to be generated.

The aspect solution file should be a standard RA,DEC based Chandra aspect solution file.

Parameter=ocsolfile (file not required filetype=output)

Output aspect solution in object-centered (OC) coordinates.

The OC-coordinate aspect solution may be used to generate an object-centered exposure map or response file (ARF).

Parameter=logfile (file not required filetype=output default=STDOUT)

debug log file.

Allowable values are either a filename - to send the output to a given file - or one of stdout or STDOUT, which sends the information to the standard output (normally the screen).

Parameter=scale (real not required filetype=input default=0)

Image pixel scale.

Values can be 0, indicating spherical coordinates with units of degrees/pixel; -1, indicating linear coordinates with units of "n" km/pixel, where "n" is automatically calculated to result in the same image size as an image produced using spherical coordinates; or some value "n" which is > 0, in which case linear coordinates of "n" km/pixel are used.

Parameter=lookuptab (file not required filetype=input default=)

Lookup table.

Lookup table for output file header merging rules. This defaults to the standard cxcds lookup table.

Parameter=clobber (boolean not required filetype=input default=no)

Overwrite existing output dataset with same name?

Parameter=verbose (integer not required filetype=input default=0 min=0 max=5)

Level of debug detail.

Increasing amounts of debug information is printed to "logfile" as the value of verbose is increased from 0 to 5.

Changes in CIAO 4.16


Bugs

Running sso_freeze twice will produce duplicate output columns

Running sso_freeze on a file that already has the PathLength and Object Centered coordinates, oc(ocx,ocy), will result in new duplicate columns with the same name being created. These duplicate, non-unique column names then cause problems with tools used later on in analysis.

See Also

tools::coordinates
reproject_aspect, reproject_events, wcs_match, wcs_update