1. Early examples
2. Online help info added in Aug2017

Derive the position angle of image (in degrees CCW from +Y) that has a valid WCS installed.

 
% image_pa n3379_B.fits 
 

There is a rather elaborate test script that retrieves and interesting DSS image and runs image_pa. It also displays the image in a ds9 window and draws the Ra,Dec grid according to the WCS in the image header. I show this script here:

 
 
% got 
% cd T_runs/image_pa/ex0/S
% cat GRAB_and_RUN
 

 
#!/bin/bash
# Pull over a DSS image that has NORTH that is 
# not quite straight up. 
cp $tdata/T_images/S2_dss/dss_bsc5-0747.fits .

printf "\n\nI am running image_pa on the DSS image named dss_bsc5-0747.fits\n"
printf "Run with verbose mode On/Off:"
read vmode

if [ $vmode = "On" ]
then 
 date >Verbose.On
else
 printf "\tI am not running in Verbose mode! \n"
fi 

#
image_pa dss_bsc5-0747.fits

fitsin="dss_bsc5-0747.fits"

# display image 
ds9_open 800 800 
xpaset -p ds9 frame frameno 1
xpaset -p ds9 file $fitsin
# impose the grey-scale limits (z1,z2)
z1="0"
z2="10000"
xpaset -p ds9 scale limits $z1 $z2
# zoom to fit the entire image
xpaset -p ds9 zoom to fit

cat NE.reg | xpaset ds9 regions -format ds9 

cat xycirc.reg | xpaset ds9 regions -format ds9 
printf "\n\nI used "xycirc.reg" to show the circle of points used. \n" 

# draw in the coordinate grid 
xpaset -p ds9 grid yes

I wrote this script when I was developing some VIRUS astrometry code. In Sep2015 we had mad some observations of the bright star BSC5-0747 at AZ=0. This star was far in the north, and as fate would have it, happenned to be located on a POSS-II plate where the digitized scan did NOT have North in a perfect straight up direction (i.e. the digital images was not NUEL = North UP East LEFT in orientation). My code had assumend this would always be the case. The figure below was mad with the ex0 test example shown above.

The figure generated with test case 0 (ex0) for the image_pa script. I used the ds9 analysis option to plot the Ra,Dec grid for the image (the blue lines above). The result of image_pa is the direction to North (thick red line) and the direction East (thick yellow line). We see that this legend agrres well with that generated by ds9 using the WCS in the DSS image header. Just because this is a rather rare case, here is the part of the header that identifies this Schmidt plate: ORIGIN = 'STScI/MAST' /GSSS: STScI Digitized Sky Survey SURVEY = 'POSSII-F' /GSSS: Sky Survey REGION = 'XP081 ' /GSSS: Region Name PLATEID = 'A1MB ' /GSSS: Plate ID SCANNUM = '01 ' /GSSS: Scan Number DSCNDNUM= '00 ' /GSSS: Descendant Number TELESCID= 3 /GSSS: Telescope ID BANDPASS= 35 /GSSS: Bandpass Code COPYRGHT= 'Caltech/Palomar' /GSSS: Copyright Holder SITELAT = 33.356 /Observatory: Latitude SITELONG= 116.863 /Observatory: Longitude TELESCOP= 'Oschin Schmidt - D' /Observatory: Telescope INSTRUME= 'Photographic Plate' /Detector: Photographic Plate EMULSION= 'IIIaF ' /Detector: Emulsion FILTER = 'RG610 ' /Detector: Filter PLTSCALE= 67.20 /Detector: Plate Scale arcsec per mm

 

% image_pa dss_bsc5-0747.fits 
355.0000   85.0001

 

% cat image_pa.out 
 355.4000   85.4000   -4.6000

% cat image_pa.explain 
paN paE (f9.4)
paN = angle in degrees CCW from +Y of North direction
paE = angle in degrees CCW from +Y of East direction
dPA = small angle relative to +Y (+ is CCW, - is CW)
 

In Aug2017 I decided to add the ability to write a second form of WCS header to my images. In the process of this I upgraded image_pa and added some improved online documenation.

 
% image_pa --help 
Usage: image_pa a.fits
arg1 - FITS file image name

image_pa:
  Use the WCS in an input FITS image to determine the direction of the North 
and East directions in the image. 

------------------------------------------------------------------------------
To change the default length (10 arcmin) of the North vector in the sky 
compass made by image_pa, put the desired value inside a local file named 
"image_pa.Rlen". Here is the part of the script that performs this change: 
# Create the NE legend (hardcode at 10 arcmin length along North direction)
Rlen="10.0"
if [ -e "image_pa.Rlen" ]
then
 read Rlen < image_pa.Rlen
fi
------------------------------------------------------------------------------

The output file made by image_pa:
image_pa.out         == lists the 3 angle values (that also go to standard out) 
image_pa.explain     == explains the 3 values above 
image_ps.explain     == gives the plate scale and error in arcsec per pixel 
NE.reg               == the ds9 region file for plotting a sky compass 
NE.explain           == explain the size and color-scheme of the sky compass 
xycirc.reg           == region file showing the angular grid used to determine PA