Capture

Detail

Captures an image on one or more cameras. The capture command allows to trigger image acquisition, wait for exposure and transfer to finish, and retrieve the image from the hardware driver memory and copy it into the Raw image nodes. The cameras can be triggered at the beginning and/or at the end of the command. If a camera to be captured is in hardware trigger mode the capture command can wait for the trigger signal with a user defined timeout.

Note

The Capture command performs a combination of Trigger and Retrieve commands. You might consider using these separate commands for more complex trigger sequences.

Trigger Terms and Definitions

Triggering

In our SDK the term “triggering” means to “prepare the hardware for image acquisition” according to each camera’s TriggerMode:

  • Hardware triggered cameras will be armed to wait for the next hardware trigger signal before starting exposure

  • Software triggered cameras will be triggered to immediately start the next exposure

After exposure has finished the hardware driver will automatically (without further NxLib API interactions) transfer the image from the camera to a memory buffer on the PC. The image can be retrieved from the driver memory buffer via cmdRetrieve or in phase 2 or 3 of the Capture command (see below) and is then present in the camera’s Raw image node of the NxLib tree.

Triggered State

NxLib uses the Triggered flag to indicate the camera’s trigger state. Triggered is true after triggering an image capture via the Capture or Trigger command:

  • while waiting for the hardware trigger signal

  • during exposure

  • during image transfer to the PC

  • until

    • the image has been successfully retrieved from the hardware driver memory by a call to cmdCapture or cmdRetrieve.

    • the capture operation is canceled by a call to cmdCapture or cmdTrigger.

    • or the capture has failed (which will also only occur when trying to retrieve the images with cmdCapture or cmdRetrieve).

Note

Capture failures will only be reported as result of a call to the Capture or Retrieve command. When triggering a camera asynchronously with cmdCapture or cmdTrigger any error during exposure or transfer of the image will only be reported in the next call to cmdCapture or Retrieve on this camera.

Capture Phases

The capture command internally executes in four phases, each affecting a subset of the cameras specified in the Cameras parameter.

Note

The command will only operate on the cameras specified in the Cameras parameter. The word “all” in the following description therefore only refers to all cameras specified in the Cameras parameter, which are not necessarily all opened cameras!

  1. Trigger the subset of cameras specified by the InitialTrigger parameter. This is equivalent to a call to Trigger with Subset set to the value of the InitialTrigger parameter.

Value of InitialTrigger parameter

Effect

“None”

Skip phase 1 entirely, continue directly to phase 2

“All”

Trigger or re-trigger all cameras:

  • Running capture operations on triggered cameras will be cancelled; images of triggered cameras will not be retrieved, even if they have already been transferred to driver memory.

  • All cameras will be triggered according to their respective TriggerMode

    • Hardware triggered cameras will be armed to wait for the next hardware trigger signal

    • Software triggered cameras will be triggered to start the next exposure

“Triggered”

Re-trigger all cameras that are currently in a triggered state.

  • The running capture operations on the triggered cameras will be cancelled; images will not be retrieved, even if they have already been transferred to driver memory.

  • The cameras will be triggered again according to their respective TriggerMode

“Untriggered”

Trigger all cameras that are currently not in triggered state.

  • The cameras will be triggered again according to their respective TriggerMode

  1. Copy images from all triggered cameras into the Raw image items if they have already been received by the driver. If the images are not yet ready in the hardware driver memory nothing will be done, i.e. there will be not wait time in this phase. This is equivalent to a call to Retrieve with Timeout set to zero.

  2. Wait for the subset of cameras specified by the WaitFor parameter. The overall wait time for all images is limited by the value of the Timeout parameter. The received images will be copied into the Raw image items. This is equivalent to a call to Retrieve with the specified Timeout.

Value of WaitFor parameter

Effect

“None”

Skip phase 3 entirely, continue directly to phase 4

“Triggered”

Wait for all Triggered cameras to return an image.

  • All images arriving within the specified Timeout period will be copied into the Raw image nodes.

  • After the timeout has elapsed and not all cameras have returned images the errCaptureTimeout error will be returned.

  1. Trigger the subset of cameras specified by the FinalTrigger parameter. This is equivalent to a call to Trigger with Subset set to the value of the FinalTrigger parameter. This phase works exactly as phase 1. Please see description of phase 1 for details.

Note

When using multiple cameras and errCaptureTimeout is returned you can use the Raw image timestamps to determine if some of the cameras returned images.

Camera Order

  • If the Cameras parameter was not specified, each trigger operation separately executes on

    • first on hardware triggered cameras (in any order)

    • then on software triggered cameras (in any order)

  • If you specified the Cameras parameter, then each phase will execute sequentially on the cameras exactly as specified in the Cameras array (starting from index 0).

Error Symbols

errCaptureTimeout

Cause: The camera did not return an image pair within the specified timeout. Solution: Increase the timeout or investigate the correctness of the trigger signal when using a hardware trigger.

errImageTransferFailed

Cause: The image could not be transferred over the bus and is lost. Solution: Decrease the camera’s PixelClock or disconnect other devices from the bus, if any. You might also want to choose a different USB port on your computer and verify that the camera is connected as the only device to one of your systems USB root hubs.

Note

Software triggering will be delayed until the LED can flash for the full exposure time without leaving its specification. See the Illumination topic for details.