Setting Acquisition Parameters in Image Acquisition Tool

Using the Acquisition Parameters Pane

The tool allows you to set acquisition parameters directly in the desktop using the Acquisition Parameters pane. Settings you make will apply to the currently selected device format in the Hardware Browser.

The Acquisition Parameters pane contains the following tabs:

  • General – Use to set up general acquisition parameters, such as frames per trigger and color space.

  • Device Properties – Use to view or change device-specific properties.

  • Logging – Use to set up logging options, such as logging mode, which determines whether your acquired data is logged to memory, disk, or both. If you want to generate a VideoWriter file of your data, use the Disk Logging option on this tab.

  • Triggering – Use to set up triggering options, such as number of triggers and trigger type. If you want to do manual triggering using the Trigger button, use the Trigger Type option on this tab.

  • Region of Interest – Use to set a Region of Interest (ROI) if you only want to use part of an image.

For more detailed information about the settings on each tab, see the Help topic for the tab while using the tool. When you click a tab, the corresponding topic will appear in the Desktop Help pane.

Note

Once you have changed parameters of a device, you can restore the device's default parameters by selecting the device format in the Hardware Browser and right-clicking Clear Selected Hardware Configuration.

Setting Frames Per Trigger

The Frames Per Trigger field on the General tab is used to set the number of frames per trigger you want to acquire.

  • If you want your acquisition to be a specific number of frames per trigger, use the default of 1 frame, or use the arrows to select the number of frames or type in the number.

  • If you want to acquire frames continuously, set the Frames Per Trigger to infinite and then use the Stop Acquisition button to stop the acquisition, or do manual triggering using the Triggering tab.

The number of frames that will be acquired when you start an acquisition depends on what is set in the Frames Per Trigger field on the General tab and the Number of Triggers field on the Triggering tab. For example, if you set Frames Per Trigger to 4 and Number of Triggers to 2, the total number of frames acquired will be 8.

Note that if you set Frames Per Trigger to infinite, you cannot set Number of Triggers on the Triggering tab.

Note

Some devices need a few frames to warm up, or may always skip the first frame. If your device does that, change the number of frames accordingly to adjust for that. You can also adjust for camera warm-up by using manual triggering on the Triggering tab.

Setting the Color Space

Use Color Space on the General tab to set the color space for the selected device format. The Returned Color Space field has three options: rgb, YCbCr, and grayscale. The setting that is your device format's default color space is shown as the default. You can use the arrow to select another setting.

Additionally, if the default color space is grayscale, a value of bayer will be available in the Returned Color Space field for some devices, and the Bayer Sensor Alignment field will also be displayed. Use the drop-down list to select one of the four possible sensor alignments. This feature allows the tool to demosaic Bayer patterns returned by the hardware and interpolate them into standard RGB color images. For more information about this feature, see the BayerSensorAlignment property reference page.

Setting Device-Specific Parameters

View or change device-specific properties using the Device Properties tab. The selected device's properties appear in the Properties area. The specific properties that appear depend on your device.

The Selected source field specifies the name of the selected source for the current device. Many device adaptors only have one input source, so for example, this might show something like input1, port1, or input0 by default. If your device supports multiple source names, they will appear in the drop-down list.

Use the Properties area to view or edit properties:

  • If a property has an edit box or slider, that value is editable.

  • If a property has an arrow indicating a drop-down list, then you can select a value from the list.

  • If a property has a value listed that is grayed out, then that value is not currently editable.

Changes you make in the Properties area are applied to your acquisition or preview dynamically. For example, to change the exposure for the camera you are using, edit the value in the Exposure property text field or use the slider to change it. You will immediately see the change in the Preview window if you are previewing at the time, or in the next acquisition when you click the Start Acquisition button.

Click the Reset to defaults button to undo any modifications you made and restore the default settings of the device.

Property Help

To get help on any of the properties in the Device Properties tab, right-click a property and select What's This?. A Help window opens and displays the help for the selected property, as well as the rest of the properties, which are available by scrolling. This is the same information as the device help you access using the imaqhelp command. For more detailed information on device-specific properties, see your device's documentation.

