Camscope
This page provides detailed information about the various features of camscope. You should read a more general introduction before reading this.
Command-line options
The list below describes the command-line options available when you start camscope.- -c #
- Specifies the number of frames to capture every time the Record (ctrl-r) button is pressed. Default: 10
- -d #
- Specifies a debugging level that prints garbage to stdout. Higher numbers = more garbage. Default: 0
- -w
- Runs camscope in windowed mode rather than fullscreen. Since the window is 1024x768, which is the highest resolution of the monitors in the lab, it's impossible to display the entire window on the screen in windowed mode.
- -v #
- Specifies the number of images to use for averaging. Default: 50.
- -i #
- Specifies the lowest image number to use or look for when starting the program (by default if camscope finds images in the directory it will behave as if it has already recorded them, and will not overwrite them). This is handy if you've accidentally deleted images 0 through 17, in which case you could use -i 18.
- -r #
- Specifies the lowest data set to use or look for when starting the program.
- -h
- Displays a rudimentary help message.
Keyboard Shortcuts
Every button visible in camscope has a corresponding keyboard shortcut. Some features have keyboard commands but no corresponding button. The list below identifies all of the keyboard commands that work in camscope. Some of these are explained in more detail later in the document.
- ctrl-p
- Play. Plays recorded images in sequence in Analyze mode. Doesn't really do much in live mode. Corresponds to the big Play button.
- ctrl-z
- Pause. Stops on the currently displayed image. Corresponds to the big Pause button.
- ctrl-r
- Record. Records a series of images as fast as possible. There is currently no way to adjust the recording speed. Corresponds to the big Record button.
- ctrl-s
- Snapshot. Takes a single image. Corresponds to the big button with a camera on it.
- ctrl-o
- Stop. Stops recording. Corresponds to the big Stop button.
- ctrl-a
- Analyze. Toggles between live and previously recorded images (Analyze mode). Corresponds to the "Analyze Mode" button.
- ctrl-left_arrow
- Previous Image. Displays the previous image. Only works in Analyze mode when paused. Corresponds to the left_arrow button.
- ctrl-right_arrow
- Next Image. Displays the next image. Only works in Analyze mode when paused. Corresponds to the right_arrow button.
- ctrl-q
- Quit. Quits the program. Corresponds to the X button in the upper right corner.
- ctrl-d
- Screen Capture. Saves an image of the entire screen. Images are saved in the form print.000.000000.bmp, where the 3-digit number is the current Data Set and the 6-digit number is the current screendump. Corresponds to the "Screen Capture" button.
- ctrl-.
- Next Data Set. Switches to the next data set. In live mode, allows recording of images in the next data set (or a new one, if the next one doesn't exist yet). In Analyze mode, allows display of recorded images in the next data set, if it exists (otherwise the button does nothing). Corresponds to the + button in the upper left corner.
- ctrl-,
- Previous Data Set. Switches to the previous data set. In live mode, allows recording of images in the previous data set (but won't go below zero). In Analyze mode, allows display of recorded images from the previous data set. Corresponds to the - button in the upper left corner.
- ctrl-1
- Decrease Brightness. Decreases the brightness setting of the camera by 1; continues to decrease as long as it is held down, until the value hits zero. Corresponds to the - button next to the brightness setting.
- ctrl-2
- Increase Brightness. Increases the brightness setting of the camera by 1; continues to increase as long as it is held down, until the value hits 511. Corresponds to the - button next to the brightness setting.
- ctrl-3
- Auto Brightness. Allows the camera to control the brightness setting automatically. Corresponds to the circle button next to the brightness setting.
- ctrl-5
- Decrease Exposure. Decreases the exposure setting of the camera by 1; continues to decrease as long as it is held down, until the value hits zero. Corresponds to the - button next to the exposure setting.
- ctrl-6
- Increase Exposure. Increases the exposure setting of the camera by 1; continues to increase as long as it is held down, until the value hits 511. Corresponds to the + button next to the exposure setting.
- ctrl-7
- Auto Exposure. Allows the camera to control the exposure setting automatically. Corresponds to the circle button next to the exposure setting.
- ctrl-9
- Decrease Saturation. Decreases the color saturation value of the camera; continues to decrease as long as it is held down, until the value hits zero. Corresponds to the - button next to the saturation setting.
- ctrl-0
- Increase Saturation. Increases the color saturation value of the camera; continues to increase as long as it is held down, until the value hits 255. Corresponds to the + button next to the saturation setting.
- ctrl-[
- Increase Sharpness. Increases the sharpness value of the camera; continues to increase as long as it is held down, until the value hits 255. Corresponds to the + button next to the sharpness setting.
- ctrl-]
- Decrease Sharpness. Decreases the sharpness value of the camera; continues to decrease as long as it is held down, until the value hits zero. Corresponds to the - button next to the sharpness setting.
- ctrl-u
- Increase Gain. Increases the gain value of the camera; continues to increase as long as it is held down, until the value hits 255. Corresponds to the + button next to the gain setting.
- ctrl-i
- Decrease Gain. Decreases the gain value of the camera; continues to decrease as long as it is held down, until the value hits zero. Corresponds to the - button next to the gain setting.
- ctrl-/
- Video Mode. Switches the video mode of the camera between the
modes listed below (in order). Can also be changed by clicking on the
current mode displayed in the lower-right corner of the screen.
- RGB: camera sends full RGB color information for each pixel. 15 frames/sec.
- MONO: camera sends monochrome (brightness only) information for each pixel. 30 frames/sec. Note that color settings (e.g. saturation, red/blue value) still affect the image in MONO mode.
- YUV411: camera sends 6 bytes per 4 pixels, containing Y (luminance) values for each pixel, and aggregate U and V (chrominance) values for the four pixels. The fastest color mode, but least accurate in terms of color. 30 frames/sec.
- YUV422: camera sends 8 bytes per 4 pixels: four Y values and two each U and V values. Slower than YUV411 and less accurate than RGB, so pretty much a useless mode. 15 frames/sec.
- ctrl-j
- Increase Blue (U) Gain. Increase the gain of the U value within the camera, making the image more bluish; continues to increase as long as it is held down, until the value hits 255. Corresponds to the + button next to the Blue setting.
- ctrl-k
- Decrease Blue (U) Gain. Decrease the gain of the U value within the camera, making the image less bluish; continues to decrease as long as it is held down, until the value hits zero. Corresponds to the - button next to the Blue setting.
- ctrl-l
- Increase Red (V) Gain. Increase the gain of the V value within the camera, making the image more reddish; continues to increase as long as it is held down, until the value hits 255. Corresponds to the + button next to the Red setting.
- ctrl-;
- Decrease Red (V) Gain. Decrease the gain of the V value within the camera, making the image less reddish; continues to decrease as long as it is held down, until the value hits zero. Corresponds to the - button next to the Red setting.
- ctrl-'
- Auto Color. Allows the camera to control the gain of the U and V channels. Enabling auto color can cause the color of structures to change rapidly over time as other structures move in and out of the camrea field of view. Even without auto color this effect happens to some extent with our current cameras, particularly with the blue channel, but it's less noticeable.
- ctrl-x
- Averaging. Toggles the averaging of images. Because images are noisy, it can be hard to detect small gradients of brightness or color from individual images. Turning averaging on makes the camera display the average pixel values of the last 50 images (by default), significantly reducing the image noise. However, with averaging on it is impossible to watch the motion of cells or other structures.
- ctrl-m
- Clear Segment. After clicking the middle mouse button to highlight a segmented region of the image, that highlight continues to be displayed until it is cleared. This key command clears the highlight.
- ctrl-c
- Increase Segment Threshold. The segmentation algorithm works by comparing both the difference between adjacent pixels and the difference between the pixel in question and the original pixel to a pre-defined threshold. This key increases that threshold, making it more likely that a given pixel will be included.
- ctrl-v
- Decrease Segment Threshold. Decreases the threshold value used for segmentation.
- ctrl-b
- Increase Expected Segment Size. An additional parameter in the segmentation code takes into account the expected size of the segment (default 400 pixels). This key increases that size by 20. The change usually has little effect on the segmentation in most cases.
- ctrl-n
- Decrease Expected Segment Size. Decreases the expected segment size by 15, to a minimum of 10 pixels.
Mouse Buttons
- Left Mouse Button
- When the cursor is over the image, this button is used to draw lines for measuring distances and velocities. When the cursor is outside this image, this button is used to click on various controls.
- Middle Mouse Button
- When the cursor is over the image, this button is used to run the segmentation algorithm. This algorithm selects pixels that surround the starting pixel and are similar in brightness. The selected pixels are displayed in magenta, and the number of pixels chosen are shown in the lower right corner. This technique is useful for measuring cell sizes.
- Right Mouse Button
- When the cursor is over the image, this button can be used to draw rectangles. The program will then display the average brightness within the rectangle. There is currently no known use for this functionality.
Adjusting Camera Settings
When you start the program, the camera settings are all on default values. For the most part, this means that the camera controls them automatically. If you're only interested in the sizes and shapes of things (e.g., watching cells shrink and swell), you can leave these settings intact. If you want to track the colors of things (e.g., if you've added a colored dye to the fluid), you should probably adjust the camera settings manually. Here's a handy guide to doing just that.
First, move the stage until you're looking at something that should be neutrally white (e.g., the part of the expriment chamber that doesn't contain any channels). For every camera setting that's on Auto, click on either the + or - button to switch that setting to manual. Don't worry if the image looks awful when you're done — we'll fix that soon.
Put the mouse pointer over the image so you can see the plots below and to the side of the image. Using the small knob under the microscope stage, move the light source up and down until the image is as bright as possible (the plot values should be close to 256). If the image is too bright (i.e. the plot lines are perfectly straight) turn down the Gain setting. If the Gain is minimized and the image is still too bright, turn down the Expose and Bright settings, in that order.
You should now have an image that's not saturated, but is probably some strange color. You can adjust the color using the Red and Blue settings. Here's where the plots come in handy. You want to adjust these settings to make the Red and Blue plots overlap with the Green plot. Using the keyboard shortcuts makes this process much easier. Once you do this, turn on averaging (click the Avg box, or press ctrl-x). The curves should become much smoother, so you can fine-tune the settings. Note that there are several combinations of the Gain, Expose, and Bright settings that will all give you reasonable-looking images, so don't be too obsessed about finding the "right" settings. However, if you play with Gain, Expose, and Bright you'll have to re-adjust the color settings.
File Formats
Images are recorded sequentially as .BMP files. The first image recorded into an empty directory is named image.000.000000.bmp, the second is named image.000.000001.bmp, and so on. Changing the data set changes the three-digit number near the beginning of the file, and resets the six-digit counter to zero. If the cursor is in the image at the time of recording, a text file is also created that contains the red, green, and blue intensities that were displayed below and to the right of the image. The text file associated with image.000.000000.bmp is named info.000.000000.txt. Screen dumps are saved in a similar sequential fashion, with the first one named print.000.000000.bmp. When the cursor marks a "line-of-interest" and a "column-of-interest" at the time that an image is recorded, the red, green, and blue intensitives of those lines and columns of interest are also recorded in the ".info" files
What To Do If Camscope Locks Up
It happens sometimes. Camscope hits a bug, the camera sends a
flaky packet, there's an electricity glitch, the Moon's gravity pulls the
CPU out of its socket — for whatever reason, camscope can
occasionally lock up. Don't panic! You haven't lost any data, and it's
easy to recover. Here's what you do: