- Generated on Thu Dec 19 2024 18:45:06
|
Impact Acquire SDK C++
|
Certain capture device (e.g. frame grabber) can process data from a wide range of imaging devices (e.g. cameras). However in order to interpret the incoming data from an imaging device correctly, the capture device needs to be given a certain amount of information about the structure of the video signal.
The Impact Acquire interface addresses this necessity by the introduction of so called "camera descriptions". A "camera description" is a certain set of parameters that should enable the capture device to cope with the incoming image data to reconstruct a correct image from the imaging device in the memory of the host system. For instance this information may contain information whether the image is transmitted as a whole or if it's transmitted as individual blocks (e.g. when dealing with interlaced cameras) that need to be reconstructed in a certain way to form the complete image.
Each capture device will support different sets of parameters. For example some capture devices will only be able to capture image data from standard video source such as a PAL or NTSC compliant camera, while others might only be capable to acquire data from digital image sources such as CameraLink compliant cameras. To reflect these device specific capabilities the "camera descriptions" have been grouped into different base classes. See mvIMPACT::acquire::CameraDescriptionBase and derived classes to find out how the basic structure of these objects look. Which basic "camera description" classes are supported by an individual device can be seen directly after the device has been initialized by creating and instance of mvIMPACT::acquire::CameraDescriptionManager. These objects will contain different lists for each camera class. One or more of this lists might be empty for a device, which indicates, that this device doesn't support this particular group of descriptions.
To select a certain camera description to be used to prepare the capture device for the expected data the property mvIMPACT::acquire::CameraSettingsFrameGrabber::type can be modified. Its translation dictionary (e.g. see mvIMPACT::acquire::EnumPropertyI::getTranslationDictString) will contain every camera description currently available.
Certain properties will affect other properties depending on the value written to the property. This section is meant to help to answer some of the questions, that might arise from this behaviour.
mvIMPACT::acquire::CameraSettingsFrameGrabber::acquisitionField <-> mvIMPACT::acquire::CameraDescriptionStandardBase::startField:
While mvIMPACT::acquire::CameraSettingsFrameGrabber::acquisitionField is set to mvIMPACT::acquire::afAuto the field selected in the property mvIMPACT::acquire::CameraDescriptionStandardBase::startField will be used to trigger the acquisition.
mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode <-> mvIMPACT::acquire::CameraDescriptionNonStandard::interlacedType:
When the latter property is set to mvIMPACT::acquire::citNone the property mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode will be invisible, as it doesn't make sense to define how an interlaced signal has to be reconstructed if no interlaced signal is present.
If mvIMPACT::acquire::CameraDescriptionNonStandard::interlacedType is set either to mvIMPACT::acquire::citInterlaced or mvIMPACT::acquire::citInvertedInterlaced, mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode can be used to define whether the resulting image shall be reconstructed from the odd and even frame of the interlaced signal (mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode then must be set to mvIMPACT::acquire::imOn) or if the single fields shall be treated as individual images (mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode then must be set to mvIMPACT::acquire::imOff).
In the latter situation either just one particular field (either odd or even) or every field can be captured. This again can be defined via the two properties mvIMPACT::acquire::CameraSettingsFrameGrabber::acquisitionField and mvIMPACT::acquire::CameraDescriptionStandardBase::startField. The following table will show the behaviour for a camera signal depending on these selections:
| Value of "interlacedType" | Value of "interlacedMode" | Value of "acquisitionField" | Value of "startField" | Result of this setting / behaviour |
| citNone | no influence(will be invisible) | no influence(will be invisible) | no influence | INTERLACED VIDEO SOURCES: All fields will be treated like individual images no matter whether it's an odd or even field. NON-INTERLACED VIDEO SOURCES: Here we are just dealing with full frames thus every frame will be captured. |
| citInterlaced or citInvertedInterlaced | imOn | no influence(will be invisible) | afEven | full images merged from one even and one odd field will be captured. The acquisition will start with the next detected even field after an image has been requested. |
| citInterlaced or citInvertedInterlaced | imOn | no influence(will be invisible) | afOdd | full images merged from one even and one odd field will be captured. The acquisition will start with the next detected odd field after an image has been requested. |
| citInterlaced or citInvertedInterlaced | imOn | no influence(will be invisible) | afAny | full images merged from one even and one odd field will be captured. The acquisition will start with the next detected field after an image has been requested. |
| citInterlaced or citInvertedInterlaced | imOff | afAuto (the value of "startField" will be used) | afEven | Only even fields will be captured. These will be treated as individual images. |
| citInterlaced or citInvertedInterlaced | imOff | afEven | no influence | |
| citInterlaced or citInvertedInterlaced | imOff | afAuto (the value of "startField" will be used) | afOdd | Only odd fields will be captured. These will be treated as individual images. |
| citInterlaced or citInvertedInterlaced | imOff | afOdd | no influence | |
| citInterlaced or citInvertedInterlaced | imOff | afAuto (the value of "startField" will be used) | afAny | all fields will be captured and treated like individual images (alternating odd and even). |
| citInterlaced or citInvertedInterlaced | imOff | afAny | afAny |
When dealing with CameraLink camera descriptions there are some other dependencies between CameraLink specific properties.
Dependency between mvIMPACT::acquire::CameraDescriptionCameraLink::bitsPerPixel and mvIMPACT::acquire::CameraDescriptionCameraLink::pixelsPerCycle:
| Value of "BitsPerPixel" | Allowed values for "PixelsPerCycle" |
| 8 | 1, 2, 3, 4, 8 |
| 10 | 1, 2, 3, 4 |
| 12 | |
| 14 | 1 |
| 16 | |
| 24 | |
| 30 | |
| 36 |
Dependency between mvIMPACT::acquire::CameraDescriptionCameraLink::pixelsPerCycle, mvIMPACT::acquire::CameraDescriptionCameraLink::tapsXGeometry and mvIMPACT::acquire::CameraDescriptionCameraLink::tapsYGeometry:
| Value of "PixelsPerCycle" | Allowed values for "TapsXGeometry" | Allowed values for "TapsYGeometry" |
| 1 | cltxg1X | cltyg1Y |
| 2 | cltxg1X | cltyg1Y2, cltyg2YE |
| cltxg1X2, cltxg2X, cltxg2XE, cltxg2XM | cltyg1Y | |
| 3 | cltxg1X3, cltxg3X | cltyg1Y |
| 4 | cltxg1X4, cltxg4X, cltxg2X2, cltxg2X2E, cltxg2X2M, cltxg4XE | cltyg1Y |
| cltxg1X2, cltxg2X, cltxg2XE, cltxg2XM | cltyg1Y2, cltyg2YE | |
| 8 | cltxg1X8, cltxg8X | cltyg1Y |
Now when a camera is connected, that differs in one or more parameter(s) from the default offered by one of the available base classes and no special description for the imaging device in question is available a new matching description must be generated.
The recommended way of adapting an imaging source to a capture device is to create a new description for a imaging device that does not completely fall into one of the offered standard descriptions. The first thing to decide when creating a new camera description is to which existing description offers the closest match for the new description. Once this has been decided a copy of this description can be created with an arbitrary name(that must be unique within the family the description is created from).
Afterwards the newly created camera description will be added to the list of existing ones. It will therefore be available via the instance of mvIMPACT::acquire::CameraDescriptionManager and also selectable via mvIMPACT::acquire::CameraSettingsFrameGrabber::type It's parameters at this point will match the "parent" description(the one the function mvIMPACT::acquire::CameraDescriptionBase::copyDescription was executed from) completely.
Now the reason for creating a new camera description was that the parameters in the existing description didn't exactly match the connected imaging device. Therefore the next step would probably be to modify some of the parameters.
To store a camera description permanently the function mvIMPACT::acquire::CameraDescriptionBase::exportDescription of the new camera description must be invoked.
As a direct result the modified settings will become the new default values of this particular camera description.
When exporting a camera description a file in XML format will be written to disk. On Windows camera descriptions will be stored under "%PUBLIC%/Documents/Balluff/ImpactAcquire/CameraFiles" (or "%MVIMPACT_ACQUIRE_DATA_DIR%/CameraFiles" which will point to the same folder), on Linux this directory will be "/opt/ImpactAcquire/data/camerafiles" while under other platforms these files will end up in the current working directory.
Now when closing and re-opening a device only the default camera descriptions an the one selected before settings have been saved will appear in the list of camera descriptions of an instance of mvIMPACT::acquire::CameraDescriptionManager. This is to save memory. However all detected camera descriptions will be available via the property mvIMPACT::acquire::CameraSettingsFrameGrabber::type
Once a description is selected, that hasn't been in the list of camera descriptions before, it will be created and thus will become available for modifications again via the class mvIMPACT::acquire::CameraDescriptionManager.
Again: For a different camera a new description should be generated, to operate complex cameras in different modes, either a new description can be generated or an existing one can be modified.
After a camera has been modified the function mvIMPACT::acquire::CameraDescriptionBase::importDescription can be used to fall back to the values stored in the camera description file. This will restore the default settings for this description. The function mvIMPACT::acquire::ComponentCollection::restoreDefault does serve the same purpose, but will work for default descriptions as well.