AutoMatch FAQ

This FAQ assumes that you capture at 640x480 pixels resolution. If your digitizer gives a higher resolution, say "WIDTHxHEIGHT", read
"WIDTHxHEIGHT" for 640x480, and
"HEIGHTxHEIGHT" for 480x480.


Q: The NIH Image source code is in the public domain. Why, then, is AM written in the NIH Image macro language rather than being compiled into NIH Image?

A: Compatibility. AM was written entirely in the macro programming language to avoid creating another NIH Image spinoff version. Several NIH Image spinoffs have been released, each of them with some additional specialized functionality. The problem with spinoffs is thatÉ
¥ the version of NIH Image which they are based upon becomes outdated very soon, since NIH Image is under constant development. Therefore, more recently added features of NIH Image (usually very important ones) are not available in the spinoff versions.
¥ the functions of one spinoff are not available in another spinoff. We ended up with switching between 3 versions - two spinoffs (Object Image, BrainImage) plus the most recent version of the original.
Written in NIH Image macro code, NIH Image will be compatible with all future versions of NIH Image, and with all spinoffs based on NIH Image 1.60 or later.


Q: Macro code is much slower than compiled code. Isn't the decision to write in macro code a big trade-off to speed, especially in the case of a computationally intense application like image mosaicing?

A: No. Macro code IS much slower than compiled code, it is true, but this does not matter in the case of AM: More than 95% of the processing time are consumed by the fourier transformations, which run in compiled code anyway (they have been coded into the original NIH Image since v1.59), and are just called by the AM macro code.


Q: In an AM "Settings" dialog, I hit the "cancel" button - and AM crashed!

A: It didn't crash. Hitting the cancel button in one of the preferences dialogs simply causes the macro execution to stop, rather than to leave the dialog without changing the settings. This is a problem with the NIH macro programming language. You MUST NOT hit cancel in any dialog; the current settings are displayed - to leave the dialog without changing the settings, click "OK" or hit the RETURN key.

Q: OK, but I did hit the cancel button and now the AM main window is still on the screen and doesn't respond to mouse clicks.
A: Since the macro programming language doesn't provide for custom dialogs, a complete graphical user interface (GUI) had to be emulated in standard NIH Image image windows. When you accidentaly hit the "cancel" button in a preferences dialog, the macro execution stops and you are back in NIH Image - with the AM main window (remember, it is simply an NIH Image image window) still open. Unexpected termination of the macro code leaves several other internal windows open in NIH Image, too (though they may be hidden from the user). These internal files are used for the internal AM filing system etc.). To get rid of all that junk, press alt-cmd-W to close all open windows and say NO when NIH Image asks you whether you want to save changes - or, even simpler, use the mini-macro "Oh bugger, it crashed" in the special menu of NIH Image.


Q: AutoMatch gave a macro execution error, terminated, and left a screen full of weird windows - and, most of all, the AM main window is still there but doesn't accept mouse clicks.

A: ¥ When the macro execution is unexpectedly terminated, you are back in NIH Image - with the AM main window (remember, it is simply an NIH Image image window) still open. Unexpected termination of the macro code leaves several other internal windows open in NIH Image, too (though some may be hidden from the user. These internal files are used for the internal AM filing system etc.). To get rid of all that junk, press alt-cmd-W to close all open windows and say NO when NIH Image asks you whether you want to save changes  - or, even simpler, use the mini-macro "Oh bugger, it crashed" in the special menu of NIH Image.

¥ Macro execution errors are most likely due to memory shortage: AM needed to create a window but there wasn't enough free memory in NIH Image. Try and allocate more memory to NIH Image (via the finder "Get Info" window). The next version of AM will try to check the memory available before attempting to open a new window.


Q: Why does AM capture square frames?
Q: Why is the video live input clipped to square dimensions, displaying and capturing only the square portion of the camera window? It takes even more video frames to cover the region of interest in the specimen!

A: You have set "Use original frames for mosaic?" to "n" (no) in the "Frame SizeÉ" dialogs!

In this case, AutoMatch will use clipped and scaled frames to build the mosaic. Automated mosaicing involves Fast Fourier Transformation (FFT) of the frames. FFT (a Fast Hartley Transform in the case of AM) works only on power of two square images. That is why only the largest possible square that fits into the camera window is displayed and captured during acquisition. Also, the acquired square frames have to be scaled to power of two squares afterwards. The scaling is also set in the "Frame SizeÉ" dialog: "small" for 128x128, "normal" for 256x256, or "large" for 512x512. With"Use original frames for mosaic?" set to "n" (no) in the "Frame SizeÉ" dialogs, AutoMatch will use the scaled squares to build the mosaic.
If you want to put it this way: yes, it takes more frames to cover the object in AM than with full-sized acquisition!
If you want to utilize the full resolution of your digitizer, set "Use original frames for mosaic?" to "y" (yes) in the "Frame SizeÉ" dialogs.
Refer to the next two FAQs and to the manual for advantages and disadvantages of using the full rectangular frames.


