Debugging ppSub: option to save stamp position used to determine the kernel

[arminrest]

One of the key elements of difference imaging is the choice of stamps used to determine the kernel. For debugging and testing, it is important to know:

#1 which stamps were rejected
#2 which stamps were used
#3 all possible stamps (used, rejected, and unused)

This information (in particular the x,y position, but also other info liek the reason why a stamp was rejected) could be saved in files, either straight ASCII tables or alternatively ds9 region files.

[Paul Price]

If you build the IPP without optimisation (no '-optimize' flag to psbuild), then the basic debugging system (what we call "trace" messages) is enabled. The programs run slower, but you get more information. Each trace message is associated with a component and a level, and you can configure on the command-line which components and levels are printed. The trace system is already used to output details about the PSF-matching process, and can be accessed if you know what to turn on. To get all trace messages regarding PSF-matching, try adding "-trace psModules.imcombine 10" to the command-line; this will produce a LOT of extra information. You can direct this to a file using "-tracedest /path/to/file". For more fine-grained control, try:

#1 rejected stamps: "-trace psModules.imcombine.pmSubtractionRejectStamps 3" (see pmSubtraction.c:866)
#2 used stamps: "-trace psModules.imcombine.pmSubtractionCalculateDeviations 5" (see pmSubtractionEquation.c:1111)
#3 all possible stamps: "-trace psModules.imcombine.pmSubtractionStampsSet 9" (see pmSubtractionStamps.c:438)

Of course, it would be good to generate a JPEG montage of stamps as QA output, and/or ds9 region files; I shall put this on my TODO list.

[Paul Price]

I've added the capability for ppSub to generate ds9 region files at various stages. Add the "-debug" flag to the ppSub (or ppStack) command-line to enable this; this works independently of whether you build optimised or not. The filenames and contents are:

#1 rejected stamps: stamps_reject_N.ds9 --> red indicates rejected, green indicates accepted
#2 used stamps: stamps_solution_N.ds9 --> red indicates bad (unused), green indicates used
#3 all possible stamps: stamps_all_N.ds9 --> red indicates bad mask, green indicates good, any other colour is bad (see the code for meaning).

For each of these, the N in the filename is an integer increasing from zero; this allows us to get the stamps at each iteration (and solution region if there are multiple).

Each region file includes a numbered grid (in blue) of sub-regions in which stamps are found. Only one stamp is taken in each sub-region (to ensure stamps are uniformly distributed over the image; it also serves to limit the number of stamps). The numbers correspond to the stamp number that is printed in the trace messages (e.g., when rejecting stamps, printing the deviations, etc).

Added on trunk at r23840.

Still need to generate a JPEG montage of stamps for ippMonitor, etc, but that's low priority.