Note About Frame Rate

If FrameRate appears in the Properties area, that means your device has a FrameRate property. The information in the table comes from your device. The value set there will be the frame rate that your device uses, in frames per second.

If FrameRate does not appear in the list, your device does not support that property.

Logging Your Data

Set logging options using the Logging tab. This determines where your data is logged to when you do an acquisition.

Use the Log to options to select where to log your acquisition. Select one of the following:

  • Memory — Acquisition is logged to memory. This means that the acquired data that you do not otherwise save (using Export Data) will be logged to your system's memory, and will be available to you only during the acquisition session. The data will be lost if you do another acquisition, or you close the tool without exporting the data. This is the default setting.

  • Disk — Acquisition is logged to disk as a VideoWriter file, in the location you specify in the Disk logging area. This means that the acquired data will be logged to disk and will be available to you there after the acquisition session. After selecting Disk, the Disk logging area becomes editable and you can enter or browse to the location and name the file.

  • Disk and memory — Acquisition will be logged to both disk, in the location you specify in the Disk logging area, and memory.

Disk Logging

If you select Disk or Disk and memory in the Log to options, the Disk logging area becomes editable so you can designate a file and location to save to.

Note

Disk logging generates a VideoWriter file. If you select a VideoWriter profile that generates an AVI file, note that AVI files are limited to a bit-depth of 8 bits per pixel for each band. If you have higher bit data, you should not log it to an AVI file because the AVI format is restricted to 8-bit data. If you log higher bit data to an AVI file, it will be scaled and then logged as 8-bit data.

To use disk logging:

  1. Click the Browse button to select a location for the file, or enter the name of the location.

  2. In the Save dialog box, browse to the location and then enter a name in the File name field, and click Save.

    Uncompressed AVI is the default profile for color devices and Grayscale AVI is the default profile for monochrome devices, so the .avi extension is appended to the name on the Logging tab initially, and the other fields become editable. You can change the profile in step 4.

  3. Optionally select Automatically increment filename if you want the tool to name subsequent acquisitions using the same root name, plus an incremented number. For example, if you enter the file name experiment.avi and then select this option, it will be replaced by experiment_0001.avi, followed by experiment_0002.avi, etc.

    This option is useful if you need to acquire multiple videos of one or more subjects. For example, a lab technician might want to acquire 10 seconds of video on a group of five different cultures and save them for later analysis. The technician may want resulting file names such as sample_0001.avi, sample_0002.avi, etc.

  4. You can use any of the profiles offered by VideoWriter. Accept the default profile (Uncompressed AVI for color devices and Grayscale AVI for monochrome devices) or select another. Currently supported profiles are:

    • 'Motion JPEG 2000' — Compressed Motion JPEG 2000 file. Can log single-banded (grayscale) data as well as multi-byte data.

    • 'Archival' — Motion JPEG 2000 file with lossless compression.

    • 'Motion JPEG AVI' — Compressed AVI file using Motion JPEG codec.

    • 'Uncompressed AVI' — Uncompressed AVI file with RGB24 video.

    • 'MPEG-4' — Compressed MPEG-4 file with H.264 encoding (systems with Windows 7 or macOS 10.7 and later).

    • 'Grayscale AVI' — Uncompressed AVI file with grayscale video. Only used for monochrome devices.

    • 'Indexed AVI' — Uncompressed AVI file with indexed video. Only used for monochrome devices.

  5. Additional logging options appear dynamically after you select a profile.

    If you select Motion JPEG 2000 or Archival as your profile, you can set the Compression Ratio, Frame Rate, Lossless Compression, and MJ2 Bit Depth options. Accept the default values or change them.

    If you select Motion JPEG AVI or MPEG-4 as your profile, you can set the Frame Rate and Quality options. Accept the default values or change them.

    If you select Uncompressed AVI or Grayscale AVI as your profile, you can set the Frame Rate option. Accept the default value or change it.

    If you select Indexed AVI as your profile, you can set the Frame Rate and Colormap options. Accept the default value for Frame Rate or change it. You must enter a Colormap value. See the “VideoWriter Options” section below for more information.

    VideoWriter Options

    • Compression Ratio is a number greater than 1 that specifies the target ratio between the number of bytes in the input image and the number of bytes in the compressed image. The data is compressed as much as possible, up to the specified target. This is only available for objects associated with Motion JPEG 2000 files. The default is 10.

    • Frame Rate is the rate of playback for the video in frames per second. The default is 30. If your device has a set frame rate, that will be used instead.

    • Lossless Compression is a Boolean value (logical true or false) only available for objects associated with Motion JPEG 2000 files. If you select true, VideoWriter uses reversible mode so that the decompressed data is identical to the input data, and ignores any specified value for CompressionRatio. The default is false for the Motion JPEG 2000 profile, and true for the Archival profile.

    • MJ2 Bit Depth is the number of least significant bits in the input image data, from 1 to 16. This is only available for objects associated with Motion JPEG 2000 files. If you do not specify a value, VideoWriter sets the bit depth based on the input data type. For example, if the input data is an array of uint8 or int8 values, MJ2BitDepth is 8.

    • Quality is a number from 0 to 100. Higher quality numbers result in higher video quality and larger file sizes. Lower quality numbers result in lower video quality and smaller file sizes. Only available for objects associated with the Motion JPEG AVI profile. The default is 75.

    • Colormap is a value that specifies the intensity of red, green, and blue for the image. Type in a value, such as hsv(128), or the name of one of the built-in MATLAB colormaps, such as jet or hot. For a list of the built-in colormaps, see the colormap function in the MATLAB documentation.

  6. After setting your profile and options, start your acquisition to log a VideoWriter file to disk.

