The purpose of out transformation code is to allow positions on one image to be transformed to positions on another image or catalog of stars. When the comparison is between images, the relevant code is ftransimages. The information gained from this can be used to build a transformed version of the image on the reference system of the second image using moveimage and moveimagespline. When the comparison is to a catalog of star positions (such as the APM or USNO catalogs), the purpose is to generate a more accurate ra/dec solution by finding stars from the catalog on the image.
The method used is to treat each star or galaxy as a single point, and then to use a linear fitting routine to fit the coefficients of a specified transformation. This method generally works quite well because our images generally contain a sufficient number of objects to allow meaningful rejection of outliers and produce small error bars on the coefficients. A method that takes advantage of the shape information for the objects, such as cross-correlation, may be theoretically superior, but suffers from several practical difficulties. First, cross-correlation and other shape-matching routines are far more computationally expensive. Second, such methods generally have a very difficult time with rotations between frames.
The available transformations are parameterized by the parameter order. As it is currently used, order does represent a polynomial of that order, but this may not always be the case. Order should instead be thought of as a tag for a certain type of transformation. Orders 0-99 are the valid range for transformations.
Unfortunately, currently we don't understand how to extend some of the pre-existing code (transpoly2d.c) to non-polynomial cases. Anybody who feels like trying to figure this out, please feel free to do so.
The coefficients for the transformations are held in the kx/ky fields of trans_struct's. Errors are stored in errkx and errky. If the deepsearch common blocks are being used, trns[a,b].kx and ky hold the transformation coefficients to take a point from the image in buffer a and transform it to a position on the image in buffer b. The inverse transformation coefficients are stored in trns[b,a].kx and ky. The order of the transformation is in trans_struct.order.
The apm solution coefficients are stored in ims_struct.apmkx and ims_struct.apmky, the order in ims_struct.apmorder, and the inverse transformations in ims_struct.apminvkx and ims_struct.apminvky. These coefficients are passed through the same machinery as trns.kx and ky, but have a scale change applied to prevent roundoff errors. This scale change is stored in trns_struct.kx[0:1], and the other coefficients are bumped up the array. The upshot of this is that trns_struct.kx must have the space to store the number of real coefficients plus two if the transformation can also be used with the apm solution. In any case it is not a good idea for imsum_struct.apmkx/apmky to have fewer elements than trns_struct.kx/ky.
This is a rough description of some of the important procedures involved in calculating and using transformations. For more information, including how to use them, use dlib,'name_of_function' or go to the detailed description section.
ftransimages.pro: This is the user interface for calculating transformations between images. It first checks to see if a transformation already exists, and if one does loads it in. If one does not exist, or it is explicitly (clobber) ordered to calculate a new one, it calls ffieldmatch.pro to do the real work.
ffieldmatch.pro: First this performs an initial match and generates a first order transformation, with iteration over the matchall tolerance. ftranscorrect is then called to calculate the real transformation.
ftranscorrect.pro: This takes the initial transformation and the matched set of points and determines the coefficients for the transformation. There is some attempt to reject bad matches through iteration and clipping based on the standard deviation of the distribution.
ftranseval.pro: This allows you to examine the quality of a inter-image transformation. It calculates some statistics about the transformation, and allows you to display the residuals as a function of position on the image.
readtransimages.pro: Reads the transformations from the database using runtransquery.c to interface with the database.
writetransimages.pro: Writes a transformation to the database, using runsqlcommand.c to interface with the database.
apmmatch.pro: This calculates the transformation between a catalog of stars and the image. It is called by default from reduceimage unless /skipapm is set.
apmscale.pro: Computes the linear scale on the chip at a given position using the apm solution.
apmeval.pro: This plays a similar role for the apm solution as ftranseval does for inter-image transforms, allowing you to evaluate the quality of an apm solution.
transpho.pro: Will apply the transformation to a input star_struct.
transxy.pro: Does the same thing as transpho, but to the straight x and y position without involving a star_struct. Smart code would just call transpho, but this isn't smart code.
moveimage.pro: Uses the transformation to move an image to the frame of another image, using linear interpolation. This preserves the photometry, but tends to worsen the seeing.
moveimagespline.pro: Does the same thing as moveimage, but uses spline interpolation to help preserve the seeing. Unfortunately, flux conservation is lost in the process. In other words, this is good for searching, but don't even think about making a light curve using subtractions based on moveimagespline. It's also substantially slower than moveimage.
ftransimages2: This is basically the user interface for the transformation code. Given two filenames and some trans_struct-s, it will try to load in the transformation between the two images. If it doesn't exist (or if it is explicitly ordered to by clobber), it calls do_ftransimages2 to actually calculate the transformation.
I am compiling this list to assist anyone who finds it necessary to add any new forms of transformation to the deepidl software. I compiled this list while in the process of adding support for 4th order polynomial transformations on and around May 25th, 2000. As of this writing many of these functions also have a (function)2.pro version which also needs to be modified. Hopefully the original versions will soon simply become wrappers to call the 2 versions.
The apm and inverse apm transformations require two additional coefficients, which are stored in the first two slots of kx and ky.
Files that may need to be modified:
IDL:deepidlstart: If you require more coefficients in kx/ky or apmkx/apmky and their ancillary variables,this is where you modify the structures that will contain them.
transpho.pro: You need to add the evaluation of the transformation as well as the error propagation here.
ftranscorrect.pro: This is where the transformation actually gets calculated, so code to evaluate the transformation will need to be added.
ftransimages.pro: If you decide to include a non-polynomial transform, you probably need to take a close look at this code.
ffieldmatch.pro: Same caution as for ftransimages.pro
moveimage.pro: This performs the non-spline image moving. You may need to modify both the box commands and the magnification vector. Also, if you are adding a non-polynomial transformation you may need to worry about how the magnification is calculated.
moveimagespline.pro: This performs the spline based image moving. Again, look for the box commands and the magnification vector. Again, you may need to worry about how to calculate the magnification.
readtransimages.pro The number of required parameters (nopar) and the code to read in the transforms from the database may need to be modified.
apmmatch.pro: You need to examine this if you are planning on allowing the apm solution to use your new transform. For a non polynomial transformation, you will need to figure out how to calculate the magnification.
apmscale.pro: Again, if you plan on allowing apm solutions to use your code, you need to look at this. Specifically, you need to add a scale-calculating entry for your transform.
subng.pro: apmkx, etc. have hard coded size limits in here which you may need to modify.
writetransimages.pro: This needs to know how many real coefficients are required.
fchartng.pro: trnsimapm.kx and ky have some hard coded limits.
getsubngsql.pro: apmkx, etc. have hard coded sizes in this file.
transxy.pro: You need to add the transformation evaluation code here.
matchall.pro: transx and transy have a hard coded size.
transpoly2d.c: Called by moveimage. I'm not sure how this actually
works, but you'll need to add an order
transpline.c: Called by moveimagespline. There is a case statement that will need your attention.
matchup.c: This needs the code to evaluate the transformation. Note that matchup.so and testmatchup.so are really the same thing, so if you make changes to this file make sure to recompile both.
runtransquery.c: This has hard coded kx, etc. limits.
runimquery.c: This has hard coded apmkx, kx, etc. limits.