ImageMatch (Kelson & Burns)
This software matches the seeing of one FITS image to another of the same field (or sub-field) by solving for a convolution kernel. The kernel is modeled as an N X N matrix, so in that sense is non-parametric. Linear least squares is used to solve for the best kernel that minimizes the residuals when the first image and convolved second image are subtracted. A quick run-down on the features of this software:
- The kernel is non-parametric.
- Image registration, sky-subtraction, and flux normalization are all part of the kernel solution.
- Uses WCS information (if present in the header) to automatically match objects for image registration and kernel matching.
- Handles images with different plate scales, orientations, etc.
- Arbitrary-order coordinate transformations between science and reference images supported.
Installing
ImageMatch is developed and distributed under the Carnegie Python Distribution (CarPy). You get it for free if you install CarPy. You can also download it from github and install into your own python environment. It works in python 2 or 3. Required modules: numpy, scipy, vtk, astropy.
Using ImageMatch
The software is entirely run from the command-line. Unfortunately, with such a complicated process, this leads to many command-line switches. We're trying to make the code work more and more automatically using FITS header information. We also plan to implement parameter files. But for now, you might want to write shell scripts each time you have a set of images. That will help in the process of tweaking and remind you want you did when you come back later.
Use the command 'ImageMatch' with the science image(s) as the argument. At the very least, you should run the program with these arguments:
ImageMatch -m <reference.fits> -sex -match -p <k> -sub <science.fits>
where <reference.fits> is the reference FITS image, <k> is the size of the kernel in pixels, and <science.fits> is (are) the science image(s). The switch '-m' identifies the reference image (which we notationally call the 'master' in the code, '-sex' runs sextractor to find objects, '-match' does the PSF matching, '-p <k>' sets the kernel size (make this greater than your typical seeing), and '-sub' does the image subtraction. This will only work if both images have the same scale and the 'SCALE' header keyword is set appropriately. A more complicated (read: realistic) example might be this one that matches a science image taken on the LCO 1-m Swope telescope with the same field taken on the LCO 2-m Dupont telescope:
ImageMatch -sex -sexdir ~/sex -match -scale 0.537 -mscale 0.199 -o 0 -p 7 -sub \
-sky -m reference.fits -wcs -fft -snx 125.67998d -sny 22.55481d -v -t 2. -s 2 science*.fits
Here is a complete list of arguments. We try to separate them into logical units.
Object Detection
| -sex | If specified, run sextractor to find objects and generate .cat catalogs. This must be done at least once |
| -sexdir | location of the sextractor param files. If not specified, default parameters will be extracted into the current folder under ./sex. |
| -pakey {str} | Name of rotation FITS keyword. Default: ROTANG |
| -scale {float} | Pixel scale (in "/pix) of the science image, either as a fixed value or as a FITS keyword that will be looked up. Default: 'SCALE' |
| -mscale {float} | Pixel scale of the reference (master) image. Default: scale of the science image. |
| -t {float} | Object detection threshold in units of background sigma (default 3) |
| -nmax {int} | Use only the nmax brightest objects (default: 50) |
| -max {float} | Saturation level in ADU for the science image. |
| -max2 {float} | Saturation level for the reference image. |
| -reject | If specified, completely reject saturated objects (rather than keep their unsaturated wings). |
Object Matching
| -s {float} | Tolerance for matching objects from reference to science (in pixels). Default 3.0. Increase this if you're not getting enough object matches. |
| -arange {a,b,c} | Specify a range of angular offsets to try between the science and reference image (if ROTANGs aren't properly specified or a full WCS is not available). Angles from a to b in steps of c will be tried (warning: this can take a long time if you make c too small). |
| -interactive | Plot science and reference image side-by-side and have the user interactively match objects. Use when the automatic algorithm can't do it. |
| -db | Once an initial matching has been done between the science and reference images, specify this switch to re-use the matches. Useful if you had to interactively match objects, but want to go back and tweak other parameters and not have to go through the matching again. |
| -wcs | If present, use WCS information in the FITS header to do match the objects. This makes life much easier (it also allows you to specify certain parameters in world coordinates rather than pixel coordinates). |
Coordinate Transformation
| -o {int} | The order of the coordinate transformation to be computed between the science and reference images. A value of -1 will compute a simple X/Y shift, 0 will compute a shift, rotation, and scale. Values >= 1 will compute a generalized o-order transformation. The program will give you an error if you try to use an order that is too high for the given number of object matches between the science and reference images. |
| -reg | If the images have already been registered with respect to each other, use this switch to bypass the coordinate transformation. |
PSF Matching
| -match | Do the PSF matching (you usually want this) |
| -p {int} | Radius of the kernel (p X p) in pixels. Special value of 0 or 1 will give you a simple flux scaling. The kernel should be larger than the seeing of the worst image. Warning: the larger the kernel, the larger the matrix that has to be inverted. Typically, p = 9-11 does the trick. |
| -X {float,float} -Y {float,float} |
Specify a range in X and Y (inclusive) to use to constrain the kernel. The larger the area, the larger the matrix that needs to be inverted. This is useful for masking out bad edges. If a WCS is defined and you use -wcs, then you can specify the limits as world coordinates by appending 'd' to the values of the floats. |
| -sky | Include a constant-offset to the kernel. This is equivalent to computing a sky offset between the science and reference images. |
| -R | Reverse the sense of the matching. Usually, the reference is blurred to match the science image. But in cases where the seeing in the science image is significantly better than the reference, you need to do the opposite and blur the science image. |
| -preserve | Compute a flux-conserving kernel (sums to 1). Useful with the -R switch so that the science image retains the same flux. |
| -sig {string} | Use this if you have a noise map. The .fits from the filename will be replaced with {string}.fits. The noise should be RMS (not variance). |
| -user_masks | Use this if you want to mask out square regions of the images. Useful if you have bad data or very saturated stars. |
| -mask_file {string} | The mask file to use with -user_masks. Each line is a mask and is specified by xmin xmax ymin ymax. The values can be pixels or, if a WCS is defined, you can use world coordinates by appending a 'd' to the values. |
| -snx {float} -sny {float} |
Specify the position of the transient so that it is automatically masked out. {float} can either be in pixels or in world coordinates (if a WCS is defined) by appending a 'd' to each value. |
| -fft | When convolving the computed kernel with the reference or science image, use an FFT to speed things up. Otherwise, the exact (but slower) shift-and-add method is used. |
Image Subtraction
| -sub | Perform the subtraction of the reference from the science image. |
| -dsize {float} | If specified and if -snx and -sny are specified, only a circular area {float} pixels in radius around snx and sny will be subtracted. Useful if you want to do differential photometry of the transient with respect to local stars on a single image. |
Miscellaneous
| -v | Verbose output. Mostly useful info and only textual. |
| -vv | More verbosity, including image-based feedback. |
What you Get
The code outputs many files, all of which an help to diagnose how well the algorithm worked. The program takes the name of the science image, removes the 'fits' extension, then adds a string.fits to the end. Most important outputs are the SN.fits, temp.fits, and diff.fits: the (perhaps blurred) science image, the (perhaps blurred and registered) reference image, and difference image. Here's a complete list:
| {file}SN.fits | The science image which, when using -R, will be convolved with the kernel. |
| {file}master.fits | The registered reference image (by not convolved with kernel) |
| {file}temp.fits | The registered and convolved (if you don't use -R) reference image |
| {file}diff.fits | The difference image. If -dsize is used, only a circular aperture will be subtracted. |
| {file}bg.fits | Background-subtracted science image |
| {file}mask.fits | The data that is used to constrain the kernel with all other pixels masked out (set to zero). |
| {file}noise.fits | Estimate of the noise in the science image. |
| {file}seg.fits | The segmentation map output by sextractor. |
| {file}bases.fits | The SVD used to invert the design matrix produces an orthogonal set of basis vectors. Have a look at them, they're pretty cool! You can think of these as the 'eigenkernels' |
| {file}grid.fits | The resulting kernel used to smear the reference (or science) image. Good diagnostic. |
| {file}rdv.fits | The eigenvalues of the problem. This is a 1D FITS file. |