Read Me for Online Version of DCI Plug-Ins -------------------------------------- This software distribution contains version 1.01 of the PixelTools 5.0 software which supports the Perceptics PixelToolsŞ PixelDCIŞ Digital Camera Interface board. The components of this online software release include: 1) A system init file named "PT50Init" which contains the PixelTools 5.0 Driver. This file goes into your System Folder. The driver allows other software to control any of the PixelTools boards, including the PixelDCI board. 2) A set of "Plug-Ins" for controlling various cameras using the PixelDCI board. A "Plug-In" is a software component which works in conjunction with certain application software packages and extends the capabilities of that application software. Adobe, Inc., has defined a standard interface to these plug-in components and has implemented this interface in their PhotoShopŞ application program. Many other application software packages, including NIH-Image 1.50 and later, have also adopted this interface. The plug-ins supplied with this software release should work with any application program which supports the standard plug-in interface (version 2 or later). This Read Me file includes installation instructions for the DCI Software, in addition to instructions for using the Plug-Ins. Please take a few moments to read this information. It will likely save you problems later on, plus, it may make you aware of features that you otherwise might not be aware of. Installation ----------- Installing the DCI software involves the following steps: Ą After downloading the archive containing this ReadMe and the Plug-Ins, Ą Copy the "PT50Init" file into your System Folder Ą Restart your Macintosh so that PT50Init will install the PixelTools driver Ą Copy the plug-ins into your application's plug-ins folder Ą Adjust the memory allocation for your application(s) which use the plug-ins These steps are discussed in more detail below. The software is contained in a Stuff-It archive. If you are reading this document, you must have already un-stuffed the archive. You should now have this ReadMe file, 4 plug-in files, and the PT50Init file in some folder on your hard disk. Move the "PT50Init" file from this folder into the "Extensions" folder inside your System Folder. The PixelTools 5.0 Driver is installed at startup by the PT50Init file. After copying the PT50Init file into your System Folder, restart your Macintosh. Now, each time the Macintosh is started, the PT50Init file will run automatically and install the PixelTools 5.0 driver. If you wish to use the plug-ins with Image, you must copy the plug-ins from this folder into the plug-ins folder for your version of Image. If you want to use the plug-ins with any other application, you must also copy them into the folder used by that application for its plug-ins. For example, if you use Photoshop, you must copy the plug-ins into Photoshop's plug-ins folder. Only copy the plug-ins you intend to use into the Plug-Ins folder. Leave the other plug-ins in the DCI Software folder. Using The Plug-Ins ----------------- To use a DCI PlugIn, select the plug-in by name from your application's File->Acquire menu. A dialog box will appear. You use the buttons and fields in this dialog to control the camera and the DCI board. Using the controls available in the dialog, you can select the operating mode for the camera, set the exposure time for the camera, load the DCI board's input LUT, select the type of acquisition (simple grab, arithmetic average, or multi-frame integration), select the post-processing operation for averaged or integrated images, select the bits of interest for display in a more-than-8-bit image, select the full camera view or ignore inactive pixels, select display of the image scaled to fit in the dialog window, initiate or terminate display of a live image, save the 16-bit result or intermediate image, scroll the image in the dialog live window, resize the image display window for faster updates, initiate an acquisition, or cancel the dialog with no changes. Each of these functions is described in more detail below. It may be helpful to refer to a picture of the dialog box as you read the discussion below. Camera Modes The camera modes are specific for the camera connected to the DCI board and are described in the camera documentation. Consult that documentation for more information. Most users will probably use Mode 0. In this mode, the exposure time is controlled from the dialog box and the camera is controlled through the DCI board by the Plug-In. With the camera mode set to 0, the exposure time field allows you to control the time the shutter is left open on the camera when an image is acquired. The desired exposure time should be entered into the indicated field before clicking on the Live button to start acquisition. Note that the value for the exposure time is entered as microseconds. You must convert the desired exposure time into microseconds for entry into the field. The range for the exposure time is camera-dependent, e.g., for a Kodak MegaPlus 1.4 camera, the range is 270-8847090 microseconds, or 0.000270 to 8.847 seconds. Input LUT The DCI board has a 16-bit input LUT which is used to map the incoming pixel values from the camera into values that are stored in the board's frame buffer memory. The DCI plug-ins allow you to load different patterns into this LUT. Specifically, you can load a standard, linear LUT, which will map pixel values "straight through", meaning that the pixel values are un-modified by the LUT. Thus, for this linear LUT, a camera pixel value of 10 will cause a value of 10 to be stored into the board's frame buffer memory for that pixel, and likewise for all other pixel values. Alternatively, you can select an inverse LUT which will cause the one's complement of the pixel value from the camera to be stored into the frame buffer. The third input LUT option is called "Other" and is actually the same as the linear LUT option. The option is provided as an easy means for a user to program their own input LUT option. With the source code for the plug-in, it is easy to modify the routine that handles the "Other" LUT option to load whatever LUT you might want. Selectable Operations The radio buttons under the Operation heading allow you to select the operation to be performed when you click the Acquire button. When the dialog is open, the operation will always be simple acquisition (called "Sample" in the dialog box). Thus, it doesn't matter which of these buttons you have selected when you click on "Live"; for the live acquisition and display, the operation will always be a simple grab. After verifying the live image, you then click the "Acquire" button to cause the selected operation to be performed. The Frames field under the Operation heading allows you to specify the number of frames of image data to be processed when you do the operation. Thus, this field is used to specify the number of frames to average or integrate. The Scale and Shift radio buttons are used to select the post-processing operations to be performed on the image data after the averaging or integration function has completed. If you select the Scale option, for example, the 16-bit result from an average or integration operation using 8-bit images will be scaled linearly so that the final result image will have values spanning the full range from 0 to 255. If, instead, you select the Shift option, the 16-bit result will be shifted (right) by the number of bits specified in the field next to the Shift button. Trim Edges The Trim Edges button is provided to allow you to select the portion of the full camera image that you want to see. Typically, cameras have a nominal size for the camera image. This size usually includes "inactive" pixels at one or more of the image edges. For example, the MegaPlus 1.4 has a nominal image size of 1360 horizontal by 1035 vertical pixels. In this image, about 28 columns at the left edge are inactive pixels, 12 columns at the right edge are inactive, and 4 rows at the top and bottom of the image are inactive. The plug-in software will trim off these inactive pixels if you select the Trim Edges option, giving you a smaller image which has no inactive pixels at the edges. This will also result in a smaller image being acquired. Scale To Fit The images produced by most digital cameras supported by the DCI board are at least 1K by 1K. This is larger than most display screens. Thus, you can usually see only a portion of the image at one time and must scroll to see the other parts of the image. The Scale To Fit option allows you to see the whole image at once so that you can, for example, adjust your camera setup, field of view, etc. When you are displaying a live image, just click on the Scale To Fit check box. The image display window will be re-sized to accomodate the full image display while maintaining the camera aspect ratio. Click on the Scale To Fit box again to return to normal display. Note that the Scale To Fit option only applies to live image display. The acquired image will always be the full size, regardless of the Scale To Fit option selected. Live Display Use the Live button to initiate display of a live image. Note that after you click the Live button, the button changes to "Freeze" to indicate that when you click on it again, the live acquisition will be stopped. While displaying a live image, you may use the scroll bars to scroll the digitized image within the display rectangle of the dialog box. You can also click in the box in the lower right corner of the image display window to re-size the display window to a smaller size. In this mode, the screen updates faster which should allow easier camera setup and focussing. Click in the box again to change it back to full size. Note also that you should freeze the live display before changing acquisition parameters such as camera mode and exposure time. You can change the input LUT and operation selection with live display active. Live Display of Images Greater Than 8 Bits The digital cameras supported by the DCI board are all grayscale cameras, of 8 or more bits per pixel. The Macintosh display can only display grayscale images to a pixel depth of 8 bits (even if you have a 24-bit display board). If the camera you are using produces more than 8 bits per pixel, you need a way to select how the camera pixels will be displayed. When you are using the Live display function of the plug-in, you can select which 8 bits of the camera pixels you wish to be displayed. To do this, you set a shift value in the text box beside the Shift radio button. The value you enter is the number of bits the 16-bit value will be shifted before the lower 8 bits are copied to the display screen. For example, consider the Kodak MegaPlus 1.6 camera. This camera produces a 10-bit value which is contained in the upper 10 bits of a 16-bit word. Thus, if you enter a shift value of 8, you will get the upper 8 bits of the 10-bit pixel value, which are also the upper 8 bits of the 16-bit word. If you enter a shift value of 6, you will get the lower 8 bits of the 10-bit pixel value, which are bits 13-6 of the 16-bit word. Another way to think of the shift value is to consider the value you enter as the bit number of the least significant bit, within the 16-bit word, of the 8-bit value you want to see. Note that you must Freeze the display and then select Live again to make the shift selection take effect. Acquiring An Image When you are ready to acquire an image into the application, i.e., either Image or PhotoShop, just press the Acquire button. The image will be grabbed into the board and passed to the application. The image will then be available for any desired processing with the application program. If you wish to exit without acquiring an image, just press the Cancel button. When you acquire an image, all of your last selections in the dialog box are saved. Then, when you later invoke the plug-in again, your previous selections will be restored. Note that the image acquisition will be performed using the operation selected. If, for example, you had selected Average of 8 frames, when you press the Acquire button, 8 images will be grabbed, averaged and post-processed. Then the result image will be passed to the application. If you want to see each of the intermediate images of the average as they are grabbed, select the Live button first then the Acquire button. If you don't care to see the intermediate images, make sure live display is not active before selecting Acquire. Saving a 16-Bit Image The raw images grabbed from a camera with more than 8 bits per pixel are considered 16-bit images. Thus, an image from the Kodak MegaPlus 1.6 camera, although actually only 10 bits, is saved as a 16-bit image. The 10 bits are acquired from the camera in the upper 10 bits of a 16-bit word as described above. When the image is saved to disk, though, the 10 bits of valid pixel data are stored into the lower 10 bits of the saved 16-bit word. This makes the image port more naturally into existing software packages that handle 16-bit images. To save a 16-bit image grabbed from a camera with more than 8 bits per pixel, just click on the Save 16 button. Supply the information in the dialog box which is then displayed and click OK. The image should then be saved and you can continue with the plug-in's dialog. The recommended format for saving images is "TIFF, Simple". This is a TIFF format which stores the image data in the most simplistic format available. It also uses a minimal file header which most TIFF-compliant applications should be able to process. Image can Import images which have been stored in this format. To import a 16-bit image into Image, select the Import function from Image's File menu. Select Custom format and then select the "Edit..." button to edit the parameters for the custom format. The width is the width of the camera image. For the MegaPlus 1.6, this value is 1536. The height is the height of the camera image. For the MegaPlus 1.6, this value is 1024. The length of the header (the value that goes into the "Offset" field) is 512 for all TIFF, Simple images. Select the Fixed Scale option as desired and enter appropriate values. Then set the image type as 16-bit unsigned and select the other options as desired. If you have an 8-bit camera, you can also save a 16-bit image. But, this 16-bit image is the accumulated result for an average or integrate function. For example, if you selected the Average function with, say, 16 frames, the 16 frames will be grabbed and summed into a 16-bit buffer in memory, then that 16-bit accumulation will be saved just as described above. After the save finishes, the average will be computed using the 16-bit accumulation and the 8-bit result will be passed on to the application, just as if you had hit the Acquire button. Notes ----- This is version 1.01 of the DCI Software. While we have attempted to provide useful features in the software and have modified features based on early user feedback, we realize that many more features could be added. Please let us know (preferably by e-mail to perceptics@applelink.apple.com or AppleLink to PERCEPTICS) if you have suggestions for future enhancements. Note also that, since this is version 1.01 of the software, it has not received much actual field testing. We have tested it internally and have had certain other users test it, but the real test always comes when you use it. PLEASE let us know as soon as possible (preferably, again, by e-mail or AppleLink) of any problems you discover in the software. You should also be aware that, like many applications (especially Image), strange things happen in the plug-in when you begin to run out of memory. Try to be very careful in managing your memory. Since the images are very large, only keep open the images which you need at any one time. Flush or save to disk any images which you don't need for a while. Also be sure to allocate lots of memory for your application. If weird things start happening, flush or save all images, quit the application, then run the application again. This should clear up memory fragmentation problems. In memory-limited systems, you may have to do this frequently. Note also that the minimum amount of memory recommended for using the DCI board with any of the supported cameras is 16 MB. Even with this much memory, you will be limited in the number of images you can process. If you need to process many images, it would be desirable to have 24 or 32 MB as a minimum.