ZTOOLS - fits image manipulation routines
Craig DeForest
These routines are for manipulating fits files, and were by-and-large
designed for manipulation of solar images. They all use the
standard FITS alignment tags to keep track
of the image-plane coordinate system.
They're not in the public domain; they are copyrighted (©
Craig DeForest). You may copy, distribute, and use them for any
non-commercial purpose. If you want to use the routines or any
derivative for a commercial purpose, you must cover RSI's IDL support
registration fee for me for a period of one year.
HOW TO USE
The download package includes three directories: "util", "images" and
"images/xform". All three directories must be in your IDL
!PATH variable. You must, in particular, include the
ztools "util" directory, which contains quirky utilities like
isvalid that are used by these routines.
If you want to use ZTRACK, you will also need supporting routines
from the
CDS
instrument software tree (notably anytim2utc by Bill
Thompson and hel2arcmin by Liyun Wang.) These are
available on the solar software tree developed by Sam Freeland and Mons Morrison.
the current library in compressed,
tarred form -- if you dare! (You'll get the misc directory and the images
directory, plus the "xform" subdirectory). Caveat you get the
last version I happened to tar up. If you want the very latest stuff, please
send me email and ask to
have it updated.
What is What (Abridged Functional Index)
Here is a summary of the more useful routines, broken out by rough
function. The really useful ones merit their own lines; moderately useful
ones are merely mentioned.
- Image Manipulation and Co-Alignment
- (See also the FIXINATE_* routines for
information on calibrating headers).
- ZMATCH - Co-align a solar image to another image's header
- ZSCALE - Rotate, scale, and/or translate a solar image (while maintaining the header info)
- ZCLIP - Clip out a specific region of an image, in pixel co-ords
- ZTRACK - Track a particular point on the solar surface
- ZHOVER - Transform an image to appear as though you were hovering over a particular surface point
- Coordinate Transformations and Image Distortion
-
- Image comparison and overlay
-
- ZOVERLAY - Superimpose two solar images, or place one inside another (SUNCP is optimized for circular, concentric overlays).
- ZMAGOVERLAY - Special "transparent-magnetogram" overlay algorithm
Complete Index by Alphabet
- SUNCP
- Overlay a circular image into the center of a larger image. Useful for overlaying coronagraph and on-disk solar data.
- ZASPECT
- Fix up the aspect ratio of an image with nonsquare pixels, for
easier manipulation.
- ZCLIP
- Clip out a portion of an image, in image coordinates
- ZCONTOUR
- Generate a 1-bit array that's a countour map of the
given image
- ZCORRALIGN
- Attempt to generate relative alignment information between two
images, using correlation analysis.
- ZD4
- Perform D4 group transformations (the symmetry group of
a square) on an image. Saves processing power, over using ZSCALE or
ZMATCH. But I almost never use it -- Hodges' Law has worked its magic
several times since I wrote this, and my computer's fast enough now that
I usually use ZSCALE instead.
- ZDEGR
- Degrade a fits image by NxN pixel averaging.
- ZDEHELIOGRAPHINIZE
- Project a heliographic image back into the image plane of
an instrument. Especially useful in combination with ZHELIOGRAPHINIZE, to view the Sun as seen
from a different angle or time. (Caveat: this isn't a coronal tomography
routine -- it only works by mapping the image plane to the surface of the Sun.)
- ZFLIP_VERT
- Even cheaper than ZD4, flips the vertical axis of an image.
Updates the header appropriately. I never use this anymore -- ZSCALE works
well enough, though this is much more efficient.
- ZGRID
- This draws a radial image-plane co-ordinate system in the
current window, aligned with the header you give it. The main use is
for testing whether an image's header is really co-aligned with the
image itself.
- ZHELIOGRAPHINIZE
- Project an image into heliographic co-ordinates: longitude and latitude referred to the central meridian that is directly under the viewpoint. An arbitrary differential-rotation delay can be added in. Useful for magnetic modelling or for looking at proper motions of stuff near the surface of the Sun.
- ZHOVER
- Reproject an image to appear as though you're at a
different vantage point and/or time -- you specify the latitude,
longitude, and time at which you wish you were observing, and the
image is transformed to appear as though you were looking straight
down on it. Uses ZHELIOGRAPHINIZE and
ZDEHELIOGRAPHINIZE, so it's a little
slower than it could be -- but, hey, it works like a champ. Called
ZHOVER because it can be used to simulate "hovering" over a part of the Sun.
(Remember that ZHOVER doesn't do stereoscopy: it treats all image features
as if they were painted on the surface of the Sun.)
- ZMAGOVERLAY
- Overlay a magnetogram on top of another image, by threshhold
replacement. Weak magnetic fields do not affect the original image; strong
ones cause pixel-by-pixel replacement. Works only on bytscled images.
- ZMATCH
- Given an original image and a target image header, move, rotate,
and scale the original image to the same coordinates as the target image.
- ZOVERLAY
- Overlay a pair of images on top of one another, after scaling to
match.
- ZPRINTSUN
- Generate a PostScript image of a fits file, with centering,
labelling, and optional grid (from ZGRID).
- ZSCALE
- Scale, translate, and/or rotate a FITS image arbitrarily.
- ZTRACK
- Given a point in image-plane pixel co-ordinates, transform
other image headers so that the point is kept stationary in the image
plane as the Sun rotates. (Uses Liyun Wang's "arcmin2hel" and
"hel2arcmin" routines).
- ZUNWRAP
- Convert a solar image to radial, polar image-plane coordinates. Useful for looking at coronal expansion ratios or for combining images with several different fields of view (eg you can view LASCO C-3 and Yohkoh together in a meaningful way).
- ZWRAP
- Convert a polar image from ZUNWRAP back to regular angular image-plane co-ordinates.