A description of the fits header position/offsets.

01dec04

Introduction:

The ao fits header has a number of keyword values that refer to positions. This note tries to explain how they are computed. These keywords are:

crval2,crval3	crval2a,crval3a	crval2b,crval3b	crval2c,crval3c	crval2g,crval3g
croff2,croff3	croff2b,croff3b
offc1,offc2,offtime	rate_c1,rate_c2	rate_cs	rate_cur
model_offaz model_offza	beam_offaz beam_offza	user_offaz user_offza	rfeed_offaz rfeed_offza	prfeed_offaz prfeed_offza
beam_offraj beam_offdecj	alfa_ang para_ang	cur_tol req_tol

The pointing program:

The pointing program has a tracking command that contains up to 3 parts:

pnt tr -Up pos1 pos2 -tPtm -cCp -o -Uo off1 off2 -tOtm -cCo -r -Ur rate1 rate2 -tRTm -cCr

The three parts are the position, offset, and the rate. The properties of a tracking command are:

All tracking commands have a position.
Tracking commands can optionally have an offset added to the position. This offset starts with the -o option.
Tracking commands can have an optional rate applied to a position. The rate starts with the -r option. Rates remain in affect once they become active.
The default position coordinate is J2000. You can change the position coordinate with the -cCp option after pos1 pos2. Cp is a single character that specifies a coordinate system. Once a coordinate system is specified, it remains in affect for the rest of the line (unless it is modified with another -c option. The offset and rate can have differing coordinate systems by using the -Co and -Cr options.
By default commands become active after they arrive at the pointing program and then get sent upstairs to the motor controllers. This is "immediate" execution (it actually is delayed about 2 seconds from when it is initially sent). You can specify that a command becomes active (at the motors) at a specific time using the -tTmPos. Tmpos is the number of seconds from midnite ast when the command should become active. You can have the offset or rate become active at a different time by using the -tOtm and -tRtm . The only constraint is that the position must become active at or before the time for the position and rate. It would not make sense to have a rate become active without first defining the position.
Each coordinate system has a default set of units (eg... ra,dec is hhmmss,ddmmss while az,za is deg,deg). The coordinate system units can be modified with the -Ux option. x specifies the units that should be used from that point on in the line.

The processing for a track command will start tracking the position when its time arrives. To this position it will add any rates (when then become active). A rate will be applied to the combined pos+off when the rate becomes active. Each of these steps can have different coordinate systems. The only constraint is that the pointing program will not go back up the coordinate transform chain. The chain is:
ra/dec epoch, ra/dec current, hourangle/dec, az/za. This means that if the position is a current ra/dec, then you can not make the offset a J2000 offset. The pointing program starts at the position coordinate system. It checks to see if the offset or rate needs to be added in and then steps to the next lowest coordinate system in the transformation from ra,dec to az,za.

The raJ, decJ requested position.

A tracking request eventually generates an azimuth , zenith angle that gets sent to the encoders. Before doing this, the pointing program will back compute this az, za back to a J2000 ra,dec. This is called the requested raJ, decJ coordinate that got stored in the interim correlator header. It is a requested position. It include the requested position and any offsets and rates that were active.

The az,za position errors.

Once a second the azimuth and zenith angle encoders are read. The measured encoder values are compared with the requested azimuth, zenith angle values that were requested for this time stamp. The az,za errors is computed as:

az_error= Requested-measured azimuth encoder values.

za_error= Requested - measured zenith encoder values.

The azimuth error is not a great circle arc on the sky.

Interpolating the positions to the data time stamps.

The raJ, decJ, and errors are computed once a second. They are then distributed via the scram net memory to different devices at the observatory. The wapp data taking computers send their data buffers to a single computer (wappreader) that collates the data from the 4 wapps. This computer also receives the scram net information (indirectly via a network broadcast of the scram net memory). It interpolates the raJ,decJ, lst, az/zaerrors to be at the start of each data sample. At the same time it tries to include the encoder position errors so that the ra,dec that it reports is the actual and not requested ra,dec positions (the errors are typically of the order of .5 arc seconds for normal tracking).

Steps in computing the positions:

The steps in going from raJ,decJ,lst,az_error,za_error to the positions in the fits headers are:

Get the time stamp for the start of the data sample. This is stored in mjd_obs in the fits header.
Interpolate raJ, decJ, lst, az_error, za_error to the start of the data time stamp.
Precess the raJ, decJ to the mjd_obs epoch (current coordinates) and then convert to azimuth, zenith angle. This should be the requested azimuth,za (without any model correction applied).
Subtract the az_error, za_error from the az, za computed and call it center_az, center_za. This is the az,za (with no model correction) that the paraxial ray would have (center of the optics).
Convert center_az, center_za back to J2000 coordinates to get center_raj, center_decJ. This is the actual raJ,decJ for the paraxial ray. It includes any measured encoder errors.
cmd_ra/dec/az/za. Start with crval2,3.

If epoch gt 0. then this is an ra,dec request. Convert to az,za using the start time of the data and the interpolated lst. This becomes cmd_az, cmd_za. It does not contain any encoder error corrections. If epoch was not equal to 2000. then precess crval2,3 to J2000. This becomes cmd_ra, cmd_dec.
If epoch eq 0 then crval2,3 are requested az,za (it does not differentiate between model or no model. it probably should). cmd_az,cmd_za is set from crval2,3 directly. It then takes the interpolated lst and back computes cmd_az,za back to cmd_ra, cmd_dec . This will be correct as long at crval2,crval3 did not have the model corrections included (-Cx).

off_az,za: off_az, za is (center_az-cmd_az)*sin(za) and (center_za-cmd_za). Center_az,za is the actual az,za for the center pixel. these are great circle offsets. off_az,za will be non-zero if :

there is an encoder error.
The pattern that loaded the crval2,crval3 applies a rate or offset. This would change the center_raJ,decJ but not the commanded.

fithdr.rfeed_offaz,_offza. Computed in spectra.c by calling find_alfarot. It is the azoff,zaoff you add to the center beam az,za to then use in back computing ra,dec, from az,za. It includes the rotation angle. The azoff is great circle so divide by sin(za) before adding it in..
h.beam_offaz,_offza. This is the az,za values to add to the center beam az,za when back computing the ra,dec of a beam if the rotation angle was 0. The az value is great circle (need to divide by sin(za) before adding it on. It will differ from rfeed_offaz, offza if the rotation angle is not zero.

The positions:

prfeed: This is the feed that is being used for the reference position. It is normally pixel 0 (the paraxial ray of the optics). When you say pnt tr ra dec .. this pixel will point at ra dec. If this is not pixel 0, then a constant offset is added to all position requests (using pnt cor setoff az za) . The amount of this offset is stored in prfeed_offaz,offza. Actually this is not quite true.. the pnt cor setoff xx xx may also include a pointing correction if you have requested it.
crval2,crval3. This looks like it is the requested postion in the pnt tr pos1 pos2 command. The header variable equinox determines if these values are ra,dec or az,za. Equinox = 0 implies az,za. If not, it is ra,dec with equinox as the epoch (usually 1950. or 2000.). crval2,3 get loaded into the fits header in specra.c (on each wapp separately). It comes from the execshm scram block where it is loaded with the setexec e_ra tcl command. The setexec command is called by some routines in exec/exec.d/..tcl . I only see crval2,3 being set in the routines: basketweave, dps, eph, fixed_drift, track, and vlbi (.tcl's). I'm not sure if other routines are loading it.
crval2a,3a. This is the time interpolated position for this feed. It is computed using crval2b,3b and then back computing to ra,dec J2000.
crval2b,crval3b: This is the az,za that would cause the paraxial ray of the telescope to point where this beam is currently pointing. This value is used to back compute the ra,dec for crval2a,3a. To compute this value the interpolated center_az,za of the paraxial ray is incremented by rfeed_offaz (rotation/offset for this feed relative to pixel 0 being the center pixel) and prfeed_offaz (offset used if you've made a beam other then pixel 0 the center pixel)..
crval2c,crval3c. This comes from center_raj, center_decj. It is the requested J2000 ra and dec, interpolated in time and with the with the encoder errors included. This always refers to the paraxial ray (center pixel).

The offsets:

Some of the offsets are:

croff2,3: This is a great circle offset in the ra/dec J2000 coordinate system. raThisBeam - center_raj. The center_raj is computed from interpolated requested raJ with the encoder errors included.
croff2b,3b: These are great circle az/za offsets. They are computed as: crval2b,3b - cmd_az,za . It measures the "az/za of this beam (after interpolation and addding encoder errors)" - the commanded az/za. The commaned az/za is not interpolated and does not contain the encoder errors. It also does not contain any offsets or rates (it comes from crval2,3). It would be the center of a cross/map if you were doing a map with offsets and rates.
rfeed_offaz,rfeed_offza : This is the offset to add to az,za of pixel 0 to then backcompute the ra,dec for rfeed. It includes the rotation angle.
prfeed,prfeed_offaz,za,prfeed. This is getting set in exec.d/wapp.tcl:wapp_spectra. It is getting set to the value in $point(rfeed_offxx). point(rfeed_xx) is set in exec.d/track.tcl:apply_pointing_corr. It is normally called when you want to select a beam to be the beam to track with. The rfeedaz,za values is passed to pnt cor setoff rfeedaz rfeedza so this offset is now set in the pointing. The value causes the beam selected to point at the ra,dec selected. The rotation value has been included. apply_pointing_corr() is called from:

set_alfabeam() (exec.d/track.tcl:set_alfabeam() ,
exec.d/wappmap.tcl: cross_wappalfa,
The pointing widget apply pointing correction which calls a local routine which calls apply_pointing_cor in the executive.
the gui routine clear_pointing_cor will remove any corrections.
alfa_point_off in the gui alfa position gui. calls alfaoff rotangel and then loads point(rfeedaz) point(rfeedza), point(rfeed) variables. So they contain the outputs of alfaoff

model_offaz,_offza: This comes from the pointing scram block: corazRd*radToDeg, corzaRd*Radtodeg. The units are degrees. This includes the model correction plus any offset that were applied via pnt cor setoff az za (prfeed offsets).
beam_offaz,offza: These are the offset from pixel 0 to this pixel in great circle az,za offsets. They do not include the rotation or any beam offsets. If pixel 0 was at the center and there was not rotation, then you would add these offsets to the az,za of the telescope and the back compute the ra/dec for to get this beams ra/dec.
user_offaz,offza: The great circle offset pointing correction that the user may have requested. The units are degrees. The user can set this in the pointing_widget. It is stored in the gui in point(coraz) (corza). It gets applied in the apply_pointing_cor() routine.
beamoff_raJ,_decJ: This is the (center_raJ - cmd_raj)*cos(dec) and (center_decJ - cmd_decJ). These are great circle offsets. They will be non zero if:

There is an encoder error,
the routine that loads crval2, 3 then applies an offset or rate. The offset, rate is reflected in center_xx but not in cmd_xx.

files/programs:

/share/wappsrc/wapp/

spectra.c: runs on each wapp. Called from wapprt.c. Inputs data, computes spectra. Hdr info comes from header passed in. Ends up writing data to wappdata routine that combines the data.

/share/wappsrc/fits

wappdata.c: runs on wappsrc. inputs data from 4 wapps, combines and writes to disc.
interp.c: called by wappdata.c to interpolate the scram net values to the start of the data samples.

/share/wappsrc/lib

alfaoff.c : find_alfaoff, find_alfarot, alfa_position . used to compute alfa az,za offsets for header computations.

/share/wappsrc/control

exec_shm.c: tcl module that implements setexec tcl command. Allows tcl program to modify exec shm.
tk_scram.c: tcl module that implements scram,scramlock,rise,slew,sky2syn...procedures.
tk_alfaoff: tcl module implements alfaoff . calls find_alfarot for each beam (1..6) and then returns all of them.

/home/aoui/develop/
Tcl directory Routines that get included in gui via resourceall

/home/aoui/develop/standalone/receiver.tcl : hold receiver definitions/parameters
/home/aoui/develop/standalone/bar.tcl:
/home/aoui/develop/standalone/rxview.tcl:
/home/aoui/develop/library/*.tcl

Routines that contain tcl commands

wappsrc/control/exec_shm .. setexec tcl command
wappsrc/control/tk_scram: scram, scramlock,rise,slew,sky2syn... alfaoff.
wappsrc/control/tk_alfa:

C routines in wappsrc/lib/alfaoff.c

alfa_position(ra,dec,lst,epoch,angle,off1,off2,beam,pra,pdec): Compute new ra,dec given center pixel ra,dec,lst ,current epoch, angle, offsets, and beam. Includes rotation.
find_alfaoff(beam,0/1): Find the alfa offset for this beam 0=> az, 1->za. units deg (great circle). This is the value to add to the az,za to make the beam point at the same location as the center pixel. To compute the new ra,dec of the beam relative to the center pixel you need to subtract these values from the az,za of the center pixel. This is for rotation angle=0.
find_alfarot(angle,beam,paz,pza). Same aas find_alfaoff except that this includes the rotation angle. To compute ra,dec of beam from az,za of center pixel, you subtract these values from the az,za center pixel. They are great circle values.

home_~phil