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!
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:
|
“Triggered” |
Re-trigger all cameras that are currently in a triggered state.
|
“Untriggered” |
Trigger all cameras that are currently not in triggered state.
|
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.
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.
|
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 of GigE cameras will be delayed until the LED can flash for the full exposure time without leaving its specification. See the Illumination topic for details.