Note about bit size of AVI files

AVI files are limited to a bit depth of 8 bits per pixel for each band. If you have higher bit data, you should not log it to a profile that creates an AVI file because the AVI format is restricted to 8-bit data. If you log higher bit data to an AVI file, it will be scaled and then logged as 8-bit data. The Archival and Motion JPEG 2000 profiles do not have this issue.

Setting Up Triggering

Use the Triggering tab to set up triggering options.

The total number of frames that will be acquired when you start an acquisition depends on what is set in the Frames Per Trigger field on the General tab and the Number of Triggers field on the Triggering tab. For example, if you set Frames Per Trigger to 4 and Number of Triggers to 2, the total number of frames in the acquisition will be 8.

Selecting the Number of Triggers

If you want to do an acquisition that is comprised of a finite number of frames, set the Number of Triggers to any number, or use the default of 1 trigger.

If you want to control the start and stop of the acquisition, regardless of the number of frames acquired, select infinite. With an infinite number of triggers, you stop the acquisition manually by clicking the Stop Acquisition button in the Preview window.

Selecting the Trigger Type

The default of Immediate means that when you start an acquisition using the Start Acquisition button, the acquisition begins immediately.

If you change the setting to Manual, the Trigger button is activated in the Preview window, and you use it to start the acquisition.

To perform manual triggering:

  1. Select your device format and optionally click Start Preview to preview the device.

  2. Optionally set any acquisition parameters and stop the preview.

  3. Select Manual in the Trigger Type field on the Triggering tab.

  4. Click the Start Acquisition button to get live feed from the device.

    The Trigger button is activated in the Preview window once the acquisition starts.

  5. Click the Trigger button when you want to start logging data.

    If you have a defined number of triggers (not infinite), then the acquisition will stop when you have acquired that number of frames, based on the Frames Per Trigger field on the General tab.

    If Number of Triggers is set to infinite, use the Stop Acquisition button to stop the acquisition.

If your device supports hardware triggering, that option will also appear in the Trigger Type field.

