Guide to Using dcam_capture

The Prosilica C-mount camera is a high resolution fire-wire camera that is in the PSM lab. Currently, the drivers and vendor-supplied software are installed on anduril. This page contains information on how to use the vendor-supplied viewing application, how to use the in-house dcam_capture command-line utility, and how to modify the dcam_capture utility.

• How to use the vendor-supplied viewer
• How to use the dcam_capture utility
• How to modify the dcam_capture utility
• Information about the various capture modes

How to use the vendor-supplied viewer

The Prosilica software includes a viewer application that allows you to view the live image feed from the camera and set a number of camera parameters. We often use this viewer to set up the initial camera location, focus, and some parameters before running the dcam_capture command-line utility to capture single images. To use the Prosilica viewer application:

• Locate the camera and lens (which should be in a yellow box on the shelf in the PSM measurement room), and the fire-wire cable. Attach the lens to the camera.
• Connect the camera to anduril and log into Windows. (Note: if you need to use another PC, you must install the drivers and software from the Prosilica CD).
• Open the explorer window and navigate to C:\Program Files\Prosilica\Viewer\.
• Run "Prosilica Viewer.exe". If the camera is connected properly, the live feed will be opened automatically. If it is not, check the cables and try again.
• The 4th button (from the left) on the toolbar opens the "Camera Controls" window. Here you can change many parameters such as exposure time, offset, gain, color balance, region of interest, etc. If at first the camera image is black, try increasing the exposure time.
• Focus the camera using the focus dial on the lens.

Note: Most of the camera parameters are retained for the duration of the time you are logged in, unless you explicitly specify a new value for the parameter (either in the Prosilica viewer or as a command-line argument to the dcam_capture utility).

How to use the dcam_capture utility

The dcam_capture command-line utility was developed to provide an interface to the camera for scripts. The utility makes use of the DCAM API, which is documented in "Prosilica DCAM API.pdf" (available on CVS, see "How to modify the dcam_capture utility"). With dcam_capture you can capture a single image or a number of images with different exposures. To use dcam_capture, follow the first two steps above in order to connect the camera to anduril and log in. It is a good idea to follow all of the steps above to make sure the camera is working correctly and focused on the object you wish to capture before using dcam_capture. Once the camera is set up and you are logged in, do the following:

• Start Cygwin.
• Type dcam_capture (which is equivalent to dcam_capture -help) to see the usage information. You will get the following output.

$ dcam_capture
Prosilica DCAM Single Capture Utility
Usage: dcam_capture filename [-e exp_time] [-o offset] [-g gain] [-m gamma] [-r x y w h] [-f format] [-s]
  filename       Currently supported extensions: .PNG, .JPG, .PGM, .PPM, .BMP
                     Use %lu to include exposure time in filename.
  -e exp_time    Set exposure time in microseconds.
                     For multiple exposures, use -e t1,t2,t3,...,tn
  -o offset      Set DAC offset.
  -g gain        Set pre-DAC gain.
  -m gamma       Set gamma (0 or 1).
  -r x y w h     Set region of interest. pixel (x,y), width w and height h.
  -s             Enable sub-sampling.
  -f format      Set format.  Currently supported formats:
                     mono8, rgb24, raw8, (mono16, raw16 for PNG only)

  -help          Display this help message.

The arguments are fairly self-explanatory. The image file format is determined by the extension, and the data format is set using the -f option. The camera parameters are all optional, and will take on default values if not specified. These default values will usually be the last known value (ie: if a value was set using the vendor-supplied viewer). However, it is a good idea to explicitly set the important parameters such as exposure time and format. Note that 16-bit single channel images can only be saved as PNG files.

When specifying the image filename you can include the exposure time in the filename by placing %lu in the filename. For instance, if the filename is outImg%lu.png and the exposure time is 500 milliseconds, then the file will be saved as outImg500000.png. Multiple exposures can be captured with a single call to dcam_capture using the argument -e t1,t2,t3,...,tn. In this case, it is essential to include the %lu in the filename, or each exposure will overwrite the same image file.

The latest version of dcam_capture has been placed in the /bin directory of Cygwin on anduril, so you should have no problem accessing it from any directory of your choice.

How to modify the dcam_capture utility

The dcam_capture code is stored in the CVS repository. The location is /imager/project/ModelingAndRendering/Repository/dcam_capture/. To make changes to dcam_capture:

• Ensure your CVSROOT environment variable is set to /imager/project/ModelingAndRendering/Repository/
• Type cvs checkout dcam_capture to check out the source.
• dcam_capture is a Windows application, so you can modify the source using MS Visual Studio .NET or simply using Cygwin (a Makefile is supplied). Note, if you add or remove files from the project, make sure to update both the Visual Studio project file as well as the Makefile.
• The main source for the program is in main.cpp.
• Documentation of the camera API is included in CVS as "Prosilica DCAM API.pdf".
• Once your changes are complete, be sure to copy the new executable (dcam_capture.exe) as well as any new DLL files to the /bin directory of Cygwin on anduril so that everyone will have access to the new version. (Note, you will need to log in as an Administrator to write to the /bin directory).
• Finally, commit your changes to CVS using cvs commit -m "your log message" updatedFile.

Information about the various capture modes

The following modes are available in dcam_capture, the API, and our custom Prosilica Recorder application:

• rgb24: 3-channel colour image (demosaicked)
• mono8: 1-channel raw sensor data. You can clearly see the bayer pattern on these images, as alternate (green) pixels are very different. The white balance settings have no effect in this mode.
• raw8: 1-channel image, subject to adjustment by white balance.

16-bit versions of the mono and raw modes are also available, although only about 10 bits are reliable. Note that the mono and raw modes appear to have been mixed up - if you want pure sensor data, use mono instead of raw.

The Prosilica-supplied viewer application's raw mode is also inconsistent with those of the API (and dcam_capture and Prosilica Recorder). Instead of a raw mode, it provides a "bayer" mode which returns 3-channel images. This appears to be some sort of RGB colour mode, and is definitely not raw sensor data, despite the misleading name.

When using 2x2 binning then only the mono mode is available. This will eliminate any bayer pattern artefacts, as groups of 4 pixels are summed to produce a single value. You will have to reduce the exposure time (or shrink the aperture) appropriately.

Incidentally, the sensor's bayer pattern is ordered such that the top-left pixel is a red one.