- Generated on Thu Jun 27 2024 18:46:31
|
Impact Acquire SDK Python
|
The function interface to devices supported by this interface. More...
Public Member Functions | |
| __init__ (self, *args) | |
| Constructs a new function interface for the device pointed to by pDev. | |
| acquisitionStart (self) | |
| Manually starts the acquisition engine of this device driver instance. | |
| acquisitionStop (self) | |
| Manually stops the acquisition engine of this device driver instance. | |
| createImageRequestControl (self, *args) | |
| Creates a new mvIMPACT.acquire.ImageRequestControl object. | |
| createSetting (self, *args) | |
| Creates a new setting. | |
| deleteSetting (self, *args) | |
| Deletes a setting from the specified location. | |
| deleteSettingFromStack (self) | |
| Deletes the last setting from the setting stack. | |
| getAvailableImageRequestControls (self) | |
| Returns the names of the image request controls available for this mvIMPACT.acquire.Device. | |
| getAvailableSettings (self) | |
| Returns the names of the settings available for this mvIMPACT.acquire.Device. | |
| getCurrentCaptureBufferLayout (self, imageRequestControl) | |
| Returns information about the current capture buffer requirements. | |
| getRequest (self, nr) | |
| Returns a pointer to the desired mvIMPACT.acquire.Request. | |
| getSetting (self, name) | |
| Returns a mvIMPACT.acquire.ComponentList object to a setting with a specified name. | |
| imageRequestConfigure (self, pRequest) | |
| Sets a request into configuration mode. | |
| imageRequestReset (self, requestCtrlNr, mode) | |
| Deletes all requests currently queued for the specified mvIMPACT.acquire.ImageRequestControl. | |
| imageRequestResultQueueElementCount (self, queueNr=0) | |
| Returns the number of mvIMPACT.acquire.Request objects in the result queue . | |
| imageRequestSingle (self, *args) | |
| Sends an image request to the mvIMPACT.acquire.Device driver. | |
| imageRequestUnlock (self, nr) | |
| Unlocks the request for the driver again. | |
| imageRequestWaitFor (self, timeout_ms, queueNr=0) | |
| Waits for a request object to become ready. | |
| isRequestNrValid (self, nr) | |
| Check if nr specifies a valid mvIMPACT.acquire.Request. | |
| isSettingAvailable (self, *args) | |
| Checks if a certain setting is available under the specified location. | |
| loadAndDeleteSettingFromStack (self) | |
| loads the last setting from the setting stack and then removes this setting from the stack. | |
| loadSetting (self, *args) | |
| Loads a previously stored setting. | |
| loadSettingFromDefault (self, *args) | |
| Loads the default settings. | |
| loadSettingFromStack (self) | |
| loads the last setting from the setting stack. | |
| requestCount (self) | |
| Returns the number of available request objects. | |
| saveCurrentSettingOnStack (self, *args) | |
| Saves the current setting on the setting stack. | |
| saveSetting (self, *args) | |
| Stores the current settings. | |
| saveSettingToDefault (self, *args) | |
| Stores the current settings under a default location. | |
| updateRequests (self) | |
| Updates the internal cache for request objects. | |
Properties | |
| availableImageRequestControls = property (getAvailableImageRequestControls, None, None, None) | |
| A list property (read-only) which returns the names of the image request controls available for this mvIMPACT.acquire.Device. | |
| availableSettings = property (getAvailableSettings, None, None, None) | |
| A list property (read-only) which returns the names of the settings available for this mvIMPACT.acquire.Device. | |
| thisown = property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc="The membership flag") | |
The function interface to devices supported by this interface.
This class contains all the basic functions needed when working with a device. There are not too many functions as most data will be represented by 'properties' in other classes of this module, keeping the set of functions to remember rather small. To construct a new function interface, a pointer to a mvIMPACT.acquire.Device object must be passed to the constructor of mvIMPACT.acquire.FunctionInterface. In order to work with the mvIMPACT.acquire.FunctionInterface object the device needs to be initialized, so if the mvIMPACT.acquire.Device object pointed to by pDev in the constructors parameter list hasn't been opened already the constructor will try to do that.
Please refer to one of the examples listed below to get an idea on how to use this class for data acquisition:
| __init__ | ( | self, | |
| * | args ) |
Constructs a new function interface for the device pointed to by pDev.
OVERLOAD 1:
In order to work with the mvIMPACT.acquire.FunctionInterface object the device needs to be initialized, so if the mvIMPACT.acquire.Device object pointed to by pDev in the constructors parameter list hasn't been opened already the constructor will try to do that. Thus internally a call to mvIMPACT.acquire.Device.open might be preformed with all consequences following from this call.
| pDev | [in] A pointer to a mvIMPACT.acquire.Device object obtained from a mvIMPACT.acquire.DeviceManager object. |
| pRequestFactory | [in] A pointer to a request factory. By supplying a custom request factory the user can control the type of request objects that will be created by the function interface. |
OVERLOAD 2: Constructs a new mvIMPACT.acquire.FunctionInterface from an existing one.
| src | [in] A constant reference to the mvIMPACT.acquire.FunctionInterface object, this object shall be created from |
| acquisitionStart | ( | self | ) |
Manually starts the acquisition engine of this device driver instance.
Calling this function will manually start this device driver's acquisition engine. This will only have an effect on the overall behaviour if mvIMPACT.acquire.Device.acquisitionStartStopBehaviour is set to mvIMPACT.acquire.assbUser.
If supported by the device driver, starting and stopping the acquisition engine manually can sometimes help to overcome capture queue underruns or certain restrictions in the underlying device driver technology.
| acquisitionStop | ( | self | ) |
Manually stops the acquisition engine of this device driver instance.
Calling this function will manually stop this device drivers acquisition engine. This will only have effect on the overall behaviour, if mvIMPACT.acquire.Device.acquisitionStartStopBehaviour is set to mvIMPACT.acquire.assbUser.
| createImageRequestControl | ( | self, | |
| * | args ) |
Creates a new mvIMPACT.acquire.ImageRequestControl object.
This function creates a new mvIMPACT.acquire.ImageRequestControl based on an existing one. New mvIMPACT.acquire.ImageRequestControl instances can only be derived from mvIMPACT.acquire.ImageRequestControl instances that already exist. When the driver has been initialized there will be at least one base mvIMPACT.acquire.ImageRequestControl called 'Base', which acts as the base for all other request controls.
All mvIMPACT.acquire.ImageRequestControl constructed by the application must be derived either from this base or any of its children using this function.
When this function succeeds, the mvIMPACT.acquire.ImageRequestControl constructor can be called with the name parameter passed to this function to get access to this newly registered mvIMPACT.acquire.ImageRequestControl.
| name | [in] The name of the new mvIMPACT.acquire.ImageRequestControl object. |
| parent | [in] The name of the mvIMPACT.acquire.ImageRequestControl the new object shall be derived from. |
| pNewRequestControl | [out] A pointer to a mvIMPACT.acquire.ComponentList object that will receive the ID of the newly created request control. This parameter can be 0 if the application is not interested in that parameter. |
| createSetting | ( | self, | |
| * | args ) |
Creates a new setting.
This function creates a new setting base on an existing one. New settings can only be derived from settings that already exist. When the driver has been initialized there will be at least one base setting called 'Base', which acts as the base for all other settings.
When a new setting is created it derives all the properties from the parent setting. That means initially the new setting will contain the very same data as the parent setting. As long as a component hasn't been modified in the new setting it will depend on the parent settings data. That means if e.g. a property in the parent list is modified, the newly created setting will also benefit from the updated value.
To release a certain component from this dependency it must be assigned a new value. The function mvIMPACT.acquire.Component.isDefault will return false afterwards indicating that the component no longer depends on the parent.
To restore this parent <-> child dependency the user can call the function mvIMPACT.acquire.Component.restoreDefault. Afterwards settings applied to the parent component will also be visible in the child component again.
When a new setting has been created successfully the name used to create the setting can be passed to any of the constructors of the setting related classes (mvIMPACT.acquire.CameraSettingsBase, mvIMPACT.acquire.ImageProcessing, ...) to access the new components.
| name | [in] The name of the setting to be created. |
| parent | [in] The name of the setting to derive the new setting from. |
| pNewSetting | [out] A pointer to a mvIMPACT.acquire.ComponentList object that will receive the ID of the newly created setting. This parameter can be 0 if the application is not interested in that parameter. |
| deleteSetting | ( | self, | |
| * | args ) |
Deletes a setting from the specified location.
This function deletes a setting from the specified location.
| name | [in] The name or the full path under where the setting is located. |
| storageLocation | [in] The location of the setting. |
| scope | [in] Specifies the scope of this operation. |
| deleteSettingFromStack | ( | self | ) |
Deletes the last setting from the setting stack.
This function deletes the last setting from the setting stack.
See mvIMPACT.acquire.FunctionInterface.saveCurrentSettingOnStack for an example how to use this feature.
| getAvailableImageRequestControls | ( | self | ) |
Returns the names of the image request controls available for this mvIMPACT.acquire.Device.
This function returns a const reference to a string array containing the names of all image request controls available for the current mvIMPACT.acquire.Device. These names are valid constructor parameters for objects of the type mvIMPACT.acquire.ImageRequestControl.
New image request controls can be created by calling mvIMPACT.acquire.FunctionInterface.createImageRequestControl.
| getAvailableSettings | ( | self | ) |
Returns the names of the settings available for this mvIMPACT.acquire.Device.
This function returns a const reference to a string array containing the names of all settings available for the current mvIMPACT.acquire.Device. These names are valid constructor parameters for objects like mvIMPACT.acquire.CameraSettingsBase, mvIMPACT.acquire.ImageProcessing, mvIMPACT.acquire.ImageDestination or classes derived from these types.
New settings can be created by calling mvIMPACT.acquire.FunctionInterface.createSetting
| getCurrentCaptureBufferLayout | ( | self, | |
| imageRequestControl ) |
Returns information about the current capture buffer requirements.
When an application wants to provide capture buffers, this function will be needed in order to get information on how the capture buffers must be constructed.
| imageRequestControl | [in] A reference to the mvIMPACT.acquire.ImageRequestControl object containing the setting for which the current capture buffer layout shall be queried. The setting can be defined via the property mvIMPACT.acquire.ImageRequestControl.setting. |
| size | [out] On a successful call this variable will receive the size needed for capturing into user supplied buffers that use the current settings. |
| alignment | [out] On a successful call this variable will receive the alignment needed for capturing into user supplied buffers that use the current settings. |
| getRequest | ( | self, | |
| nr ) |
Returns a pointer to the desired mvIMPACT.acquire.Request.
This function returns a pointer to the mvIMPACT.acquire.Request stored at nr in the internal array of requests.
| nr | [in] The number of the request to return |
| getSetting | ( | self, | |
| name ) |
Returns a mvIMPACT.acquire.ComponentList object to a setting with a specified name.
This function returns a mvIMPACT.acquire.ComponentList object to a setting with a specified name or will raise an exception if no such setting exists.
| name | [in] The name of the setting to locate |
| imageRequestConfigure | ( | self, | |
| pRequest ) |
Sets a request into configuration mode.
In configuration mode certain properties like mvIMPACT.acquire.Request.imageData, mvIMPACT.acquire.Request.imageSize, mvIMPACT.acquire.Request.imageMemoryMode of a request object can be modified. This can be used to configure one or more requests to use a user supplied memory. To use only a subset of the mvIMPACT.acquire.Request objects available the mvIMPACT.acquire.ImageRequestControl.requestToUse feature can be used.
Only requests that are currently not used by the driver and are not locked because they contain image data that hasn't been processed can be set into configuration mode.
User supplied buffers must follow the alignment and size requirements reported by versions of the function mvIMPACT.acquire.FunctionInterface.getCurrentCaptureBufferLayout. Calling a version of this function will return all the information required to allocate buffers that can be used to capture data for the specified settings.
When allocating memory on the heap, the complete buffer size is needed which is calculated like this:
size + alignment
| pRequest | [in] A const pointer to the request object to configure |
| imageRequestReset | ( | self, | |
| requestCtrlNr, | |||
| mode ) |
Deletes all requests currently queued for the specified mvIMPACT.acquire.ImageRequestControl.
This function will terminate all running image acquisitions associated with the queue bound to the specified image request control and in addition to that will empty the queue of pending image requests for that queue. Also all requests that reside in the result queue and have not been picked up by the application will be unlocked and removed from the result queue. So after this function returns only the requests currently in possession of the application (so requests that have been picked up by successful calls to mvIMPACT.acquire.FunctionInterface.imageRequestWaitFor that have NOT been unlocked) need to be handled. All other requests are in a state where they can be queued for an acquisition again.
| requestCtrlNr | [in] The mvIMPACT.acquire.ImageRequestControl for which all the requests shall be cancelled. |
| mode | [in] Currently unsupported. MUST be set 0. |
| imageRequestResultQueueElementCount | ( | self, | |
| queueNr = 0 ) |
Returns the number of mvIMPACT.acquire.Request objects in the result queue .
This functions queries the number of mvIMPACT.acquire.Request objects currently in the result queue that are available for pickup. This number reflects the number of mvIMPACT.acquire.FunctionInterface.imageRequestWaitFor calls that could be executed afterwards the would return with a valid mvIMPACT.acquire.Request object immediately without waiting!
| queueNr | [in] The result queue to be queried. |
| imageRequestSingle | ( | self, | |
| * | args ) |
Sends an image request to the mvIMPACT.acquire.Device driver.
OVERLOAD 1:
This functions sends a single image request to the capture device. To wait for the image to become ready call the function mvIMPACT.acquire.FunctionInterface.imageRequestWaitFor.
OVERLOAD 2: Sends an image request to the mvIMPACT.acquire.Device driver.
This functions sends a single image request to the capture device. To wait for the image to become ready call the function mvIMPACT.acquire.FunctionInterface.imageRequestWaitFor.
| imageRequestControl | [in] The mvIMPACT.acquire.ImageRequestControl object to be used for this request. mvIMPACT.acquire.ImageRequestControl objects define (among other things), which setting will be used for this image acquisition (via the property mvIMPACT.acquire.ImageRequestControl.setting). |
| imageRequestUnlock | ( | self, | |
| nr ) |
Unlocks the request for the driver again.
To ensure that no image data is overwritten by another image request while the user still deals with the image from a previous acquisition each image buffer will be locked by the driver when it is returned to the user by a call to mvIMPACT.acquire.FunctionInterface.imageRequestWaitFor. No new image will be captured into the same buffer until the user unlocks the buffer again by calling mvIMPACT.acquire.FunctionInterface.imageRequestUnlock.
| nr | [in] The number of the request to unlock. This is typically a value returned from a call to mvIMPACT.acquire.FunctionInterface.imageRequestWaitFor. |
| imageRequestWaitFor | ( | self, | |
| timeout_ms, | |||
| queueNr = 0 ) |
Waits for a request object to become ready.
This function waits for a request object previously sent to the capture device by calling mvIMPACT.acquire.FunctionInterface.imageRequestSingle. When a new request became ready during the period of time specified by the timeout_ms parameter this request is extracted from the result queue and is returned to the user so the same request can not be returned twice until it has been processed and unlocked by the application.
| timeout_ms | [in] The maximum wait time in milliseconds (ms) for this request to become ready. If timeout_ms is '-1', the function's timeout interval never elapses. If the result queue specified by the queueNr parameter already contains a request when calling this function the function will return immediately. Please note that each request has its own timeout that is independent from this wait timeout, thus this function will return with a valid request after the timeout for this request has elapsed even if e.g. a trigger has not been detected. For detailed information on the interaction of the timeout of this function and the timeout of a request please refer to the chapter Acquiring Data in the C++ section. |
| queueNr | [in] The queue where to wait for the request. The number of request queues available depends on the number of video channels offered by the device. The queue a processed request ends up in can be defined by setting the property mvIMPACT.acquire.ImageRequestControl.resultQueue BEFORE calling mvIMPACT.acquire.FunctionInterface.imageRequestSingle. |
| isRequestNrValid | ( | self, | |
| nr ) |
Check if nr specifies a valid mvIMPACT.acquire.Request.
| isSettingAvailable | ( | self, | |
| * | args ) |
Checks if a certain setting is available under the specified location.
This function checks if a certain setting is available under the specified location.
| name | [in] The name or the full path under where the setting is located. |
| storageLocation | [in] The location of the setting. |
| scope | [in] Specifies the scope of this operation. |
| loadAndDeleteSettingFromStack | ( | self | ) |
loads the last setting from the setting stack and then removes this setting from the stack.
This function loads the last setting from the setting stack and then removes this setting from the stack.
See mvIMPACT.acquire.FunctionInterface.saveCurrentSettingOnStack for an example how to use this feature.
See also mvIMPACT.acquire.FunctionInterface.loadSetting to find out which features of a GenICam device are stored in a setting and which are not!
| loadSetting | ( | self, | |
| * | args ) |
Loads a previously stored setting.
This function can be used to restore a previously stored setting again.
To load a setting from a file the mvIMPACT.acquire.sfFile should be specified as part of storageFlags. To load a setting from a platform specific location such as the Registry under Windows© mvIMPACT.acquire.sfNative should be specified. It's not allowed to combine mvIMPACT.acquire.sfFile and mvIMPACT.acquire.sfNative for this operation.
| Impact Acquire Version | Loading an XML settings file created with Impact Acquire version < 2.9.0 | Loading an XML settings file created with Impact Acquire version 2.9.0 - 2.10.1 | Loading an XML settings file created with Impact Acquire version 2.11.0 or later |
|---|---|---|---|
| < 2.9.0 | YES | NO | NO |
| 2.9.0 - 2.10.1 | YES | YES | NO |
| >= 2.11.0 | YES | YES | YES |
| name | [in] The name or the full path under where the setting is located. |
| storageFlags | [in] The flags which define which information shall be read from the location and how this information shall be interpreted. |
| scope | [in] Specifies where the information is located. |
| loadSettingFromDefault | ( | self, | |
| * | args ) |
Loads the default settings.
This function will try to load the settings from a default location. This function can only succeed if a setting has been stored previously by a call to mvIMPACT.acquire.FunctionInterface.saveSettingToDefault.
| scope | [in] Specifies where the information is located. |
| loadSettingFromStack | ( | self | ) |
loads the last setting from the setting stack.
This function loads the last setting from the setting stack.
See mvIMPACT.acquire.FunctionInterface.saveCurrentSettingOnStack for an example how to use this feature.
See also mvIMPACT.acquire.FunctionInterface.loadSetting to find out which features of a GenICam device are stored in a setting and which are not!
| requestCount | ( | self | ) |
Returns the number of available request objects.
| saveCurrentSettingOnStack | ( | self, | |
| * | args ) |
Saves the current setting on the setting stack.
This function saves the current setting on the setting stack. Together which the functions mentioned below this implements a stack for capture settings. This can become handy when entering a section of code that might modify the current capture settings in various ways and depending on the result these modifications shall either be kept or discarded at the end of the operation.
DISCARD_SETTING = 1 APPLY_SETTING = 2 fi = getFunctionInterfaceFromSomewhere() fi.saveCurrentSettingOnStack() option = enterSectionThatModifiesDeviceSettings() if option == DISCARD_SETTING: # discard fi.loadAndDeleteSettingFromStack() # revert all changes just applied without worrying about what these changes actually are elif option == APPLY_SETTING: # apply fi.deleteSettingFromStack() # remove the setting from the stack, but keep changes
The stack makes use of Impact Acquires ability to store capture settings in the memory of the current process. Once the last instance of this mvIMPACT.acquire.FunctionInterface object is deleted all settings pushed on this stack will be deleted automatically.
| storageFlags | [in] The flags which define which information shall be stored and how this information shall be stored. |
| saveSetting | ( | self, | |
| * | args ) |
Stores the current settings.
This function can be used to store the current settings either in an XML-file or (under Windows©) into the Registry. A setting contains all the values set for properties that control the overall way an image is acquired( e.g. the exposure time, etc.).
To store a setting in a file the mvIMPACT.acquire.sfFile should be specified as part of storageFlags. To store a setting in a platform specific location such as the Registry under Windows© mvIMPACT.acquire.sfNative should be specified. Both flags can be combined. In that case the same setting will be stored in a file AND in a platform specific location if these location differ (platform dependent!).
| name | [in] The name or the full path under which this setting shall be stored |
| storageFlags | [in] The flags which define which information shall be stored and how this information shall be stored. |
| scope | [in] Specifies where the information shall be stored. |
| saveSettingToDefault | ( | self, | |
| * | args ) |
Stores the current settings under a default location.
Under Windows© this will be in the Registry. A setting contains all the values set for properties that control the overall way an image is acquired( e.g. the exposure time, etc.).
| scope | [in] Specifies where the information shall be stored. |
| updateRequests | ( | self | ) |
Updates the internal cache for request objects.
Calling this function isn't strictly necessary but doing so can speed up the initial execution of other functions after the request count has been modified using the mvIMPACT.acquire.SystemSettings.requestCount property. Not doing so will execute the work performed by this function when calling any of the following functions for the first time after modifying the request count:
|
static |
A list property (read-only) which returns the names of the image request controls available for this mvIMPACT.acquire.Device.
See mvIMPACT.acquire.FunctionInterface.getAvailableImageRequestControls()
|
static |
A list property (read-only) which returns the names of the settings available for this mvIMPACT.acquire.Device.
See mvIMPACT.acquire.FunctionInterface.getAvailableSettings()
|
static |