Q: Don't we lose a lot of image information when scaling down from, say, 480x480 to 256x256?

A: Not really if the 480x480 frame is a CCD video camera frame. The images generated by a CCD video camera are somewhat fuzzy or blurred, so not every single pixel carries information about your object (there is less information about the object in the digitized video frame than there coud be in terms of pixel resolution).
In this case of a blurred signal, scaling from 480x480 to 256x256 will rather cause a packing, a mapping of essentialy the same information into fewer pixels. What was a larger Gaussian blurred spot before will become a smaller and more distinct spot in the scaled image. Since there was no information within that blurred large spot, nothing essential is lost.

Therefore, setting "Use original frames for mosaic?" to "n" (no) and scaling down to 256x256 results in smaller and sharper images that carry the same information. This is convenient for working on-screen with large mosaics. For printing (where you need 300 dpi) you might prefer larger frames.
Either scale to 512x512, or use the original frames for building the mosaic. If you want to utilize the full resolution of your digitizer, set "Use original frames for mosaic?" to "y" (yes) in the "Frame SizeÉ" dialogs.
Refer to the next FAQ and to the manual for advantages and disadvantages of using the full rectangular frames.

If your digitizer gives a resolution significantly higer than 640x480, you will also prefer to either clip and scale to 512x512 during acquisition ("large" with "Use original frames for mosaic?" set to "n" (no)), or to use original frames and match them with large scaling ("Use original frames for mosaic?" set to "y" (yes) during acquisition and "large" during mosaicking). Either option needs substantially more free RAM in NIH Image, however, and takes much more time to compute.


Q: Wouldn't it be a better idea to scale the frames only for calculating the frame-to-frame translation vectors, then scaling the vectors back, and mosaicing the original frames, whatever their size might be?
With non-proportional scaling, this would even work for non-square frames!

A: You can do this! You just need to set "Use original frames for mosaic?" to "y" (yes) in the "Frame SizeÉ" dialogs. The problem, however, is the accuracy in the calculation of the translations. When scaling 640x480 frames into 256x256 frames (option "normal" in the "Frame SizeÉ" dialogs) just for calculating the cross correlations, there are only 256 possible values for the X- and Y-coordinates of the translations. 
For best precision, choose "large". This gives a scaling from 640x480 to 512x512, and accuracy along the Y-axis is less than 1, and along the X-axis it is still 1.25. However, it takes huge amounts of free RAM in NIH Image and considerably more time to calculate.


Q: What happens if there is not enough overlap between two frames, if there is no overlap at all, or if the region of overlap doesn't provide enough/any information for matching (empty region on the slide, e.g.)?

A: With the current version of AM, this gives a corrupted image. AM looks only for the absolute maximum of the cross correlation function and there will always be some  absolute maximum. I have not yet found a suitable answer for that problem - I would really appreciate your suggestions.

If the mosaic was acquired with the "Use original frames for mosaic?" set to "y" (yes) in the "Frame SizeÉ" dialogs, you can try to set a larger frame size in this dialog. Frames that don't get mosaicked properly with the frame size set to "small", e.g., may mosaic successfully in "normal" or "large", given they have some overlap. If they don't have any overlap, or if they were acquired with "Use original frames for mosaic?" set to "n" (no) and they result in corrupted mosaics, there is nothing you can do but re-acquire with higher overlap.


Q: Why doesn't AM make use of the background correction ("Save Blank Field") which is provided by NIH Image (and which allows for a more sophisticated correction than the simple subtraction+offset method as done by AM)?

A: Because the NIH Image "Blank Field" is always one single (temporal) frame, i.e. you cannot average the Blank Field when you capture it. Therefore the white noise on the Blank Field is inherited by all following frames that are corrected on the basis of the (noisy) blank field.


Q: Wouldn't it be easier to capture the series of frames using the NIH Image "Capture Frame" command?

A: You cannot do frame averaging then at all.


 Q: To display only the largest possible square of the camera window, AM shifts the "Camera" window beyond the right border of the screen so that only the square is visible (That's one of the reasons why AM needs to know the screen dimensions). Wouldn't it be more elegant to use the "Paste Live" command to create a square live video window?

A: It seems that "Paste Live" gives slower frame rates than displaying the live video straight in the camera window.