Dave Mitchell's DigitalMicrograph™ Scripting Website

Function

A script to acquire a sequence of images from a Gatan CCD automatically.

Version

version:20211004, v2.0

Author

D. R. G. Mitchell

Acknowledgements

Comments

Updates in v2.0 If you are using an earlier version of this script with a CCD camera, such as the Ultrascan or Orius, then stick with that version of the script. There is no new functionality in this version for users of those older systems. This script has been revised to make it more compatible with newer fast cameras, such as OneView and Rio. The key modification has been to incorporate a delay in fast mode, to account for the very fast output (25fps) of these cameras even when integrating to produce effectively slower frame rates. More details are provided in the script header.

This script has two modes of operation: Slow and Fast.

In Slow mode it can acquire a number of frames with a delay between them. This may be useful for recording a slow sequence of events such as a heating, irradiation or cooling experiment. The maximum acquisition rate is determined by the camera overhead, usually about one frame every 1-5s depending on camera/binning/exposure. The camera parameters are set in the dialog and the recording can be set running freeing up brain space for keeping track of focus, specimen drift, temperature controllers etc.

In Fast mode the script captures the updating image shown in the live Camera View (Gatan interface). Here the acquisition parameters are set in the Gatan Camera view panel. The maximum frame rate may be 5-25 frames per second, depending on camera, binning, CCD area used etc. Use this mode for capturing fast action such as an in-situ indentation. Images captured by the script can be saved into either a 3D stack - the limit to the number of frames stored in the stack being set by the available computer memory (RAM), or they can be spooled to disk - effectively no limit. The latter allows many minutes of action to be recorded at a high rate. My Orius camera produces around 11 frames per second, when optimised for speed.

Spooled images are saved to disk in .dm4 format, preserving image bit depth and resolution, which may be lost in some video encoding systems, and especially in direct screen video captures. Spooled images can be batch converted into TIFFs offline and then assembled into a movie in ImageJ or similar. Spooled .dm4 images can be assembled into a 3D stack offline using the Stack Alignment script available at this site. If you assemble the stack on an offline computer which is 64 bit and has a lot of memory, you can build a very large stack, which you may not be able to do on your microscope computer.

System Requirements

Tested on GMS 2.3 with Ultrascan and Orius cameras and GMS 3.3 with a Rio16 camera.

Known Issues

If you chose to save data into a 3D stack (Spool option off), the data is saved into memory. The script will attempt to create the stack based on the byte size, frame size and number of frames you specify. Since the image is written into memory (RAM) close all unecessary programs and save and close all work in DigitialMicrograph before proceeding, to maximise RAM availability. If there is inadequate RAM available for the stack you specified, it will ask you to down-size. You can use 2byte instead of 4byte, a smaller frame size, and/or smaller number of frames. If you choose the Spool option the data is written to disk directly. Here, you typically have unlimited space and can save hundreds or thousands of frames. For very fast cameras you may find that the hard disk writing becomes the rate-determining step. You might try installing a small solid state drive (SSD) and spooling to that. Write speeds for such drives can be 5-10x faster than slow spinning hard drives. Your mileage may vary, depending on where the bottleneck is. If it is the camera hardware or the script, then an SSD will not help.

In the case of fast acquisition, images are captured from the updating Gatan live View image, which needs to be displayed before starting the script. Unlike direct screen capture, the size at which the live view image is displayed does not affect the size/resolution of the captured data, so you can make the live image small and push it into a corner of the screen if you wish. To maximise the frame rate typically use large binning and use a sub-area on the CCD. My Orius camera can produce up to 11 frames per second (0.09s per frame) with 4x binning - even where I specify a much shorter exposure time (e.g. 0.001s). Under these conditions the frame rate is hardware-limited. To avoid potential unpredictable frame skips, it might be a good idea to set the Camera View exposure time to be slightly longer than the achievable minimum frame duration - e.g. set the exposure to 0.1s per frame (10 frames per second), to ensure that the hardware is not running flat out. The above frame rates and times will vary with camera, so experiment with your system.The 2byte data format will maximise the number of frames you can (Fast mode) capture into RAM. However, due to a conversion overhead (the data is sourced from the camera in 4byte format), this may lead to a slight reduction in frame rate. With less data to write to disk (Slow mode), 2byte may speed things up if a slow spinning disk is your bottleneck. If you are writing to a much faster SSD - then choosing 2byte may result in a slightly slower frame rate. You will need to experiment with your system to find out where the sweet spots are.

The script provides the option to spool files in either .dm4 format or .tif format. Do not use the TIFF format, since TIFF writes are very slow and the maximum spool rate will be around half of what you will get with .dm4, due to the format conversion overhead. In any case, .dm4 is a much better format for preserving bit depth, and of course spooled .dm4 files can always be batch converted to TIFF after acquisition.

When spooling files there is an option to save the file with a time stamp in the filename. You may need to turn this off if you intend converting the files to TIFF and assembling them into an AVI movie in ImageJ - the files may need sequential file names (Frame 00001, Frame 00002 etc) for this to work. The .dm4 files have the elapsed time at which the frame was captured saved in a (TEM Recorder) tag on the image, so even if the filenames do not contain times you can find the exact exposure of each frame. TIFF files do not support universally accessible calibrations or tags, so a small text file is saved with TIFF images which records the image's calibration and the elapsed time at which each frame was captured.

You may already have some kind of video capture system in place. This script may well work in parallel with your existing video capture solution. The advantage of capturing both a video and a sequence of .dm4 images or stack is that when you wish to extract a particular frame from the video to highlight an event or feature, the video frame may be of poor quality and low contrast and 8 bit depth. Here, the saved .dm4 file can be used and the contrast optimised much more readily due to the superior bit depth.

There is an extensive description of the script functions at the start of the source code.

Supported

Yes, but please be aware, if I do not have the same camera as you, my ability to troubleshoot is very limited.

Included Files

Source code.

Source Code