To perform hardware triggering:

  1. Select your device format and optionally click Start Preview to preview the device.

  2. Optionally set any acquisition parameters and stop the preview.

  3. Select Hardware in the Trigger Type field on the Triggering tab.

  4. Select your Trigger Source. This indicates the hardware source that is monitored for trigger conditions. When the condition specified in Trigger Condition is met, the trigger is executed and the acquisition starts. Trigger Source is device-specific. The drop-down list will show the mechanisms your particular device uses to generate triggers. For example, it might be something like Port0 and Port1, or OptoTrig and TTL.

  5. Select your Trigger Condition. This specifies the condition that must be met, via the Trigger Source, before a trigger event occurs. Trigger Condition is device-specific. The drop-down list will show the conditions your particular device uses to generate triggers. For example, it might be something like risingEdge and fallingEdge.

  6. Click the Start Acquisition button to get live feed from the device.

  7. When the Trigger Condition is met, the acquisition begins.

    If you have a defined number of triggers (not infinite), then the acquisition will stop when you have acquired that number of frames, based on the Frames Per Trigger field on the General tab.

    If Number of Triggers is set to infinite, use the Stop Acquisition button to stop the acquisition.

Setting a Region of Interest

By default your acquisition will consist of the entire frame that the device acquires, which is equal to the selected format's resolution. If you want to acquire a portion of the frame, use the Region of Interest tab to set the desired region. The ROI window defines the actual size of the frame logged by the tool, measured with respect to the top-left corner of an image frame.

You can set a Region of Interest (ROI) manually by using the Manual Configuration settings on the Region of Interest tab, or interactively in the Preview Window.

Setting Region of Interest Manually

To set up an ROI manually using the Manual Configuration field on the Region of Interest tab:

  1. Start your preview by clicking the Start Preview button in the Preview Window.

  2. Adjust one or more of the X-Offset, Y-Offset, Width, or Height settings until you reach the desired region.

    Use the arrows in each field to adjust the numbers. The preview resizes as you make changes.

  3. When the region is the desired size, start your acquisition by clicking the Start Acquisition button.

Note: You cannot adjust the ROI after starting the acquisition.

Setting Region of Interest Interactively

You can also set a region of interest interactively while previewing your image.

To set a region of interest interactively:

  1. Start your preview by clicking the Start Preview button in the Preview Window.

  2. Click the Select Region of Interest button in the top-left corner of the Preview Window to activate the interactive ROI feature.

    Your cursor becomes a selection tool.

    Note that the Select Region of Interest button is enabled only during preview mode.

  3. Position the cursor at one of the edges of the region you want to capture and click the left mouse button. Hold the button while dragging the selection tool over the image to outline the region you want to capture.

  4. Release the mouse button to freeze the region.

    The region is not set until you take action to commit it.

  5. If the selected area is the region you want to use, start your acquisition by clicking the Start Acquisition button.

    In this case, the region appears as follows.

    Before starting the acquisition, if you want to adjust the region further, you can drag the selected region around while still in selection mode. You can also drag any of the handles on the region outline to change the dimensions of the region. You can then commit the region by pressing Enter or using the right-click menu Commit Region of Interest inside the region. You can also commit a region by pressing the space bar or double-clicking inside the selection, or starting the acquisition.

    You can clear the drawn region before you commit it by single-clicking anywhere in the Preview Window outside of the selected area. You will still be in ROI selection mode. If you want to clear the selected region and exit ROI selection mode, press the Delete key, press the Escape key, or use the right-click menu Exit Region of Interest Mode inside the region.

Note: If you start another acquisition with the same device, the ROI that you set will remain the default that is used in subsequent acquisitions. To reset to the original image size, click the Reset Region of Interest to Maximum button in the Preview Window or the Reset button on the Region of Interest tab.

Restoring Default Parameters

Once you have changed parameters of a device, you can restore the device's default parameters by selecting the device format in the Hardware Browser and right-clicking Clear Selected Hardware Configuration. That clears any changes you have made and resets the default parameters of that device format.

If you want to save a configuration before clearing it, first select Export Selected Hardware Configuration from the right-click menu.

Image Acquisition Toolbox Documentation

Support