eBUS Python Class List

class eBUS.IPConfig

Bases: object

property thisown

The membership flag

property mIPAddress
property mSubnetMask
class eBUS.IPvChunkData(*args, **kwargs)

Bases: object

Generic chunk data interface.

property thisown

The membership flag

ResetChunks()

See PvBuffer.ResetChunks

Same as PvBuffer equivalent. Provided with this interface for convenience.

AddChunk(self, aID, aData) → PvResult

Add chunk data to the buffer payload section by specifying the ID of the chunk data. See PvBuffer.ResetChunks for more information.

Parameters:

  • aID (int, in) – Chunk data ID for aIndex.

  • aData (python bytes object, in) – Payload data of the chunk data. Python bytes object.

Return type:

PvResult

Returns:

A PvResult is used to capture the success or failure of the operation:

SetChunkLayoutID(aChunkLayoutID)

Set the chunk data layout ID.

Parameters:

aChunkLayoutID (int, in) – Chunk data layout ID.

HasChunks()

Returns true if the buffer has data chunks.

Unlike GetChunkCount, chunks do not need to be parsed or resolved with this method.

Return type:

boolean

Returns:

True if the buffer holds data chunks, false if not.

GetChunkCount()

See PvBuffer.GetChunkCount.

Same as PvBuffer equivalent. Provided with this interface for convenience.

Return type:

int

Returns:

Data chunks count. 0 if no chunks are available.

GetChunkIDByIndex(self, aIndex) → PvResult, int

Returns a tuple of PvResult and the ID of a chunk based on its index.

If the index is out of range or the PvBuffer does not have any data chunk, 0 is returned in ID.

Parameters:

aIndex (int, in) – Data chunk Index.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, chunkID):
  • PvResult representing the outcome:

    • PV_OK

    • PV_NOT_FOUND if the index is out of range or the buffer does not have any chunks

  • chunkID:

    • Chunk ID.

GetChunkSizeByIndex(aIndex)

See PvBuffer.GetChunkSizeByIndex.

Same as PvBuffer equivalent. Provided with this interface for convenience.

Parameters:

aIndex (int, in) – Data chunk index.

Return type:

int

Returns:

Data chunk size. 0 if the index is out of range.

GetChunkSizeByID(aID)

See PvBuffer.GetChunkSizeByID.

Same as PvBuffer equivalent. Provided with this interface for convenience.

Parameters:

aID (int, in) – Data chunk ID.

Return type:

int

Returns:

Data chunk size. 0 if the chunk ID is not found.

GetChunkRawDataByIndex(self, aIndex) → ndarray

See PvBuffer::GetChunkRawDataByIndex. Same as PvBuffer equivalent. Provided with this interface for convenience.

Parameters:

aIndex (int, in) – Data chunk index.

Return type:

ndarray

Returns:

A 1-dimensional python numpy array with dtype np.uint8 describing the chunk data. Empty if the index is out of range.

GetChunkRawDataByID(aID)

GetChunkRawDataByIndex(self, aIndex) -> ndarray See PvBuffer.GetChunkRawDataByIndex. Same as PvBuffer equivalent. Provided with this interface for convenience.

Parameters:

aIndex (int, in) – Data chunk index.

Return type:

ndarray

Returns:

A 1-dimensional python numpy array with dtype np.uint8 describing the chunk data. Empty if the index is out of range.

GetChunkLayoutID()

Get the chunk data layout ID.

Return type:

int

Returns:

The current chunk data layout ID.

GetChunkDataSize()

Returns the current chunk data size.

In a transmission context this method returns how many bytes are used for extra chunk data. It includes the chunk headers for all chunk data and if applicable the chunk header for the main chunk (typically the image).

This method has no use in a reception context where the data receiver delivers the buffer. Use either the direct chunk access methods or the GenApi interface of the device to access chunk data.

Return type:

int

Returns:

Chunk data size in bytes.

GetChunkDataCapacity()

Returns the current chunk data capacity.

In a transmission context where you create the buffer, memory is allocated for chunks. This method returns how many bytes can still be added as chunk data.

One chunk is always made of 8-bytes of headers plus the chunk data length. You also need to reserve another 8-bytes for the main chunk (typically the image) unless you buffer only contains chunk data.

This method has no use in a reception context where the data receiver delivers the buffer. Use either the direct chunk access methods or the GenApi interface of the device to access chunk data.

Return type:

int

Returns:

Chunk data capacity.

class eBUS.IPvGenApiFactory(*args, **kwargs)

Bases: object

GenApi factory used to add custom GenApi parameters to a software-based GigE Vision Device GenICam XML file.

GenApi features can only be added to the device’s GenICam XML file using the IPvSoftDeviceGEVEventSink.OnCreateCustomGenApiFeatures callback. See IPvSoftDeviceGEVEventSink and PvSoftDeviceGEV for more information.

To add a feature, set all of its attributes in the factory and then call one of the Create methods. After calling a Create method, ALL feature attributes in the factory are reset to their default value.

The following sequence will work and is valid:

  • Set Feature A name.

  • Set Feature A category.

  • Create Feature A.

  • Reset feature attributes of the factory.

  • Set Feature B name.

  • Set Feature B category.

  • Create Feature B.

The following sequence will fail because Feature B would not have a category defined:

  • Set Feature A name.

  • Set Feature A category.

  • Create Feature A.

  • Reset feature attributes of the factory.

  • Set Feature B name.

  • Create Feature B.

property thisown

The membership flag

SetName(aName)

Sets the name of the next feature to be added to the GenICam XML file.

The name must not contain any special characters. It can only contain letters, digits, and underscores. The feature name must begin with a letter.

Parameters:

aName (str, in) – Feature name.

SetDisplayName(aDisplayName)

Sets the display name of the next feature to be added to the GenICam XML.

The display name can be used by GenApi browsers in order to present the features in a simpler user-interface. Display names do not have to be unique and do can contain spaces.

Features for which display names are not provided will have a display name automatically generated for them.

Automatically generated display names created by adding spaces and removing the last sub-category prefix from the name of the feature:

  • DeviceType from DeviceControl category: Type

  • WidthMax from ImageFormatControl category: Width Max

  • EventTestTimestamp from EventControlEventTestData category: Test Timestamp

These simple rules should be enough for most features. If you need more control on the display name of a feature, just call this method to set a custom display name before using the factory to create the feature.

Parameters:

aDisplayName (str, in) – Feature name.

SetCategory(*args)
SetDescription(aDescription)

Sets the description of the next feature to be added to the GenICam XML file.

Parameters:

aDescription (str, in) – Feature description.

SetToolTip(aToolTip)

Sets the tooltip of the next feature to be added to the GenICam XML file.

Parameters:

aToolTip (str, in) – Feature tooltip.

SetAccessMode(aAccessMode)

Sets the access mode of the next feature to be added to the GenICam XML file.

The access mode can be different than the register that it is bound to. However, it does not make sense for it to be more restrictive. As an example, a register could be read-write and the GenApi feature be read-only.

Parameters:

aAccessMode (int, in) – Feature access mode.

SetRepresentation(aRepresentation)

Sets the numeric representation of the next feature to be added to the GenICam XML file.

Parameters:

aRepresentation (int, in) – Feature representation.

SetVisibility(aVisibility)

Sets the visibility of the next feature to be added to the GenICam XML.

Parameters:

aVisibility (int, in) – Feature visibility.

SetCachable(aCache)

Sets the cache behavior of the next feature to be added to the GenICam XML file.

Possible values:

  • PvGenCacheWriteThrough: The cached value of the register behind the feature is updated to the new value on write operations.

  • PvGenCacheWriteAround: The cached value of the register behind the feature is invalidated on write operations and refreshed with the value read from PvSoftDeviceGEV on the next read operation.

  • PvGenCacheNone: The register value behind the feature is not cached and is refreshed every #SetPollingTime ms cycle.

Parameters:

aCache (int, in) – Feature cachable.

SetPollingTime(aPollingTime)

Sets the polling time, in ms, of the next feature to be added to the GenICam XML file.

The polling time provides a hint of how often no-cache features should be updated from GenApi browsers.

Parameters:

aPollingTime (int, in) – Feature polling time.

SetNameSpace(aNameSpace)

Sets the namespace of the next feature to be added to the GenICam XML file.

Possible values: - PvGenNameSpaceStandard for GenICam SFNC features. - PvGenNameSpaceCustom for custom features.

Parameters:

aNameSpace (int, in) – Feature namespace.

SetTLLocked(aLocked)

Sets the TLParamsLocked behavior of the next feature to be added to the GenICam XML file.

A feature with its TLLocked attribute set to True will be forced to read-only when the PvSoftDeviceGEV is streaming.

As an example, the Width and Height features use TLLocked (transport layer locked) to prevent the user from changing their values when the PvSoftDeviceGEV is streaming.

Parameters:

aLocked (boolean, in) – Feature TLLocked attribute.

SetStreamable(aStreamable)

Sets the streamable behaviour of the next feature to be added to the GenICam XML.

A feature with its streamable attribute set to true will be be considered when creating a persistence file of the GenApi interface of the device.

Parameters:

aStreamable (boolean, in) – Feature streamable attribute.

SetUnit(aUnit)

Sets the units for an integer or float feature.

This string-based unit is only used for display purpose, it carries not functional signification.

Applies to integer or float feature, SwissKnife or Converter.

Parameters:

aUnit (str, in) – Feature unit attribute.

SetPValue(aFeatureName)

Sets the pValue attribute of the next feature to be added to the GenICam XML.

Most GenApi features are linked to a register. With pValue you replace the register by the link or pointer to another feature.

When defining a register as pValue, do not provide a register when calling the factory create method, use NULL instead.

For ADVANCED GenApi support use cases.

Parameters:

aFeatureName (str) – [in] Feature name to use for pValue.

SetPIsAvailable(aFeatureName)

Sets the pIsAvaialble attribute of the next feature to be added to the GenICam XML.

This attribute can be used to make a feature dynamically available or unavailable. It has to be the name of another feature.

If you need an more complex expression to control the available state of a feature, create a private integer SwissKnife that returns non-zero (1 or true) when the feature should be available.

See #SetCategory for more information on private features. See #CreateIntSwissKnife for more information on SwissKnifes.

When pIsAvailable evaluates to true the feature is available as defined: read-write, read-only or write-only. When pIsAvailable evaluates to false the feature is not readable and not writable. The eBUS GenApi browser shows a feature that state as {Not available}.

For ADVANCED GenApi support use cases.

Parameters:

aFeatureName (str) – [in] Feature name to use for pIsImplemented.

SetPIsLocked(aFeatureName)
MapChunk(aChunkID, aAddress, aLength, aEndianness=0)

Maps the next feature to be added to the GenICam XML file to a chunk, identified by its ID.

Sets the chunk ID and mapping (address, length, and endianness) of the next feature to be added to the GenICam XML file.

By default all features map to a PvSoftDeviceGEV register provided in the Create calls, unless #MapChunk or #MapEvent are called when defining the feature attributes.

Parameters:

  • aChunkID (int, in) – Chunk ID to map.

  • aAddress (int, in) – Data offset of the feature in the chunk, in bytes.

  • aLength (int, in) – Data length of the feature in the chunk, in bytes.

  • aEndianness (int, in, optional) – Data endianness.

MapEvent(aEventID, aAddress, aLength, aEndianness=0, aAdjustAddress=True)

Maps the next feature to be added to the GenICam XML file to a messaging channel event, identified by its ID.

Sets the messaging channel event ID and mapping (address, length, and endianness) of the next feature to be added to the GenICam XML file.

By default all features map to a PvSoftDeviceGEV register provided in the Create calls, unless #MapChunk or #MapEvent are called when defining the feature attributes.

Parameters:

  • aEventID (int, in) – Event ID to map.

  • aAddress (int, in) – Data offset of the feature in the event data, in bytes.

  • aLength (int, in) – Data length of the feature in the event data, in bytes.

  • aEndianness (int, in, optional) – Data endianness.

  • aAdjustAddress (boolean, in, optional) – Applies an offset on the provided address.

AddSelected(aFeatureName)

Adds a selector to the next feature to be added to the GenICam XML file.

A selector, as specified by the GenICam SFNC, is used to index which instance of the feature is accessed in situations where multiple instances of a feature exist (For instance, the analog gain for each separate channel of the red/green/blue component of a color camera).

Feature A can be the selector for Features B and C. We could also say that B and C are indexed by A. In that case, Feature A needs to be identified as the selector for Feature B and Feature C.

Example

A feature can have more than one selector. A feature with one selector could be thought of as a one-dimensional vector. A feature with two selector would be like a table with columns and rows, etc.

Parameters:

aFeatureName (str, in) – Name of the feature that is selecting the new feature.

AddInvalidator(aFeatureName)

Add an invalidator to the next feature to be added to the GenICam XML file.

Add one invalidator to a feature. For example, Feature A being invalidated by Feature B has the cache of Feature A being invalidated when a new value is written to Feature B.

Parameters:

aFeatureName (str, in) – Name of the feature that is invalidating the new feature.

AddEnumEntry(*args)

Overload 1:

Add an enumeration entry to the next feature to be added to the GenICam XML file.

When #CreateEnum is called, it will be populated with the enumeration entries added using this method. Call #AddEnumEntry for each enumeration entry of the new feature.

If one of the Create methods other than #CreateEnum is called, the enumeration entries added to the factory are ignored.

Parameters:

  • aName (str, in) – Name of the new enumeration entry.

  • aValue (int, in) – Value of the new enumeration entry.


Overload 2:

Add an enumeration entry to the next feature to be added to the GenICam XML file.

When #CreateEnum is called, it will be populated with the enumeration entries added using this method. Call #AddEnumEntry for each enumeration entry of the new feature.

If one of the Create methods other than #CreateEnum is called, the enumeration entries added to the factory are ignored.

Parameters:

  • aName (str, in) – Name of the new enumeration entry.

  • aValue (int, in) – Value of the new enumeration entry.

  • aDisplayName (str, in) – Custom display name for the new enum entry. If an empty string is provided a default display name is generated for the enum entry.

  • aNameSpace (int, in, optional) – Namespace for the new enum entry. See #SetNameSpace for more information on GenICam XML namespaces.


Overload 3:

Add an enumeration entry to the next feature to be added to the GenICam XML file.

When #CreateEnum is called, it will be populated with the enumeration entries added using this method. Call #AddEnumEntry for each enumeration entry of the new feature.

If one of the Create methods other than #CreateEnum is called, the enumeration entries added to the factory are ignored.

Parameters:

  • aName (str, in) – Name of the new enumeration entry.

  • aValue (int, in) – Value of the new enumeration entry.

  • aDisplayName (str, in) – Custom display name for the new enum entry. If an empty string is provided a default display name is generated for the enum entry.

  • aNameSpace – Namespace for the new enum entry. See #SetNameSpace for more information on GenICam XML namespaces.

AddVariable(aFeatureName)

Adds a variable that will be declared for the next SwissKnife of Converter to be added to the GenICam XML file.

In order to refer to a feature in a SwissKnife or Converter formula, it first needs to be defined as a variable.

Variables are defined using the exact case sensitive feature name. They are then used in the formulas using the same exact feature name.

A SwissKnife can have one or more variables.

A Converter can have zero or more variables. Important: the main feature a Converter operates on (TO/FROM) does not have to be defined as a variable.

Variables are ignored if the next feature to be added to the GenICam XML file is not a SwissKnife or Converter.

For ADVANCED GenApi support use cases.

Parameters:

aFeatureName (str) – [in] Feature name to use as variable.

CreateInteger(*args)
CreateFloat(*args)
CreateString(aRegister=None)

Adds a string feature to the GenICam XML file using the current state of the factory for its attributes.

After calling this method, all feature creation attributes are reset to their default values.

Parameters:

aRegister (IPvRegister, in, optional) – Register that the new string feature maps to or NULL if creating a chunk or messaging channel event data feature.

Return type:

PvResult

Returns:

Includes:

CreateRegister(aRegister=None)
CreateBoolean(aRegister=None)

Adds a Boolean feature to the GenICam XML file using the current state of the factory for its attributes.

After calling this method, all feature creation attributes are reset to their default values.

Parameters:

aRegister (IPvRegister, in, optional) – Register that the new Boolean feature maps to or NULL if creating a chunk or messaging channel event data feature.

Return type:

PvResult

Returns:

Includes:

CreateCommand(aRegister=None)

Adds a command feature to the GenICam XML file using the current state of the factory for its attributes.

After calling this method, all feature creation attributes are reset to their default values.

Parameters:

aRegister (IPvRegister, in, optional) – Register that the new command feature maps to.

Return type:

PvResult

Returns:

Includes:

CreateEnum(aRegister=None)

Adds an enumeration feature to the GenICam XML file using the current state of the factory for its attributes.

After calling this method, all feature creation attributes are reset to their default values.

Parameters:

aRegister (IPvRegister, in, optional) – Register that the new enumeration feature maps to or NULL if creating a chunk or messaging channel event data feature.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • PV_INVALID_PARAMETER

    • If aRegister is NULL and none of chunk ID, messaging channel event or pValue has been defined.

    • If no enumeration entries have been defined for the new feature.

  • PV_NOT_INITIALIZED if #SetName has not be called for the new feature.

CreateIntSwissKnife(aFormula)

Adds an integer SwissKnife to the GenICam XML file using the current state of the factory for its attributes.

An integer SwissKnife is a GenApi read-only feature that resolves a formula whenever it is read. The formula is defined as a string and evaluates to an integer. It can refer to other features as long as they have been declared with #AddVariable. Variables can be integer, float (truncated to integer), enum (integer value) boolean (1 or 0 integer value) or command as long as they are readable.

Example of a simple SwissKnife adding the value of two features:

lFactory->SetName( "MySwissKnife" );
lFactory->SetCategory( "MyCategory" );
lFactory->AddVariable( "ValueA" );
lFactory->AddVariable( "ValueB" );
lFactory->CreateIntSwissKnife( "ValueA + ValueB" );

When MySwissKnife is read, the formula is evaluated. If ValueA is 4 and ValueB is 3, MySwissKnife will read as 7: 4 + 3.

Formula examples:

  • Simple constant: 42

  • Simple feature: ValueA

  • Simple mathematical expression: 32 + 10

  • Simple mathematical expression with features: ValueA + (10 * ValueB)

  • Bitwise operations: (ValueA << 16) | (ValueB >> 16)

  • ‘if’ statement: (ValueA = 4) ? 8 : 16

  • Switch-case statement with default: (ValueA = 0) ? 0x0000B824 : (ValueA = 1) ? 0x0000B82C : (ValueA = 2) ? 0x0000B884 : (ValueA = 3) ? 0x0000B88C : 0xFFFFFFFF

After calling this method, all feature creation attributes are reset to their default values.

GenApi formulas are compatible with expressions defined for the Kirill Zaborsk’s math parser library, the CCalc library from Walery Studennikov. More information is available at http://kirya.narod.ru/mathparser.html.

For ADVANCED GenApi support use cases.

Parameters:

aFormula (str) – [in] SwissKnife formula.

Return type:

PvResult

Returns:

Includes:

CreateFloatSwissKnife(aFormula)

Adds a float SwissKnife to the GenICam XML file using the current state of the factory for its attributes.

A float SwissKnife is a GenApi read-only feature that resolves a formula whenever it is read. The formula is defined as a string and evaluates to a float. It can refer to other features as long as they have been declared with #AddVariable. Variables can be integer (converter to float), float, enum (integer value converted to float) boolean (1 or 0 integer value converted to float) or command as long as they are readable.

Example of a simple SwissKnife adding the value of two features:

lFactory->SetName( "MySwissKnife" );
lFactory->SetCategory( "MyCategory" );
lFactory->AddVariable( "ValueA" );
lFactory->AddVariable( "ValueB" );
lFactory->CreateFloatSwissKnife( "ValueA + ValueB" );

When MySwissKnife is read, the formula is evaluated. If ValueA is 4.1 and ValueB is 3.2, MySwissKnife will read as 7.3: 4.1 + 3.2.

Formula examples:

  • Simple constant: 42.4

  • Simple feature: ValueA

  • Simple mathematical expression: 32.34 + 10.714

  • Simple mathematical expression with features: ValueA + (10.1 * ValueB)

  • Advanced mathematical expression: SIN(0.814)

  • Advanced mathematical expression with feature: SQRT(ValueA)

  • ‘if’ statement: (ValueA > 4) ? 8.12 : 16.991

  • Bitwise operations are not supported with float SwissKnife.

After calling this method, all feature creation attributes are reset to their default values.

GenApi formulas are compatible with expressions defined for the Kirill Zaborsk’s math parser library, the CCalc library from Walery Studennikov. More information is available at http://kirya.narod.ru/mathparser.html.

For ADVANCED GenApi support use cases.

Parameters:

aFormula (str) – [in] SwissKnife formula.

Return type:

PvResult

Returns:

Includes:

CreateIntConverter(aValueFeatureName, aFromFormula, aToFormula)

Adds an integer Converter to the GenICam XML file using the current state of the factory for its attributes.

A converter is a read-write GenApi construct that allows reading from and writing to a referenced feature using SwissKnife-like formulas.

The referenced feature is provided through aValueFeatureName and represents the feature on which the expressions operates. It is referred to as FROM and TO in the converter formulas and does not have to be declared as a variable.

The formula used to read the referenced feature is provided with aFromFormula. The raw value read from the reference is available as the special TO variable.

The formula used to write to the referenced feature is provided with aToFormula. The raw value written to the converter is available as the special FROM variable.

If the converter formulas need to reference additional features they should first be declared using the #AddVariable method.

Example of a converter handling conversion between milliseconds and nanoseconds:

lFactory->SetName( "MyNanosecondFeature" );
lFactory->SetCategory( "MyCategory" );
lFactory->SetUnit( "ms" );
lFactory->CreateIntConverter( "MyMillisecondFeature", "TO * 1000", "FROM / 1000" );
In the example above:

  • We create a MyNanosecondFeature.

  • The referenced feature is MyMillisecondFeature.

  • The converter read formula is TO * 1000, where TO is the value read from MyMillisecondFeature.
    • Reading from the MyNanosecondFeature converter:

      • Reads the referenced feature, MyMillisecondFeature (4)

      • Replaces TO in the ‘from’ formula with the value read from MyMillisecondFeature (4 * 1000)

      • Evaluates the formula (4000)

      • Completes the read operation returning 4000

  • The converter write formula is is FROM / 1000, where FROM is the value written to the converter.
    • Writing to the MyNanosecondFeature converter:

      • Value written to the converter (2000)

      • Replaces FROM in the ‘to’ formula with the value written to the converter (2000 / 1000)

      • Evaluates the formula (2)

      • Writes 2 to MyMillisecondFeature

See #CreateFloatSwissKnife for more information on formulas.

For ADVANCED GenApi support use cases.

After calling this method, all feature creation attributes are reset to their default values.

Parameters:

  • aValueFeatureName (str) – [in] Main feature the converter operates on, referred as TO and FROM in the formulas.

  • aFromFormula (str) – [in] Formula used when reading from the converter.

  • aToFormula (str) – [in] Formula used when writing to the converter.

Return type:

PvResult

Returns:

Includes:

CreateFloatConverter(aValueFeatureName, aFromFormula, aToFormula)

Adds a float Converter to the GenICam XML file using the current state of the factory for its attributes.

A converter is a read-write GenApi construct that allows reading from and writing to a referenced feature using SwissKnife-like formulas.

The referenced feature is provided through aValueFeatureName and represents the feature on which the expressions operates. It is referred to as FROM and TO in the converter formulas and does not have to be declared as a variable.

The formula used to read the referenced feature is provided with aFromFormula. The raw value read from the reference is available as the special TO variable.

The formula used to write to the referenced feature is provided with aToFormula. The raw value written to the converter is available as the special FROM variable.

If the converter formulas need to reference additional features they should first be declared using the #AddVariable method.

Example of a converter handling conversion between inches and centimeters:

lFactory->SetName( "MyCentimeterFeature" );
lFactory->SetCategory( "MyCategory" );
lFactory->SetUnit( "cm" );
lFactory->CreateFloatConverter( "MyInchesFeature", "TO * 2.54", "FROM * 0.3937" );
In the example above:

  • We create a MyCentimeterFeature.

  • The referenced feature is MyInchesFeature.

  • The converter read formula is TO * 2.54, where TO is the value read from MyInchesFeature.
    • Reading from the MyCentimeterFeature converter:

      • Reads the referenced feature, MyInchesFeature (4)

      • Replaces TO in the ‘from’ formula with the value read from MyInchesFeature (4 * 2.54)

      • Evaluates the formula (10.16)

      • Completes the read operation returning 10.16

      • The converter write formula is is FROM * 0.3937, where FROM is the value written to the converter.

    • Writing to the MyCentimeterFeature converter:

      • Value written to the converter (2)

      • Replaces FROM in the ‘to’ formula with the value written to the converter (2 * 0.3937)

      • Evaluates the formula (0.7874)

      • Writes 0.7874 to MyInchesFeature

See #CreateFloatSwissKnife for more information on formulas.

For ADVANCED GenApi support use cases.

After calling this method, all feature creation attributes are reset to their default values.

Parameters:

  • aValueFeatureName (str) – [in] Main feature the converter operates on, referred as TO and FROM in the formulas.

  • aFromFormula (str) – [in] Formula used when reading from the converter.

  • aToFormula (str) – [in] Formula used when writing to the converter.

Return type:

PvResult

Returns:

Includes:

AddInvalidatorTo(aStandardFeatureName, aInvalidatorFeatureName)

Adds a a custom invalidator to a feature managed by PvSoftDeviceGEV.

This methods allows defining extra custom invalidators for features managed by PvSoftDeviceGEV. As an example, if you call this method to add an ComponentSelector invalidator to the PvSoftDeviceGEV managed (or owned) PixelFormat feature, the invalidator is added to the invalidators of PixelFormat when creating the GenICam XML of the device. With this example, the GenApi cache of PixelFormat would be invalidated when the value of ComponentSelector changes client-side.

For ADVANCED GenApi support use cases.

Parameters:

  • aStandardFeatureName (str) – [in] Name of the feature to add the invalidator to.

  • aInvalidatorFeatureName (str) – [in] Name of the feature which changes causes aStandardFeatureName to be invalidated.

Return type:

PvResult

Returns:

Includes:

SetPIsAvailableFor(aStandardFeatureName, aPIsAvailableFeatureName)

Forces a pIsAvailable reference for a feature managed by PvSoftDeviceGEV.

The pIsAvailable would typically be an IntSwissKnife defined as a global feature in the IPvSoftDeviceGEVEventSink.OnCreateCustomGenApiFeatures callback. The feature identified by aStandardFeatureName would only be available when the IntSwissKnife referred to by aPIsAvailableFeatureName evaluates to non-zero.

With most use-cases #SetPIsAvailableFor should be called in the same context.

For ADVANCED GenApi support use cases.

Parameters:

  • aStandardFeatureName (str) – [in] Name of the feature to add the pIsAvailable for.

  • aPIsAvailableFeatureName (str) – [in] Feature used to evaluate if the feature is available or not.

Return type:

PvResult

Returns:

Includes:

SetPIsAvailableForEnumEntry(aStandardFeatureName, aEnumEntryName, aPIsAvailableFeatureName)

Forces a pIsAvailable reference for a the enum entry of an enum feature managed by PvSoftDeviceGEV.

The pIsAvailable would typically be an IntSwissKnife defined as a global feature in the IPvSoftDeviceGEVEventSink.OnCreateCustomGenApiFeatures callback. aEnumEntry of the enum feature identified by aStandardFeatureName would only be available when the IntSwissKnife referred to by aPIsAvailableFeatureName evaluates to non-zero.

With most use-cases #SetPIsAvailableFor should be called in the same context.

For ADVANCED GenApi support use cases.

Parameters:

  • aStandardFeatureName (str) – [in] Name of the enum feature the enum entry belongs to.

  • aEnumEntryName (str) – [in] Name of the enum entry to add the pIsAvailable for.

  • aPIsAvailableFeatureName (str) – [in] Feature used to evaluate if the enum entry is available or not.

Return type:

PvResult

Returns:

Includes:

SetPIsLockedFor(aStandardFeatureName, aPIsLockedFeatureName)
SetPValueFor(aStandardFeatureName, aPValueFeatureName)

Forces a pValue reference for a feature managed by PvSoftDeviceGEV.

For ADVANCED GenApi support use cases.

Parameters:

  • aStandardFeatureName (str) – [in] Name of the feature to force pValue for.

  • aPValueFeatureName (str) – [in] Name of the feature used provide the value of the aStandardFeatureName feature.

Return type:

PvResult

Returns:

Includes:

SetPMinFor(aStandardFeatureName, aPMinFeatureName)

Forces a pMin reference for an integer or float feature managed by PvSoftDeviceGEV.

For ADVANCED GenApi support use cases.

Parameters:

  • aStandardFeatureName (str) – [in] Name of the feature to force pMin for.

  • aPMinFeatureName (str) – [in] Name of the feature used provide the minimum of the aStandardFeatureName feature.

Return type:

PvResult

Returns:

Includes:

SetPMaxFor(aStandardFeatureName, aPMaxFeatureName)

Forces a pMax reference for an integer or float feature managed by PvSoftDeviceGEV.

For ADVANCED GenApi support use cases.

Parameters:

  • aStandardFeatureName (str) – [in] Name of the feature to force pMax for.

  • aPMaxFeatureName (str) – [in] Name of the feature used provide the maximum of the aStandardFeatureName feature.

Return type:

PvResult

Returns:

Includes:

SetPIncFor(aStandardFeatureName, aPIncFeatureName)

Forces a pInc reference for an integer feature managed by PvSoftDeviceGEV.

For ADVANCED GenApi support use cases.

Parameters:

  • aStandardFeatureName (str) – [in] Name of the feature to force pInc for.

  • aPIncFeatureName (str) – [in] Name of the feature used provide the maximum of the aStandardFeatureName feature.

Return type:

PvResult

Returns:

Includes:

SetPMin(aFeatureName)

Sets node to use for integer or float dynamic minimum attribute.

Sets the pMin attribute of an integer or float to point to another GenApi node like a Swiss Knife. When pMin is set for a new feature, it has precedence on any defined constant minimum.

Parameters:

aFeatureName (str) – [in] Name of the feature the integer or float minimum attribute points to.

SetPMax(aFeatureName)

Sets node to use for integer or float dynamic maximum attribute.

Sets the pMax attribute of an integer or float to point to another GenApi node like a Swiss Knife. When pMax is set for a new feature, it has precedence on any defined constant maximum.

Parameters:

aFeatureName (str) – [in] Name of the feature the integer or float maximum attribute points to.

SetPInc(aFeatureName)

Sets node to use for integer dynamic increment attribute.

Sets the pInc attribute of an integer to point to another GenApi node like a Swiss Knife. When pInc is set for a new feature, it has precedence on any defined constant increment.

Parameters:

aFeatureName (str) – [in] Name of the feature the integer increment attribute points to.

class eBUS.IPvImage(*args, **kwargs)

Bases: object

Generic image interface.

property thisown

The membership flag

GetDataPointer(self) → ndarray

Get the numpy aray describing the image’s data.

The GetDataPointer method returns a numpy array describing the buffer. The number of channels determine the dimensions, the dtype of the ndarray is determined by the number of bits per pixel.

  • Any packed pixel format (10 bits/pixel, 12 bits/pixel… etc) is described as a 1-dimensional numpy array with dtype np.uint8. The user is in charge of unpacking if needed.

  • Unpacked Mono and Bayer images are described as a 2-dimensional numpy array with shape (height,width), the dtype of the array is either np.uint8 or np.uint16 based on the actual bits/pixel.

  • Unpacked RGB, YUV or YCbCr images are described as a 3-dimensional numpy array with shape (height, width, channels), the dtype of the array is either np.uint8 or np.uint16. For example, PvPixelYUV422_8_UYVY has shape (height, width, 2) with dtype np.uint8, PvPixelYCbCr8_CbYCr has shape (height, width, 3) with dtype np.uint8, PvPixelBGR16 has shape (height, width, 3) with dtype np.uint16.

Return type:

ndarray

Returns:

A numpy array pointing to the image data.

GetImageSize()

Actual image size within the payload or buffer.

Uses the GEV leader for the actual width. Uses the GEV trailer for line count which is the actual height.

Return type:

int

Returns:

The actual image size within the payload or buffer

GetWidth()

Get the image’s width.

Return type:

int

Returns:

The image’s width in pixels.

GetHeight()

Get the image’s height.

Return type:

int

Returns:

The image’s height, in pixels.

GetPixelType()

The buffer’s pixel type.

Return type:

int

Returns:

The pixel type. The pixel depth, colorspace, and other information are coded into the value.

GetBitsPerPixel()

Returns how many bits are required to hold a pixel using the current buffer’s pixel type

Return type:

int

Returns:

Bits per pixel for the current buffer’s pixel type.

GetOffsetX()

Get the image’s horizontal offset.

Return type:

int

Returns:

The image’s horizontal offset, in pixels.

GetOffsetY()

Get the image’s vertical offset.

Return type:

int

Returns:

The image’s vertical offset, in pixels.

GetPaddingX()

Get the horizontal image padding.

Images lines could be grabbed in increments of, let’s say, 32 bytes. For an image 511 bytes across, the video interface adds a meaningless byte to make the line total 512 bytes (divisible by 32). In this case, the paddingX value would be 1 (byte).

Other devices may have different requirements on line length. Divible by 4, 8, 16, etc. or no specific limitations or requirements.

Return type:

int

Returns:

The horizontal image padding, in bytes; the number of bytes at the end of an image’s line that contain meaningless data.

GetPaddingY()

Get the vertical image padding.

Additional bytes appended at the end of an image.

See #GetPaddingX.

Return type:

int

Returns:

The vertical image padding, in bytes.

See also: GetPaddingX

GetBlockID()

Return the block ID.

This method returns the block ID. The GigE Vision or USB3 Vision transmitter typically increments the value by 1 for each new image. You can use this value to ensure the blocks are in order and that none are missing. The value is unsigned and wraps around to 1 (skipping 0) when it reaches 65536.

Return type:

int

Returns:

The block ID

GetTimestamp()

Get the image’s timestamp.

With hardware timestamps and GigE Vision devices, the device defines the timestamp tick frequency. The effective value can be retrieved from the GenApi interface of the device.

With hardware timestamps and USB3 Vision devices, timestamps are always defined in nanoseconds.

With software timestamps the timestamps are in micro seconds.

Use the PvStream GenApi interface to configure whether hardware or software time stamps are used.

Return type:

int

Returns:

The image’s hardware timestamp; For Pleora devices, this is the value of the relative timestamp clock when the grabber began receiving data from the camera head - on the rising edge of the FVAL.

GetReceptionTime()

Get the buffer’s reception timestamp.

Return type:

int

Returns:

The buffer’s reception time on the host, in micro seconds. Not an absolute time value.

class eBUS.IPvImageJPEG(*args, **kwargs)

Bases: object

Generic interface to a JPEG image.

Preliminary JPEG support in the context of GigE Vision multi-part support. The data is provided as-received and the eBUS SDK does not currently offer more support for JPEG payloads.

property thisown

The membership flag

GetDataPointer(self) → ndarray

Get the numpy array describing the buffer data.

The GetDataPointer method returns a numpy array describing the buffer data.

Return type:

ndarray

Returns:

A 1-dimensional python numpy array with dtype np.uint8 describing the buffer data.`

GetFlag()

Returns the native JPEG flags of the compressed image.

Return type:

uint8_t

Returns:

JPEG flags of the image.

GetTimestampTickFrequency()

Returns the timetstamp tick frequency as provided in the GVSP header.

Return type:

int

Returns:

Timestamp tick frequency.

GetDataFormat()

Returns the JPEG data format.

Return type:

int

Returns:

JPEG data format.

GetDataSize()

Returns the JPEG data size.

Return type:

int

Returns:

JPEG data size.

class eBUS.IPvMessageChannel(*args, **kwargs)

Bases: object

Messaging channel interface of the software-based GigE Vision Device.

Can be retrieved from a properly initialized PvSoftDeviceGEV to monitor the messaging channel state and send events to the GigE Vision controller.

This class cannot be instantiated and there is no use case where you would need to implement this interface.

property thisown

The membership flag

FireEvent(aEventID, aData, aBlockID=0, aChannelIndex=65535) → PvResult
  • Fires a messaging channel event.

    • Sends a messaging channel event with data to the messaging channel destination that is currently registered.

    • An event ID needs to be provided.

If the event is sent in the context of a streaming event, we recommend that you set the block ID and streaming channel that the event is associated to.

The default value for the block ID and channel index when an event is not associated to a streaming event is zero.

It is possible to map event data to the GenApi interface of the PvSoftDeviceGEV. See IPvGenApiFactory.MapEvent for more information.

Overload 1:

Use FireEvent( aEventID, aBlockID = 0, aChannelIndex = 0xFFFF) to send an event with no data.

Parameters:

  • aEventID (int, in) – Event ID. Use standard event codes or a value between 0x9000 and 0xFFFF for custom events.

  • aBlockID (int, in, opt) – aBlockID Block ID that the event is related to or zero.

  • aChannelIndex (int, in, opt) – aChannelIndex Channel index that the event is related to or 0xFFFF if no stream channel involved.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Use FireEvent( aEventID, aData, aBlockID = 0, aChannelIndex = 0xFFFF) to send an event with data.

Parameters:

  • aEventID (int, in) – Event ID. Use standard event codes or a value between 0x9000 and 0xFFFF for custom events.

  • aData (python bytes object, in) – aData Python bytes object of the data attached to the event.

  • aBlockID (int, in, opt) – aBlockID Block ID that the event is related to or zero.

  • aChannelIndex (int, in, opt) – aChannelIndex Channel index that the event is related to or 0xFFFF if no stream channel involved.

Return type:

PvResult

Returns:

Includes:

IsOpened()

Indicates whether the messaging channel is open.

For the messaging channel to be opened, a GigE Vision controller must be connected to the PvSoftDeviceGEV and must have set the messaging channel destination on the MCDA (0x0B10) and MCP (0x0B00) registers.

Return type:

boolean

Returns:

True if open.

class eBUS.IPvMultiPartContainer(*args, **kwargs)

Bases: IPvMultiPartContainerWriter

Interface to a multi-part container.

Implements both IPvMultiPartContainerReader and IPvMultiPartContainerWriter.

See IPvMultiPartContainerReader for more information on how to access a multi-part buffer as received from a GigE Vision source.

See IPvMultiPartContainerWriter for more information on how to create and populate a multi-part buffer in order to transmit it from a GigE Vision source.

property thisown

The membership flag

class eBUS.IPvMultiPartContainerReader(*args, **kwargs)

Bases: object

Interface used to read from a multi-part container.

To receive and access multi-part data from a GigE Vision device, use a PvStream or PvPipeline to receive buffers and then use PvBuffer::GetMultiPartContainer to retrieve an IPvMultiPartContainerReader or IPvMultiPartContainer interface.

Each part is represented by a multi-part section that can be accessed through an IPvMultiPartSection interface.

Retrieve the section count with GetPartCount and then access the individual sections with the GetPart or operator[] of this interface.

property thisown

The membership flag

GetPartCount()

Part count of the multi-part container.

Return type:

int

Returns:

Part count.

GetPart(*args)

Overload 1:

Indexed part (section) const accessor.

Parameters:

[in] – aIndex Zero-based index of the part.

Return type:

IPvMultiPartSection

Returns:

Returns a const section interface from its index.


Overload 2:

Indexed part (section) accessor.

Parameters:

[in] – aIndex Zero-based index of the part.

Return type:

IPvMultiPartSection

Returns:

Returns a section interface from its index.

class eBUS.IPvMultiPartContainerWriter(*args, **kwargs)

Bases: IPvMultiPartContainerReader

Interface used to write to a multi-part container.

This interface is used to create a multi-part PvBuffer than can be transmitted using PvSoftDeviceGEV.

A multi-part buffer would typically be prepared for transmission by:

  • Creating a PvBuffer by specifying a payload type of PvPayloadTypeMultiPart to the constructor.

  • Retrieving the IPvMultiPartContainerWriter interface using PvBuffer::GetMultiPartContainer.

  • Defining the parts using the #AddImagePart, #AddJPEGPart and #AddChunkPart methods.

  • Allocating/attaching memory using either #AllocAllParts or a mix of #AllocPart and #AttachPart.

  • Filling the part data using IPvMultiPartContainerReader and IPvMultiPartSection.

  • Using the #Validate method to make sure the multi-part container is valid.

  • Transmitting the part from a streaming source of PvSoftDeviceGEV.

Adding parts with this interface only creates the part definition in the part index of the container. Memory then needs to be allocated or attached for all parts. Make sure to call #Validate after defining the parts and allocating or attaching memory to make sure the multi-part container is properly setup.

You can either have no data chunk part of one chunk part and that part needs to be the last part. Use The IPvChunkData interface to the section to define the chunk data and confirm the chunk length using #SetPartFinalLength to confirm the chunk data length.

See SoftGEVDeviceMultiPart C++ eBUS SDK sample for more information.

GigE Vision restricts the maximum part count to 10. This limitation comes from the part index size in the context of the maximum GVSP header size.

property thisown

The membership flag

Reset()

Resets the multi-part container index to empty - no parts.

AddImagePart(aDataType, aWidth, aMaxHeight, aPixelType, aOffsetX=0, aOffsetY=0, aPaddingX=0)

Adds an image part to the index of a multi-part container.

Calling this method only defines a new image in the multi-part container index. Memory needs to be allocated or attached using the AllocAllParts, AllocPart or AttachPart methods.

The height is initially defined as maximum height. It is possible to later call SetPartFinalImageHeight to confirm the effective height of the image, as long as the confirmed height is less or equal to the maximum height defined here. This allows linescan-like scenario where the final height of the image is not known when the image part is defined and its memory allocated or attached.

Parameters:

  • [in] – aDataType Image data type. Must be between PvMultiPart2DImage and PvMultiPartConfidenceMap, inclusive.

  • [in] – aWidth Width of the image, in pixels.

  • [in] – aMaxHeight Height of the image, in pixels.

  • [in] – aPixelType Pixel type of the image.

  • [in] – aOffsetX Offset X of the image, in pixels.

  • [in] – aOffsetY Offset Y of the image, in pixels.

  • [in] – aPaddingX Padding X of the image, in bytes.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • PV_INVALID_PARAMETER aDataType does not represent an image, aWidth is zero or aHeight is zero.

  • PV_NOT_SUPPORTED if the PvBuffer accessed from this interfaced is not defined as a multi-part buffer.

  • PV_ERR_OVERFLOW if the maximum number of parts supported by the GigE Vision specification has already been reached.

  • PV_STATE_ERROR if the previously added part is of type chunk data which is only valid as the last part.

AddJPEGPart(aDataType, aMaxLength, aFlag, aTimestampTickFrequency, aDataFormat)

Adds a JPEG part to the index of a multi-part container.

Calling this method only defines a new JPEG image in the multi-part container index. Memory needs to be allocated or attached using the AllocAllParts, AllocPart or AttachPart methods.

The length is initially defined as maximum length, in bytes. It is possible to later call SetPartFinalLength to confirm the effective length of the compressed image, as long as the confirmed length is less or equal to the maximum length defined here. This allows reserving memory for the worse-case compression scenario and defining the real compressed image length when putting the part together before transmission.

Parameters:

  • [in] – aDataType Multi-part data type. Either PvMultiPartJPEGImage or PvMultiPartJPEG2000Image.

  • [in] – aMaxLength Maximum length for the compressed image. Defined here as worse-case compression, exact size later confirmed with SetPartFinalLength.

  • [in] – aFlag JPEG flags.

  • [in] – aTimestampTickFrequency Timestamp tick frequency. Can be used with JPEG2000 to turn buffer timestamp into real time units.

  • [in] – aDataFormat JPEG data format.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • PV_NOT_SUPPORTED if the PvBuffer accessed from this interfaced is not defined as a multi-part buffer.

  • PV_ERR_OVERFLOW if the maximum number of parts supported by the GigE Vision specification has already been reached.

  • PV_STATE_ERROR if the previously added part is of type chunk data which is only valid as the last part.

AddChunkPart(aMaxLength, aChunkLayoutID)

Adds a chunk data part to the index of a multi-part container.

The chunk data section is always last in a multi-part container. There can only be one chunk data section for a multi-part container. A chunk data section can contain one or more chunks.

Parameters:

  • [in] – aMaxLength Maximum length for chunk data.

  • [in] – aChunkLayoutID Chunk layoud ID for the chunk data.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • PV_NOT_SUPPORTED if the PvBuffer accessed from this interfaced is not defined as a multi-part buffer.

  • PV_ERR_OVERFLOW if the maximum number of parts supported by the GigE Vision specification has already been reached.

  • PV_STATE_ERROR if the previously added part is of type chunk data which is only valid as the last part.

SetPartIDs(aIndex, aSourceID, aDataPurposeID, aRegionID)

Sets the source, data purpose and region IDs of a part.

See IPvMultiPartSection for more information about these IDs.

If this method is not called after adding a part to the multi-part container index, all IDs are zero.

Parameters:

  • aIndex (int) – [in] Zero-based index of the part.

  • aSourceID (int) – [in] Source ID to assign to the part

  • aDataPurposeID (int) – [in] Data purpose ID to assign to the part.

  • aRegionID (int) – [in] Region ID to assign to the part.

Return type:

PvResult

Returns:

Includes:

SetPartZoneInfo(aIndex, aAdditionalZones, aZoneDirectionMask)

Sets the zone info of a part.

See IPvMultiPartSection for more information about zone info.

If this method is not called after adding a part to the multi-part container index, the number of additional zones and direction mask are both set to zero.

Parameters:

  • aIndex (int) – [in] Zero-based index of the part.

  • aAdditionalZones (uint8_t) – [in] Number of additional zones for this part.

  • aZoneDirectionMask (int) – [in] Zone direction of for all zones of this part.

Return type:

PvResult

Returns:

Includes:

AllocAllParts()

Allocates memory for all parts defined by the part index of the multi-part container.

With this method all parts are allocated as a single contiguous memory buffer.

Memory is allocated based on each parts definition: image size is inferred from width, max height, pixel format and padding X. JPEG from the maximum length. Chunk from the maximum chunk length.

If memory was allocated for all parts or individual parts, it is freed before being re-allocated. If memory was attached for any part, it is simply detached.

Return type:

PvResult

Returns:

Includes:

AllocPart(aIndex)

Allocates memory for one of the parts as defined by the index of the part.

If memory has been previously allocated for all parts, new memory for this part alone is allocated and used instead. Unused memory for the part is still reserved in the contiguous buffer.

Memory is allocated based on each parts definition: image size is inferred from width, max height, pixel format and padding X. JPEG from the maximum length. Chunk from the maximum chunk length.

Parameters:

aIndex (int) – [in] Zero-based index of the part.

Return type:

PvResult

Returns:

Includes:

AttachPart(self, aIndex, aBuffer) → PvResult

Attaches a part to an external memory buffer..

Parameters:

  • aIndex (int, in) – Zero-based index of the part.

  • aBuffer (ndarray, in) – A 1-dimensional python numpy array with dtype np.uint8 to use as the external memory buffer.

Return type:

PvResult

Returns:

Includes:

SetPartFinalLength(aIndex, aLength)

Sets the final length of a part.

Used to confirm final length of JPEG and chunk data parts. If this method is not called, the part length is assumed to be the full maximum part length as defined in AddJPEGPart or AddChunkPart.

See AddJPEGPart and AddChunkPart for more information.

Parameters:

  • aIndex (int) – [in] Zero-based index of the part.

  • aLength (int) – [in] aLength Final length of the part.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • PV_INVALID_PARAMETER if aIndex is out of range, aLength is bigger than the maximum part length or the part is an image.

SetPartFinalImageHeight(aIndex, aHeight)

Sets the final height of an image part.

Used to confirm final height of image parts. If this method is not called, the image height is assumed to be the full maximum image height as defined in AddImagePart.

See AddImagePart for more information.

Parameters:

  • aIndex (int) – [in] Zero-based index of the part.

  • aHeight (int) – [in] Final height of the part.

Return type:

PvResult

Returns:

Includes:

  • PV_INVALID_PARAMETER if aIndex is out of range, aHeight is bigger than the maximum height for this part or the part is not an image.

Validate()

Validates the part index and allocated/attached part memory.

This method goes through all parts defined in the part index of this container and makes sure that enough memory is allocated or attached to each individual part. It can also fail if not part has been defined.

Return type:

PvResult

Returns:

Includes:

class eBUS.IPvMultiPartSection(*args, **kwargs)

Bases: object

One section (part) of a multi-part container.

property thisown

The membership flag

GetDataPointer(self) → ndarray

Get the numpy array describing the section’s buffer data.

The GetDataPointer method returns a numpy array describing the buffer data.

Return type:

ndarray

Returns:

A 1-dimensional python numpy array with dtype np.uint8 describing the buffer data.`

GetSize()

Returns the section’s maximum possible data size in bytes.

Return type:

int

Returns:

Maximum possible data size in bytes.

GetEffectiveSize()

Returns the section’s maximum possible data size in bytes.

Return type:

int

Returns:

Maximum possible data size in bytes.

GetDataType()

Returns the data type of the section.

Return type:

int

Returns:

Section data type.

GetImage()

Returns an IPvImage interface to the section.

Returns a point to an IPvImage interface to the section if the section is PvMultiPart2DImage, PvMultiPart2DPlaneOfBiPlanar, PvMultiPart2DPlaneOfTriPlanar, PvMultiPart2DPlaneOfQuadPlanar, PvMultiPart3DImage, PvMultiPart3DPlaneOfBiPlanar, PvMultiPart3DPlaneOfTriPlanar, PvMultiPart3DPlaneOfQuadPlanar or PvMultiPartConfidenceMap.

Return NULL if any other data type.

The returned pointer is owned by the section. The caller must not attempt to free or delete it.

Return type:

IPvImage

Returns:

IPvImage interface to the section.

GetJPEG()

Returns an IPvImageJPEG interface to the section.

Returns a point to an IPvImageJPEG interface to the section if the section is PvMultiPartJPEGImage or PvMultiPartJPEGImage2000.

Return NULL if any other data type.

The returned pointer is owned by the section. The caller must not attempt to free or delete it.

Return type:

IPvImageJPEG

Returns:

IPvImageJPEG interface to the section.

GetChunkData()

Returns an IPvChunkData interface to the section.

Returns a point to an IPvChunkData interface to the section if the section is PvMultiPartChunkData.

Return NULL if any other data type.

The returned pointer is owned by the section. The caller must not attempt to free or delete it.

The chunk data section is always last in a multi-part container.

Return type:

IPvChunkData

Returns:

IPvChunkData interface to the section.

GetSourceID()

Returns the source ID of the section.

The source ID is an integer used to identify data produced by the same source.

See GigE Vision specification for more information on sources in the multi-part context.

Return type:

int

Returns:

Source ID of the section.

GetDataPurposeID()

Returns the data purpose ID of the section.

The data purpose ID is integer used to tag parts having a different purpose. Different color planes would share the same Data Purpose ID, while a 3D data and validity mask parts would use different Data Purpose ID.

See GigE Vision specification for more information on the data purpose ID in the multi-part context.

Return type:

int

Returns:

Data purpose ID of the section.

GetRegionID()

Returns the region ID of the section.

The registion ID is an integer used to tag parts that belong to the same region. This can be used when data from different regions is transmitted in the same block.

See GigE Vision specification for more information on the region ID in the multi-part context.

Return type:

int

Returns:

Region ID of the section.

GetAdditionalZones()

Returns additional zone count of the section.

Reports the number of additional zones in the data part. The number of zones (contiguous bands) is equal to the value of this field plus one (0 indexed value).

See GigE Vision specification for more information on zones in the multi-part context.

Return type:

int

Returns:

Addtional zone count for the section.

GetZoneDirectionMask()

Returns the zone direction mask of the section.

Reports the transmission direction of each zone. bit 0 (msb)
  • Direction of zone 0. Reports the transmission direction of zone ID 0. When set to zero, the zone is

    transmitted top-down (lowest data addresses first). Otherwise, it is transmitted bottom-up (highest data addresses first). bit 1

  • Direction of zone 1. Reports the transmission direction of zone ID 1. When set to zero, the zone is transmitted top-down

    (lowest data addresses first). Otherwise, it is transmitted bottom up (highest data addresses first).

  • …

See GigE Vision specification for more information on zones in the multi-part context.

Return type:

int

Returns:

Zone direction mask of the section.

class eBUS.IPvRegister(*args, **kwargs)

Bases: IPvRegisterInfo

Interface that is used to access the registers of the software-based GigE Vision Device.

This interface is retrieved through the IPvRegisterMap interface and can be used to read from or write to registers. It is also possible to register event sinks to registers using this interface.

This interface cannot be instantiated and there is no use case where you would need to implement this interface.

property thisown

The membership flag

Write(*args)

Overload 1:

Writes an array of bytes to a register.

Parameters:

  • aData (python bytes object, in) – python bytes containing the data to write to the register.

  • aOffset (int, in, optional) – Offset (in bytes) of the write operation in the register.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Writes the register content from a 4-byte unsigned integer.

Convenience method. Works the same as the bytes-array Write but writes from a 4-byte unsigned integer directly.

Parameters:

  • aValue (int, in) – Value to write to the register.

  • aOffset (int, in, optional) – Offset of the write operation in the register.

Return type:

PvResult

Returns:

Includes:


Overload 3:

Writes the register content from a string.

Convenience method. Works the same as the byte-array Write but writes from a string directly.

Parameters:

aValue (str, in) – Value to write to the register.

Return type:

PvResult

Returns:

Includes:

ReadFloat() → PvResult, float

Reads the register content to a 4-byte float.

Convenience method. Works the same as the byte-array Read but reads to a float directly.

Return type:

Tuple(PvResult, float)

Returns:

Tuple composed of (result, floatValue)
  • result representing the outcome:
  • floatValue:

    • Float contents of register.

WriteFloat(aValue)

Writes the register content from a float.

Convenience method. Works the same as the byte-array Write but writes from a float directly.

Parameters:

aValue (float, in) – Value to write to the register.

Return type:

PvResult

Returns:

Includes:

ReadDouble() → PvResult, float

Reads the register content to a double precision floating point.

Convenience method. Works the same as the byte-array Read but reads to a double precision float directly.

Return type:

Tuple(PvResult, float)

Returns:

Tuple composed of (result, floatValue)
  • result representing the outcome:
  • floatValue:

    • Double precision contents of register.

WriteDouble(aValue)

Writes the register content from a double precision floating point.

Convenience method. Works the same as the byte-array Write but writes from a double precision float directly.

Parameters:

aValue (float, in) – Value to write to the register.

Return type:

PvResult

Returns:

Includes:

AddEventSink(aEventSink)

Registers a IPvRegisterEventSink for register callbacks.

See also: IPvRegisterEventSink

Parameters:

aEventSink (IPvRegisterEventSink, in) – Pointer to the event sink.

Return type:

PvResult

Returns:

Includes:

RemoveEventSink(aEventSink)

Removes an event sink registered with AddEventSink.

Parameters:

aEventSink (IPvRegisterEventSink, in) – Pointer to the event sink that is being removed.

Return type:

PvResult

Returns:

Includes:

ReadString() → PvResult, str

Reads the register content to a string.

Convenience method. Works the same as the byte-array Read but reads to a string directly.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, stringValue)
  • result representing the outcome:
  • stringValue:

    • String with the contents of the register.

ReadInt(aOffset=0) → PvResult, int

Reads the register content to a 4-byte unsigned integer.

Convenience method. Works the same as the byte-array Read but reads to a 4-byte unsigned integer directly.

Parameters:

aOffset (int, in ,opt) – Offset (in bytes) of the write operation in the register.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, intValue)
  • result representing the outcome:
  • intValue:

    • 32 bit integer.

ReadBytes(aDataLength, aOffset=0) → PvResult, ndarray

Reads a register to an array of bytes.

Parameters:

  • aDataLength (int, in) – length of the ndarray data to read from the register.

  • aOffset (int, in ,opt) – Offset (in bytes) of the write operation in the register.

Return type:

Tuple(PvResult, ndarray)

Returns:

Tuple composed of (result, BytesValue)
  • result representing the outcome:
  • BytesValue:

    • A 1-dimensional python numpy array with dtype np.uint8 describing the data read.

class eBUS.IPvRegisterEventSink

Bases: object

Interface that is used to report the register activity of the software-based GigE Vision Device.

To receive register access callbacks, inherit one of your classes from IPvRegisterEventSink and pass a pointer to an object of that class to IPvRegister.AddEventSink for the register that you want to get callbacks from.

It is possible to have more than one event sink registered for callbacks to the same register. It is possible (and can be convenient) to use the same event sink for more than one register. When an event sink is used for more than one register, all IPvRegisterEventSink callbacks will have the register of interest provided as the first parameter, to provide contextual differentiation.

property thisown

The membership flag

PreRead(aRegister)

Pre-read register notification.

This notification is invoked before a register read operation on the PvSoftDeviceGEV. The notification handler is a good place to update the content of the register with dynamic information.

As an example, the PvSoftDeviceGEV uses this notification to update the timestamp register every time it is read.

Returning an error from this notification will cause the read operation to fail up to where it was initiated, which could be from an internal IPvRegister read operation or from a READREG_CMD or READMEM_CMD GVCP remote operation.

Parameters:

aRegister (IPvRegister, in) – Register to which the notification applies.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • Any PvResult error code on failure.

PostRead(aRegister)

Post-read register notification.

This notification is invoked after a register read operation on the PvSoftDeviceGEV.

Parameters:

aRegister (IPvRegister, in) – Register to which the notification applies.

PreWrite(aRegister)

Pre-write register notification.

This notification is invoked before a register write operation on the PvSoftDeviceGEV. The notification handler is a good place to validate a new value before it is committed to the register.

On receiving this notification, the value of the register can be retrieved using the IPvRegister interface. On failure, the register will revert back to its original value.

Returning an error from this notification will cause the write operation to fail up to where it was initiated, which could be from an internal IPvRegister write operation or from a WRITEREG_CMD or WRITEMEM_CMD GVCP remote operation.

We recommend that you do not react to new register values in this notification handler. It is possible that other event sinks for the register could refuse the write, which will result in the operation failing and will cause the register to revert back to its original value. Use the #PostWrite notification instead.

Parameters:

aRegister (IPvRegister, in) – Register to which the notification applies.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • Any PvResult error code on failure.

PostWrite(aRegister)

Post-write register notification.

This notification is invoked after a register write operation on the PvSoftDeviceGEV. It can be used to react to the value of a register being changed.

As an example, PvSoftDeviceGEV uses this notification internally to open or close the streaming channel on SCDA or SCP changes.

Parameters:

aRegister (IPvRegister, in) – Register to which the notification applies.

Persist(aRegister, aStore)

Peristence request for selected registers for user-sets.

This interface callback is invoked when saving to or loading from registers in the context of user-sets.

Most registers can be saved to device user-sets by only setting the Streamable attribute of their attached GenApi feature when creating the GenICam XML file.

Some registers have GenApi selector(s) and thus contain more than one value. These registers need to be “walked” through all possible selector(s) values when persisted. Here the word “persisted” is used for both Save and Load use-cases.

These registers must implement this Persist method and call IPvRegisterStore.Persist for each possible selector(s) combination.

See also: IPvSoftDeviceGEV.SetUserSetCount

Parameters:
Return type:

PvResult

Returns:

Includes:

  • PV_OK if the method successfully handled persistence for the register.

  • PV_NOT_IMPLEMENTED if the register does not need advanced persistence. Returned by default implementation.

  • Any other PvResult error code on failure.

class eBUS.IPvRegisterFactory(*args, **kwargs)

Bases: object

Class used for register creation.

The #AddRegister method can be used to add customer registers to the PvSoftDeviceGEV. Note however that custom registers can only be added from the IPvSoftDeviceGEVEventSink.OnCreateCustomRegisters notification. A pointer to this register factory interface is provided with the notification.

property thisown

The membership flag

AddRegister(aName, aAddress, aLength, aAccessMode, aRegisterEventSink=None, aContext=None)

Adds a new register (Integer, Float) to the PvSoftDeviceGEV register map.

Parameters:

  • aName (str, in) – The name of the new register to create.

  • aAddress (int, in) – The address for the new register. It must be unique and must not overlap previously-allocated register space.

  • aLength (int, in) – Register length, in bytes. Must be 4 or 8.

  • aAccessMode (int, in) – Access mode of the register: PvGenAccessModeReadOnly, PvGenAccessModeReadWrite, or PvGenAccessModeWriteOnly.

  • aRegisterEventSink (IPvRegisterEventSink, in, optional) – An optional event sink to register on creation.

  • aContext (void, in, optional) – A contextual pointer that is specific to the register. It can be retrieved using IPvRegisterInfo.GetContext.

Return type:

PvResult

Returns:

Includes:

AddByteArray(aName, aAddress, aLength, aAccessMode, aRegisterEventSink=None, aContext=None)

Adds a new array of bytes (String, Register) to the PvSoftDeviceGEV register map.

Parameters:

  • aName (str, in) – The name of the new register to create.

  • aAddress (int, in) – The address for the new register. It must be unique and must not overlap previously-allocated register space.

  • aLength (int, in) – Register length, in bytes. Must be divisible by 4.

  • aAccessMode (int, in) – Access mode of the register: PvGenAccessModeReadOnly, PvGenAccessModeReadWrite, or PvGenAccessModeWriteOnly.

  • aRegisterEventSink (IPvRegisterEventSink, in, optional) – An optional event sink to register on creation.

  • aContext (void, in, optional) – A contextual pointer that is specific to the register. It can be retrieved using IPvRegisterInfo.GetContext.

Return type:

PvResult

Returns:

Includes:

class eBUS.IPvRegisterInfo(*args, **kwargs)

Bases: object

Interface to access basic information about a PvSoftDeviceGEV register.

This interface can be used to query basic information about a register.

This class cannot be instantiated and there is no use case where you would need to implement this interface.

property thisown

The membership flag

GetName()

Returns the register name.

All PvSoftDeviceGEV registers are named. This method allows the user to retrieve this name.

The GigE Vision standard does not require that you name your registers. The name is used internally to provide contextual information about the register in logs or user interfaces.

Return type:

str

Returns:

Register name.

GetAddress()

Returns the register address.

Return type:

int

Returns:

Register address.

GetLength()

Returns the length of the register, in bytes.

Return type:

int

Returns:

Register length.

GetContext(*args)

Overload 1:

Returns the contextual pointer provided at register creation.

Return type:

void

Returns:

Const contextual pointer.


Overload 2:

Returns the contextual pointer provided at register creation.

Return type:

void

Returns:

Contextual pointer.

IsWritable()

Indicates whether the register is writable.

Whether the register is writable (or not) is only enforced when the register is accessed from the GigE Vision controller.

Using the internal APIs it is possible to write to read-only registers. However, take care when doing so: If you do not fully control the custom register, it could cause issues (and is not recommended).

Return type:

boolean

Returns:

True if the register is writable.

IsReadable()

Indicates whether the register is readable.

Return type:

boolean

Returns:

True if the register is readable.

IsArrayOfBytes()

Indicates whether the register is an array of bytes or plain data type.

Return type:

boolean

Returns:

True if the register is array of bytes.

class eBUS.IPvRegisterMap(*args, **kwargs)

Bases: object

Register map interface for a software-based GigE Vision Device.

The interface to the PvSoftDeviceGEV register map can be retrieved using IPvSoftDeviceGEV.GetRegisterMap any time after the device has been started.

This interface can be used to browse the register map using the #GetRegisterCount and #GetRegisterByIndex methods. If you know the address of the register that you are looking for, you can access it directly with #GetRegisterByAddress.

property thisown

The membership flag

GetRegisterCount()

Obtains a count of how many registers are in the PvSoftDeviceGEV register map.

Typically used to enumerate all registers. Call #GetRegisterByIndex with aIndex iterating from 0 to #GetRegisterCount - 1, inclusively.

Return type:

int

Returns:

Register count.

GetRegisterByIndex(aIndex)

Obtains a register from the register map based on the register’s index.

Parameters:

aIndex (int, in) – 0-based index.

Return type:

IPvRegister

Returns:

Register interface or NULL on failure.

GetRegisterByAddress(aAddress)

Obtains a register from the register map based on the register’s address.

Parameters:

aAddress (int, in) – Register address.

Return type:

IPvRegister

Returns:

Register interface or NULL on failure.

Lock(*args)

Overload 1:

Locks the register map for safe register access.

We recommend that you lock the register map before accessing the registers using the IPvRegisterMap interface. The lock should not be held for longer than necessary and should be released as soon as possible.

Failure to lock the register map before accessing its content could mean that an IPvRegister obtained through #GetRegisterByIndex or #GetRegisterByAddress could be deleted while using it in parallel with a PvSoftDeviceGEV reset.

Locking the register map prevents register map additions or removals while it is being accessed. However, it does not prevent register access, which can safely occur in parallel, because each individual register is thread-safe on read/write operations.

It is very important that you call Release after a #Lock() success. Failure to do so will likely result in a PvSoftDeviceGEV deadlock on reset or shutdown.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Locks the register map for safe register access but fails on timeout.

See #Lock() for more information.

Parameters:

aTimeout (int, in) – Timeout, in ms, to wait for the lock.

Return type:

PvResult

Returns:

Includes:

Release()

Releases a lock acquired with #Lock.

Not calling this method after calling #Lock will most likely result in a PvSoftDeviceGEV deadlock on reset or shutdown.

class eBUS.IPvRegisterStore(*args, **kwargs)

Bases: object

Class used with register persistence in the context of user-sets.

The register store is where user-set data is stored. On Windows it is the Registry, on Linux user-profile files in the home directory. On embedded applications it could also be any static storage like flash memory.

See also: IPvRegisterEventSink.Persist See also: IPvSoftDeviceGEV.SetUserSetCount

property thisown

The membership flag

Persist(aRegister, aNameSuffix)

Persists a register to the register store using a name suffix.

Use this method from the IPvRegisterEventSink::Persist callback when walking registers through all possible selector(s) values. This method saves data to the store when saving a user-set and loads data from the store when loading a user-set.

See also: IPvRegisterEventSink.Persist See also: IPvSoftDeviceGEV.SetUserSetCount

Parameters:

  • aRegister (IPvRegister, in) – Register to save to or load from the store.

  • aNameSuffix (str, in) – Name suffix to use when saving to or loading from the store.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • Any other error code on failure.

class eBUS.IPvSoftDeviceGEV(*args, **kwargs)

Bases: object

Interface to the main class of the software-based GigE Vision Device.

property thisown

The membership flag

AddStream(aSource)

Adds a new stream to the PvSoftDeviceGEV.

All streams must be added before starting the PvSoftDeviceGEV.

Parameters:

aSource (IPvStreamingChannelSource, in) – Interface to a user-provided source.

Return type:

PvResult

Returns:

Includes:

SetUserSetCount(aCount)

Sets the number of user-sets supported by the PvSoftDeviceGEV.

The maximum supported user-set count is 256.

Can only be changed before starting the device.

User-sets are all about device-side persistence. The status of the device can be saved or retrieved from some static store on the device. User-sets are first and foremost managed at the register level. The SFNC allowing defines the UserSetFeatureSelector which is populated with feature names. This creates an imperfect but mostly acceptable one-to-one link between Streamable (persistent) GenApi features and the register providing its implementation.

Features marked as Streamable (persistent) when creating the GenICam XML file of the device are used for device-side persistence through user-sets.

Persistent features have the content of the register they directly map to saved to the persistent store of the device. The persistent store is implemented through the Registry on Windows and profile home files on Linux. Hardware implementations could rely on Flash memory to store user-sets.

Most registers are simply persisted as-is: their binary content is simply saved to or loaded from the store.

Some registers have only one address but can contain many values when indexed through device-managed selectors. If those registers are Streamable (persistent) the application must handle the IPvRegisterEventSink::Persist event for the registers and for each possible selector combination call IPvRegisterStore.Persist. For the application the same code is used for both save and load operations, thus the generic “persist” naming.

The SoftDeviceGEV sample shows basic use of user-sets.

Conditional comment: The SoftDeviceGEV3d sample shows how to handle complex multi-selector registers in the context of user-sets. End of conditional comment.

Selected registers handling in pseudo-code:

  • Save current selector of interest values

  • Set selectors to 1st combination

  • Call IPvRegisterStore.Persist with register and unique name suffix representing selector of interest values

  • Set selectors to 2nd combination

  • Call IPvRegisterStore.Persist with register and unique name suffix representing selector of interest values

  • …

  • Restore selector values

The IPvRegisterStore.Persist method loads or saves the register content in the store using the feature name and provided suffix.

On startup the default user-set is always updated in the store from the fresh device status. If the UserSetDefault GenApi feature is assigned to a user-set other than Default, the user-set is automatically loaded on device startup.

The UserSetDefault GenApi feature is special: it is not saved to a user-set but is immediately and automatically persistent to the store whenever changed.

User-sets can be saved and loaded explicitly using the UserSetSelector, UserSetSave, and UserSetLoad GenApi features.

The UserSetFeatureSelector and UserSetFeatureEnable GenApi features can be used to control which features are saved to the user-sets. All features defined as Streamable when creating the GenICam XML file of the device should be available under the UserSetFeatureSelector enum feature.

Parameters:

aCount (int, in) – Count of user-sets supported, in addition to the default user-set.

Return type:

PvResult

Returns:

Includes:

SetUserSetNotify(aUserSetNotify)
Binds in a class which will contain a callback which will be called when the

state of a UsersetLoad/Save changes.

Return type:

PvResult

Returns:

Includes

SetTCPTransportEnabled(aEnabled)

Enables experimental TCP transport.

PvSoftDeviceGEV supports optional, experimental TCP transport for GigE Vision devices. It affects GVCP control, GVCP messaging channel and GVSP streaming.

When TCP is enabled the device still respond to UDP requests as usual. Additional TCP sockets are opened to optionally accept TCP connections from the host.

As long as TCP is not fully ratified by the GigE Vision specification, enabling TCP could and most likely will break GigE Vision compliance. It also means only the eBUS PvDeviceGEV and PvStreamGEV can be used to interact with the device when using TCP transport.

Parameters:

aEnabled (boolean, in) – Toggles TCP support.

Return type:

PvResult

Returns:

PV_OK

SetRTPProtocolEnabled(aEnabled)

Enables the option of using RTP for streaming.

PvSoftDeviceGEV supports optional RTP protocol for GigE Vision devices.

When RTP is enabled it can be selected as the protocol used to data transmission at the stream channel level of the GenApi interface of the device.

RTP supported is not covered by the GigE Vision specification. A GigE Vision Device actively streaming using RTP goes beyond the bounds covered by the GigE Vision standard.

The RTP implementation is however compliant with the RTP RFCs covering the transport of images (RFC 4175) and H.264 data (RFC 6184).

When a stream transmits using the RTP protocol, the stream is announced on a multicast channel (224.2.127.254:9875) using the SAP protocol with a SDP descriptor as required by the DEFSTAN 0082 specification.

Parameters:

aEnabled (boolean, in) – Toggles RTP support.

Return type:

PvResult

Returns:

PV_OK

SetActionHandler(aActionHandler)
Return type:

PvResult

Returns:

PvResult.

RegisterEventSink(aEventSink)

Registers an event sink to receive notifications from the PvSoftDeviceGEV.

This method can be called before the PvSoftDeviceGEV is started.

See also: IPvVirtualDeviceEventSink

Parameters:

aEventSink (IPvSoftDeviceGEVEventSink, in) – Pointer to a PvSoftDeviceGEV event sink.

Return type:

PvResult

Returns:

Includes:

UnregisterEventSink(aEventSink)

Unregisters a previously registered event sink.

This method can be called before the PvSoftDeviceGEV is started and after it has been stopped.

Parameters:

aEventSink (IPvSoftDeviceGEVEventSink, in) – Pointer to a PvSoftDeviceGEV event sink.

Return type:

PvResult

Returns:

Includes:

Start(aIpAddress)

Starts the PvSoftDeviceGEV.

Both GVCP and GVSP are operated from a background thread. Even though the Start method returns, the device is running in your process until you call Stop or until the object is destroyed.

Parameters:

aMACAddress – MAC address of the interface to bind the PvSoftDeviceGEV to.

Return type:

PvResult

Returns:

Includes:

Stop()

Stops the PvSoftDeviceGEV.

Return type:

PvResult

Returns:

Includes:

GetInfo()

Obtains the information interface of the PvSoftDeviceGEV.

Only available after the PvSoftDeviceGEV has been started.

IPvSoftDeviceGEVInfo is used to set the information strings in the read-only bootstrap registers of the PvSoftDeviceGEV, such as Model Name, Vendor Name, etc.

Return type:

IPvSoftDeviceGEVInfo

Returns:

Information interface of the PvSoftDeviceGEV or NULL if the device is not running.

GetRegisterMap()

Obtains the register map interface of the PvSoftDeviceGEV.

Only available after the PvSoftDeviceGEV has been started.

IPvRegisterMap can be used to directly access the register map of the PvSoftDeviceGEV. It is also possible to subscribe to register read/write events using IPvSoftDeviceGEVEventSink.

See IPvSoftDeviceGEVEventSink.OnCreateCustomRegisters for information about adding custom registers to a PvSoftDeviceGEV.

Return type:

IPvRegisterMap

Returns:

Register map interface of the PvSoftDeviceGEV or NULL if the device is not running.

GetStatistics()

Obtains the statistics interface of the PvSoftDeviceGEV.

Only available after the PvSoftDeviceGEV has been started.

Return type:

IPvSoftDeviceGEVStatistics

Returns:

Statistics interface of the PvSoftDeviceGEV or NULL if the device is not running.

GetMessagingChannel()

Obtains the messaging channel interface of the PvSoftDeviceGEV.

The IPvMessageChannel interface can be used to send events on the messaging channel when a GigE Vision controller is connected to the PvSoftDeviceGEV and has properly set up a destination for messaging channel events.

See also: IPvMessageChannel

Only available after the PvSoftDeviceGEV has been started.

Return type:

IPvMessageChannel

Returns:

Messaging channel interface of the PvSoftDeviceGEV or NULL if the device is not running.

GetGenICamXMLFile() → PvResult, str

Returns the GenICam XML file of the device.

Can be used to retrieve the GenICam XML file of the device after the Start method has been called.

Can be used on success or failure of the Start method.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, xmlFile)
  • result representing the outcome:

    • PV_OK

    • STATE_ERROR if the GenICam XML file is not available (likely Start has not been called yet)

  • xmlFile:

    • String where the XML file is copied.

class eBUS.IPvSoftDeviceGEVEventSink

Bases: object

Interface that is used by PvSoftDeviceGEV to report internal events.

To receive these events, inherit one of your classes from IPvSoftDeviceGEVEventSink, instantiate an object from your class, and pass a pointer to this event sink to PvSoftDeviceGEV.RegisterEventSink.

When the events occur, the corresponding method in your class will be invoked. The events are usually invoked from a different thread, other than the main application thread.

It is possible to use this callback interface to create device-scope and GenApi parameters. See IPvSoftDeviceGEVEventSink.OnCreateCustomGenApiFeatures and IPvSoftDeviceGEVEventSink.OnCreateCustomRegisters for more information. You should create streaming channel source GenApi feature and registers for source-specific features like deinterlacing, gain, exposure time. Look at IPvStreamingChannelSource.CreateRegisters and IPvStreamingChannelSource.CreateGenApiFeatures to create streaming channel source scope features. Note that chunks and messaging channel GenApi parameters should always be created from IPvSoftDeviceGEVEventSink and be at the device-scope.

property thisown

The membership flag

OnApplicationConnect(aDevice, aIPAddress, aPort, aAccessType)

Notification that a GigE Vision controller has taken ownership of the control channel of your PvSoftDeviceGEV.

Parameters:

  • aDevice (IPvSoftDeviceGEV, in) – Pointer to the PvSoftDeviceGEV object that is sending the notification.

  • aIPAddress (str, in) – IP address of the GigE Vision controller in string format, such as “192.168.138.115”.

  • aPort (int, in) – UDP port of the GigE Vision controller.

  • aAccessType (int, in) – Access type secured by the GigE Vision controller.

OnControlChannelStart(aDevice, aMACAddress, aIPAddress, aMask, aGateway, aPort)

Notification that the control channel of the PvSoftDeviceGEV has been started.

The control channel is the GVCP command server of the PvSoftDeviceGEV.

Parameters:

  • aDevice (IPvSoftDeviceGEV, in) – Pointer to the PvSoftDeviceGEV object that is sending the notification.

  • aMACAddress (str, in) – MAC address of the local network interface.

  • aIPAddress (str, in) – IP address that the control channel is bound to.

  • aMask (str, in) – Subnet mask of the IP address that the control channel is bound to.

  • aGateway (str, in) – Default gateway of the network interface that is used by the control channel.

  • aPort (int, in) – UDP port that the control channel is listening to. Hardcode this value to GigE Vision standard 3956.

OnApplicationDisconnect(aDevice)

Notification that the GigE Vision controller has released the control channel of the PvSoftDeviceGEV.

The notification can be triggered if the control channel has been released by the PvSoftDeviceGEV on a heartbeat refresh failure.

Parameters:

aDevice (IPvSoftDeviceGEV, in) – Pointer to the PvSoftDeviceGEV object that is sending the notification.

OnControlChannelStop(aDevice)

Notification that the control channel of the PvSoftDeviceGEV has been stopped.

The control channel is the GVCP command server of the PvSoftDeviceGEV.

Parameters:

aDevice (IPvSoftDeviceGEV, in) – Pointer to the PvSoftDeviceGEV object that is sending the notification.

OnDeviceResetFull(aDevice)

Notification that the PvSoftDeviceGEV has performed a full reset.

A full reset is the equivalent of a power cycle.

Parameters:

aDevice (IPvSoftDeviceGEV, in) – Pointer to the PvSoftDeviceGEV object that is sending the notification.

OnDeviceResetNetwork(aDevice)

Notification that the PvSoftDeviceGEV has reset its network stack.

A PvSoftDeviceGEV network reset usually happens after it has received a FORCEIP_CMD command.

Parameters:

aDevice (IPvSoftDeviceGEV, in) – Pointer to the PvSoftDeviceGEV object that is sending the notification.

OnCreateCustomRegisters(aDevice, aFactory)

Notification that the PvSoftDeviceGEV should create its custom registers, if they are needed.

Register creation must happen at a specific point in the PvSoftDeviceGEV initialization. To create custom registers in your application, implement the IPvSoftDeviceGEVEventSink interface, register an object of this class to PvSoftDeviceGEV.RegisterEventSink, and perform custom register creation in the IPvSoftDeviceGEVEventSink.OnCreateCustomRegisters notification.

Custom register creation occurs BEFORE the creation of custom GenApi features, inside the PvSoftDeviceGEV.Start call.

Parameters:
OnCreateCustomGenApiFeatures(aDevice, aFactory)

Notification that the PvSoftDeviceGEV should create its custom GenApi parameters, if they are needed.

GenApi feature creation must happen at a specific point in the PvSoftDeviceGEV initialization. To create custom GenApi features in your application, implement the IPvSoftDeviceGEVEventSink interface, register an object of this class to PvSoftDeviceGEV.RegisterEventSink, and perform custom GenApi feature creation in the IPvSoftDeviceGEVEventSink.OnCreateCustomGenApiFeatures notification.

Custom GenApi feature creation occurs AFTER the creation of custom registers, inside the PvSoftDeviceGEV.Start call.

Parameters:
class eBUS.IPvSoftDeviceGEVInfo(*args, **kwargs)

Bases: object

Interface that is used to customize the identity of a software-based GigE Vision Device.

Can be retrieved from a PvSoftDeviceGEV to access device identity strings and GenICam XML version and GUIDs.

The device identity strings can be set before or after calling PvSoftDeviceGEV.Start. However, the GenICam XML version and GUIDs must be set before calling PvSoftDeviceGEV.Start.

Setting the GenICam XML version and GUIDs is recommended but not always required. Some non-Pleora software applications will use this information to manage the cached versions of the GenICam XML file and will not download a newer XML file from the device if the GenICam XML version GUID and/or version do not change.

The recommended practice is to always update the GenICam XML GUID and version when releasing a new version of your GigE Vision Device. We also recommend that all of your GigE Vision Device products use a different GenICam XML Product GUID.

Set your GenICam XML version with #SetGenICamXMLVersion.

Set your GenICam XML GUIDs with #SetGenICamXMLGUIDs.

This class cannot be instantiated and there is no use case where you would need to implement this interface.

property thisown

The membership flag

GetManufacturerName()

Returns the current manufacturer name.

Maps to GigE Vision 0x0048 bootstrap register: 32 bytes, read-only.

Return type:

str

Returns:

Manufacturer name string.

GetModelName()

Returns the current model name.

Maps to GigE Vision 0x0068 bootstrap register: 32 bytes, read-only.

Return type:

str

Returns:

Model name string.

GetDeviceVersion()

Returns the current PvSoftDeviceGEV version string.

Maps to GigE Vision 0x0088 bootstrap register: 32 bytes, read-only.

Return type:

str

Returns:

PvSoftDeviceGEV version string.

GetDeviceFirmwareVersion()

Returns the current PvSoftDeviceGEV firmware version string.

Maps to GigE Vision 0x3FFF0100 bootstrap register: 32 bytes, read-only.

Return type:

str

Returns:

PvSoftDeviceGEV firmware version string.

GetManufacturerInformation()

Returns the current manufacturer information string.

Maps to GigE Vision 0x00A8 bootstrap register: 32 bytes, read-only.

Return type:

str

Returns:

Manufacturer information string.

GetSerialNumber()

Returns the current serial number string.

Maps to GigE Vision 0x00D8 bootstrap register: 16 bytes, read-only.

Return type:

str

Returns:

Serial number string.

SetManufacturerName(aValue)

Updates the manufacturer name string.

Maps to GigE Vision 0x0048 bootstrap register: 32 bytes, read-only.

Parameters:

aValue (str, in) – New manufacturer name, maximum 31 characters (31 + NULL).

Return type:

PvResult

Returns:

Includes:

SetModelName(aValue)

Updates the model name string.

Maps to GigE Vision 0x0068 bootstrap register: 32 bytes, read-only.

Parameters:

aValue (str, in) – New model name, maximum 31 characters (31 + NULL for 32 bytes).

Return type:

PvResult

Returns:

Includes:

SetDeviceVersion(aValue)

Updates the device version string.

Maps to GigE Vision 0x0088 bootstrap register: 32 bytes, read-only.

Parameters:

aValue (str, in) – New device version, maximum 31 characters (31 + NULL for 32 bytes).

Return type:

PvResult

Returns:

Includes:

SetDeviceFirmwareVersion(aValue)

Updates the device firmware version string.

Maps to GigE Vision 0x3FFF0100 bootstrap register: 32 bytes, read-only.

Parameters:

aValue (str, in) – New device version, maximum 31 characters (31 + NULL for 32 bytes).

Return type:

PvResult

Returns:

Includes:

SetManufacturerInformation(aValue)

Updates the manufacturer information string.

Maps to GigE Vision 0x00A8 bootstrap register: 48 bytes, read-only.

If the PvSoftDeviceGEV is running without a valid license, the manufacturer information is overridden to provide a warning that indicates that the device is unlicensed.

Parameters:

aValue (str, in) – New device version, maximum 47 characters (47 + NULL for 48 bytes).

Return type:

PvResult

Returns:

Includes:

SetSerialNumber(aValue)

Updates the serial number string.

Maps to GigE Vision 0x00D8 bootstrap register: 16 bytes, read-only.

Parameters:

aValue (str, in) – New serial number, maximum 15 characters (15 + NULL for 16 bytes).

Return type:

PvResult

Returns:

Includes:

GetGenICamXMLVersionMajor()

Returns the GenICam XML file major version.

See #SetGenICamXMLVersion for more information.

Return type:

int

Returns:

Major version.

GetGenICamXMLVersionMinor()

Returns the GenICam XML file minor version.

See #SetGenICamXMLVersion for more information.

Return type:

int

Returns:

Minor version.

GetGenICamXMLVersionSubMinor()

Returns the GenICam XML file subminor version.

See #SetGenICamXMLVersion for more information.

Return type:

int

Returns:

Subminor version.

GetGenICamXMLProductGUID()

Returns the GenICam XML file Product GUID.

See #SetGenICamXMLGUIDs for more information.

Return type:

str

Returns:

Product GUID.

GetGenICamXMLVersionGUID()

Returns the GenICam XML file Version GUID.

See #SetGenICamXMLGUIDs for more information.

Return type:

str

Returns:

Version GUID.

GetGenICamXMLRegDescModelName()

Returns the GenICam XML Register Description model name.

See #SetGenICamXMLRegDescModelName for more information.

Return type:

str

Returns:

XML Register Description Model Name

GetGenICamXMLRegDescVendorName()

Returns the GenICam XML Register Description vendor name.

See #SetGenICamXMLRegDescVendorName for more information.

Return type:

str

Returns:

XML Register Description Vendor Name

SetGenICamXMLVersion(aMajor, aMinor, aSubMinor)

Sets the GenICam XML file version.

See the IPvSoftDeviceGEVInfo class description for usage and recommendations.

Parameters:

  • aMajor (int, in) – Major version for GenICam XML file header.

  • aMinor (int, in) – Minor version for GenICam XML file header.

  • aSubMinor (int, in) – Subminor version for GenICam XML file header.

Return type:

PvResult

Returns:

Includes:

SetGenICamXMLGUIDs(aProduct, aVersion)

Sets the GenICam XML file version.

A GUID (globally unique identifier) is a 128-bit number that is used to identify information in computer systems. The term UUID (universally unique identifier) can also be used.

Valid GUID example: CB9328DB-1273-42A3-90C7-EB3224537C39

You can generate unique GUIDs using the Create GUID tool in Visual Studio, which can be accessed from the Visual Studio Tools menu. It uses the system unique MAC address and date/time components to ensure uniqueness.

See the IPvSoftDeviceGEVInfo class description for usage and recommendations.

Parameters:

  • aProduct (str, in) – Product GUID for GenICam XML file header.

  • aVersion (str, in) – Version GUID for GenICam XML file header.

Return type:

PvResult

Returns:

Includes:

SetGenICamXMLRegDescModelName(aModelName)

Set the GenICam XML register description model name.

Sets the model name attribute of the RegisterDescription in the device XML file If not called GenICamXML register description model name will be the same as the device model name.

Parameters:

aModelName (str, in) – GenICam XML register description model name, maximum 31 characters (31 + NULL for 32 bytes).

Return type:

PvResult

Returns:

Includes:

SetGenICamXMLRegDescVendorName(aVendorName)

Set the GenICam XML register description vendor name.

Sets the vendor name attribute of the RegisterDescription in the device XML file If not called GenICamXML register description vendor name will be the same as the device manufacturer name.

Parameters:

aModelName – GenICam XML register description vendor name, maximum 31 characters (31 + NULL for 32 bytes).

Return type:

PvResult

Returns:

Includes:

class eBUS.IPvSoftDeviceGEVStatistics(*args, **kwargs)

Bases: object

Interface that is used to retrieve control channel statistics from a software-based GigE Vision Device.

Can be retrieved from a properly initialized PvSoftDeviceGEV to access the statistics provided by this interface.

This class cannot be instantiated and there is no use case where you would need to implement this interface.

property thisown

The membership flag

Reset()

Resets all counters to zero.

GetReadMemsReceived()

GVCP read memory (READMEM_CMD) commands received.

Return type:

int

Returns:

Read memory command count.

GetWriteMemsReceived()

GVCP write memory (WRITEMEM_CMD) commands received.

Return type:

int

Returns:

Write memory command count.

GetReadRegsReceived()

GVCP read register (READREG_CMD) commands received.

Return type:

int

Returns:

Read register command count.

GetWriteRegsReceived()

GVCP write register (WRITEREG_CMD) commands received.

Return type:

int

Returns:

Write register command count.

GetDiscoveriesReceived()

GVCP discovery (DISCOVERY_CMD) commands received.

Return type:

int

Returns:

Discovery command count.

GetActionCommandsReceived()

GVCP action command (ACTION_CMD) received.

Return type:

int

Returns:

Action command count.

GetForceIpsReceived()

GVCP force IP configuration (FORCEIP_CMD) commands received.

Return type:

int

Returns:

Force IP configuration command count.

GetPacketResendRequestsReceived()

GVCP packet resend (PACKETRESEND_CMD) commands received.

Return type:

int

Returns:

Packet resend command count.

GetPendingAcksIssued()

GVCP pending acknowledges (PENDING_ACK) issued.

Return type:

int

Returns:

Pending acknowledges count.

GetRetriesReceived()

GVCP command retries received.

Return type:

int

Returns:

Command retries count.

GetRetriesReceivedMax()

GVCP command retries maximum for a single command.

Return type:

int

Returns:

Command retries maximum count.

GetEventsIssued()

GVCP messaging channel event commands (EVENT_CMD) issued.

Return type:

int

Returns:

Messaging channel event count.

GetEventDatasIssued()

GVCP messaging channel event (with data) comands (EVENTDATA_CMD) issued.

Return type:

int

Returns:

Messaging channel event (with data) count.

GetEventRetriesIssued()

GVCP retries issued for unacknowledged messaging channel event or event data commands.

Return type:

int

Returns:

Messaging channel event retries count.

GetEventRetriesIssuedMax()
Return type:

int

Returns:

GVCP maximum retries issued for a single unacknowledged messaging channel event or event data command.

Return type:

int

Returns:

Messaging channel event retries maximum count.

GetSessionsOpened()

Returns the device controller session open count.

Return type:

int

Returns:

Session open count.

GetSessionsClosed()

Returns the device controller session close count.

Return type:

int

Returns:

Session close count.

GetHeartbeatFailedCount()

Returns the device controller session close on heartbeat failure count.

Return type:

int

Returns:

Session close on heartbeat failure count.

GetGVSPTestPacketsIssued()

Returns the number of GVSP test packets issued.

Return type:

int

Returns:

GVSP test packets count.

class eBUS.IPvStreamingChannelSource

Bases: object

Interface that is used by PvSoftDeviceGEV to query and report information from a streaming source implemented by your application.

For the application to provide a streaming source to your software-based GigE Vision Device, inherit one of your classes from IPvStreamingChannelSource, implement all of the methods, instantiate an object from your class, and pass a pointer to your class to PvSoftDeviceGEV.AddStream.

The GigE Vision Device will use this interface to query the application about stream capabilities and to report streaming events, such as acquisition start and stop. The GigE Vision Device also uses this interface to manage streaming data.

To properly report the PayloadSize GenApi parameter, your application must provide the GigE Vision Device with the width, height, pixel format, and data chunk size values using the GetWidth, GetHeight, GetPixelFormat, and GetChunksSize methods.

You can hardcode the supported chunk size by returning the required chunk size using GetChunksSize. You could also provide more information about the supported chunk types using GetSupportedChunk. Doing so will allow the GigE Vision Device to properly populate the ChunkSelector of its GenApi interface to let the user decide which chunks it should support. The streaming source should decide whether or not to append a specific chunk type by looking at whether the master chunk active mode is enabled AND that the specific chunk type is enabled.

It is possible to create streaming channel source custom registers and GenApi parameters. See IPvStreamingChannelSource.CreateGenApiFeatures and IPvStreamingChannelSource.CreateRegisters for more information. You should create streaming channel source GenApi feature and registers for source-specific features like deinterlacing, gain, exposure time. Look at IPvSoftDeviceGEVEventSink.OnCreateCustomRegisters and IPvSoftDeviceGEVEventSink.OnCreateCustomGenApiFeatures to create device-scope features. Note that chunks and messaging channel GenApi parameters should always be created from IPvSoftDeviceGEVEventSink and be at the device-scope.

Here is what a typical streaming session would look like when it comes to buffer management:

  • A PvSoftDeviceGEV object is instantiated by your application

  • A MySource object that implements the IPvStreamingChannelSource interface is instantiated by your application

  • PvSoftDeviceGEV.AddStream is called by your application with a pointer to MySource

  • PvSoftDeviceGEV.Start is called by your application

    • #AllocBuffer is called to allow your application to allocate streaming buffers until NULL is returned or the maximum number of buffers is reached

    • #GetWidthInfo, #GetHeightInfo, and #GetSupportedPixelType are called on MySource to inquire about the image attributes supported by MySource

    • #OnOpen is called on MySource when the streaming channel is opened (when a GigE Vision controller connects to your GigE Vision Device)
      • #OnStreamingStart is called on MySource to notify the application that streaming is starting (when the GigE Vision controller calls AcquisitionStart)
        • Internal acquisition loop run from a GigE Vision Device thread:

          • Calls #QueueBuffer on MySource until it fails to provide MySource with buffers to fill with image data

          • Calls #RetrieveBuffer on MySource until it fails to retrieve all MySource filled buffers that are ready for transmission

          • End of acquisition loop

      • #OnStreamingStop is called on MySource to notify the application that streaming is stopping (when the GigE Vision controller calls AcquisitionStop)

        • #AbortQueuedBuffers is called on MySource

        • #RetrieveBuffer is called on MySource until it fails to retrieve all MySource buffers, whether they were acquired or aborted

    • #OnClose is called on MySource when the streaming channel is closed (when the GigE Vision controller disconnects from the GigE Vision Device)

  • PvSoftDeviceGEV.Stop is called explicitly by your application or by the PvSoftDeviceGEV destructor

property thisown

The membership flag

GetWidth()

Returns the current image width.

Your application must implement this method and return the current image width when invoked.

Return type:

int

Returns:

Current image width.

GetHeight()

Returns the current image height.

Your application must implement this method and return the current image height when invoked.

Return type:

int

Returns:

Current image height.

GetOffsetX()

Returns the current image offset X.

Your application must implement this method and return the current image offset X when invoked.

Return type:

int

Returns:

Current image offset X.

GetOffsetY()

Returns the current image offset Y.

Your application must implement this method and return the current image offset Y when invoked.

Return type:

int

Returns:

Current image offset Y.

GetPixelType()

Returns the current pixel type.

Your application must implement this method and return the current image pixel type when invoked.

Return type:

int

Returns:

Current pixel type.

GetWidthInfo()

Returns the stream channel width attributes.

When using the GigE Vision Device as a transmitter, the Width parameter is automatically added to the device’s GenICam XML file. This method is used to query the minimum, maximum, and increment attributes for the Width parameter.

Return type:

Tuple[int, int, int]

Returns:

Tuple composed of the width minimum, maximum and increment.

GetHeightInfo()

Returns the stream channel height attributes.

When using the GigE Vision Device as a transmitter, the Height parameter is automatically added to the device’s GenICam XML file. This method is used to query the minimum, maximum, and increment attributes for the Height parameter.

Return type:

Tuple[int, int, int]

Returns:

Tuple composed of the height minimum, maximum and increment.

GetChunksSize()

Gets the stream channel chunk size attributes.

When using data chunks, it is important to report the chunk data size when queried through this method.

The chunk data size needs to be taken into account when reporting the PayloadSize GenICam parameter to the GigE Vision controller, so it can properly allocate its buffer for streaming without forced buffer re-allocation.

The size reported must for each chunk adds 4 bytes for the chunk ID and another 4 bytes for the chunk length fields. If you have a chunk that is 64 bytes long and it is your only data chunk, you need to report 64 + 4 + 4 (72 bytes) when GetChunksSize is called.

Return type:

int

Returns:

Chunk data size as currently configured.

GetPayloadSize()

Stream channel payload size in bytes. Return zero to have it inferred from width, height and pixel format.

If not using image streams (raw data, multi-part, etc.) use implement the GetPayloadSize method and return the payload size for the current streaming channel source configuration. If GetPayloadSize returns 0 the payload size will be inferred from the width, height, pixel format and data chunk size.

When using multi-part, return the sum of the maximum size of all parts plus data chunk.

When payload size is not zero, the payload size value is simply used as provided. Nothing is added to it, not even data chunk size.

Return type:

int

Returns:

Payload size to use or 0.

GetScanType()

Returns the scan type that is used by the streaming source.

Return PvScanTypeArea if your image source is areascan or PvScanTypeLine if your image source is linescan.

Return type:

int

Returns:

Scan type of the streaming source.

GetChunkModeActive()

Indicates whether the current master chunk mode is active.

The application must implement this method and return the current master chunk mode state. Return false as a hardcoded value if chunks are not supported by the streaming source.

Return type:

boolean

Returns:

True if chunk mode is enabled for this streaming source.

GetChunkEnable(aChunkID)

Returns the current chunk enabled state.

The application must implement this method and return the current chunk enabled state for the specified chunk ID. The streaming source should maintain an enabled/disabled state for each chunk type that it supports.

The application should append the chunk represented by the specified chunk ID if it is enabled and if the master chunk mode (see #GetChunkModeActive) is true.

Parameters:

aChunkID (int, in) – Chunk ID.

Return type:

boolean

Returns:

True if the chunk specified by aChunk ID is enabled for this streaming source.

GetSupportedPixelType(aIndex)

Obtains an index of supported pixel types. Used at PvSoftDeviceGEV.Start time to create the GenICam XML of the device.

This method is used by the PvSoftDeviceGEV to query the application about the supported pixel types for the streaming channel.

The PvSoftDeviceGEV will query the application using this stream interface for all supported pixel types. It will start at index 0 and then increase until something other than PV_OK` is returned.

If the application supports Mono8, BayerRG8, and RGBa8 it needs to handle the request to GetSupportedPixelType, as follows:

  • GetSupportedPixelType( 0 ) -> (PV_OK, PvPixelMono8)

  • GetSupportedPixelType( 1 ) -> (PV_OK, PvPixelBayerRG8)

  • GetSupportedPixelType( 2 ) -> (PV_OK, PvPixelRGBa8)

  • GetSupportedPixelType( 3 ) -> (PV_INVALID_PARAMETER, 0)

Parameters:

aIndex (int, in) – Index of the pixel type to return.

Return type:

Tuple[PvResult, PvPixelType]

Returns:

Tuple composed of (result, aPixelType).
  • result includes:

    • PV_OK if aIndex represents a valid index and aPixelType has been set.

    • PV_INVALID_PARAMETER or any other error code if aIndex is not valid.

  • aPixelType

    • The PvPixelType requested by aIndex. See PvPixelType Enum.

GetSupportedChunk(aIndex)

Returns the indexed supported chunk type. Used at PvSoftDeviceGEV.Start time to create the GenICam XML of the device.

This method is used by the PvSoftDeviceGEV to query the application about the supported chunk types for this streaming channel.

The PvSoftDeviceGEV will query the application through this stream interface for all supported chunk types. It will start at index 0 and then increase until something other than PV_OK is returned.

The information retrieved through this method is used to populate the chunk selector, allowing the GigE Vision controller to enable or disable each chunk type individually.

If the application supports ChunkSample (ID 0x4001) and ChunkHistogram (ID 0x4002) it needs to handle request to GetSupportedChunk as follows:

  • GetSupportedChunk( 0 ) -> (PV_OK, 0x4001, “ChunkSample”)

  • GetSupportedChunk( 1 ) -> (PV_OK, 0x4002, “ChunkHistogram”)

  • GetSupportedChunk( 2 ) -> (PV_INVALID_PARAMETER, 0, )

Parameters:

aIndex (int, in) – Index of the chunk type to return.

Return type:

Tuple[PvResult, int, str]

Returns:

Tuple composed of (result, chunkID, chunkName).
  • result includes:

    • PV_OK if aIndex represents a valid index and aPixelType has been set.

    • PV_INVALID_PARAMETER or any other error code if aIndex is not valid.

  • chunkID:

    • The ChunkID integer.

  • chunkName

    • chunk name in string and should always use the “Chunk” prefix for GenICam SFNC compliance.

GetGevSCPSPacketSizeInfo()

Return the customized max value for GevSCPSPacketSize. Used at PvSoftDeviceGEV.Start time to create the GenICam XML of the device.

This method is optional, it is used by the PvSoftDeviceGEV to query the application about the max value to use for GenICam node GevSCPSPacketSize to fit your system needs. The default max value is 9000 bytes if choose not to implement.

The max value configured here will be used for PacketSize Auto-negotiation by the receiver to determine the most suitable packet size for the system. The user is able to configure up to 65535 for certain special use case.

In order for the eBUS Receiver to negotiate the packet size based on the maximum value configured here, the eBUS Receiver version needs to be at least 6.5.

Return type:

Tuple[PvResult, int]

Returns:

Tuple composed of (result, maxValue).
  • result includes:

    • PV_OK if the default aMax have been changed.

    • PV_NOT_IMPLEMENTED or any other error code if to keep the default settings.

  • maxValue:

    • The max value allowed for PacketSize Negotiation.

SetWidth(aWidth)

Request from the PvSoftDeviceGEV to change the image width.

The PvSoftDeviceGEV will call SetWidth when the Width GenApi parameter or the underlying register is changed by the GigE Vision controller.

To accept the new width, return PV_OK and update your streaming code to use the new width.

Parameters:

aWidth (int, in) – New image width.

Return type:

PvResult

Returns:

Includes:

SetHeight(aHeight)

Request from the PvSoftDeviceGEV to change the image height.

The PvSoftDeviceGEV will call SetHeight when the Height GenApi parameter or the underlying register is changed by the GigE Vision controller.

To accept the new height, return PV_OK and update your streaming code to use the new height.

Parameters:

aHeight (int, in) – New image height.

Return type:

PvResult

Returns:

Includes:

SetOffsetX(aOffsetX)

Request from the PvSoftDeviceGEV to change the image offset X.

To accept the new offset X, return PV_OK and update your streaming code to use the new value.

Parameters:

aOffsetX (int, in) – New image offset X.

Return type:

PvResult

Returns:

Includes:

SetOffsetY(aOffsetY)

Request from the PvSoftDeviceGEV to change the image offset Y.

To accept the new offset Y, return PV_OK and update your streaming code to use the new value.

Parameters:

aOffsetY (int, in) – New image offset Y.

Return type:

PvResult

Returns:

Includes:

SetPixelType(aPixelType)

Request from the PvSoftDeviceGEV to change the image pixel type.

The PvSoftDeviceGEV will call SetPixelType when the PixelType GenApi parameter or the underlying register is changed by the GigE Vision controller.

To accept the new pixel type, return PV_OK and update your streaming code to use the new pixel type.

Parameters:

aPixelType (int, in) – New image pixel type.

Return type:

PvResult

Returns:

Includes:

  • PV_OK when accepting the new pixel type.

  • PV_GENERIC_ERROR or another error code to refuse the new pixel type.

SetChunkModeActive(aEnabled)

Set the master chunk mode active state.

The streaming source should append a specific chunk type to its streaming data when both the #GetChunkModeActive (master chunk mode) and #GetChunkEnable for this specific chunk type are true.

Parameters:

aEnabled (boolean, in) – True to enable chunk mode for this streaming channel, false to disable it.

Return type:

PvResult

Returns:

Includes:

SetChunkEnable(aChunkID, aEnabled)

Sets the chunk enabled state for a specific chunk type.

The streaming source should append a specific chunk type to its streaming data when both the #GetChunkModeActive (master chunk mode) and #GetChunkEnable for this specific chunk type are true.

Parameters:

  • aChunkID (int, in) – Chunk ID of the chunk type to enable or disable.

  • aEnabled (boolean, in) – True to enable the chunk type, false to disable it.

Return type:

PvResult

Returns:

Includes:

OnOpen(aDestIP, aDestPort)

Notification from the PvSoftDeviceGEV that this streaming channel has been opened.

Parameters:

  • aDestIP (str, in) – IP address of the stream destination as a string in the “192.168.138.115” format (SCDA).

  • aDestPort (int, in) – UDP port of the stream destination (SCP).

OnClose()

Notification from the PvSoftDeviceGEV that this streaming channel has been closed.

OnStreamingStart()

Notification that the GigE Vision controller has requested that the device start streaming on this channel.

OnStreamingStop()

Notification that the GigE Vision controller has requested that the device stop streaming on this channel.

AllocBuffer()

Request by the PvSoftDeviceGEV to allocate a PvBuffer.

On initialization, the PvSoftDeviceGEV will call this method, asking the application to allocate buffers that will be used for image acquisition and transmission. The application should return buffers until it has reached the desired number of buffers it wants to use for streaming and then return NULL.

The more buffers you use, the more buffers you can have queued in the application for image acquisition and the more buffers you can leave in the transmission output queue for packet resend. The downside of using more buffers is increased memory usage.

Buffers returned on AllocBuffer calls should be unique: you should not return the same buffer more than once.

A maximum of 64 buffers can be used by one streaming channel of the PvSoftDeviceGEV. If your application does not return NULL on the 64th buffer, AllocBuffer will not be called a 64th time.

Return type:

PvBuffer

Returns:

Pointer to a new PvBuffer that can be used by the PvSoftDeviceGEV’s acquisition manager.

FreeBuffer(aBuffer)

Request by the PvSoftDeviceGEV to free or release a buffer allocated with AllocBuffer.

You should not delete or free any PvBuffer provided by the AllocBuffer method. FreeBuffer will be called for each buffer created with AllocBuffer when PvSoftDeviceGEV.Stop is called.

Parameters:

aBuffer (PvBuffer, in) – Buffer to free.

QueueBuffer(aBuffer)

Request by the PvSoftDeviceGEV to queue a buffer for acquisition.

If the application can accept the buffer and queue it for image acquisition, it returns success. If the acquisition queue or pipeline is full, return a PvResult error code.

Parameters:

aBuffer (PvBuffer, in) – Buffer to queue for image acquisition.

Return type:

PvResult

Returns:

Includes:

  • PV_OK to accept the buffer.

  • Any error code to refuse the buffer.

PreQueueBufferProc()

This is an advanced feature used mostly internally. For expert users only. It is higly recommended to not override but use the default implementation.

Return type:

boolean

Returns:

True if the processing loop can proceed with queueing/retrieving next buffer.

PostRetrieveBufferProc()

This is an advanced feature used mostly internally. For expert users only. It is higly recommended to not override but use the default implementation.

RetrieveBuffer(aBuffer)

IPvStreamingChannelSource::GetSupportedChunk( notused ) -> ( aResult, aBuffer ) Request by the PvSoftDeviceGEV to retrieve a buffer from the streaming source.

During acquisition, buffers retrieved with this method will contain valid image data and are going to be transmitted using the GVSP protocol. This method is also used to retrieve queued buffers after calling AbortQueuedBuffers.

If no image is immediately available, we recommend that you wait until an image is available in this method to allow the acquisition thread to wait efficiently for a new image. | If getting a new image can take a long time, your application should wait small chunks of time (10, 20, or 50 ms) to prevent deadlocking the acquisition thread and to allow the PvSoftDeviceGEV to stop streaming gracefully.

Parameters:

notused (void, in) – Dummy argument. Unused.

Return type:

Tuple[PvResult, PvBuffer]

Returns:

Tuple composed of (result, pvbuffer).
  • result includes:

    • PV_OK if a buffer has been retrieved.

    • or any other error code if aIndex is not valid.

  • pvbuffer:

    • The PvBuffer object retrieved.

AbortQueuedBuffers()

Request by the PvSoftDeviceGEV to abort all buffers queued for acquisition.

This method should block until acquisition has been aborted or canceled for all buffers provided by QueueBuffer that have not yet been retrieved with RetrievedBuffer.

When this method returns, it should be possible to call RetrieveBuffer for all aborted buffers.

CreateRegisters(aRegisterMap, aFactory)

When called, the streaming channel source should create its custom registers if they are needed.

To create source-specific custom registers in your application, implement the CreateRegisters method of the IPvStreamingChannelSource interface.

Custom source-specific register creation occurs BEFORE custom source-specific GenApi features creation, inside the PvSoftDeviceGEV.Start call.

If more than one streaming channel source is created from the same class, you must make sure its registers are still unique: RegisterXYZ in Source0 and Source1 should not have the same address. It is also recommended to assign them unique names like RegisterXYZ0 and RegisterXYZ1.

Parameters:

  • aRegisterMap (IPvRegisterMap, in) – The register map of the device.

  • aFactory (IPvRegisterFactory, in) – Register factory used to create the new registers.

CreateGenApiFeatures(aRegisterMap, aFactory)

When called, the streaming channel source should create its custom GenApi parameters if they are needed.

Create GenApi features from this callback if the feature is associated with a streaming channel source. For global-device, non streaming channel source features use IPvSoftDeviceGEVEventSink.OnCreateCustomGenApiFeatures instead.

In a multi-source application, GenApi features created by a streaming channel source will only be available when the SourceSelector is set to the streaming channel source that created the feature.

If FeatureXYX is created by Source0 and Source1 but not by Source2, the feature will only be available in the GenApi interface when SourceSelector is set to Source0 or Source1.

  • MySource0 has Feature0, Feature1, Feature2

  • MySource1 has Feature0, Feature3, Feature4

  • In a GenApi browser with SourceSelector=Source0, Feature0, Feature1, Feature2 are available. Feature3 and Feature4 are disabled.

  • In a GenApi browser with SourceSelector=Source1, Feature0, Feature3, Feature4 are available. Feature1 and Feature2 are disabled.

If integers with the same name are created for more than one source but with source-specific minimum, maximum and increment attributes, these attributes will be handled by GenICam SwissKnife operators in the GenICam XML so they are dynamically adjusted based on the value of SourceSelector. The same applies to float maximum and minimum.

  • MyInteger is created for Source0 with min:0 max:100 increment:4

  • MyInteger is created for Source1 with min:4 max:200 increment:1

  • In a GenApi browser, MyInteger will report min:0 max:100 increment:4 with Source0 is selected

  • In a GenApi browser, MyInteger will report min:4 max:200 increment:1 with Source1 is selected

If enumerations with the same name are created for more than one source but with different enum entries, they will be added to the GenICam XML file of the device in way that the correct enum entries should be available for the enum features based on the current SourceSelector value:

  • MyEnum is created with EE0, EE1, EE2 for Source0

  • MyEnum is created with EE0, EE3, EE4 for Source1

  • In a GenApi browser with SourceSelector=Source0, you would see EE0, EE1, EE2 in the combo box

  • In a GenApi browser with SourceSelector=Source1, you would see EE0, EE3, EE4 in the combo box

Creating features of the same name but different types is not supported. Attempting to do so should have the PvSoftDeviceGEV.Start call failing with an appropriate error description.

GenApi features created for a streaming channel source should use registers unique to this streaming channel source. If you have a source class MySource that creates registers and features, it should still create unique register having their own unique addresses. They should however use the same parameter name. The GenApi parameters created by MySource should use the right register for the source instance. The complexity of overlapping per-source feature name is handled by PvSoftDeviceGEV when creating the GenICam XML file from PvSoftDeviceGEV.Start.

  • For Source0:

    • MySource creates MySourceRegister0 @ 0x20000000 + 0x1000 * source index + 0

    • MySource creates MySourceParameter named “MySourceParameter” for Source0 using MySourceRegister0

  • For Source1:

    • MySource creates MySourceRegister1 @ 0x20000000 + 0x1000 * source index + 4

    • MySource creates MySourceParameter named “MySourceParameter” for Source1 using MySourceRegister1

The exception to this rule is selectors: if selectors are created at the streaming source level they must all use the same register, sharing the same register address.

Custom source-specific GenApi features creation occurs AFTER custom source-specific registers creation, inside the PvSoftDeviceGEV.Start call.

Parameters:

  • aRegisterMap (IPvRegisterMap, in) – The register map of the device.

  • aFactory (IPvGenApiFactory, in) – GenApi factory used to create the new GenApi features.

IsPayloadTypeSupported(aPayloadType)

When called, the streaming source has to return whether the specificed payload type is supported or not.

Return true if the streaming source exlusively or non-exclusively can stream buffers of the specified payload type. A default implementation is provided for this method which returns false.

This method must be implemented and returning true for aPayloadType being equal to PvPayloadTypeMultiPart when multi-part is supported by the streaming source.

See #SetTestPayloadFormatMode and #SetMultiPartAllowed for more information on propertly supporting the multi-part payload type.

Parameters:

aPayloadType (int) – [in] The payload type for which support is queried.

Return type:

boolean

Returns:

Return true if the payload type is supported, false if not.

SetMultiPartAllowed(aAllowed)

Sets whether the streaming source is allowed or not, but not forced, to transmit multi-part data.

Streaming sources supporting multi-part data transmission must support non-multi-part streaming by default. All devices starting in a mode where multi-part is not allowed. The GigE Vision controller must unlock the multi-part capability of a GVSP streaming channel using either the SCCx and SCCFGx bootstrap registers or the GevSCCFGMultiPartEnabled GenApi parameter.

The GevSCCFGMultiPartEnabled GenApi parameter is automatically added to the GenICam XML file of a PvSoftDeviceGEV device when #IsPayloadTypeSupported returns true when prompted with PvPayloadTypeMultiPart.

See #IsPayloadTypeSupported and #SetTestPayloadFormatMode for more information on propertly supporting the multi-part payload type.

Parameters:

aAllowed (boolean) – [in] True if multi-part is allowed.

SetLargeLeaderTrailerEnabled(aEnabled, aMaxMultiPartCount)

Sets whether the streaming source which transmit multi-part data uses large data leader and trailer packets.

Streaming sources using multi-part data transmission without large data leader and trailer enabled only supports up to 10 multi-parts due to the data leader and trailer packet size limitation. Large data leader and data trailer packets can be enabled by configuring the GevSCCFGLargeLeaderTrailerEnabled GenApi parameter to allow more than 10 parts. The large leader and trailer packet size is then set to the value allowed by the SCPSx register.

The GevSCCFGLargeLeaderTrailerEnabled GenApi parameter is automatically added to the GenICam XML file of a PvSoftDeviceGEV device when #IsPayloadTypeSupported returns true when prompted with PvPayloadTypeMultiPart. This parameter will only be available when GevSCCFGMultiPartEnabled is set to true.

Parameters:

  • aEnabled (boolean) – [in] True if Large Leader Trailer is enabled.

  • aMaxMultiPartCount (int) – [in] The number of maximum allowed Multi parts calculated from the value allowed by the SCPSx register.

SetTestPayloadFormatMode(aPayloadType)

When called, the streaming source has to ensure it can stream buffers of the specified payload type.

The GigE Vision Validation Framework has to be able to set the device in a functional streaming mode for some payload types (currently only multi-part with more to come) in order to properly validate the device.

This method must be implemented and for aPayloadType being PvPayloadTypeMultiPart when multi-part is supported by the streaming source. The streaming source must be able to configure itself in a mode where it will be able to stream data for certification with the GigE Vision Validation Framework.

Of course, this method will only be called on a streaming source for payload type that have been reported as supported with #IsPayloadTypeSupported.

How to prepare your multi-source device source for GigE Vision Validation Framework validation:

  • Implement #IsPayloadTypeSupported and return true if aPayloadType is PvPayloadTypeMultiPart.

  • Implement #SetTestPayloadFormatMode
    • If aPayloadType is PvPayloadTypeMultiPart

      • Setup your streaming source for autonomous multi-part streaming if needed

      • Return PV_OK

    • Else if aPayloadType is PvPayloadTypeNone

      • Disable test mode, go back to streaming source normal operation mode

      • Return PV_OK

    • Else

See the SoftDeviceGEVMultiPart C++ sample for an example of how to implement this method, #SetMultiPartAllowed, and #IsPayloadTypeSupported.

Parameters:

aPayloadType (int, in) – Payload type to prepare test for. PvPayloadTypeNone sets the device back in normal operation mode.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • Any error code can be returned to indicate failure.

class eBUS.PvBuffer(aPayloadType=1)

Bases: IPvChunkData

Represents a block of GigE Vision or USB3 Vision data in memory

A PvBuffer object is typically used to receive data from a GigE Vision or USB3 Vision transmitter or to transmit data to a GigE Vision receiver. To learn about receiving data from a GigE Vision or USB3 Vision transmitter, see PvStream. To learn about transmitting GigE Vision data to a GigE Vision receiver, see PvTransmitterGEV.

A block of GigE Vision or USB3 Vision data has an associated payload which can be an image, raw data, file, chunk data, extended chunk data or device specific.

In order to access the payload specific data, use methods like PvBuffer.GetImage in order to get a pointer to an interface giving you access to payload specific methods and properties.

The current payload type of a PvBuffer can be determined by using the PvBuffer.GetPayloadType method.

In this section:

  • Creating and configuring buffers (“#configuring”)

  • Accessing payload type specific data (“#accessing”)

  • Processing images (“#processing”)

## id=”configuring”Creating and configuring buffers

To create and configure buffers:

  • Create several buffers using the default constructor.

  • Set the size of the buffer. The method you use depends on whether you want to use

    an internally or externally controlled block of memory: - To use memory that the PvBuffer object allocates and owns, use #Alloc. - To use memory that you control (external to the PvBuffer object), use #Attach.

## id=”accessing”Accessing payload type specific data

To determine the payload type and access payload type specific data:

## id=”processing”Processing images

To process an image:

  • Retrieve a PvImage interface to the buffer use #GetImage

  • Test the success of the image acquisition. Use the aOperationResult parameter in PvStream.RetrieveBuffer or PvBuffer.GetOperationResult

  • Process the image using your own code. You may process the image in place, if you wish. Use:

    • PvImage.GetAcquiredSize

    • PvImage.GetHeight and PvImage.GetWidth

    • PvImage.GetOffsetX and PvImage.GetOffsetY

property thisown

The membership flag

__init__(aPayloadType=1)

Constructor.

Parameters:

aPayloadType (int, in, optional) – The block type (default PvPayloadTypeImage).

GetPayloadType()

Returns the payload type currently used by the buffer

If data chunks are available, the buffer payload type is the same as if no data chunks were available. Use GetChunkCount to determine if chunks are available.

Return type:

int

Returns:

PvPayloadType The current payload type for the PvBuffer. See PvPayloadType enum.

GetImage(*args)

Overload 1:

Returns the PvImage interface to the buffer.

If the payload type of the PvBuffer is PvPayloadTypeImage, a pointer to the PvImage interface of the buffer is returned.

If the payload type of the PvBuffer is NOT PvPayloadTypeImage, a NULL pointer is returned.

This PvImage pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

Return type:

PvImage

Returns:

Pointer to PvImage interface or NULL, depending on payload type.


Overload 2:

Returns the PvImage interface to the buffer.

Const version.

Return type:

PvImage

Returns:

Pointer to PvImage interface or NULL, depending on payload type.

GetRawData(*args)

Overload 1:

Returns the PvRawData interface to the buffer.

If the payload type of the PvBuffer is PvPayloadTypeRawData, a pointer to the PvRawData interface of the buffer is returned.

If the payload type of the PvBuffer is NOT PvPayloadTypeRawData, a NULL pointer is returned.

This PvRawData pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

Return type:

PvRawData

Returns:

Pointer to PvRawData interface or NULL, depending on payload type.


Overload 2:

Returns the PvRawData interface to the buffer.

Const version.

Return type:

PvRawData

Returns:

Pointer to PvRawData interface or NULL, depending on payload type.

GetPleoraCompressed(*args)

Overload 1:

Returns the PvPleoraCompressed interface to the buffer.

If the payload type of the PvBuffer is PvPayloadTypePleoraCompressed, a pointer to the PvPleoraCompressed interface of the buffer is returned.

If the payload type of the PvBuffer is NOT PvPayloadTypePleoraCompressed, a NULL pointer is returned.

This PvPleoraCompressed pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

Return type:

PvPleoraCompressed

Returns:

Pointer to PvPleoraCompressed interface or NULL, depending on payload type.


Overload 2:

Returns the PvPleoraCompressed interface to the buffer.

Const version.

Return type:

PvPleoraCompressed

Returns:

Pointer to PvPleoraCompressed interface or NULL, depending on payload type.

GetChunkData(*args)

Overload 1:

Returns the PvChunkData interface to the buffer.

If the payload type of the PvBuffer is PvPayloadTypeChunkData, a pointer to the PvChunkData interface of the buffer is returned.

If the payload type of the PvBuffer is NOT PvPayloadTypeChunkData, a NULL pointer is returned.

This PvChunkData pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

Return type:

PvChunkData

Returns:

Pointer to PvChunkData interface or NULL, depending on payload type.


Overload 2:

Returns the PvChunkData interface to the buffer.

Const version.

Return type:

PvChunkData

Returns:

Pointer to PvChunkData interface or NULL, depending on payload type.

GetMultiPartContainer(*args)

Overload 1:

Returns the IPvMultiPartContainer interface to the buffer.

If the payload type of the PvBuffer is PvPayloadTypeMultiPart, a pointer to the IPvMultiPartContainer interface of the buffer is returned.

If the payload type of the PvBuffer is NOT PvPayloadTypeMultiPart, a NULL pointer is returned.

This IPvMultiPartContainer pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

Return type:

IPvMultiPartContainer

Returns:

Pointer to IPvMultiPartContainer interface or NULL, depending on payload type.


Overload 2:

Returns the IPvMultiPartContainer interface to the buffer.

Const version.

Return type:

IPvMultiPartContainer

Returns:

Pointer to IPvMultiPartContainer interface or NULL, depending on payload type.

GetH264AccessUnit(*args)

Overload 1:

Returns the IPvH264AccessUnit interface to the buffer.

If the payload type of the PvBuffer is PvPayloadTypeH264, a pointer to the IPvH264AccessUnit interface of the buffer is returned.

If the payload type of the PvBuffer is NOT IPvH264AccessUnit, a NULL pointer is returned.

This IPvH264AccessUnit pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

Return type:

IPvH264AccessUnit

Returns:

Pointer to IPvH264AccessUnit interface or NULL, depending on payload type.


Overload 2:

Returns the IPvH264AccessUnit interface to the buffer.

Const version.

Return type:

IPvH264AccessUnit

Returns:

Pointer to IPvH264AccessUnit interface or NULL, depending on payload type.

GetDataPointer(self) → ndarray

Get the numpy array describing the buffer data.

The GetDataPointer method returns a numpy array describing the buffer data. To set the memory location, use PvBuffer.Alloc or PvBuffer.Attach.

Return type:

ndarray

Returns:

A 1-dimensional python numpy array with dtype np.uint8 describing the buffer data.

GetID()

Get the buffer’s ID.

See #SetID.

Return type:

int

Returns:

The buffer’s ID. See #SetID.

SetID(aValue)

Set the buffer’s ID.

The #SetID method lets you assign an arbitrary number to a buffer. When you retrieve the buffer later, you can also recover the number you assigned.

The ID is completely arbitrary and solely available for your own use. It can be useful to keep track of buffers in an application.

Parameters:

aID – The buffer’s ID.

IsExtendedID()

Check if the buffer is currently in extended ID mode.

When the extended ID mode is not enabled, the maximum block ID is 0xFFFFFF and the maximum packet ID is 0xFFFFFF as per the GEV 1.X specification. When the extended ID mode is enabled, the maximum block ID is 0xFFFFFFFFFFFFFFFF and the maximum packet ID is 0xFFFFFFFF as per the GEV 2.X specification.

When a PvBuffer is received, the extended ID mode is initialized based on the information received by PvStream. When a PvBuffer is sent, the extended ID mode will be initialized by the PvTransmitterGEV.PvTransmitterGEV according to its configuration.

Return type:

boolean

Returns:

true if the extended if mode is in usage:

IsAttached()

Returns true if the buffer has been attached (instead of allocated)

Return type:

boolean

Returns:

True if attached.

IsAllocated()

Returns true if the buffer has been attached (instead of attached)

Return type:

boolean

Returns:

True if allocated.

GetAcquiredSize()

Gets the size in bytes of the block received by the data receiver including, if present, additional chunk data and headers, optional padding.

Return type:

int

Returns:

The size, in bytes, of bytes received for this buffer.

GetRequiredSize()

Gets the size of buffer required to hold the acquired block including, if present, additional chunk data and headers, padding.

Return type:

int

Returns:

The size, in bytes, required to hold the block in this buffer.

GetSize()

Get the buffer’s allocated or attached size (total capacity) in bytes.

Return type:

int

Returns:

The buffer’s (allocated or attached) size in bytes

Reset(aPayloadType=1)

Reconstruct the object with a new payload type.

Parameters:

aPayloadType (int, in, optional) – The payload type to reset the buffer to.

Return type:

PvResult

Returns:

PV_OK if successful.

Alloc(aSize)

Allocates memory for this PvBuffer.

Parameters:

aSize (int, in) – The size of the buffer, in bytes.

Return type:

PvResult

Returns:

Includes:

AllocChunk(aSize)

Alloc a separate space for chunk data in this PvBuffer.

Designed for use when attaching external data buffers that cannot be resized to accomodate chunk data.

Parameters:

aSize (int, in) – The size, in bytes, required for the buffer.

Return type:

PvResult

Returns:

Includes:

See also: FreeChunk

Free()

Frees (de-allocates) the buffer’s internal memory.

See also: Alloc

FreeChunk()

Frees (de-allocates) an attached memory buffer of chunk data.

See also: AllocChunk

Attach(self, aBuffer) → PvResult

Attach this PvBuffer to an external memory buffer.

To use an internal memory buffer, use PvBuffer.Alloc.

Parameters:

aBuffer (ndarray, in) – A 1-dimensional python numpy array with dtype np.uint8 to use as a buffer.

Return type:

PvResult

Returns:

Includes:

See also: Detach

Detach(self) → ndarray

Releases an attached memory buffer. Does nothing other then resetting the memory buffer pointer to NULL.

Return type:

ndarray

Returns:

The previously attached numpy array. See PvBuffer.Attach.

See also: Attach

GetBlockID()

Return the block ID.

This method returns the block ID. The GigE Vision or USB3 Vision transmitter typically increments the value by 1 for each new image. You can use this value to ensure the blocks are in order and that none are missing. The value is unsigned and wraps around to 1 (skipping 0) when it reaches 65536 (for legacy 16bit Block ID mode) or 2^64 (for 64 bit Extended Block ID mode).

Return type:

int

Returns:

The block ID

GetOperationResult()

Returns the value of aOperationResult when this buffer was last received through a PvStream.

Buffers with BUFFER_TOO_SMALL, ABORTED, NOT_CONNECTED and NO_MORE_ITEM operation results are never returned to the user with PvPipeline. PvPipeline handles these operation results internally without returning the buffers. Buffers with these operation results can only reach the user when using PvStream directly.

Return type:

PvResult

Returns:

Result of the acquisition operation; Includes:

See also: PvStream.RetrieveBuffer, PvPipeline.RetrieveNextBuffer

GetTimestamp()

Get the buffer’s timestamp.

With hardware timestamps and GigE Vision devices, the device defines the timestamp tick frequency. The effective value can be retrieved from the GenApi interface of the device.

With hardware timestamps and USB3 Vision devices, timestamps are always defined in nanoseconds.

With software timestamps the timestamps are in micro seconds.

Use the PvStream GenApi interface to configure whether hardware or software time stamps are used.

Return type:

int

Returns:

The buffer’s hardware timestamp; For Pleora devices, this is the value of the relative timestamp clock when the grabber began receiving data from the camera head - on the rising edge of the FVAL.

GetReceptionTime()

Get the buffer’s reception timestamp.

Return type:

int

Returns:

The buffer’s reception time on the host, in micro seconds. Not an absolute time value.

GetDuration()

Get the buffer’s duration.

Buffer duration when applicable. Typically used by stream decoders to control frame rate of a sequence of frames.

Return type:

int

Returns:

Buffer duration.

SetTimestamp(aTimestamp)

Set the timestamp to place in the block leader.

When transmitting blocks to a GigE Vision receiver, by default, the timestamp on outgoing blocks is zero. However, the calling application may set a timestamp on the outgoing blocks if desired by calling #SetTimestamp.

Parameters:

aTimestamp (int) – The timestamp to set in the block leader

Return type:

PvResult

Returns:

PV_OK if successful.

SetDuration(aDuration)

Set the duration of the buffer in the context of a stream.

Parameters:

aDuration (int, in) – Duration of the buffer.

Return type:

PvResult

Returns:

PV_OK if successful.

SetBlockID(aBlockID)

Sets the block ID of a buffer.

Should only be used for creating synthetic test PvBuffers or copies of a PvBuffer which caries some information over from the original.

Parameters:

aBlockID (int) – Block ID to assign to the buffer.

Return type:

PvResult

Returns:

PV_OK if successful.

SetReceptionTime(aReceptionTime)

Sets the reception time of a buffer.

Should only be used for creating synthetic test PvBuffers or copies of a PvBuffer which caries some information over from the original.

Parameters:

aReceptionTime (int) – Reception tiome to assign to the buffer.

Return type:

PvResult

Returns:

PV_OK if successful.

GetPacketsRecoveredCount()

The number of lost packets successfully recovered by packet resend requests. Duplicate received packets are not counted.

Return type:

int

Returns:

The expected resend count

GetPacketsRecoveredSingleResendCount()

The number of lost packets successfully recovered by packet resend requests without any resend request retries.

Return type:

int

Returns:

The expected resend count

GetResendGroupRequestedCount()

The number of resend requests issued by the data receiver.

Return type:

int

Returns:

The resend requested count

GetResendPacketRequestedCount()

The number of packets the data receiver requests with ResendGroupRequested.

Return type:

int

Returns:

The received resend requested packet count

GetLostPacketCount()

Packets that were not successfully delivered when this PvBuffer was filled by the data receiver.

Return type:

int

Returns:

The lost packet count

GetIgnoredPacketCount()

Packets received that were ignored when this buffer was filled by the data receiver.

Return type:

int

Returns:

The ignored packet count

GetRedundantPacketCount()

Number of packets received more than once

Return type:

int

Returns:

The redundant packet count

GetPacketOutOfOrderCount()

Number of packets received out of order

Return type:

int

Returns:

The packet out of order count

GetMissingPacketIdsCount() → PvResult, int

Get the number of missing packet groups that represent unpopulated areas of memory in this buffer

Notes: This is an advanced feature that requires knowledge of how GigE Vision data is transmitted.

Does not apply to USB3 Vision devices which do not have the concept of packet resends.

When receiving data from a GigE Vision transmitter, network conditions may prevent the successful delivery of all the data for a given block. Although the eBUS data receiver provides a mechanism for requesting lost packets, there are cases when it is desirable to ignore missing packets and make use of a buffer that contains missing information. In some cases, there are portions of a block that are less important and can thus be disregarded. #GetMissingPacketIdsCount and #GetMissingPacketIds can provide information about which packets were lost. To use this feature take note of the following procedure:

  • Enable the feature that causes the data receiver to keep track of missing packets

    (see the EnableMissingPacketsList property of PvStream).

  • Optionally disable the mechanism that requests lost packets

    (see the RequestMissingPackets property of PvStream).

  • Check the operation result when a new block is received (see PvBuffer.GetOperationResult).

  • If the operation result is PV_MISSING_PACKETS, call #GetMissingPacketIdsCount to determine how many groups of packets are missing.

  • Iterate through the missing packet groups using #GetMissingPacketIds.

  • Note that there is no particular order to the missing packet groups that are returned.

  • Take note of the packet size set on the GigE Vision transmitter from which you are receiving

    to determine the areas of the payload where information is missing.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, count):
  • result representing the outcome:
  • count:

    • The number of missing packet groups that represent unpopulated areas of memory in this buffer

GetMissingPacketIds(self, aIndex) → PvResult, int, int

Get a missing packet group that represents an unpopulated area of memory in this buffer

Notes: This is an advanced feature that requires knowledge of how GigE Vision data is transmitted.

Refer to #GetMissingPacketIdsCount for further details on how this feature is used.

Does not apply to USB3 Vision devices which do not have the concept of packet resends.

Parameters:

aIndex (int) – The index of the missing packet group being retrieved.

Return type:

Tuple(PvResult, int, int)

Returns:

Tuple composed of (result, low, high):
  • result representing the outcome:
  • low:

    • The first packet of a range of missing packets.

  • high:
    • The last packet of a range of missing packets. A value of 0xFFFFFF ( or 0xFFFFFFFF for ExtendedID )

      indicates that the last packet of the block went missing and therefore the actual size of the block is unknown.

ResetChunks()

Resets the internal chunk state.

Used when creating PvBuffer with chunks for transmission. This method should always be called before adding the first chunk block to a buffer. It removes chunk data from the previous sequence of AddChunk.

If you are adding more than one chunk block to a buffer, you would normally perform this sequence for every buffer setup for transmission:

  1. lBuffer.ResetChunks();

  2. lBuffer.SetChunkLayoutID( CHUNKLAYOUTID );

  3. lBuffer.AddChunk( CHUNKID1, lData1 );

  4. lBuffer.AddChunk( CHUNKID2, lData2 );

AddChunk(self, aID, aData) → PvResult

Add chunk data to the buffer. Add chunk data to the buffer payload section by specifying the ID of the chunk data. See PvBuffer.ResetChunks for more information.

Parameters:

  • aID (int, in) – Chunk data ID for aIndex.

  • aData (python bytes object, in) –

    • Python bytes object containing chunk data.

    • Payload data can be formatted with struct.pack. eg. data = struct.pack(“<I32s”, some_int, some_string)

Return type:

PvResult

Returns:

A PvResult is used to capture the success or failure of the operation:

SetChunkLayoutID(aChunkLayoutID)

Set the chunk data layout ID.

Parameters:

aChunkLayoutID (int, in) – Chunk data layout ID.

HasChunks()

Returns true if the buffer has data chunks.

Unlike GetChunkCount, chunks do not need to be parsed or resolved with this method.

Return type:

boolean

Returns:

True if the buffer holds data chunks, false if not.

GetChunkCount()

Returns the number of data chunks in the PvBuffer.

If no data chunks are available, 0 is returned.

Counting chunks requires the chunks to be parsed and resolved which has a performance hit.

If you need to access chunks directly, you need to use this method to enumerate the chunks. If you access the chunks through GenICam, just use HasChunks to see if you need to attach the buffer the GenICam parameter array of the device.

Return type:

int

Returns:

Data chunks count. 0 if no chunks are available.

GetChunkIDByIndex(self, aIndex) → PvResult, int

Returns a tuple of PvResult and the ID of a chunk based on its index.

If the index is out of range or the PvBuffer does not have any data chunk, 0 is returned in ID.

Parameters:

aIndex (int, in) – Data chunk Index.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, chunkID):
  • result representing the outcome:

    • PV_OK

    • PV_NOT_FOUND if the index is out of range or the buffer does not have any chunks

  • chunkID:

    • Chunk ID.

GetChunkSizeByIndex(aIndex)

Returns the size in bytes of the data chunk at zero-based aIndex.

Chunks are enumerated from the end of the payload data to its beginning. If the index is out of range or the PvBuffer does not have any data chunk 0 is returned.

Parameters:

aIndex (int, in) – Data chunk index.

Return type:

int

Returns:

Data chunk size. 0 if the index is out of range.

GetChunkSizeByID(aID)

Returns the size in bytes of the data chunk identified by aID.

If the aID chunk is not found or the PvBuffer does not have any chunks 0 is returned.

Parameters:

aID (int, in) – Data chunk ID.

Return type:

int

Returns:

Data chunk size. 0 if the chunk ID is not found.

GetChunkRawDataByIndex(self, aIndex) → ndarray

Returns a numpy array pointing to the data chunk at zero-based aIndex.

Chunks are enumerated from the end of the payload data to its beginning. If the index is out of range or the PvBuffer does not have any data chunk an empty array is returned.

Parameters:

aIndex (int, in) – Data chunk index.

Return type:

ndarray

Returns:

A 1-dimensional python numpy array with dtype np.uint8 describing the chunk data. Empty if the index is out of range.

GetChunkRawDataByID(self, aID) → ndarray

Returns a const pointer to the data chunk with its ID matching aID.

If the aID chunk is not found or the PvBuffer does not have any chunks NULL is returned.

Parameters:

aID (int, in) – Data chunk ID.

Return type:

ndarray

Returns:

A 1-dimensional python numpy array with dtype np.uint8 describing the chunk data. Empty if the chunk ID is not found.

GetPayloadSize()

Returns payload size in bytes, excluding any extra padding.

Gets the size in bytes of the block received by the data receiver including, if present, additional chunk data and headers.

Different than GetAcquiredSize as it does not include optional additional padding when data chunks are present.

If data chunks are not present, this method returns the same value as GetAcquiredSize as extra padding is only an issue when data chunks are present.

This method is required in order to parse the chunk data using GenICam.

Return type:

int

Returns:

Payload size in bytes, excluding any extra padding.

GetChunkLayoutID()

Get the chunk data layout ID.

Return type:

int

Returns:

The current chunk data layout ID.

GetChunkDataSize()

Returns the current chunk data size.

In a transmission context this method returns how many bytes are used for extra chunk data. It includes the chunk headers for all chunk data and if applicable the chunk header for the main chunk (typically the image).

This method has no use in a reception context where the data receiver delivers the buffer. Use either the direct chunk access methods or the GenApi interface of the device to access chunk data.

Return type:

int

Returns:

Chunk data size in bytes.

GetChunkDataCapacity()

Returns the current chunk data capacity.

In a transmission context where you create the buffer, memory is allocated for chunks. This method returns how many bytes can still be added as chunk data.

One chunk is always made of 8-bytes of headers plus the chunk data length. You also need to reserve another 8-bytes for the main chunk (typically the image) unless you buffer only contains chunk data.

This method has no use in a reception context where the data receiver delivers the buffer. Use either the direct chunk access methods or the GenApi interface of the device to access chunk data.

Return type:

int

Returns:

Chunk data capacity.

IsHeaderValid()

Returns whether this buffer has valid header (GVSP) information.

If the buffer header is not valid (missing) the buffer has to be manipulated with extreme caution. To start with, it is impossible to confirm the payload type. The timestamp and other shared header information is not valid. Finally, information specific to some payload types (like with, height, pixel format, etc. for the image payload type) is not available or valid this buffer.

When a buffer is attached or allocated for use other than receiving GVSP data, this attribute evaluates to true in order to appear as valid.

Return type:

boolean

Returns:

True if the GVSP header is valid.

IsTrailerValid()

Returns whether this buffer has valid trailer (GVSP) information.

If the buffer trailer is not valid (missing) some information about the buffer could be missing. As an example, the image payload type confirms the number of lines received in the trailer.

When a buffer is attached or allocated for use other than receiving GVSP data, this attribute evaluates to true in order to appear as valid.

Return type:

boolean

Returns:

True if the GVSP header is valid.

IsLargeLeaderTrailerEnabled()

Returns whether this buffer has large data leader and data trailer enabled.

If the buffer is used for Multi-Part streaming, the maximum allowed number of parts is limited by whether Large data leader and trailer is enabled.

Return type:

boolean

Returns:

True if the Large Data Leader and Trailer is enabled on the buffer which contains Multi-part.

class eBUS.PvBufferConverter(aMaxNumberOfThreads=-1)

Bases: object

Used to convert a PvBuffer to another pixel type.

To change an image’s format:

  • Acquire an image. See PvStream.RetrieveBuffer.

  • Create an image-format converter (PvBufferConverter object). Use PvBufferConverter.PvBufferConverter.

  • Test if you can convert your image to your preferred pixel type. Use #IsConversionSupported.

    For your source pixel type, use PvImage.GetPixelType; for your destination, select an enumeration from PvPixelType.h.

  • Create a destination buffer. See PvBuffer (you define the destination image’s pixel type during this step).

  • Optionally, configure options like Bayer filtering, use #SetBayerFilter.

  • Convert the image to the new pixel type. Use #Convert.

Consult the PvPixelType documentation in order to find which pixel types are supported as conversion destinations.

property thisown

The membership flag

__init__(aMaxNumberOfThreads=-1)

Constructor.

Parameters:

aMaxNumberOfThreads (int, in, optional) – Maximum number of threads the buffer converter is allowed to use in order to speed up conversion. If 0 or smaller than 0, one thread per processor is assumed. Threads have no specific processor affinity.

static IsConversionSupported(aSource, aDestination)

Test if a pixel type can be converted to another type.

Converting from one pixel type to another isn’t a trivial mathematical calculation - all conversions require specialized, dedicated algorithms.

The #IsConversionSupported method tests if the #Convert method has an available conversion algorithm.

Parameters:

  • aSource (int, in) – The original pixel type. For available pixel types, see PvPixelType.h.

  • aDestination (int, in) – The new pixel type. See aSource.

Return type:

boolean

Returns:

True if #Convert has an available conversion algorithm; otherwise, false.

Convert(*args) → PvResult, PvBuffer

To convert the Pixel Type, you should create a destination image/buffer and define the destination image’s pixel type first before calling this API.

Overload 1:

Convert a buffer from one format to another.

Parameters:

  • aSource (PvBuffer, in) – The original image/buffer.

  • aDestination (PvBuffer, in) – The destination image/buffer to convert to.

  • aReallocIfNeeded (boolean, in, optional) – Depending on the conversion, the memory footprint of the new image may be greater than aDestination current size. By setting this parameter to true, the buffer is re-allocated if aDestination is too small. If aDestination memory buffer is not owned by the PvBuffer and is too small, #Convert fails.

  • aFlipY (boolean, in, optional) – When performing the conversion, flips the image on its Y axis.

Return type:

Tuple(PvResult, PvBuffer)

Returns:

Tuple composed of (result, pvbuffer_destination)


Overload 2:

Convert a buffer from one format to another.

Parameters:

  • aSource (IPvImage, in) – The original image.

  • aDestination (IPvImage, in) – The destination image to convert to.

  • aReallocIfNeeded (boolean, in, optional) – Depending on the conversion, the memory footprint of the new image may be greater than aDestination current size. By setting this parameter to true, the buffer is re-allocated if aDestination is too small. If aDestination memory buffer is not owned by the PvBuffer and is too small, #Convert fails.

  • aFlipY (boolean, in, optional) – When performing the conversion, flips the image on its Y axis.

Return type:

Tuple(PvResult, PvBuffer)

Returns:

Tuple composed of (result, pvbuffer_destination)

GetBayerFilter()

Retrieves current optional Bayer filtering.

See #SetBayerFilter

Return type:

int

Returns:

The Bayer filter’s type; a PvBayerFilterType enumeration.

SetBayerFilter(aFilter)

Set the optional Bayer filtering for this converter.

Of course, only applies if the #Convert method uses a PvBuffer having a Bayer pixel type. Simply ignored otherwise.

Parameters:

aFilter (int, in) – The new filter settings; a PvBayerFilterType enumeration.

Return type:

PvResult

Returns:

Includes:

ResetRGBFilter()

Resets the RGB filter used for conversion (if any)

Return type:

PvResult

Returns:

Includes:

SetRGBFilter(aFilter)

Assigns a RGB filter to be used during conversion

Parameters:

aFilter (PvBufferConverterRGBFilter, in) – The RGB filter to be used during conversion.

Return type:

PvResult

Returns:

Includes:

GetConversionThreadsPriority()

Get the priority of the threads doing the conversion in background

See #SetConversionThreadsPriority for details about the meaning of the values returned

Return type:

int

Returns:

The priority of the thread

SetConversionThreadsPriority(aPriority)

Set the priority of the threads doing the conversion

By default one conversion thread is created for each processing core of the system. We only allow setting priority for the threads of one converter object as a group.

If you change the thread priorities, it may alterate the stability of the system. For this reason, if you report a bug to Pleora, ensure to clearly mention that you change threads priorities.

See #GetConversionThreadsPriority

Parameters:

aPriority (int, in) – See PvPipeline.SetBufferHandlingThreadPriority for description of the supported values

Return type:

PvResult

Returns:

Includes:

class eBUS.PvBufferConverterRGBFilter

Bases: object

Contains a RGB filter configuration that can be used with a PvBufferConverter.

To configure an RGB filter (manual):

  • Create an RGB filter controller.

  • Set the filter’s values. Use SetGain* and SetOffset* methods. See #SetGainB.

To configure a white balance filter (automatic):

  • Create an RGB filter object.

  • Calculate and apply white-balance settings. Use #WhiteBalance.

property thisown

The membership flag

__init__()

Constructor.

GetGainR()

Get the filter’s gain (red).

See #SetGainB.

Return type:

float

Returns:

See #SetGainB.

GetGainG()

Get the filter’s gain (green).

See #SetGainB.

Return type:

float

Returns:

See #SetGainB.

GetGainB()

Get the filter’s gain (blue).

See #SetGainB.

Return type:

float

Returns:

See #SetGainB.

SetGainR(aValue)

Set the filter’s gain (red)

See #SetGainB.

Parameters:

aValue (float, in) – See #SetGainB.

SetGainG(aValue)

Set the filter’s gain (green)

See #SetGainB.

Parameters:

aValue (float, in) – See #SetGainB.

SetGainB(aValue)

Set the filter’s gain (blue).

The SetGain* and SetOffset methods let you control the transformation made by the filter, for the colors red, green, and blue.

The transformation uses the form:

x’ = kx + y

where:

  • x’ is the modified color level (for one of red, blue, or green)

  • x is the original color level (for one of red, blue, or green)

  • k is the level multiplier

  • y is the offset

To set a filter’s values, use:

  • #SetGainB

  • #SetGainG

  • #SetGainR

  • #SetOffsetB

  • #SetOffsetG

  • #SetOffsetR

To get a filter’s values, use:

  • #GetGainB

  • #GetGainG

  • #GetGainR

  • #GetOffsetB

  • #GetOffsetG

  • #GetOffsetR

type aValue:

float, in

param aValue:

The new gain (blue).

GetOffsetR()

Get the filter’s offset (red).

See #SetGainB.

Return type:

int

Returns:

See #SetGainB.

GetOffsetG()

Get the filter’s offset (green).

See #SetGainB.

Return type:

int

Returns:

See #SetGainB.

GetOffsetB()

Get the filter’s offset (blue).

See #SetGainB.

Return type:

int

Returns:

See #SetGainB.

SetOffsetR(aValue)

Set the filter’s offset (red)

See #SetGainB.

Parameters:

aValue (int, in) – See #SetGainB.

SetOffsetG(aValue)

Set the filter’s offset (green)

See #SetGainB.

Parameters:

aValue (int, in) – See #SetGainB.

SetOffsetB(aValue)

Set the filter’s offset (blue)

See #SetGainB.

Parameters:

aValue (int, in) – See #SetGainB.

WhiteBalance(aBuffer)

Calculate white-balance gains.

The #WhiteBalance method receives an image and calculates appropriate gains to white-balance the image. This method sets the gains as if having called #SetGainB, #SetGainG, and #SetGainR.

Internally, the #WhiteBalance method uses the following procedure:

  • Calculate the average colors in the image: Bavg, Gavg, Ravg.

  • Select the maximum of the three averages: Max = max (Bavg, Gavg, Ravg).

  • Set the new gains, where:

    • Bgain = Max / Bavg

    • Ggain = Max / Gavg

    • Rgain = Max / Ravg

The #WhiteBalance method produces the best results for images that have an even mix of dark and light tones, and an even mix of colors.

Parameters:

aBuffer (PvBuffer, in) – The sample image; the image upon which to base the white-balance settings.

Return type:

PvResult

Returns:

Includes:

Reset()

Reset the RGB filter configuration.

This method resets the RGB filter configuration (PvBufferConverterRGBFilter) to its default values.

Gains are set to 1; offsets, to 0. After a reset, applying the filter doesn’t change the image.

class eBUS.PvChunkData(*args, **kwargs)

Bases: IPvChunkData

Raw data interface to a PvBuffer.

A PvBuffer represents a generic buffer with no specific payload type. If the payload type is chunk data, the user can obtain a pointer to a PvChunkData buffer interface through PvBuffer.GetChunkData.

This PvChunkData pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

To use in a receiver context, retrieve PvBuffer from PvStream or PvPipeline and when PvBuffer.GetPayloadType is PvPayloadChunkData use PvBuffer.GetChunkData to retrieve a pointer to this interface. Use the various chunk methods in this class to access the chunk data by ID or index or alternatively attach the PvBuffer to the GenApi interface of the transmitter with PvGenParameterArray.AttachDataChunks to access the chunk data using GenApi.

To use in a transmitter context, create a PvBuffer, set its payload type to PvPayloadTypeChunkData in the constructor. Use PvBuffer.GetChunkData to retrieve a point to this interface, use PvChunkData::Alloc to allocate enough memory for all chunks and their headers (64 bytes per chunk for the headers) and then add chunks to the buffer using PvChunkData.AddChunk. Use PvTransmitterGEV to transmit the buffer.

property thisown

The membership flag

__init__(*args, **kwargs)
GetChunkDataPayloadLength()

Get the chunk data payload length specified in the trailer information of this block.

Return type:

int

Returns:

The payload length specified in the trailer information of this block.

Alloc(aMaximumChunkLength)

Allocates memory for this PvChunkData.

Allocs a PvChunkData of specific payload length. No extra data can or need to be priovisioned for chunks as the whole payload is made of chunks.

Parameters:

aMaximumChunkLength (int, in) – Maximum size in bytes to store chunk data (must include extra 64 bits for each chunk header).

Return type:

PvResult

Returns:

Includes:

Free()

Frees (de-allocates) the buffer’s internal memory.

Attach(self, aRawBuffer) → PvResult

Attach this PvChunkData to an external memory buffer.

Parameters:

aRawBuffer (ndarray, in) – A 1-dimensional python numpy array with dtype np.uint8 to use as a buffer.

Return type:

PvResult

Returns:

Includes:

See also: Detach

Detach(self) → ndarray

Releases an attached memory buffer. Does nothing other then resetting the memory buffer pointer to NULL.

Return type:

ndarray

Returns:

The previously attached numpy array. See PvChunkData.Attach.

See also: Attach

class eBUS.PvCompressionFilter

Bases: object

Filter used for image compression.

property thisown

The membership flag

__init__()

Constructor.

Execute(aIn, aOut)

Convert(self, aIn, aOut) -> PvResult, PvBuffer

To compress an image using Pleora Compression, you should create a destination buffer first before calling this API.

Execute Pleora compression on a PvBuffer that is an image.

Parameters:

  • aIn (PvBuffer, in) – The original image buffer.

  • aOut (PvBuffer, in) – The buffer with the Pleora compressed data.

Return type:

Tuple(PvResult, PvBuffer)

Returns:

Tuple composed of (result, aOut)

SetThreadCount(aCount)

Sets the maximum of threads to use for compression. Not supported for compression.

Parameters:

aCount (int) – [in] How many threads to use for compression.

Return type:

PvResult

Returns:

Includes: - PV_NOT_SUPPORTED the compression filter does not support multi-threading.

GetThreadCount()

Returns how many threads are used for compression.

Return type:

int

Returns:

How many threads are used for compression.

GetThreadsPriority(aPriority)

Gets the thread priority of the filter’s worker threads.

Parameters:

aPriority (int) – [out] Output reference to the worker threads priority.

Return type:

PvResult

Returns:

Includes: - PV_OK - PV_NOT_SUPPORTED if the filter does not support multi-threading.

SetThreadsPriority(aPriority)

Sets the thread priority of the filter’s worker threads.

Only one worker thread is created. Setting thread priority isn’t supported.

Return type:

PvResult

Returns:

Includes: - PV_OK - PV_NOT_SUPPORTED if the filter does not support multi-threading. - PV_INVALID_PARAMETER if aPriority maps to nothing on the target system.

SetEncoding(aValue)

Sets the encoding used when compressing the image.

Parameters:

aValue (int) – [in] Encoding to be used by the filter.

Return type:

PvResult

Returns:

Includes: - PV_OK - PV_NOT_SUPPORTED if the requested encoding is not supported.

GetEncoding()

Returns the encoding used when compressing the image.

class eBUS.PvDecompressionFilter

Bases: object

Filter used for image decompression.

property thisown

The membership flag

__init__()

Constructor.

Execute(aIn, aOut)

Convert(self, aIn, aOut) -> PvResult, PvBuffer

To decompress the Pleora Compressed data, you should create a destination buffer first before calling this API.

Execute decompression on a Pleora compressed buffer.

Parameters:

  • aIn (PvBuffer, in) – The original Pleora compressed buffer.

  • aOut (PvBuffer, in) – The buffer for the decompressed image.

Return type:

Tuple(PvResult, PvBuffer)

Returns:

Tuple composed of (result, aOut)

SetThreadCount(aCount)

Sets the maximum of threads to use for decompression.

Parameters:

aCount (int) – [in] How many threads to use for decompression. Min: 1, Max: 64.

Return type:

PvResult

Returns:

Includes: - PV_OK - PV_INVALID_PARAMETER if aCount is not valid. - PV_NOT_ENOUGH_MEMORY if all threads could not be allocated. - PV_NOT_SUPPORTED if the filter does not support multi-threading.

GetThreadCount()

Returns how many threads are used for decompression.

Return type:

int

Returns:

How many threads are used for decompression.

GetThreadsPriority(aPriority)

Gets the thread priority of the filter’s worker threads.

Parameters:

aPriority (int) – [out] Output reference to the worker threads priority.

Return type:

PvResult

Returns:

Includes: - PV_OK - PV_NOT_SUPPORTED if the filter does not support multi-threading.

SetThreadsPriority(aPriority)

Sets the thread priority of the filter’s worker threads.

The default is 3 - THREAD_PRIORITY_NORMAL, see PvPipeline::SetBufferHandlingThreadPriority(). We only allow setting priority for the threads of one converter object as a group. By default one worker thread is created for half of the total number of logical CPUs of the system.

If you change the thread priorities, it may alterate the stability of the system. For this reason, if you report a bug to Pleora, ensure to clearly mention that you change threads priorities.

Return type:

PvResult

Returns:

Includes: - PV_OK - PV_NOT_SUPPORTED if the filter does not support multi-threading. - PV_INVALID_PARAMETER if aPriority maps to nothing on the target system.

static IsCompressed(aIn)

Returns true if the buffer can be decompressed using an object of this class.

Parameters:

aIn (PvBuffer) – [in] Buffer to inspect.

Return type:

boolean

Returns:

True if the buffer can be decompressed.

static GetOutputFormatFor(aIn)

Convert(self, aIn) -> PvResult, PvPixelType, int, int

Retrieve image format from Pleora compressed header.

Parameters:

aIn (PvBuffer, in) – The Pleora compressed buffer.

Return type:

Tuple(PvResult, PvPixelType, int, int)

Returns:

Tuple composed of (result, aPixelType, aWidth, aHeight)

class eBUS.PvDevice(*args, **kwargs)

Bases: object

Connect, configure and control a GigE Vision or USB3 Vision device.

It is not possible to instantiate a generic PvDevice. PvDeviceGEV and PvDeviceU3V can be instantiated directly.

If order to write hybrid code one could use the static CreateAndConnect methods. These methods dynamically allocated a PvDevice of the right type to connect to the requested device. Just remember to free the dynamically allocated device object using the static Free method.

property thisown

The membership flag

__init__(*args, **kwargs)
static CreateAndConnect(*args) → PvResult, PvDevice

Dynamically allocates a PvDevice of the right type.

Objects allocated with CreateAndConnect should be freed with PvDevice.Free.

Overload 1:

This static method takes PvDeviceInfo identifying a device, creates the right type of PvDevice (PvDeviceGEV or PvDeviceU3V) and connects it.

Parameters:

aDeviceInfo (PvDeviceInfo, in) – The GigE Vision devices network connectivity information.

Return type:

Tuple(PvResult, PvDevice)

Returns:

Tuple composed of (result, pvdevice)


Overload 2:

This static method takes a string identifying a device, creates the right type of PvDevice (PvDeviceGEV or PvDeviceU3V) and connects it.

Parameters:

aInfo (str, in) – String identifying the device. See PvDevice.Connect for more information.

Return type:

Tuple(PvResult, PvDevice)

Returns:

Tuple composed of (result, pvdevice)

static Free(aDevice)

Frees an object allocated with CreateAndConnect.

Even though calling delete on a PvDevice created with CreateAndConnect should work in most cases, sometime it is necessary to call “delete” in the same context where “new” was called to avoid false positives on memory leaks.

It is a good practice to use this method to free a PvDevice allocated with CreateAndConnect.

Parameters:

aDevice (PvDevice, in) – Pointer to the device object to delete.

GetType()

Returns the type of the instantiated device.

Return type:

int

Returns:

Type of device controller. See PvDeviceType enum

Connect(*args)

Overload 1:

Connect to a GigE Vision or USB3 Vision device.

The #Connect method connects to a GigE Vision device found using a PvSystem or device finder dialog object. Only one device can be connected to at a time.

Parameters:

aDeviceInfo (PvDeviceInfo, in) – The GigE Vision device’s network connectivity information; a PvDeviceInfo object.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Connect to a GigE Vision or USB3 Vision device.

If you know the GigE Vision device’s IP address, MAC address or DeviceUserID, you can use this method to connect to it.

If you know the USB3 Vision device’s GUID or DeviceUserID, you can use this method to connect it.

  • If aInfo contains an IP address, the connection attempt connecting a GigE Vision device is direct.

  • If aInfo contains a MAC address:

    • An internal PvSystem is used to find all reachable GigE Vision devices

    • Found devices are browsed, looking for a match on the MAC address

    • If the device is found, connection is attempted.

  • If aInfo contains a USB3 Vision GUID:

    • All USB3 Vision devices are enumerated

    • Found devices are browsed, looking for a match on the GUID

    • If the device is found, connection is attempted.

  • If aInfo contains a device user ID:

    • All GigE Vision and USB3 Vision are enumerated

    • Found devices are browsed, looking for a match on device user ID

    • If the device is found, connection is attempted.

Parameters:

aInfo (str, in) – Information that uniquely identifies the device. You may use one of the following: - GigE Vision device’s MAC address. Use the form 00:11:22:33:44:5F. - GigE Vision device’s IP Address. Use the form 192.168.1.114. - GigE Vision or USB3 Vision device’s DeviceUserID. - USB3 Vision GUID.

Return type:

PvResult

Returns:

Includes:

Disconnect()

Disconnect the PvDevice object from the GigE Vision or USB3 Vision device to which it is currently connected.

Return type:

PvResult

Returns:

Includes:

See also: Connect

StreamEnable(aChannel=0)

Enables streaming on the device.

For GigE Vision devices, this takes care of setting the TLParamsLocked so that changes to streaming related parameters are prevent in the GenICam interface of the device.

For USB3 Vision devices, this takes care of the TLParamsLocked, configures the driver for streaming and sets the streaming enable bit on the device.

After calling StreamEnable, the user must still execute the AcquisitionStart GenICam command of the device to instruct the device to begin acquisition.

Parameters:

aChannel (int, in, optional) – The channel on which to enable streaming.

Return type:

PvResult

Returns:

Includes:

StreamDisable(aChannel=0)

Disables streaming on the device.

For GigE Vision devices, this takes care of resetting the TLParamsLocked so that changes to streaming related parameters are possible again.

For USB3 Vision devices, this takes care of the TLParamsLocked and sets the streaming enable bit on the device.

StreamDisable should be called after the AcquisitionStop GenICam command has been executed and all images have been received.

Parameters:

aChannel (int, in, optional) – The channel on which to enable streaming.

Return type:

PvResult

Returns:

Includes:

IsConnected()

Test if this PvDevice is currently connected to a GigE Vision or USB3 Vision device.

Return type:

boolean

Returns:

True if this PvDevice is currently connected to a GigE Vision or USB3 Vision device otherwise, false.

IsPleoraPowered()

Test if this PvDevice is currently connected to a Pleora powered GigE Vision or USB3 Vision device.

Return type:

boolean

Returns:

True if this PvDevice is currently connected to a Pleora powered GigE Vision or USB3 Vision device, false otherwise.

DumpGenICamXML(aFilename)

Save the GigE Vision or USB3 Visio device’s GenICam XML file to disk.

If the XML is stored in a zip file on the device, the zip file containing the XML is saved on the disk.

Parameters:

aFilename (str) – The file’s name.

Return type:

PvResult

Returns:

Includes:

GetDefaultGenICamXMLFilename() → PvResult, str

Returns a good default filename to use with DumpGenICamXML.

The filename is built from the URL that was used in order to locate the GenICam XML file of the device.

Return type:

Tuple(PvResult, string)

Returns:

Tuple composed of (result, filename)

GetParameters()

Get the parameters used to control the GigE Vision or USB3 Vision device to which you are connected.

Each device provides its own GenICam XML file with parameters describing its behaviour referred to as features. The PvGenParameterArray object returned by this method provides an interface to these features.

Return type:

PvGenParameterArray

Returns:

The parameters used to control the GigE Vision device to which you are connected

GetCommunicationParameters()

Get the parameters used to define how PvDevice connects to and communicates with the device.

For a listing of all the available parameters, refer to GEV Device Communication Parameters (“devicecommunicationGEV.html”)

or U3V Device Communication Parameters (“devicecommunicationU3V.html”)

Return type:

PvGenParameterArray

Returns:

The parameters used to define how PvDevice connects to and communicates with the device

ReadMemory(aAddress, aByteCount) → PvResult, ndarray

Reads bytes starting at a specific register address on the GigE Vision or USB3 Vision device.

See warnings about accessing the register map directly in #WriteMemory.

Parameters:

  • aAddress (int, in) – Start address of the read memory operation (mod 4).

  • aByteCount (int, in) – Bytes to read from the device (mod 4, non 0).

Return type:

Tuple(PvResult, ndarray)

Returns:

Tuple composed of (result, abuffer)

WriteMemory(aAddress, aByteCount) → PvResult

Returns a unique string identifier for the device.

Parameters:

  • aAddress (int, in) – Start address of the read memory operation (mod 4).

  • aSource (ndarray, in) – A 1-dimensional python numpy array with dtype np.uint8 describing the data to write to the device.

Return type:

PvResult

Returns:

WaitForMessagingChannelIdle(aTimeout)

Waits for the messaging channel to become idle.

This method returns once the host-side messaging channel in-queue is empty or aTimeout (ms) has elapsed.

Parameters:

aTimeout (int, in) – Maximum time to wait, in ms.

Return type:

PvResult

Returns:

Includes:

RegisterEventSink(aEventSink)

Register an event sink used for callbacks.

Parameters:

aEventSink (PvDeviceEventSink, in) – A pointer to the event sink.

Return type:

PvResult

Returns:

Includes:

UnregisterEventSink(aEventSink)

Unregister an event sink

Parameters:

aEventSink (PvDeviceEventSink, in) – A pointer to the event sink.

Return type:

PvResult

Returns:

Includes:

GetHeartbeatThreadPriority()

Get the priority of the heartbeat thread

See #SetHeartbeatThreadPriority for details about the meaning of the values returned

Return type:

int

Returns:

The priority of the thread

SetHeartbeatThreadPriority(aPriority)

Set the priority of the heartbeat thread

The heartbeat thread priority is critical to most applications. This thread must never starve against any other system thread to the risk of losing the device connection.

This thread takes all messages queued for deferred processing by the interrupt link thread and fires all GenApi and PvDeviceEventSink callback. All callbacks are fired/run in the context of this thread.

See #GetHeartbeatThreadPriority

Parameters:

aPriority (int, in) – See PvPipeline.SetBufferHandlingThreadPriority for description of the supported values

Return type:

PvResult

Returns:

Includes:

GetInterruptLinkThreadPriority()

Get the priority of the interrupt link thread

See #SetInterruptLinkThreadPriority for details about the meaning of the values returned

Return type:

int

Returns:

The priority of the thread

SetInterruptLinkThreadPriority(aPriority)

Set the priority of the interrupt link thread

Interrupt link thread receives messaging channel packets from the device, sends acknowledge back and queues the message in the interrupt queue. Process and callbacks are not done from this thread.

This thread takes all messages queued for deferred processing by the interrupt link thread and fires all GenApi and PvDeviceEventSink callback. All callbacks are fired/run in the context of this thread.

See #GetInterruptLinkThreadPriority

Parameters:

aPriority (int, in) – See PvPipeline.SetBufferHandlingThreadPriority for description of the supported values

Return type:

PvResult

Returns:

Includes:

GetInterruptQueueThreadPriority()

Get the priority of the interrupt queue thread

See #SetInterruptQueueThreadPriority for details about the meaning of the values returned

Return type:

int

Returns:

The priority of the thread

SetInterruptQueueThreadPriority(aPriority)

Set the priority of the interrupt queue thread

This thread is simply used to fire/invoke the OnLinkDisconnected and OnLinkReconnected PvDeviceEventSink events.

This thread takes all messages queued for deferred processing by the interrupt link thread and fires all GenApi and PvDeviceEventSink callback. All callbacks are fired/run in the context of this thread.

See #GetInterruptQueueThreadPriority

Parameters:

aPriority (int, in) – See PvPipeline.SetBufferHandlingThreadPriority for description of the supported values

Return type:

PvResult

Returns:

Includes:

GetPayloadSize()

Returns the payload size the device is currently configured to stream with.

This method attempts to read the GenICam PayloadSize parameter of the device. If the operation fails the payload size is computed from width, height and pixel format as a fall back. If even this fails, a value that is still valid to allocate buffers is finally returned.

Return type:

int

Returns:

The recommended payload size. 0 can only be returned if the device is not connected.

GetUniqueID() → PvResult, str

Returns a unique string identifier for the device.

Return type:

Tuple(PvResult, string)

Returns:

Tuple composed of (result, uniqueID)
  • result representing the outcome:
  • uniqueID:

    • A unique str indentifier for the device.

class eBUS.PvDeviceAdapter(aDevice)

Bases: object

IPvDeviceAdapter default implementation for the eBUS SDK.

The IPvDeviceAdapter interface can be implemented for any SDK that can control GigE Vision and/or USB3 Vision devices in order to use PvDeviceSerialPort.

PvDeviceAdapter provides a default implementation of the IPvDeviceAdapter that can be used with the eBUS SDK.

property thisown

The membership flag

__init__(aDevice)

Constructor.

Parameters:

aDevice (PvDevice, in) – A device.

IsGenIntegerInNodeMap(aParameterName)

See IPvDeviceAdapter for description.

Parameters:

aParameterName (str, in) – Name of the parameter to test for.

Return type:

boolean

Returns:

True if the parameter is present, false if not.

IsGenEnumInNodeMap(aParameterName)

See IPvDeviceAdapter for description.

Parameters:

aParameterName (str, in) – Name of the parameter to test for.

Return type:

boolean

Returns:

True if the parameter is present, false if not.

IsGenBooleanInNodeMap(aParameterName)

See IPvDeviceAdapter for description.

Parameters:

aParameterName (str, in) – Name of the parameter to test for.

Return type:

boolean

Returns:

True if the parameter is present, false if not.

IsGenRegisterInNodeMap(aParameterName)

See IPvDeviceAdapter for description.

Parameters:

aParameterName (str, in) – Name of the parameter to test for.

Return type:

boolean

Returns:

True if the parameter is present, false if not.

IsGenReadable(aParameterName)

See IPvDeviceAdapter for description.

Parameters:

aParameterName (str, in) – Name of the parameter to test for.

Return type:

boolean

Returns:

True if the parameter is present and readable, false if either condition fails.

IsGenWritable(aParameterName)

See IPvDeviceAdapter for description.

Parameters:

aParameterName (str, in) – Name of the parameter to test for.

Return type:

boolean

Returns:

True if the parameter is present and writable, false if either condition fails.

IsGenEnumEntryAvailable(aParameterName, aEnumEntry)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter to test for.

  • aEnumEntry (str, in) – Name of the enum entry to test for.

Return type:

boolean

Returns:

True if the parameter is present and contains the specific enum entry, false if either condition fails.

GetGenIntegerValue(aParameterName, aValue)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aValue (int, out) – Value of the parameter.

Return type:

PvResult

Returns:

OK on success.

GetGenEnumEntriesAvailable(aParameterName, aList)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aList (PvStringList, out) – A list containing the string representation of all available enum entries.

Return type:

PvResult

Returns:

OK on success.

GetGenEnumValue(aParameterName, aEnumEntry)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aEnumEntry (str, out) – Value of the parameter.

Return type:

PvResult

Returns:

OK on success.

SetGenEnumValue(aParameterName, aEnumEntry)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aEnumEntry (str, in) – New value for the enumeration.

Return type:

PvResult

Returns:

OK on success.

GetGenBooleanValue(aParameterName, aValue)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aValue (boolean, out) – Value of the parameter.

Return type:

PvResult

Returns:

OK on success.

SetGenBooleanValue(aParameterName, aValue)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aValue (boolean, in) – New value for the enumeration.

Return type:

PvResult

Returns:

OK on success.

GetGenStringValue(aParameterName, aValue)

Returns the string value of string parameter identified by its name.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aValue (str, out) – Value of the parameter.

Return type:

PvResult

Returns:

OK on success.

GetGenRegisterLength(aParameterName, aLength)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aLength (int, in) – Length (in bytes) of the register.

Return type:

PvResult

Returns:

OK on success.

GetGenRegisterData(aParameterName, aDataBuffer, aByteCount)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aDataBuffer (uint8_t, out) – Buffer where to copy the data.

  • aByteCount (int, in) – How many bytes to copy to aDataBuffer.

Return type:

PvResult

Returns:

OK on success.

SetGenRegisterData(aParameterName, aDataBuffer, aByteCount)

See IPvDeviceAdapter for description.

Parameters:

  • aParameterName (str, in) – Name of the parameter.

  • aDataBuffer (uint8_t, out) – Buffer to copy the data from.

  • aByteCount (int, in) – How many bytes to copy from aDataBuffer to the register.

Return type:

PvResult

Returns:

OK on success.

RegisterGenInvalidator(aParameterName)

See IPvDeviceAdapter for description.

Parameters:

aParameterName (str, in) – Name of the parameter.

Return type:

PvResult

Returns:

OK on success.

UnregisterGenInvalidator(aParameterName)

See IPvDeviceAdapter for description.

Parameters:

aParameterName (str, in) – Name of the parameter.

Return type:

PvResult

Returns:

OK on success.

WriteRegister(aAddress, aValue)

See IPvDeviceAdapter for description.

Parameters:

  • aAddress (int, in) – Address of the register.

  • aValue (int, in) – Value to write to the register.

Return type:

PvResult

Returns:

OK on success.

ReadRegister(aAddress)

See IPvDeviceAdapter for description.

Parameters:

  • aAddress (int, in) – Address of the register.

  • aValue (int, out) – Value read from the register.

Return type:

PvResult

Returns:

OK on success.

WriteMemory(aBuffer, aAddress, aLength)

See IPvDeviceAdapter for description.

Parameters:

  • aBuffer (uint8_t, in) – Pointer to the data to write.

  • aAddress (int, in) – Address where to write the data.

  • aLength (int, in) – Length of the data to write, in bytes.

Return type:

PvResult

Returns:

OK on success.

ReadMemory(aBuffer, aAddress, aLength)

See IPvDeviceAdapter for description.

Parameters:

  • aBuffer (uint8_t, in) – Pointer of the buffer where the data will be written.

  • aAddress (int, in) – Address where to read the daa.

  • aLength (int, in) – Length of the data to read, in bytes.

Return type:

PvResult

Returns:

OK on success.

WaitForMessagingChannelIdle(aTimeout)

See IPvDeviceAdapter for description.

Parameters:

aTimeout (int, in) – A timeout.

Return type:

PvResult

Returns:

OK if the messaging channel is idle. TIMEOUT if the timeout elapsed before it becomes idle.

IsConnected()

See IPvDeviceAdapter for description.

Return type:

boolean

Returns:

True if the device is connected, false if not.

IsPleoraPowered()

See IPvDeviceAdapter for description.

Return type:

boolean

Returns:

True if the device runs on a Pleora design, false if not.

IsGigEVision()

See IPvDeviceAdapter for description.

Return type:

boolean

Returns:

True if using the GigE Vision protocol, false if not.

IsUSB3Vision()

See IPvDeviceAdapter for description.

Return type:

boolean

Returns:

True if using the USB3 Vision protocol, false if not.

RegisterEventSink(aEventSink)

See IPvDeviceAdapter for description.

Parameters:

aEventSink (IPvDeviceEventSink, in) – Pointer to an object implementing the IPvDeviceEventSink interface.

Return type:

PvResult

Returns:

OK on success.

UnregisterEventSink(aEventSink)

See IPvDeviceAdapter for description.

Parameters:

aEventSink (IPvDeviceEventSink, in) – Pointer to an object implementing the IPvDeviceEventSink interface.

Return type:

PvResult

Returns:

OK on success.

GetUniqueID()

Returns a unique string identifier for the device.

Parameters:

aID (str, out) – Unique string identifier for the device.

Return type:

PvResult

Returns:

Includes:

class eBUS.PvDeviceEventSink

Bases: object

Observer interface for an observable PvDevice object

PvDeviceEventSink defines a set of callback methods from a PvDevice object to any object implementing this interface.

## GigE Vision Recovery

A PvDeviceGEV object continually sends a heartbeat message every HeartbeatInterval (“devicecommunicationGEV.html#HeartbeatInterval”) milliseconds to the connected GigE Vision device to maintain its control channel privilege and ensure that the two entities are aware of each other’s continued existence.

If the GigE Vision device fails to receive a heartbeat message after a given period of time (see the GevHeartbeatTimeout GigE Vision parameter and DefaultHeartbeatTimeout (“devicecommunicationGEV.html#DefaultHeartbeatTimeout”)), it loses its control channel privilege so that another controller may connect to the device in the event of a connection loss.

Each heartbeat sent by the PvDeviceGEV object is acknowledged by the device. If the GigE Vision device fails to respond to the heartbeat (within AnswerTimeout (“devicecommunicationGEV.html#AnswerTimeout”) milliseconds) after CommandRetryCount (“devicecommunicationGEV.html#CommandRetryCount”) retries, it considers itself disconnected and notifies any registered PvDeviceEventSink objects using the #OnLinkDisconnected callback.

Device recovery (or reconnection) must be performed at the application level. After a #OnLinkDisconnected callback, the current session should be cleaned up (disconnecting or deleting your PvDevice controller, closing your PvStream, etc.) and you should start polling with FindDevice from PvSystem to see when the device is available again. When the device is available, reconnect and restore any previously known good application configuration.

For a complete working example of how to initiate recovery and continue streaming in the event of a connection loss, refer to the ConnectionRecovery sample.

## USB3 Vision Recovery

A PvDeviceU3V object continually sends a heartbeat message every HeartbeatInterval (“devicecommunicationU3V.html#HeartbeatInterval”) milliseconds to the connected USB3 Vision device to ensure that the two entities are aware of each other’s continued existence.

If a PvDeviceU3V fails to respond to the heartbeat (within AnswerTimeout (“devicecommunicationU3V.html#AnswerTimeout”) milliseconds), it considers itself disconnected and notifies any registered PvDeviceEventSink objects using the #OnLinkDisconnected callback.

USB3 Vision devices do not require the heartbeat. There is no concept of control channel or even a heartbeat being required in order to keep the control channel opened. The heartbeat is only used for the host to know that the device is still connected and responsive.

See GigE Vision section above for instructions on how to perform application level recovery after a disconnect event.

## Messaging channel events

To receive raw events notifications:

  • Create an instance of your MySink class.

  • Connect to the GigE Vision device as you normally would. See PvDevice.

  • Register your MySink class with the PvDevice object. Use PvDevice.RegisterEventSink.

  • Control the GigE Vision device as you normally would. See PvDevice.

  • Handle events when PvDevice calls your #OnEvent overridden method.

property thisown

The membership flag

__init__()

Constructor.

OnLinkDisconnected(aDevice)

Notification that the PvDevice unexpectedly lost contact with the device.

Parameters:

aDevice (PvDevice, in) – Pointer to the device object that invoked this callback.

OnLinkReconnected(aDevice)

Deprecated, no longer used.

PvDevice no longer attempts automatic reconnection. After receiving an #OnLinkDisconnected notification, it is recommend to properly complete disconnection at the application level and then either attempting reconnection until it succeeds or trying find the device in a loop with PvSystem.FindDevice until it succeeds and then finally reconnecting PvDevice, re-opening PvStream, etc.

Parameters:

aDevice (PvDevice, in) – Pointer to the device object that invoked this callback.

OnEvent(aDevice, aEventID, aChannel, aBlockID, aTimestamp, aData)

Messaging channel raw event notification.

This #OnEvent handler lets users access the raw GigE Vision or USB3 Vision event before it is forwarded to the GenApi layer.

Notes: This callback is an advanced feature that should only be used by developers who are aware of the event IDs that are being sent from their device. It is recommended to use OnEventGenICam whenever possible.

Depending on the nature of the event being received, there may be data returned that is pointed to by aData (otherwise aData is None). This additional data is received on the wire in the device’s Endianess.

All other parameters are provided in the Endianess of the host.

Parameters:

  • aDevice (PvDevice, in) – PvDevice object that triggered the callback.

  • aEventID (int, in) – Event ID. Some standard event IDs are defined but usually device dependent.

  • aChannel (int, in) – Streaming channel associated with the event, if any. 0xFFFF is used if the event is not associated to a streaming channel.

  • aBlockID (int, in) – Streaming block ID associated with the event, if any. Can be used to pair one or more than one event with a block received from a device. 0 is used if the event is not associated to a block.

  • aTimestamp (int, in) – Timestamp of the event on the time domain of the device. Time unit is defined by the device. 0 if timestamps are not supported by the device that generated the event.

  • aData (ndarray, in) – A 1-dimensional python numpy array with dtype np.uint8 describing the event Data, if applicable. (None otherwise).

OnEventGenICam(aDevice, aEventID, aChannel, aBlockID, aTimestamp, aData)

Messaging channel GenICam event notification.

This #OnEvent handler lets users access the event as mapped through the GenApi interface of the device.

Unlike the other OnEvent that provides a pointer to the raw event data, the data is provided as a list of GenApi parameters that have been invalidated when the event has been attached to the GenApi node map of the device.

If events with no data or events with data not mapped in the GenApi interface of the device are received, this callback is still invoked by the parameter list containing is not provided, it is simply set to NULL.

Parameters:

  • aDevice (PvDevice, in) – Pointer to the PvDevice object that triggered the callback.

  • aEventID (int, in) – Event ID. Some standard event IDs are defined but usually device dependent.

  • aChannel (int, in) – Streaming channel associated with the event, if any. 0xFFFF is used if the event is not associated to a streaming channel.

  • aBlockID (int, in) – Streaming block ID associated with the event, if any. Can be used to pair one or more than one event with a block received from a device. 0 is used if the event is not associated to a block.

  • aTimestamp (int, in) – Timestamp of the event on the time domain of the device. Time unit is defined by the device. 0 if timestamps are not supported by the device that generated the event.

  • aData (PvGenParameterList, in) – List containing all parameters invalidated by this event. Can be NULL if the event carried no data or the data was does not invalidate any GenApi parameters of the device.

OnCmdLinkRead(aBufferTuple)

Callback invoked after a port read.

Used to report read activity on the GenApi IPort implementation of the command link of the PvDevice.

The callback is invoked AFTER the read operation so the content of aBuffer contains the data that was read from the device.

This callback is only invoked on a successful read operation.

If aLength is 4 bytes, that data is represented as a 4 bytes value formatted as big endian.

If data is more that 4 bytes, it is presented as a stream of bytes requiring proper interpretation..

Parameters:

aBufferTuple (Tuple(ndarray, int)) –

Tuple composed of (aBuffer, aAddress):

  • aBuffer which is a 1-dimensional python numpy array with dtype np.uint8 describing the data read.

  • aAddress representing the address of the data read on the device.

OnCmdLinkWrite(aBufferTuple)

Callback invoked after a port write.

Used to report write activity on the GenApi IPort implementation of the command link of the PvDevice.

The callback is invoked AFTER the write operation. The content of aBuffer represents the data that was written to the device.

This callback is only invoked on a successful write operation.

If aLength is 4 bytes, that data is represented as a 4 bytes value formatted as big endian.

If data is more that 4 bytes, it is presented as a stream of bytes requiring proper interpretation.

Parameters:

aBufferTuple (Tuple(ndarray, int)) –

Tuple composed of (aBuffer, aAddress):

  • aBuffer which is a 1-dimensional python numpy array with dtype np.uint8 describing the data written to the device.

  • aAddress representing the address of the data written to the device.

class eBUS.PvDeviceGEV

Bases: PvDevice

Connect, configure and control a GigE Vision device

To connect and configure a GigE Vision device to begin transmitting data:

  • Select the GigE Vision device to which you want to connect. See PvSystem, PvInterface, PvDeviceInfo.

  • Connect to a GigE Vision device. Use #Connect.

  • Get the GigE Vision device’s GenICam interface. Use #GetParameters.

  • Configure the device through the GenICam interface. See PvGenParameterArray.

  • Configure the receiver and take note of its IP address and port.

  • Configure your PvDevice’s streaming destination using PvDeviceGEV.SetStreamDestination.

  • Lock the interface for streaming. Set TLParamsLocked feature of the GigE Vision device’s GenICam interface to 1.

  • Configure the GigE Vision device to send images. Use AcquisitionStart feature of the GigE Vision device’s GenICam interface.

  • Release the interface for streaming. Set TLParamsLocked feature of the GigE Vision device’s GenICam interface to 0.

  • Configure the GigE Vision device to stop sending images. Use AcquisitionStop feature of the GigE Vision device’s GenICam interface.

For a complete example that illustrates the steps above, refer to the following samples:

  • MulticastMaster - Configure a GigE Vision device to transmit

  • PvPipelineSample - Configure a GigE Vision device to transmit and receive the data it transmits in the same application

## Recovery

The SDK can let you automatically recover from problems such as accidental disconnects, power interrupts, and so on. To learn more, see PvDeviceEventSink.

property thisown

The membership flag

__init__()

Constructor.

Connect(*args)

Overload 1:

Connect to a GigE Vision device.

The #Connect method connects to a GigE Vision device found using a PvSystem or device finder dialog object. Only one device can be connected to at a time.

Parameters:

aDeviceInfo (PvDeviceInfo, in) – The GigE Vision device’s network connectivity information; a PvDeviceInfo object.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Connect to a GigE Vision device (found with PvSystem, PvInterface, PvDeviceInfo).

The #Connect method connects to a GigE Vision device found using a PvSystem or device finder dialog object. Only one device can be connected to at a time.

Parameters:

  • aDeviceInfo (PvDeviceInfo, in) – The GigE Vision device’s network connectivity information; a PvDeviceInfo object.

  • aAccessType (int, in) – The GigE Vision device’s availability for connections by multiple controllers. See PvAccessType.

Return type:

PvResult

Returns:

Includes:


Overload 3:

Connect to a GigE Vision device with the default access control mode.

If you know the GigE Vision device’s IP address, MAC address or DeviceUserID, you can use this method to connect to it.

  • If aInfo contains an IP address, the connection attempt is direct.

  • If aInfo contains a MAC address or DeviceUserID:

    • An internal PvSystem is used to find all reachable GigE Vision devices

    • Found devices are browsed, looking for a match on either MAC address or DeviceUserID

    • If the device is found, connection is attempted.

Parameters:

aInfo (str, in) – Information that uniquely identifies the GigE Vision device. You may use one of the following: - GigE Vision device’s MAC address. Use the form 00:11:22:33:44:5F. - GigE Vision device’s IP Address. Use the form 192.168.1.114. - GigE Vision device’s DeviceUserID.

Return type:

PvResult

Returns:

Includes:


Overload 4:

Connect to a GigE Vision device.

If you know the GigE Vision device’s IP address, MAC address or DeviceUserID, you can use this method to connect to it.

  • If aInfo contains an IP address, the connection attempt is direct.

  • If aInfo contains a MAC address or DeviceUserID:

    • An internal PvSystem is used to find all reachable GigE Vision devices

    • Found devices are browsed, looking for a match on either MAC address or DeviceUserID

    • If the device is found, connection is attempted.

Parameters:

  • aInfo (str, in) – Information that uniquely identifies the GigE Vision device. You may use one of the following: - GigE Vision device’s MAC address. Use the form 00:11:22:33:44:5F. - GigE Vision device’s IP Address. Use the form 192.168.1.114. - GigE Vision device’s DeviceUserID.

  • aAccessType (int, in) – The access control privilege to set at the time of connection. See PvAccessType.

Return type:

PvResult

Returns:

Includes:

SetStreamDestination(aIPAddress, aDataPort, aChannel=0)

Set the UDP/IP destination to which the GigE Vision device transmits data.

The destination constists of an IP address (unicast or multicast) and a port number.

Parameters:

  • aIPAddress (str, in) – The receiving PC’s IP address (GenICam feature name: GevSCDA) or a multicast IP address.

  • aDataPort (int, in) – The receiving PC’s data port (feature name: GevSCPHostPort) or the multicast port.

  • aChannel (int, in, optional) – The GigE Vision stream channel; the channel over which the GigE Vision device transmits images. Use 0 for device having supporting a single streaming channel.

Return type:

PvResult

Returns:

Includes:

ResetStreamDestination(aChannel=0)

Resets the UDP/IP streaming destination of the GigE Vision device.

This method is equivalent to calling #SetStreamDestination with values (“0.0.0.0”, 0, aChannel).

Parameters:

aChannel (int, in, optional) – See the aChannel parameter for the #SetStreamDestination method.

Return type:

PvResult

Returns:

Includes:

SetPacketSize(aPacketSize, aChannel=0)

Sets the packet size for a streaming channel.

Applies a specific packet size to a streaming channel. Unlike the NegotiatePacketSize method, it does not attempt to find the best packet size, it just uses the one provided as a parameter.

Parameters:

  • aPacketSize (int, in) – The packet size to use for aChannel.

  • aChannel (int, in, optional) – The streaming channel. Use 0 for most GigE Vision devices only supporting a single streaming channel.

Return type:

PvResult

Returns:

Includes:

NegotiatePacketSize(aChannel=0, aDefaultPacketSize=0)

Automatically finds and sets the optimal packet size.

The #NegotiatePacketSize method tests the network connection for the largest as possible packet size that the network can support between the GigE Vision transmitter and the controlling PC.

Calling this method resets the streaming destination for aChannel. You should always call this method AFTER connecting, BEFORE setting the GigE Vision streaming destination using SetStreamDestination.

The highest possible packet size from { MTU (if below 9000), 9000, 8000, 4000, 2000, 1500, 1000, 600 } is used. These values are used as raw seeds and are adjusted by removing 24 bytes for the Ethernet layer and then rounded down to meet the increment requirement imposed by the GevSCPSPacketSize parameter.

Parameters:

  • aChannel (int, in, optional) – The streaming channel. Use 0 for most GigE Vision devices only supporting a single streaming channel.

  • aDefaultPacketSize (int, in, optional) – The packet size to use, in bytes, should the negotiation fail. Use 1476 for a safe packet size; 0 to continue using the GigE Vision device’s original setting in case of failure.

Return type:

PvResult

Returns:

Includes:

ReadRegister() → PvResult, int

Read an inteter value from a specific register address on the GigE Vision device.

Operations are always performed as Big Endian and on Intel platforms are corrected to/from Little Endian.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, value)

WriteRegister(aAddress, aValue, aAcknowledge=True)

Write a 32-bit value to a specific register address on the GigE Vision device.

See warnings about accessing the register map directly in #WriteMemory.

aValue is provided in the platform’s expected Endianess. GigE Vision single register operations are always performed as Big Endian and on Intel platforms are corrected to/from Little Endian.

Parameters:

  • aAddress (int, in) – The GigE Vision device’s register address (mod 4).

  • aValue (int, in) – The value to be written to the register.

  • aAcknowledge (boolean, in, optional) – When sending the command, sets the acknowledge requested bit and waits for that acknowledge. If set to false, the acknowledge is not requested and the method returns as soon as the command has been pushed in the UDP socket. If not specified true is assumed.

Return type:

PvResult

Returns:

See #WriteMemory.

GetClass()

Returns the GigE Vision device class of the connected device.

If no device is connected, PvDeviceClassTransmitter is returned.

Return type:

int

Returns:

Device class of the device was connected with. See PvDeviceClass enum

GetIPAddress()

Returns the IP address of the connected device.

If no device is connected, an empty string is returned.

Return type:

str

Returns:

IP address of the device.

GetMACAddress()

Returns the MAC address of the connected device.

If no device is connnected, an emptyu string is returned.

Return type:

str

Returns:

MAC address of the device.

static GetAccessType(*args)

Overload 1:

Returns the access type of the connected device.

If no device is connected, PvAccessUnknown is returned.

Return type:

int

Returns:

Access type of the device was connected with. See PvAccessType enum


Overload 2:

Returns the current access type of a device identified by its IP address.

This function is static. It does not work on an specific object but will return the access type of a GigE Vision device identified by its IP address.

Parameters:

  • aDeviceIPAddress (str, in) – The IP address of the GigE Vision device.

  • aAccessType (int, out) – The access type of the GigE Vision device on success. See PvAccessType enum. PvAccessUnknown on failure.

Return type:

PvResult

Returns:

Includes:

static SetIPConfiguration(*args)

Sets the GigE Vision device’s IP address.

This static method lets you configure the GigE Vision device’s IP address. You cannot change the IP address when a PvDevice is connected.

Can be used to assign a valid IP configuration to a device before connecting a PvDevice to a GigE Vision device (using the #Connect method). The GigE Vision device to be configured is identified using its MAC address.

Parameters:

  • aMACAddress (str, in) – The GigE Vision device’s MAC address.

  • aIP (str, in) – The GigE Vision device’s new IP address.

  • aSubnetMask (str, in, optional) – The GigE Vision device’s new subnet mask.

  • aGateway (str, in, optional) – The GigE Vision device’s new gateway.

Return type:

PvResult

Returns:

Includes:

class eBUS.PvDeviceInfo(*args, **kwargs)

Bases: object

Information identifying a device

PvDeviceInfo provides information about a device (GigE Vision, USB3 Vision or Pleora Protocol) as found by either PvSystem/PvInterface or device finder dialog.

To use PvDeviceInfo, see PvDevice.

property thisown

The membership flag

__init__(*args, **kwargs)
Copy()

Creates a copy of the PvDeviceInfo object.

The user is responsible from freeing/deleting the object after use. The object is fully detached from PvSystem or the device finder dialog object.

Return type:

PvDeviceInfo

Returns:

Pointer to the PvDeviceInfo copy. The user is reponsable to delete/free this pointer.

GetType()

Returns the type of the device info object.

Return type:

int

Returns:

Type of the device info object. see PvDeviceInfoType enum.

GetVendorName()

Get the device’s manufacturer name.

Return type:

str

Returns:

The device’s manufacturer name.

GetModelName()

Get the device’s model name.

Return type:

str

Returns:

The device’s model name.

GetVersion()

Get the device’s version.

Return type:

str

Returns:

The GigE Vision or USB3 Vision device’s firmware version.

GetManufacturerInfo()

Get the manufacturer information returned by the device

Return type:

str

Returns:

The manufacturer information returned by the GigE Vision or USB3 Vision device.

GetSerialNumber()

Get the GigE Vision device’s serial number.

Return type:

str

Returns:

The GigE Vision or USB3 Vision device’s serial number represented as a string.

GetUserDefinedName()

Get the device’s user defined name.

This feature is only supported by devices having persistence memory. It can therefor be blank if not supported by the device, or simply not yet assigned.

Return type:

str

Returns:

The device’s name.

GetLicenseMessage()

Get a message of whether license is valid, and if not why

This string provides information on validity of the license. If the license is valid, then it is simply ‘valid’. Otherwise, the reason for the invalidity is provided as a string.

Return type:

str

Returns:

A string indicating ‘valid’ if license is valid, or a reason for invalid license

GetDisplayID()

Get a string identifying this device for display purpose.

Return type:

str

Returns:

A string identifying the device.

GetUniqueID()

Get a string uniquely identifying this device.

The content of the unique ID is not garanteed to be represent anything or to be constant between revisions of the eBUS SDK. It should only be used to opaquely, uniquely match other device unique IDs from within the same application life cycle.

Do not assume the unique ID will be using a MAC address for network devices or the USB GUID for USB devices.

If you need the MAC address of a GigE Vision device, use PvDeviceInfoGEV.GetMACAddress.

If you need the USB GUID of a USB3 Vision device, use PvDeviceInfoU3V.GetGUID.

Return type:

str

Returns:

A unique string identifying the device.

GetConnectionID()

Get a unique string identifying this device for connection purpose.

This string can be used with the factory methods of PvDevice and PvStream to create a GigE Vision device or USB3 Vision device from generic PvDeviceInfo.

Return type:

str

Returns:

A unique string identifying the device.

GetInterface()

Get the network adapter (PvInterface) through which this device was reached.

Return type:

PvInterface

Returns:

A pointer to the interface the device was found on.

IsConfigurationValid()

Test if the device can be reached as currently configured.

This method compares the GigE Vision device and NIC’s IP configurations to ensure they are on the same subnet. For USB3 Vision devices, the configuration is considered valid if the device can be enumerated and the Pleora driver is associated to the device.

Return type:

boolean

Returns:

True if valid.

IsLicenseValid()

Test if the eBUS SDK license is valid for this device.

To connect to third-party devices, the eBUS SDK requires a valid license. If you don’t have a license, contact sales.

Return type:

boolean

Returns:

True if the license is valid; otherwise, false.

GetClass()

Get the device class.

Return type:

int

Returns:

The device’s class; a PvDeviceClass enumeration.

class eBUS.PvDeviceInfoGEV

Bases: PvDeviceInfo

Information identifying a GigE Vision device

property thisown

The membership flag

__init__()

Constructor.

GetMACAddress()

Get the GigE Vision device’s MAC address.

Return type:

str

Returns:

The GigE Vision device’s MAC address, in the form aa:bb:cc:dd:ee:ff, where aa through ff are lowercase hexadecimal numbers ranging from 0x00 to 0xff.

GetIPAddress()

Get the GigE Vision device’s current IP address.

Return type:

str

Returns:

The GigE Vision device’s current IP address; the GevCurrentIPAddress feature. The form is a.*b*.*c*.*d*, where a through d are decimal numbers ranging from 0 to 255.

GetDefaultGateway()

Get the GigE Vision device’s default gateway.

Return type:

str

Returns:

The GigE Vision device’s default gateway; the GevCurrentDefaultGateway feature. For the form, see #GetIPAddress.

GetSubnetMask()

Get the GigE Vision device’s subnet mask.

Return type:

str

Returns:

The GigE Vision device’s subnet mask; the GevCurrentSubnetMask feature. For the form, see #GetIPAddress.

GetGEVVersion()

Get the GigE Vision device’s network protocol version.

The high 16 bits contain the major version and The low 16 bits the minor version.

Return type:

int

Returns:

The GigE Vision device’s network protocol version.

GetIPConfigOptionsString()

Get the GigE Vision device’s IP config options.

Return type:

str

Returns:

The GigE Vision device’s IP config options; The form is LLA(L)**DHCP(D)**Persistent_IP(P)**PAUSE_reception(PR)**PAUSE_generation(PG), where each represents device’s possible IP configuration options.

GetIPConfigCurrentString()

Get the GigE Vision device’s current IP config.

Return type:

str

Returns:

The GigE Vision device’s current IP config; The form is LLA(L)**DHCP(D)**Persistent_IP(P)**PAUSE_reception(PR)**PAUSE_generation(PG), where each represents device’s currently set IP configuration.

IsLLAAvailable()

Check if LLA is one of the IP config options for the GigE Vision device.

Return type:

boolean

Returns:

True, if LLA is an option, False otherwise.

IsDHCPAvailable()

Check if DHCP is one of the IP config options for the GigE Vision device.

Return type:

boolean

Returns:

True, if DHCP is an option, False otherwise.

IsPersistentAvailable()

Check if Persistent_IP is one of the IP config options for the GigE Vision device.

Return type:

boolean

Returns:

True, if Persistent_IP is an option, False otherwise.

IsPRAvailable()

Check if PAUSE_reception is one of the IP config options for the GigE Vision device.

Return type:

boolean

Returns:

True, if PAUSE_reception is an option, False otherwise.

IsPGAvailable()

Check if PAUSE_generation is one of the IP config options for the GigE Vision device.

Return type:

boolean

Returns:

True, if PAUSE_generation is an option, False otherwise.

IsLLAEnabled()

Check if LLA is in current IP config for the GigE Vision device.

Return type:

boolean

Returns:

True, if LLA is in current IP config, False otherwise.

IsDHCPEnabled()

Check if DHCP is in current IP config for the GigE Vision device.

Return type:

boolean

Returns:

True, if DHCP is in current IP config, False otherwise.

IsPersistentEnabled()

Check if Persistent_IP is in current IP config for the GigE Vision device.

Return type:

boolean

Returns:

True, if Persistent_IP is in current IP config, False otherwise.

IsPREnabled()

Check if PAUSE_reception is in current IP config for the GigE Vision device.

Return type:

boolean

Returns:

True, if PAUSE_reception is in current IP config, False otherwise.

IsPGEnabled()

Check if PAUSE_generation is in current IP config for the GigE Vision device.

Return type:

boolean

Returns:

True, if PAUSE_generation is in current IP config, False otherwise.

class eBUS.PvDeviceInfoPleoraProtocol

Bases: PvDeviceInfo

Information about a Pleora Protocol device.

The eBUS SDK allows enumerating devices using the Pleora protocol. However, it does not allow connecting to or controlling these device.

property thisown

The membership flag

__init__()

Constructor.

GetMACAddress()

Get the Pleora Protocol device’s MAC address.

Return type:

str

Returns:

The Pleora Protocol device’s MAC address, in the form aa:bb:cc:dd:ee:ff, where aa through ff are lowercase hexadecimal numbers ranging from 0x00 to 0xff.

GetIPAddress()

Get the Pleora Protocol device’s current IP address.

Return type:

str

Returns:

The Pleora Protocol device’s current IP address; the GevCurrentIPAddress feature. The form is a.*b*.*c*.*d*, where a through d are decimal numbers ranging from 0 to 255.

GetSubnetMask()

Get the Pleora Protocol device’s subnet mask.

Return type:

str

Returns:

The Pleora Protocol device’s subnet mask; the GevCurrentSubnetMask feature. For the form, see #GetIPAddress.

GetDefaultGateway()

Get the Pleora Protocol device’s default gateway.

Return type:

str

Returns:

The Pleora Protocol device’s default gateway; the GevCurrentDefaultGateway feature. For the form, see #GetIPAddress.

GetDeviceID()

Returns the Device ID of the Pleora Protocol device.

Return type:

uint8_t

Returns:

Device ID.

GetModuleID()

Returns the Module ID of the Pleora Protocol device.

Return type:

uint8_t

Returns:

Module ID.

GetSubID()

Returns the Sub ID of the Pleora Protocol device.

Return type:

uint8_t

Returns:

Sub ID.

GetVendorID()

Returns the Vendor ID of the Pleora Protocol device.

Return type:

uint8_t

Returns:

Vendor ID.

GetSoftwareMajor()

Major version of the firmware running on the Pleora Protocol device.

Return type:

uint8_t

Returns:

Major version of the firmware.

GetSoftwareMinor()

Minor version of the firmware running on the Pleora Protocol device.

Return type:

uint8_t

Returns:

Minor version of the firmware.

class eBUS.PvDeviceInfoU3V

Bases: PvDeviceInfoUSB

Information about a USB3 Vision device.

property thisown

The membership flag

__init__()

Constructor.

GetGenCPVersion()

Get the USB3 Vision device’s GenCP protocol version.

The high 16 bits contain the major version and The low 16 bits the minor version.

Return type:

int

Returns:

The USB3 Vision device’s GenCP protocol version.

GetU3VVersion()

Get the USB3 Vision device’s USB3 Vision protocol version.

The high 16 bits contain the major version and The low 16 bits the minor version.

Return type:

int

Returns:

The USB3 Vision device’s USB3 Vision protocol version.

GetDeviceGUID()

Get the USB3 Vision GUID of the device.

GUID stands for “Globally Unique Identifier”. It is the USB3 Vision counterpart of the MAC of a GigE Vision device.

Return type:

str

Returns:

USB3 Vision GUID of the device.

GetFamilyName()

Returns the family name of the device.

Return type:

str

Returns:

Family name of the device.

GetU3VSerialNumber()

Returns the U3V serial number of the device.

Return type:

str

Returns:

U3V serial number of the device.

GetDevicePath()

Returns the U3V device path.

Cryptic, internal device key used to load the driver for a device from a device info.

Return type:

str

Returns:

U3V device key.

GetDeviceKey()

Returns the U3V device key.

Cryptic, internal device key used to load the driver for a device from a device info.

Return type:

str

Returns:

U3V device key.

GetSpeedMessage()

Get a message of the speed negotiated between the controller and the device (low, high, full, super) or an error message

Return type:

str

Returns:

A string indicating the negotiated speed (‘low’, ‘high’, ‘full’, ‘super’) or an error message:

  • ’Unknown’ if the negotiation speed is not known

  • ’Connect to USB 3.0 port” if a device that can only support higher speeds is connected to lower speed ports

GetPowerMessage()

Get a message of whether device is powered properly or not

This string provides information on whether the device seems to be powered properly or not

Return type:

str

Returns:

A string indicating ‘Ok’ if devices seems to be powered or an error message (e.g. “Ensure correct power”) otherwise

IsLowSpeedSupported()

Returns true if the device supports USB1.0 speed.

Return type:

boolean

Returns:

True if the device supports low speed.

IsFullSpeedSupported()

Returns true if the device supports USB1.1 speed.

Return type:

boolean

Returns:

True if the device supports full speed.

IsHighSpeedSupported()

Returns true if the device supports USB2 speed.

Return type:

boolean

Returns:

True if the device supports high speed.

IsSuperSpeedSupported()

Returns true if the device supports USB3 speed.

Return type:

boolean

Returns:

True if the device supports super speed.

IsCurrentSpeedSupported()

Returns true if the current speed of the device is supported by the host controller.

Return type:

boolean

Returns:

True if the host controller supports the current speed of the device.

GetSpeed()

Returns the currently effective connection speed of the USB3 Vision device.

If a device supporting super speed is connected in a slower hub or controller it is not able to negotiate up to its maximum supported speed.

If a device IsSuperSpeedSupported returns true and GetSpeed returns something slower look into the supported speed of the hubs chain to the controller or the controller itself.

Return type:

int

Returns:

Effective connection speed. See PvUSBSpeed Enum.

GetMaxPower()

Power consumption of the device in milliamp.

Return type:

int

Returns:

Power consumption of the device.

GetMaxPacketSize()

Maximum packet size that can be used by the device in bytes.

Return type:

int

Returns:

Maximum packet size.

IsPleoraDriverInstalled()

Returns true if the currently selected driver for the device is the Pleora driver.

Return type:

boolean

Returns:

True is the device is using the Pleora driver.

IsInitializedCapabilities()

Returns true if the device U3V capabilities were retrieved and initialized

Return type:

boolean

Returns:

True if the device’s capabilities are accessible, false otherwise (indicating device may not be powered properly)

class eBUS.PvDeviceInfoUSB

Bases: PvDeviceInfo

Information about a generic USB device.

property thisown

The membership flag

__init__()

Constructor.

GetStatus()

Returns the enumeration status of the USB device.

Return type:

int

Returns:

Current enumeration status.

class eBUS.PvDevicePleoraProtocol(*args, **kwargs)

Bases: object

Class simply used to configure the IP address of a Pleora Protocol device.

property thisown

The membership flag

__init__(*args, **kwargs)
static SetIPConfiguration(*args)

Sets the Pleora Protocol device’s IP address.

This static method lets you configure the Pleora Protocol device’s IP address.

Parameters:

  • aMACAddress (str, in) – The Pleora Protocol device’s MAC address.

  • aIP (str, in) – The Pleora Protocol device’s new IP address.

  • aSubnetMask (str, in, optional) – The Pleora Protocol device’s new subnet mask.

  • aGateway (str, in, optional) – The Pleora Protocol device’s new gateway.

Return type:

PvResult

Returns:

Includes:

class eBUS.PvDeviceSerialPort

Bases: object

Provides access the a serial port on a Pleora GigE Vision or USB3 Vision device.

PvDeviceSerialPort uses a proprietary serial communication protocol on top of GigE Vision’s GVCP or USB3 Vision’s GenCP protocol. It does not support non-Pleora devices.

Use of the PvDeviceSerialPort class to directly access the camera head will interfere with the synchronization between the device and the camera head. Avoid accessing device features linked to the camera head while using the PvDeviceSerialPort class to interact with the camera head.

## How to use this class

To use a serial port:
To check if a device supports a specific serial port:

For a simple example illustrating how to use PvDeviceSerialPort, refer to the sample entitled DeviceSerialPort.

property thisown

The membership flag

__init__()

Constructor.

Open(aDevice, aPort)

Opens the serial port.

The #Open method opens a serial port to a device - mainly configuring it for serial communication readiness.

Parameters:

  • aDevice (IPvDeviceAdapter, in) – Pointer to a PvDevice object. The device must be connected prior to opening a serial port.

  • aPort (int, in) – PvDeviceSerial enumeration value representing the device’s serial port to open.

Return type:

PvResult

Returns:

Includes:

Close()

Closes the serial port.

Return type:

PvResult

Returns:

Includes:

IsOpened()

Returns true if the serial port is opened.

Return type:

boolean

Returns:

True if the port is opened.

Write(aBuffer) → PvResult, int

Writes data to the serial port.

Parameters:

aBuffer (ndarray, in) – A 1-dimensional python numpy array with dtype np.uint8 containing the bytes to write on the serial port.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, aBytesWritten).
  • result includes:
  • aBytesWritten

    • The number of bytes successfully written on the serial port

GetWriteProgress() → PvResult, int, int

Gets the progress of an ongoing write operation.

This method can be called from a different thread than the blocking Write call in order track or report the progress of the operation.

After a successful write operation, this method returns aWritten equals to aTotal until the begining of the next write operation.

Return type:

Tuple(PvResult, int, int)

Returns:

Tuple composed of (result, aWritten, aTotal).
  • result includes:
  • aWritten

    • How many bytes have been written up to now.

  • aTotal

    • The total number of bytes to write.

Read(aSize, aTimeout=0) → PvResult, ndarray, int

Reads from the serial port.

Parameters:

  • aSize (int, in) – Size of the numpy array or maximum number of bytes that are read from the serial port

  • aTimeout (int, in, optional) – Time to wait for new bytes, in ms.

Return type:

Tuple(PvResult, ndarray, int)

Returns:

Tuple composed of (result, aBuffer, aBytesRead).
  • result includes:
  • aBuffer:

    • A 1-dimensional python numpy array with dtype np.uint8 describing the received bytes.

  • aBytesRead

    • The number of bytes read from the serial port.

NotifyReadComplete()

Method used to trigger a OnReadComplete event to PvDeviceSerialPortEchoSink subscribers.

Return type:

PvResult

Returns:

Includes:

FlushRxBuffer()

Empties the read buffer.

Return type:

PvResult

Returns:

Includes:

GetRxBytesReady()

Returns the number of bytes in the read buffer.

Parameters:

aBytes (int, out) – Number of bytes currently queued in the receive buffer.

Return type:

PvResult

Returns:

Includes:

GetRxBufferSize()

Returns the current capacity of the receive buffer.

If more data than the receive buffer’s capacity is received before being read using #Read, oldest bytes are dropped first.

Parameters:

aSize (int, out) – Current capacity of the receive buffer.

Return type:

PvResult

Returns:

Includes:

SetRxBufferSize(aSize)

Sets the capacity of the receive buffer. The receive buffer needs to be big enough to buffer all incoming bytes before the user calls #Read Resizing the receive buffer flushes all data in that buffer.

Parameters:

aSize (int, in) – New capacity for the receive buffer.

Return type:

PvResult

Returns:

Includes:

See also: GetRxBufferSize

static IsSupported(aDevice, aPort)

Tests if a specific serial port is supported on a device.

This static method can be used to probe which serial ports are supported by a specific PvDevice.

Parameters:

  • aDevice (IPvDeviceAdapter, in) – Pointer to a PvDevice object. The device must be connected.

  • aPort (int, in) – PvDeviceSerial enumeration value representing the device’s serial port.

Return type:

boolean

Returns:

True if supported.

static RegisterEchoSink(aSink)

Registers an echo sink for all device serial communication in the process.

Parameters:

aSink (PvDeviceSerialPortEchoSink, in) – pointer to an object of a class inheriting PvDeviceSerialPortEchoSink.

Return type:

PvResult

Returns:

Includes:

static UnregisterEchoSink(aSink)

Unregisters an echo sink for all device serial communication in the process.

Parameters:

aSink (PvDeviceSerialPortEchoSink, in) – pointer to the object of a class inheriting PvDeviceSerialPortEchoSink to unregister.

Return type:

PvResult

Returns:

Includes:

GetBytesSent()

Returns how many bytes were sent through the serial port.

Return type:

int

Returns:

Bytes sent.

GetBytesReceived()

Returns how many bytes were received from the serial port.

Return type:

int

Returns:

Bytes received.

ResetStatistics()

Resets the port statistics.

class eBUS.PvDeviceU3V

Bases: PvDevice

Connect, configure and control a USB3 Vision device

property thisown

The membership flag

__init__()

Constructor.

Connect(*args)

Overload 1:

Connect to a USB3 Vision device.

The #Connect method connects to a USB3 Vision device found using a PvSystem or device finder dialog object. Only one device can be connected to at a time.

Parameters:

aDeviceInfo – The USB3 Vision device’s connectivity information; a PvDeviceInfo object.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Connect to a USB3 Vision device.

The #Connect method connects to a USB3 Vision device found using a PvSystem or device finder dialog object. Only one device can be connected to at a time.

Parameters:

aInfo – The USB3 Vision device’s 12 hex digit GUID.

Return type:

PvResult

Returns:

Includes:

GetGUID()

Returns the GUID of the connected device.

If no device is connected, an empty string is returned.

Return type:

str

Returns:

GUID of the device.

class eBUS.PvFPSStabilizer

Bases: object

Display frame rate manager. Used to stabilize the frames-per-seconds displayed.

This class is pretty simple to use. Just instantiate an object and call the IsTimeToDisplay every time you have a new frame to display, specifying the desired frame rate.

This class is not tied to the display. It simply keeps track of the times associated with displayed frames (IsTimeToDisplay returning true) in a circular buffer and uses this history to decide if it is time to display a new frame.

property thisown

The membership flag

__init__()

Constructor.

IsTimeToDisplay(aTargetFPS)

Checks whether displaying a frame now would bring us close to the desired display frame rate or not.

If the new frame will bring you closer to your desired frame rate, the method returns true and you send the frame to be displayed to a PvDisplayWnd or your own display class.

If it returns false, this new frame would bring you above the desired display rate. The frame can still be processed, etc. but displaying it would bring you above the desired frame rate. The expected course of action would then be to simply not display the frame and wait for a new incoming frame - instead of holding to the current one and trying to display it later.

Parameters:

aTargetFPS (int, in) – The target (desired) display frame rate.

Return type:

boolean

Returns:

True if the frame should be displayed, false if not.

GetAverage()

Queries the displayed frame rate average

Used by eBUS Player in the status control that displays the display frame rate.

Return type:

int

Returns:

Returns the current display frame rate average.

Reset()

Resets the history.

class eBUS.PvGenBoolean(*args, **kwargs)

Bases: PvGenParameter

GenICam feature: Boolean. A feature which can either be true or false.

To use this class, see PvGenParameter.

property thisown

The membership flag

__init__(*args, **kwargs)
SetValue(aValue)

Set the feature’s value.

Parameters:

aValue (boolean, in) – The feature’s new value.

Return type:

PvResult

Returns:

Includes: - PV_OK - PV_GENERIC_ERROR (Use PvResult.GetDescription to get more information.)

GetValue() → PvResult, int

Get the feature’s value.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, value):

class eBUS.PvGenCategory(*args, **kwargs)

Bases: object

GenICam category.

property thisown

The membership flag

__init__(*args, **kwargs)
GetName() → PvResult, str

Get the category’s name.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, name):

GetToolTip() → PvResult, str

Get the category’s tool tip.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, tooltip):

GetDescription() → PvResult, str

Get the feature’s Description.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, description)

GetDisplayName() → PvResult, str

Get the category’s display name; a name that can be used to identify a category in a user-interface context instead of #GetName. (None if PvResult outcome is not PV_OK)

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, displayname)

GetNameSpace() → PvResult, int

Get the category’s name space.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, namespace)

GetVisibility() → PvResult, int

Get the category’s recommended user level (visibility).

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, visibility)

IsVisible(aCurrentVisibility) → PvResult, bool

Test if the category is visible at the specified visibilty level.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsVisible)
  • result representing the outcome:
  • IsVisible:

    • True if the category is visible at the specified visibilty level.

IsImplemented() → PvResult, bool

Test if the category is implemented. Typically the IsImplemented attribute does not change during the lifetime of a category. However some GenICam interfaces are using using IsImplemented in order to activate hidden or advanced features.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsImplemented)
  • result representing the outcome:
  • IsImplemented:

    • True if the parameter is currently implemented; otherwise, false.

GetNode()

Returns the GenApi node wrapped by this PvGenCategory

Return type:

PV_GENAPI_NS::INode

Returns:

GenApi node wrapped by this PvGenCategory

For advanced use only.

GenApi headers and link libraries are not provided with the eBUS SDK. In order to use the GenApi node provided by this method, install the GenApi SDK.

class eBUS.PvGenCommand(*args, **kwargs)

Bases: PvGenParameter

GenICam feature: Command. A feature which can only be activated.

To use this class, see PvGenParameter.

property thisown

The membership flag

__init__(*args, **kwargs)
Execute()

Activate the feature.

Return type:

PvResult

Returns:

Includes:

IsDone() → PvResult, bool

Query whether the command is executed.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsDone)
  • result representing the outcome:
  • IsDone:

    • True if the command has completed its execution. (None if PvResult outcome is not PV_OK)

class eBUS.PvGenEnum(*args, **kwargs)

Bases: PvGenParameter

GenICam feature: Enumeration. A feature which can take one of many defined values.

PvGenEnum is a list of selectable values. In a UI, PvGenEnum objects are typically represented as dropdown lists.

Each list entry is a PvGenEnumEntry object.

Thus, the enumeration list might be represented as:

List position

Entry value

Entry name

0

5

Orange

1

4

Apple

2

99

Watermelon

However, the UI presents only a selection of entry names (Orange, etc.); the list position and entry values are hidden. The entry names are always unique.

Enumerations can’t be set to any arbitrary value; they can only be set to a value of an entry on the list. If a user selected Orange, you could set the new value in the following ways:

  • Set the entry value directly with #SetValue ( 5 ).

  • Set the entry value by the name with #SetValue ( “Orange” ).

property thisown

The membership flag

__init__(*args, **kwargs)
SetValue(*args)

Overload 1:

Set the feature’s value.

Parameters:

aValue (int, in) – The enumerator entry’s feature’s value (PvGenEnumEntry.GetValue).

Return type:

PvResult

Returns:

See #GetEntriesCount.


Overload 2:

Set feature’s value.

Parameters:

aValue (str, in) – The enumerator entry’s name (PvGenEnumEntry.GetName).

Return type:

PvResult

Returns:

See #GetEntriesCount.

GetEntriesCount() → PvResult, int

Get the number of enumaration entries.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, count)

GetEntryByName(aEntryName) → PvResult, int

Query whether the command is executed.

Parameters:

aEntryName (str, in) – The enumeration entry’s name (See PvGenEnumEntry.GetName).

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, entry)

GetEntryByIndex(aIndex) → PvResult, int

Get an enumeration entry (by list position).

The enumeration entry’s position in the list. The enumerator (PvGenEnum object) has a list that ranges from 0 to PvGenEnum::GetEntriesCount.

Parameters:

aIndex (int, in) – The enumeration entry’s position in list (PvGenEnumEntry::GetEntriesCount).

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, entry)

GetEntryByValue(aValue) → PvResult, int

Get an enumeration entry (by value).

Parameters:

aValue (int, in) – The enumeration entry’s value (PvGenEnumEntry::GetValue).

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, entry)

GetValueString() → PvResult, str

Get the feature’s value (as a string).

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, valuestring)
  • result representing the outcome:
  • valuestring:

    • The feature’s value in string (equivalent to PvGenEnumEntry::GetValueString). (None if PvResult outcome is not PV_OK)

GetValueInt() → PvResult, int

Get the feature’s value (as an integer).

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, valueint)
  • result representing the outcome:
  • valueint:

    • The feature’s value in int (equivalent to PvGenEnumEntry::GetValueInt). (None if PvResult outcome is not PV_OK)

class eBUS.PvGenEnumEntry(*args, **kwargs)

Bases: object

GenICam feature: Enumeration entry

To use PvGenEnumEntry, see PvGenEnum.

property thisown

The membership flag

__init__(*args, **kwargs)
GetValue() → PvResult, int

Get the enumeration entry’s value.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, value)

GetName() → PvResult, str

Get the enumeration entry’s name.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, name)

GetToolTip() → PvResult, str

Get a short description of the enum entry.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, tooltip)

GetDescription() → PvResult, str

Get a longer description of the enum entry.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, description)

GetVisibility() → PvResult, int

Get the enumeration entry’s current visibility level.

See PvGenParameter.GetVisibility.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, visibility)

GetDisplayName() → PvResult, str

Get the enum entry’s display name.

Raises:

RuntimeError – An error occurred. See exception text.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, displayname)
  • result representing the outcome:
  • displayname:
    • The enum entry’s display name; a name that can be used to identify an enum entry in a

      user-interface context instead of #GetName. (None if PvResult outcome is not PV_OK)

GetNameSpace() → PvResult, int

Get the enum enty’s name space.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, namespace)

IsVisible(aVisibility) → PvResult, bool

Test if the parameter is visible at the specified visibilty level.

Parameters:

aVisibility (int, in) – See PvGenVisibility Enum.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsVisible)
  • result representing the outcome:
  • IsVisible:

    • True if the parameter is visible at the specified visibilty level.

IsAvailable() → PvResult, bool

Test if the enumeration entry is currently available.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsAvailable)

class eBUS.PvGenEventSink(*args, **kwargs)

Bases: object

Observer interface for an observable PvGenParameter object

To use PvGenEventSink, see PvGenParameter.RegisterEventSink.

property thisown

The membership flag

__init__(*args, **kwargs)
OnParameterUpdate(aParameter)

Callback that is invoked when a feature’s value is updated.

Parameters:

aParameter (PvGenParameter, in) – The feature that was updated.

class eBUS.PvGenFloat(*args, **kwargs)

Bases: PvGenParameter

GenICam feature: Float

To use this class, see PvGenParameter.

property thisown

The membership flag

__init__(*args, **kwargs)
SetValue(aValue)

Set the feature’s value.

Parameters:

aValue (float, in) – The feature’s new value.

Return type:

PvResult

Returns:

Includes:

GetValue() → PvResult, float

Get the feature’s value.

Return type:

Tuple(PvResult, float)

Returns:

Tuple composed of (result, value)

GetMin() → PvResult, float

Get the feature’s limits (minimum).

Return type:

Tuple(PvResult, float)

Returns:

Tuple composed of (result, min)

GetMax() → PvResult, float

Get the feature’s limits (maximum).

Return type:

Tuple(PvResult, float)

Returns:

Tuple composed of (result, max)

GetRepresentation() → PvResult, int

Get the feature’s suggested presentation format.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, representation)

GetUnit() → PvResult, str

Get the feature’s measurement unit. The #GetUnit method returns a string with the units for the feature. For example, the string might contain “pixels”, “bytes”, “ms”, and so on. The string is informational and has no intrinsic value for converting to other units.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, unit)

class eBUS.PvGenInteger(*args, **kwargs)

Bases: PvGenParameter

GenICam feature: Integer

To use this class, see PvGenParameter.

property thisown

The membership flag

__init__(*args, **kwargs)
SetValue(aValue)

Set the feature’s new value.

Parameters:

aValue (int, in) – The feature’s new value.

Return type:

PvResult

Returns:

Includes:

GetValue() → PvResult, int

Get the feature’s value.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, value)

GetMin() → PvResult, int

Get the feature’s limits (minimum).

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, min)

GetMax() → PvResult, int

Get the feature’s limits (maximum).

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, max)

GetIncrement() → PvResult, int

Get the feature’s suggested increment. The #GetIncrement method suggests how much an up/down button in the UI should increment/decrement the current value.

For example, a feature with a range of 0 to 1000000 might have an increment of 100000 to keep the user from having to click excessively.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, increment)

GetRepresentation() → PvResult, int

Get the feature’s suggested presentation format.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, representation)

GetUnit() → PvResult, str

Get the feature’s measurement unit. The #GetUnit method returns a string with the units for the feature. For example, the string might contain “pixels”, “bytes”, “ms”, and so on. The string is informational and has no intrinsic value for converting to other units.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, unit)

class eBUS.PvGenParameter(*args, **kwargs)

Bases: object

Base class for all GenICam feature types.

property thisown

The membership flag

__init__(*args, **kwargs)
GetName() → PvResult, str

Get the parameter’s name.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, name)

GetType() → PvResult, int

Get the parameter’s type.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, type)

GetCategory() → PvResult, str

Get the parameter’s category.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, category)

GetToolTip() → PvResult, str

Get the parameter’s tool tip.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, tooltip)
  • result representing the outcome:
  • tooltip:

    • The parameter’s tool tip; typically a brief description of how to use the parameter. (None if PvResult outcome is not PV_OK)

GetDescription() → PvResult, str

Get the parameter’s description.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, description)
  • result representing the outcome:
  • description:

    • The parameter’s description; typically a long description of what the parameter is. (None if PvResult outcome is not PV_OK)

GetDisplayName() → PvResult, str

Get the parameter’s display name.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, displayname)
  • result representing the outcome:
  • displayname:

    • The parameter’s display name; a name that can be used to identify a parameter in a user-interface context instead of #GetName. (None if PvResult outcome is not PV_OK)

GetNameSpace() → PvResult, int

Get the parameter’s name space.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, namespacec)

IsValueCached() → PvResult, bool

Test if the parameter’s value is cached in the PC.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsValueCached)
  • result representing the outcome:
  • IsValueCached:

    • True if the PC keeps a cached version of the parameter’s value;

    • False if the value must be retrieved from the video interface each time it’s requested.

IsPersistent() → PvResult bool

Test if the parameter is to be considered when saving the state of a GenICam interface to disk.

The #IsPersistent tests if the feature’s persistence attribute is true.

Features that might not be persistent:

  • Features such as a clock’s current value and others that are meaningless shortly after the value is retrieved.

  • Some network configuration settings.

  • Etc.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsPersistent)
  • result representing the outcome:
  • IsPersistent:

    • True if the parameter’s value is persistent; otherwise, false.

IsImplemented() → PvResult, bool

Test if the parameter is implemented.

Typically the IsImplemented attribute does not change during the lifetime of a parameter.

However some GenICam interfaces are using IsImplemented in order to activate hidden or advanced features.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsImplemented)

IsAvailable() → PvResult, bool

Test if the parameter is currently available, but may be available latter on.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsAvailable)
  • result representing the outcome:
  • IsAvailable:

    • True if the parameter is currently available; otherwise, false.

IsWritable() → PvResult, bool

Test if the parameter is writable.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsWritable)
  • result representing the outcome:
  • IsWritable:

    • True if the parameter is currently writable; otherwise, false.

IsReadable() → PvResult, bool

Test if the parameter is readable.

‘Readable’ is an attribute in the GenICam specification; in practice most parameters are readable.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsReadable)
  • result representing the outcome:
  • IsReadable:

    • True if the parameter is currently readable; otherwise, false.

IsStreamable() → PvResult, bool

Test if the parameter is streamable.

‘Streamable’ is an attribute in the GenICam specification; If true, it means the parameter should be considered for persistence.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsStreamable)
  • result representing the outcome:
  • IsStreamable:

    • True if the parameter to be considered for persistence; otherwise, false.

GetVisibility() → PvResult, int

Get the parameter’s recommended user level (visibility)

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, visibility)

IsVisible(aCurrentVisibility) → PvResult, bool

Test if the parameter is visible at the specified visibilty level.

Parameters:

aCurrentVisibility (int, in) – PvGenVisibility, the category’s recommended user level (visibility). See PvGenVisibility Enum.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsVisible)

IsSelector() → PvResult, bool

Queries whether this parameter is a selector or not.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, IsSelector)

GetSelectedParameters() → PvResult, PvGenParameterList

Returns all parameters selected by this parameter.

Return type:

Tuple(PvResult, PvGenParameterList)

Returns:

Tuple composed of (result, parameterList)

GetSelectingParameters() → PvResult, PvGenParameterList

Returns all selectors for this parameter.

Return type:

Tuple(PvResult, PvGenParameterList)

Returns:

Tuple composed of (result, parameterList)

RegisterEventSink(aEventSink)

Register an event sink interface that will be used for callbacks on this parameter.

Event sinks are automatically unregistered when the PvGenParameter object is destroyed (even if #UnregisterEventSink wasn’t called).

Parameters:

aEventSink (PvGenEventSink, in) – The event sink.

Return type:

PvResult

Returns:

Includes:

UnregisterEventSink(aEventSink)

Unregister an event sink.

Parameters:

aEventSink (PvGenEventSink, in) – See #RegisterEventSink

Return type:

PvResult

Returns:

Includes:

ToString() → PvResult, str

Gets the parameter value as a string. Typically used for UI, persistence.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, stringValue)

FromString(aValue)

Sets the parameter value from a string.

Parameters:

aValue (str, in) – A string representing the new value to set the parameter to.

Typically used for UI, persistence.

Return type:

PvResult

Returns:

Includes:

GetNode()

Returns the GenApi node wrapped by this PvGenParameter

Return type:

PV_GENAPI_NS::INode

Returns:

GenApi node wrapped by this PvGenPArameter

For advanced use only.

GenApi headers and link libraries are not provided with the eBUS SDK. In order to use the GenApi node provided by this method, install the GenApi SDK.

GetUpdatesEnabled()

Returns true if parameter update notifications are temporarily disabled.

Return type:

boolean

Returns:

True if they are disabled, false if not.

SetUpdatesEnabled(aEnabled)

Temporarily disable (or re-enable) parameter update notifications.

Parameters:

aEnabled (boolean, in) – False to disable, true to re-enable.

class eBUS.PvGenParameterArray

Bases: object

GenICam feature array

## id=”controlling”Controlling features (programmatically)

To control features:
  • Get the list of features. Use one of the following:

    • PvDevice.GetParameters (Parameters used to control the GigE Vision device to which you are connected)

    • PvDevice.GetCommunicationParameters (Parameters used to define how PvDevice connects to and communicates with the device - see Device Communication Parameters (GEV (“devicecommunicationGEV.html”)/U3V (“devicecommunicationU3V.html”))

    • PvStream.GetParameters (Parameters used to define how PvStream receives data from a GigE Vision transmitter - see Stream Parameters (GEV (“streamparametersGEV.html”)/U3V (“streamparametersU3V.html”))

  • Get a feature. Use #Get.

  • Get the feature’s type. Use PvGenParameter.GetType.

  • Optionally:

## id=”controllingGUI”Controlling features (using a GUI)

To control features (using a GUI):

  • See GenICam browser dialog documentation.

## Running code when a feature’s value changes

In some cases, you may want to know when a feature value or attribute changes without using CPU-intensive polling to regularly check (and re-check) the feature’s value.

To create a callback that runs when the feature’s value changes:
property thisown

The membership flag

__init__()

Constructor.

GetCount()

Get the number of parameters (PvGenParameter objects) in the array.

Return type:

int

Returns:

The number of parameters (PvGenParameter objects) in the array.

Get(*args)

Overload 1:

Get a parameter (PvGenParameter object) from the array (using array position).

Parameters:

aIndex (int, in) – The parameter’s position in the array. The valid range for aIndex is: 0 =< aIndex < #GetCount.

Return type:

PvGenParameter

Returns:

The parameter (PvGenParameter object), or NULL if the index is out of bounds.


Overload 2:

Get a parameter (PvGenParameter object) from the array (using parameter name).

Parameters:

aName (str, in) – The parameter’s name. See PvGenParameter.GetName.

Return type:

PvGenParameter

Returns:

The parameter (PvGenParameter object), or NULL if the name does not match any paramaters in the array.

GetCategoryCount()

Get the number of categories (PvGenCategory objects) in the array.

Return type:

int

Returns:

The number of categories (PvGenCategory objects) in the array.

GetCategory(*args)

Overload 1:

Get a category (PvGenCategory object) from the array (using array position).

Parameters:

aIndex (int, in) – The category’s position in the array. The valid range for aIndex is: 0 =< aIndex < #GetCategoryCount.

Return type:

PvGenCategory

Returns:

The parameter (PvGenCategory object), or NULL if the index is out of bounds.


Overload 2:

Get a category (PvGenCategory object) from the array (using category name).

Parameters:

aName (str, in) – The category’s name. See PvGenCategory::GetName.

Return type:

PvGenCategory

Returns:

The category (PvGenCategory object), or NULL if the name does not match any categories in the array.

InvalidateCache()

Invalidates the cache of the GenICam parameter array.

Return type:

PvResult

Returns:

Includes:

GetNodeMap()

Returns the interface of the GenApi node map wrapped by this PvGenParameterArray

Return type:

PV_GENAPI_NS::INodeMap

Returns:

Interface of the GenApi node map wrapped by this PvGenPArameterArray

For advanced use only.

GenApi headers and link libraries are not provided with the eBUS SDK. In order to use the GenApi node map provided by this method, install the GenApi SDK.

GetInteger(aName)

Helper method returning a PvGenParameter casted as a PvGenInteger.

Returns NULL if the parameter does not exist in the node map or the parameter is not an integer.

Parameters:

aName (str, in) – Name of the parameter.

Return type:

PvGenInteger

Returns:

PvGenInteger parameter pointer from the parameter array.

GetFloat(aName)

Helper method returning a PvGenParameter casted as a PvGenFloat.

Returns NULL if the parameter does not exist in the node map or the parameter is not a float.

Parameters:

aName (str, in) – Name of the parameter.

Return type:

PvGenFloat

Returns:

PvGenFloat parameter pointer from the parameter array.

GetEnum(aName)

Helper method returning a PvGenParameter casted as a PvGenEnum.

Returns NULL if the parameter does not exist in the node map or the parameter is not an enumeration.

Parameters:

aName (str, in) – Name of the parameter.

Return type:

PvGenEnum

Returns:

PvGenEnum parameter pointer from the parameter array.

GetBoolean(aName)

Helper method returning a PvGenParameter casted as a PvGenBoolean.

Returns NULL if the parameter does not exist in the node map or the parameter is not a boolean.

Parameters:

aName (str, in) – Name of the parameter.

Return type:

PvGenBoolean

Returns:

PvGenBoolean parameter pointer from the parameter array.

GetCommand(aName)

Helper method returning a PvGenParameter casted as a PvGenCommand.

Returns NULL if the parameter does not exist in the node map or the parameter is not a command.

Parameters:

aName (str, in) – Name of the parameter.

Return type:

PvGenCommand

Returns:

PvGenBoolean parameter pointer from the parameter array.

GetString(aName)

Helper method returning a PvGenParameter casted as a PvGenString.

Returns NULL if the parameter does not exist in the node map or the parameter is not a string.

Parameters:

aName (str, in) – Name of the parameter.

Return type:

PvGenString

Returns:

PvGenString parameter pointer from the parameter array.

GetRegister(aName)

Helper method returning a PvGenParameter casted as a PvGenRegister.

Returns NULL if the parameter does not exist in the node map or the parameter is not a register.

Parameters:

aName (str, in) – Name of the parameter.

Return type:

PvGenRegister

Returns:

PvGenRegister parameter pointer from the parameter array.

GetIntegerValue(aName) → PvResult, int

Helper method used to directly read an integer parameter value of this parameter array.

Parameters:

aName (str, in) – Name of the parameter to read the value from.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, intValue)
  • result representing the outcome:
  • intValue:

    • Value read from the parameter.

SetIntegerValue(aName, aValue)

Helper method used to directly write an integer parameter value of this parameter array.

Parameters:

  • aName (str, in) – Name of the parameter to write the value to.

  • aValue (int, out) – Value written to the parameter.

Return type:

PvResult

Returns:

Includes:

GetFloatValue(aName) → PvResult, float

Helper method used to directly read a float parameter value of this parameter array.

Parameters:

aName (str, in) – Name of the parameter to read the value from.

Return type:

Tuple(PvResult, float)

Returns:

Tuple composed of (result, floatValue)
  • result representing the outcome:

    • PV_OK

    • NOT_FOUND if the parameter does not exist or is not the right type

    • Any other error code from PvGenFloat.GetValue

  • floatValue:

    • Value read from the parameter.

SetFloatValue(aName, aValue)

Helper method used to directly write a float parameter value of this parameter array.

Parameters:

  • aName (str, in) – Name of the parameter to write the value to.

  • aValue (float, out) – Value written to the parameter.

Return type:

PvResult

Returns:

Includes:

SetEnumValue(*args)

Overload 1:

Helper method used to directly write an enumeration parameter value (as a string) of this parameter array.

Parameters:

  • aName (str, in) – Name of the parameter to write the value to.

  • aValue (str, in) – Value written to the parameter.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Helper method used to directly write an enumeration parameter value (as an integer) of this parameter array.

Parameters:

  • aName (str, in) – Name of the parameter to write the value to.

  • aValue (int, in) – Value written to the parameter.

Return type:

PvResult

Returns:

Includes:

GetBooleanValue(aName) → PvResult, bool

Helper method used to directly read a boolean parameter value of this parameter array.

Parameters:

aName (str, in) – Name of the parameter to read the value from.

Return type:

Tuple(PvResult, bool)

Returns:

Tuple composed of (result, value)
  • resuult representing the outcome:

    • PV_OK

    • NOT_FOUND if the parameter does not exist or is not the right type

    • Any other error code from PvGenBoolean::GetValue

  • value:

    • Value read from the parameter.

SetBooleanValue(aName, aValue)

Helper method used to directly write a boolean parameter value of this parameter array.

Parameters:

  • aName (str, in) – Name of the parameter to write the value to.

  • aValue (boolean, out) – Value written to the parameter.

Return type:

PvResult

Returns:

Includes:

GetStringValue(aName) → PvResult, str

Helper method used to directly read a string parameter value of this parameter array.

Parameters:

aName (str, in) – Name of the parameter to read the value from.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, value)
  • result representing the outcome:
  • value:

    • Value read from the parameter.

SetStringValue(aName, aValue)

Helper method used to directly write a string parameter value of this parameter array.

Parameters:

  • aName (str, in) – Name of the parameter to write the value to.

  • aValue (str, out) – Value written to the parameter.

Return type:

PvResult

Returns:

Includes:

ExecuteCommand(aName)

Helper method used to directly execute a command parameter of this parameter array.

Parameters:

aName (str, in) – Name of the parameter to execute.

Return type:

PvResult

Returns:

Includes:

GetIntegerRange(aName) → PvResult, int, int

Helper method used to directly retrieve the range of an integer parameter.

Parameters:

aName (str, in) – Name of the parameter to read the value from.

Raises:

RuntimeError – An error occurred. See exception text.

Return type:

Tuple(PvResult, int, int)

Returns:

A tuple composed of (result, min, max):
  • result representing the outcome:
  • min:

    • The minimum of the range in int.

  • max:

    • The maximum of the range in int.

GetFloatRange(aName) → PvResult, float, float

Helper method used to directly retrieve the range of a float parameter.

Parameters:

aName (str, in) – Name of the parameter to read the value from.

Return type:

Tuple(PvResult, float, float)

Returns:

A tuple composed of (result, min, max):
  • result representing the outcome:
  • min:

    • The minimum of the range in float.

  • max:

    • The maximum of the range in float.

AttachDataChunks(aBuffer) → PvResult

Attaches a payload containing data chunks to a GenICam node map. from the buffer matching chunk IDs in the node map are available through the node map once the buffer is attached.

Using GenICam instead of the PvBuffer raw chunk methods access allows to access the chunks as structured data, as long as the chunks are described in the GenICam XML file of the device.

Parameters:

aBuffer (ndarray, in) – A 1-dimensional python numpy array with dtype np.uint8 containing buffer data (usually PvBuffer::GetRawData)

Return type:

PvResult

Returns:

Includes:

  • PV_OK: Success.

  • PV_INVALID_PARAMETER: aBuffer is NULL or aBufferLength is 0.

  • PV_INVALID_DATA_FORMAT: the chunk layout is invalid and has been rejected by GenApi.

  • PV_GENERIC_ERROR: if an error happened within GenApi. Use PvResult.GetDescription to get more information.

DetachDataChunks()

Detach previously attached data chunks.

Return type:

PvResult

Returns:

Includes:

GetAccessMode()

Returns the access mode of the port of the GenICam node map.

Return type:

int

Returns:

Includes:

  • PvGenAccessModeReadOnly

  • PvGenAccessModeReadWrite

  • PvGenAccessModeNotAvailable

Poll()

Invalidates nodes having reach their defined polling time since last update.

Goes through all parameters having polling times defined and invalidates those that need to be invalidated based on the last time they were invalidated.

Return type:

PvResult

Returns:

Includes:

GetEnumValueString(aName) → PvResult, str

Helper method used to directly read an enumeration parameter value (as a string) of this parameter array.

Parameters:

aName (str, in) – Name of the parameter to read the value from.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, valueString)
  • result representing the outcome:

    • PV_OK

    • NOT_FOUND if the parameter does not exist or is not the right type

    • Any other error code from PvGenEnum::GetValueString

  • valueString:

    • Value read from the parameter, string representation.

GetEnumValueInt(aName) → PvResult, int

Helper method used to directly read an enumeration parameter value (as an integer) of this parameter array.

Parameters:

aName (str, in) – Name of the parameter to read the value from.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, valueInt)
  • result representing the outcome:

    • PV_OK

    • NOT_FOUND if the parameter does not exist or is not the right type

    • Any other error code from PvGenEnum::GetValueInt

  • valueInt:

    • Value read from the parameter, integer representation.

class eBUS.PvGenParameterList

Bases: object

Class used to hold a group of PvGenParameter pointers.

Unlike the PvGenParameterArray, this class does not wrap a node map. It only contains pointers to PvGenParameter objects living in a PvGenParameterArray of their own.

To use this class, see PvGenParameter GetSelectedParameters and GetSelectingParameters. It is used by the eBUS SDK to return a list of pointers to parameters whithin a PvGenParameterArray.

The list can be accessed iteratively with GetFirst and GetNext or randomly with GetSize, GetItem or the operator[].

### How to use PvGenParameterList with PvGenParameter

 PvGenParameter *lGenParameter = // ...get a parameter from a PvGenParameterArray

 PvGenParameterList lList;
 lGenParameter->GetSelectedParameters( lList );

 PvGenParameter *lP = lList.GetFirst();
 while ( lP != NULL )
 {
...
     Do something with lP
    ...

    lP = lList.GetNext();
 }
property thisown

The membership flag

__init__()

Constructor

Clear()

Clears the parameter list

Add(aParameter)

Adds an item to the parameter list.

Notes: Adding an item in the list resets the #GetFirst, #GetNext internal iterator.

Parameters:

aParameter (PvGenParameter, in) – The PvGenParameter pointer to add to the list.

GetSize()

Returns the size of the list.

Return type:

int

Returns:

The size, or count of items contained in the list.

GetItem(aIndex)

Returns a specific item from the list.

Return type:

PvGenParameter

Returns:

Index of the requested PvGenParameter pointer.

Parameters:

aIndex (int, in) – of the item to get.

GetFirst()

Returns the first item of the list.

Sets the internal iterator to the first item. Subsequent calls to #GetNext can be used to scroll through the list.

Return type:

PvGenParameter

Returns:

Pointer to the first item in the list, NULL if the list is empty.

GetNext()

Returns the next item in the list.

Calling this method advances the internal iterator to the next item in the list.

NULL is returned if the end of the list is reached.

If #GetFirst is not called before #GetNext, the first call to #GetNext returns the first item in the list.

Return type:

PvGenParameter

Returns:

Pointer to the next item in the list. NULL if the end of the list is reached.

class eBUS.PvGenRegister(*args, **kwargs)

Bases: PvGenParameter

GenICam feature: Register, or IRegister. A feature providing direct access to a section of the device’s register map.

To use this class, see PvGenParameter.

property thisown

The membership flag

__init__(*args, **kwargs)
Set(aBuffer, aLength)

Write to the register.

Partial (less than #GetLength) writes are supported at the GenICam level, but the behaviour is defined by the device.

GigE Vision enforces a mod-4 (can be divided by 4 bytes) length restriction on all read/write operations.

Parameters:

  • aBuffer (uint8_t, in) – Data to write to the register.

  • aLength (int, in) – Length of the buffer, in bytes.

Return type:

PvResult

Returns:

Includes:

Get(aBuffer, aLength)

Reads from the register.

Partial (less than #GetLength) reads are supported at the GenICam level, but the behaviour is defined by the device.

GigE Vision enforces a mod-4 (can be divided by 4 bytes) length restriction on all read/write operations.

Parameters:

  • aBuffer (uint8_t, out) – Data read from the register.

  • aLength (int, out) – Length of the buffer, in bytes.

Return type:

PvResult

Returns:

See #Set.

GetLength()

Returns the length of the register mapped with this feature.

Parameters:

aLength (int, out) – Length of the register, in bytes.

Return type:

PvResult

Returns:

See #Set.

class eBUS.PvGenStateStack(aParameters)

Bases: object

Performs changes to a GenICam node map, tracks them and restores the previous state on destruction.

This class can be used to perform temporary changes to a GenICam node map. Every parameter changed through this class is tracked and its original value is saved. When the object is destroyed, the original value of all parameters is restored in the reverse order.

This class is very useful when dealing with selectors. If you want to change a selected value without affecting the current selector state of the node map, create an object of this type, change the selector(s) using the Set methods, perform your changes and let the object go out of scope: the selectors will go back to their original values.

Assume A is originally 1, B is 2, C is 3. If you use this class to change A 4, B to 5 and C to 6 (in that order) when the object goes out of scope C will be set back to 3, B to 2 and A to 1 (in that order as well).

If a value cannot be set (an error occurs) the previous value is not pushed on the stack of parameters that will be restored when the destructor is called.

If the parameter is already set to the requested value, its value IS NOT changed, and IS NOT pushed on the stack to be eventually restored. This is done to minimize traffic to the device and prevent too much invalidators to be fired when a selector is already set to the rigth value.

property thisown

The membership flag

__init__(aParameters)

Constructor.

Parameters:

aParameters (PvGenParameterArray, in) – The GenICam parameter array to operate on.

SetIntegerValue(aName, aValue)

Changes the value of an integer parameter.

Parameters:

  • aName (str, in) – The name of the parameter to change.

  • aValue (int, in) – The new value of the parameter.

Return type:

PvResult

Returns:

Includes:

SetFloatValue(aName, aValue)

Changes the value of a float parameter.

Parameters:

  • aName (str, in) – The name of the parameter to change.

  • aValue (float, in) – The new value of the parameter.

Return type:

PvResult

Returns:

Includes:

SetEnumValue(*args)

Overload 1:

Changes the value of an enum parameter.

Parameters:

  • aName (str, in) – The name of the parameter to change.

  • aValue (str, in) – The new symbolic (string) value of the parameter.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Changes the value of an enum parameter.

Parameters:

  • aName (str, in) – The name of the parameter to change.

  • aValue (int, in) – The new integer value of the parameter.

Return type:

PvResult

Returns:

Includes:

SetBooleanValue(aName, aValue)

Changes the value of a boolean parameter.

Parameters:

  • aName (str, in) – The name of the parameter to change.

  • aValue (boolean, in) – The new value of the parameter.

Return type:

PvResult

Returns:

Includes:

SetStringValue(aName, aValue)

Changes the value of a string parameter.

Parameters:

  • aName (str, in) – The name of the parameter to change.

  • aValue (str, in) – The new value of the parameter.

Return type:

PvResult

Returns:

Includes:

class eBUS.PvGenString(*args, **kwargs)

Bases: PvGenParameter

GenICam feature: String

To use this class, see PvGenParameter.

property thisown

The membership flag

__init__(*args, **kwargs)
SetValue(aValue)

Set the feature’s value.

Parameters:

aValue (str, in) – The feature’s new value.

Return type:

PvResult

Returns:

Includes:

GetValue() → PvResult, str

Get the feature’s value.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, value)

GetMaxLength() → PvResult, int

Returns the maximum length of the string.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, maxlength)
  • result representing the outcome:
  • maxlength:

    • Maximum length of the register, in characters. (None if PvResult outcome is not PV_OK)

class eBUS.PvImage(*args, **kwargs)

Bases: IPvImage

Image interface to a PvBuffer.

A PvBuffer represents a generic buffer with no specific payload type. If the payload type is image, the user can obtain a pointer to a PvImage buffer interface through PvBuffer.GetImage.

This PvImage pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

## id=”accessing”Accessing image specific data

To determinate the payload type and access image specific data:
property thisown

The membership flag

__init__(*args, **kwargs)
GetMaximumChunkLength()

Returns the maximum chunk length possible for the currently allocated memory vs image attributes.

Return type:

int

Returns:

Maximum chunk length, in bytes.

static GetPixelSize(aPixelType)

Static method returning the pixel size in bits for a specific pixel type

Parameters:

aPixelType (int, in) – Pixel type.

Return type:

int

Returns:

Pixel size, in bits.

static IsPixelColor(aPixelType)

Static method returning whether a pixel type is color or not

Parameters:

aPixelType (int, in) – Pixel type.

Return type:

boolean

Returns:

True if color.

static IsPixelHighRes(aPixelType)

Static method returning whether a pixel type is higher than 8-bit per channel or not

10, 12, 14 and 16-bit pixel type are considered high resolution. RGB8 counts as 8 so high resolution here means per channel.

Parameters:

aPixelType (int, in) – Pixel type.

Return type:

boolean

Returns:

True if higher than 8 bit per channel.

static GetBitsPerComponent(aPixelType)

Static method returning the number of bit per components for a pixel type.

PvPixelMono8 and PvPixelRGBa8 would be 8. Mono16, PvPixelRGB16, PvPixelBayerRG16 would be 16, etc.

Parameters:

aPixelType (int, in) – Pixel type.

Return type:

int

Returns:

True if higher than 8 bit per channel.

static PixelTypeToString(aPixelType)

Static method returning a string representation of a pixel type.

Parameters:

aPixelType (int, in) – Pixel type.

Return type:

str

Returns:

String representation of the pixel type.

GetRequiredSize()

Gets the size of buffer required to hold the acquired image.

This attribute is valid if the last image acquisition was successful or if it failed because the buffer was too small. It can be used to re-allocate the acquisition buffers if the acquisition failed because the buffer was too small.

The required size is only computed for the last image - based on the number of lines as provided in the GigE Vision or USB3 Vision streaming protocol trailer.

It is possible that with devices outputting images of varying length (like line scan cameras) that the last image required size may be smaller than the maximum possible size.

In order to be 100% sure of allocating buffers correctly, you should either hard code the buffer size to known big enough sizes or use the device GenICam GevPayloadSize parameter for dynamic cases.

Return type:

int

Returns:

The size, in bytes, required to hold the image in this buffer.

GetEffectiveImageSize()

Effective image size.

Uses same size x and y as GetImageSize() but excludes all padding.

Return type:

int

Returns:

The effective image size

SetOffsetX(aValue)

Sets the Offset X attribute of the image.

Parameters:

aValue (int, in) – New value.

SetOffsetY(aValue)

Sets the Offset X attribute of the image.

Parameters:

aValue (int, in) – New value.

IsAllocated()
IsAttached()
Alloc(aSizeX, aSizeY, aPixelType, aPaddingX=0, aPaddingY=0, aMaximumChunkLength=0)

Allocates memory for this PvImage.

Allocs a PvImage of specific width, height and pixel format

Parameters:

  • aSizeX (int, in) – The width of the image, in pixels. See #GetWidth.

  • aSizeY (int, in) – The height of the image, in pixels. See #GetHeight.

  • aPixelType (int, in) – The GEV pixel type from which the pixel depth is extracted. For supported pixel types, see PvPixelType.h.

  • aPaddingX (int, in, optional) – The horizontal padding of the image, in pixels. See #GetPaddingX.

  • aPaddingY (int, in, optional) – The vertical padding of the image, in pixels. See #GetPaddingY.

  • aMaximumChunkLength (int, in, optional) – The chunk size in bytes.

Return type:

PvResult

Returns:

Includes:

Free()

Frees (de-allocates) the buffer’s internal memory.

See also: Alloc

Attach(self, aRawBuffer, aPixelType, aPaddingX, aPaddingY, aMaximumChunkLength) -> PvResultAttach(self, aRawBuffer, aPixelType, aPaddingX, aPaddingY, aMaximumChunkLength) -> PvResultAttach(self, aRawBuffer, aPixelType, aPaddingX, aPaddingY, aMaximumChunkLength) -> PvResultAttach(self, aRawBuffer, aPixelType, aPaddingX, aPaddingY, aMaximumChunkLength) → PvResult

Attach this PvImage to an external memory buffer.

Parameters:
Return type:

PvResult

Returns:

Includes:

Detach(self) → ndarray

Releases an attached memory buffer.

Does nothing other then resetting the memory buffer pointer to NULL.

Return type:

ndarray

Returns:

The previously attached numpy array. See PvImage.Attach.

See also: Attach

IsPartialLineMissing()

If true, the grabber (on the device) was missing at least one pixel in at least one of the lines when the frame was grabbed.

Return type:

boolean

Returns:

True if at least one pixel was missing, false otherwise

IsFullLineMissing()

If true, the grabber (on the device) was missing at least one line when the frame was grabbed.

Return type:

boolean

Returns:

True if full lines were missing, false otherwise

SetFullLineMissing(aValue, aLineNumber)

Simulates the FullLineMissing used by Pleora video interfaces.

Parameters:

  • aValue (boolean, in) – True to enable, false to disable

  • aValue – The Actual line number in the image.

SetEOFByLineCount(aValue=True)

Simulates the EOFByLineCount used by Pleora video interfaces.

Parameters:

aValue (boolean, in, optional) – True to enable, false to disable

ClearEOFStatus()

Set the EoFByLineCount and FullLineMissing Status of PvImage to the default value false.

This method should be called on every PvImage if the EoFByLineCount feature is used for streaming. It set the EoFByLineCount and FullLineMissing Status of the PvImage to the default value false, the user could then decide if and which status needs to be set on the current PvImage.

IsEOFByLineCount()

End of Frame by Line Count status bit.

Return type:

boolean

Returns:

True if previous frame was NOT the last one of a sequence of sub frames. False otherwise.

IsInterlacedEven()

The image contained in the PvImage is an interlaced Even field.

Return type:

boolean

Returns:

True interlaced Even field. False otherwise.

IsInterlacedOdd()

The image contained in the PvImage is an interlaced Odd field.

Return type:

boolean

Returns:

True interlaced Odd field. False otherwise.

IsImageDropped()

Image dropped status bit.

Return type:

boolean

Returns:

True if the previous frame was dropped. False otherwise.

IsDataOverrun()

Data overrun status bit.

Return type:

boolean

Returns:

True if there was a data overrun. False otherwise.

GetBuffer()

Returns the PvBuffer this PvImage belongs to.

Return type:

PvBuffer

Returns:

Pointer to a PvBuffer.

HasWatermark()

Returns the watermark tag.

A watermark is applied onto the image if the system is not provided with a valid eBUS receiver license.

Use this method to check if a watermark was applied to the image or not.

Return type:

boolean

Returns:

The watermark tag.

class eBUS.PvInterface(*args, **kwargs)

Bases: object

Represents one interface (network adapter or USB host controller) on a system (the PC)

To use this class, see PvSystem.

property thisown

The membership flag

__init__(*args, **kwargs)
Copy()

Creates a copy of the PvInterface object.

The user is responsible from freeing/deleting the object after use. The object is fully detached from PvSystem or the device finder dialog object.

Return type:

PvInterface

Returns:

Pointer to the PvInterface copy. The user is reponsable to delete/free this pointer.

GetType()

Get the interface type.

Return type:

int

Returns:

Type of interface (network interface or USB host controller). See PvInterfaceType Enum.

GetName()

Get the description of the NIC, as reported by the OS.

Return type:

str

Returns:

The description of the NIC, as reported by the OS. The value is intended only for human reading.

GetDisplayID()

Get a string that can be used in a user interface to identify the interface.

Return type:

str

Returns:

The interface’s display ID.

GetUniqueID()

Get a string uniquely identifying the interface.

The content of the unique ID is not garanteed to be represent anything or to be constant between revisions of the eBUS SDK. It should only be used to opaquely, uniquely match other interface unique IDs from within the same application life cycle.

Do not assume the unique ID will be using a MAC address for network adapters or anything specifc for USB host controllers.

If you need the MAC address of a network adapter, use PvNetworkAdapter.GetMACAddress.

If you need specific information about a USB host controller, use the PvUSBHostController class.

Return type:

str

Returns:

The interface’s unique ID.

GetCompareID()

Get a string that can be used to sort interfaces.

The content of the compare ID is not garanteed to be represent anything or to be constant between revisions of the eBUS SDK.

It should only be used to opaquely, uniquely compare other interface sorting IDs to allow consistent sorting and ordering of interfaces, typically in a user interface context.

Return type:

str

Returns:

String that can be used to sort interfaces.

GetDeviceCount()

Get the number of found devices on this PvInterface.

Return type:

int

Returns:

The number of devices found through this PvInterface.

GetDeviceInfo(aIndex)

Get information identifying a device.

Returns information identifying a device discovered on this interface (network adapter or USB host controller). This information can be used to connect and control it with a PvDevice object.

To connect, use PvDevice.CreateAndConnect (supports both GigE Vision and USB3 Vision devices), PvDeviceGEV.Connect or PvDeviceU3V.Connect.

Parameters:

aIndex (int, in) – The device’s array position. The zero-based parameter accepts 0 through #GetDeviceCount-1.

Return type:

PvDeviceInfo

Returns:

Information identifying a device; a PvDeviceInfo object. If aIndex is out of bounds, the return is NULL.

static Compare(a1, a2)

Static method used for sorting interfaces

Parameters:
Return type:

boolean

Returns:

  • true if the value of the first character that doesn’t match is lower in a1’s ID or all compared characters match but the compared ID is shorter.

  • false otherwise.

GetPleoraDriverVersion()

Get the eBUS driver version installed on this PvInterface.

Return type:

str

Returns:

  • The eBUS driver version, if installed. The numbers are, in order: the major, minor, subminor and build number (format: #.#.#.#.####).

  • An empty string if the eBUS driver is not currently installed on the interface.

class eBUS.PvLogSink

Bases: object

property thisown

The membership flag

__init__()
Log(aLevel, aFile, aLine, aFunction, aCategory, aMessage)
class eBUS.PvLogger(aCategory)

Bases: object

property thisown

The membership flag

__init__(aCategory)
LogInfo(self, aMessage)

Log at info level.

Parameters:

aMessage (str, in) – Message to log.

LogError(self, aMessage)

Log at error level.

Parameters:

aMessage (str, in) – Message to log.

LogWarning(self, aMessage)

Log at warning level.

Parameters:

aMessage (str, in) – Message to log.

LogCritical(self, aMessage)

Log at critical level.

Parameters:

aMessage (str, in) – Message to log.

LogDebug(self, aMessage)

Log at debug level.

Parameters:

aMessage (str, in) – Message to log.

SetLogPriority(aLevel)
GetLogPriority()
class eBUS.PvNetworkAdapter

Bases: PvInterface

Represents one Ethernet network adapter on a system (the PC)

To use this class, see PvSystem.

property thisown

The membership flag

__init__()

Constructor.

GetMACAddress()

Get the NIC’s MAC address.

Return type:

str

Returns:

The NIC’s MAC address. The form is ##.##.##.##.##.##, where # is a 0-9 or A-F.

GetDescription()

Returns the operating system provided description of the network adapter.

Return type:

str

Returns:

Description of the network adapter.

GetIPAddressCount()

Returns one of the IP addresses for the network adapter, index-based.

IP addresses and subnet masks are enumerated together. GetIPAddressCount is used to get the 0-based range that can be used with both GetIPAddress and GetSubnetMask. The subnet mask of 0 matches the IP addresses of 0, etc.

Return type:

int

Returns:

One of the IP addresses used by the adapter represented as a string.

GetIPAddress(aIndex)

Returns the IP address of the network adapter.

IP addresses and subnet masks are enumerated together. The subnet mask of 0 matches the IP addresses of 0, etc.

Parameters:

aIndex (int, in) – The IP configuration index.

Return type:

str

Returns:

One of the IP addresses of the network adapter.

GetSubnetMask(aIndex)

Returns the subnet mask of one of the IP addresses of the network adapter.

IP addresses and subnet masks are enumerated together. The subnet mask of 0 matches the IP addresses of 0, etc.

Parameters:

aIndex (int, in) – The IP configuration index.

Return type:

str

Returns:

One of the IP addresses of the network adapter.

GetDefaultGateway()

The NIC’s default gateway.

Return type:

str

Returns:

The NIC’s default gateway. The form follows that of #GetIPAddress.

IsPleoraDriverInstalled()

Returns true if the Pleora driver is installed on this network interface.

Return type:

boolean

Returns:

True if the Pleora driver is installed on this network interface.

class eBUS.PvPipeline(aStream)

Bases: object

Helper class for receiving data from a GigE Vision or USB3 Vision transmitter.

The process of receiving data from a GigE Vision or USB3 Vision transmitter involves queuing buffers into the data receiver ensuring that there are always buffers available for the incoming data. PvPipeline partners with a PvStream object to allocate and push buffers into the data receiver as needed.

For further information on how PvPipeline fits in with the process of receiving data from a GigE Vision transmitter, refer to the receiving data from a transmitter (“receivingdata.html”) page.

property thisown

The membership flag

__init__(aStream)

Constructor.

The PvPipeline is just a helper of a PvStream class. Your code is still the owner of the PvStream class.

Parameters:

aStream (PvStream, in) – The object responsible for receiving data from a GEV transmitter; a PvStream object.

GetBufferSize()

Get the size for all managed buffers in bytes.

Return type:

int

Returns:

The size of managed buffers, in bytes.

GetBufferCount()

Get number of buffers owned and used by the pipeline.

Return type:

int

Returns:

The number of buffers.

GetOutputQueueSize()

Returns the number of PvBuffer objects currently available in the output queue.

PvBuffer objects are pushed into the output queue as soon as they have been populated with incoming data. PvBuffer objects are pulled out of the output queue by calling #RetrieveNextBuffer. The number of buffers available in the pool managed by PvPipeline is limited to #GetBufferCount. If the calling application cannot retrieve buffers at the rate that data is arriving, buffers are silently dropped. To obtain a count of dropped buffers, refer to the PipelineImagesDropped property of the PvStream parameters.

Return type:

int

Returns:

The number of PvBuffer currently available in the output queue.

GetHandleBufferTooSmall()

Returns if the pipeline is configured to handle BUFFER_TOO_SMALL operation results automatically.

Return type:

boolean

Returns:

True if the pipeline handles BUFFER_TOO_SMALL operation results automatically.

See also: PvPipeline.SetHandleBufferTooSmall

IsStarted()

Test if the pipeline has started.

Return type:

boolean

Returns:

True if the pipeline has been started (using #Start); otherwise, false.

SetBufferSize(aSize)

Set the optimal size of buffers being queued into the data receiver

Each time a buffer is queued into the data receiver, it is re-allocated as necessary according to the following behavior:

  • If the buffer size is less than the require buffer size (BUFFER_TOO_SMALL) it is re-allocated.

  • If the buffer size is more than four times the required buffer size, it is re-allocated in order to save memory.

Originally the buffer size can be specified using SetBufferSize. The pipeline automatically adjusts the buffer size based on incoming buffers. As buffers are returned to the pipeline and being queued by the data receiver they may be re-allocated as described above.

Parameters:

aSize (int, in) – The size of the buffer, in bytes.

See also: PvBuffer.Alloc

SetBufferCount(aBufferCount)

Set the number of buffers owned and used by the PvPipeline.

Buffers are added or removed as necessary until the actual buffer count matches the desired buffer count being set. During this time, the pipeline is paused temporarily.

Parameters:

aBufferCount (int, in) – The total number of buffers.

Return type:

PvResult

Returns:

Includes:

SetHandleBufferTooSmall(aValue)

Configures whether the pipeline handles BUFFER_TOO_SMALL operation result or not.

If the pipeline is configured to handle BUFFER_TOO_SMALL operation results the buffers are automatically re-allocated and re-queued for acquisition when this condition occurs.

If the pipeline is not configured to handled BUFFER_TOO_SMALL operation results the buffers are queued in the pipeline output queue just as any other buffer and what to do with the buffer is deferred to the application using PvPipeline.

If the pipeline handles BUFFER_TOO_SMALL operation results, the PvPipelineEventSink.OnBufferTooSmall callback is invoked in order to order to query how to handle the condition. If not implemented the default behaviour is applied. See PvPipelineEventSink.OnBufferTooSmall for more information.

PvPipelineEventSink.OnBufferTooSmall is not invoked when the pipeline is not configured to handle BUFFER_TOO_SMALL operation results.

Parameters:

aValue (boolean, in) – If true, the pipeline handles BUFFER_TOO_SMALL operation results automatically. If false the pipeline queues these buffers in the output queue and defers handling of these buffers to the application.

RetrieveNextBuffer(aTimeout=4294967295) → PvResult, PvBuffer, PvResult

Retrieve the next acquired block

Once the method returns, you can determine the ultimate success of the image acquisition by testing the operational_result. For example, #RetrieveBuffer may return a result of PV_OK, even if the operation was aborted (by a call to #AbortQueuedBuffers or #Close). In this case, operation_result would be PV_ABORTED.

Parameters:

aTimeout (int, in) – The maximum time, in ms, to wait for a buffer to be received. The default value is 0xFFFFFFFF milliseconds (wait forever)

Return type:

Tuple(PvResult, PvBuffer, PvResult)

Returns:

Tuple composed of (result, pvbuffer, operational_result).

ReleaseBuffer(aBuffer)

Return a buffer to the pipeline.

IMPORTANT: all buffers retrieved through #RetrieveNextBuffer must be released back to the PvPipeline. A minimum of 4 buffers must be available to the PvPipeline at all times.

Parameters:

aBuffer (PvBuffer, in) – A pointer to the buffer to return to the queue.

Return type:

PvResult

Returns:

Includes:

Start()

Starts the PvPipeline.

In order to retrieve images from the stream and make them available to #RetrieveNextBuffer, the pipeline must be running. This starts a thread that continually ensures that buffers are allocated and ready in the PvStream so that incoming data is captured.

Return type:

PvResult

Returns:

Includes:

Stop()

Stops the PvPipeline.

Return type:

PvResult

Returns:

Includes:

Reset()

Resets the pipeline.

Synchronously aborts the stream, waits for all buffers to be removed from the stream and queues in a fresh set of buffers. Call ONLY when it is running, otherwise it returns error

Return type:

PvResult

Returns:

Includes:

RegisterEventSink(aEventSink)

Register an event sink used for callbacks.

Parameters:

aEventSink (PvPipelineEventSink, in) – A pointer to the event sink.

Return type:

PvResult

Returns:

Includes:

UnregisterEventSink(aEventSink)

Unregister an event sink

Parameters:

aEventSink (PvPipelineEventSink, in) – A pointer to the event sink.

Return type:

PvResult

Returns:

Includes:

GetBufferHandlingThreadPriority()

Get the priority of the pipeline thread

See #SetBufferHandlingThreadPriority for details about the meaning of the values returned

Return type:

int

Returns:

The priority of the thread

SetBufferHandlingThreadPriority(aPriority)

Set the priority of the pipeline thread

This thread is pretty much the pipeline itself: it queues buffers in PvStream and retrieves them when they are ready, making them available in an output queue.

In Linux, the priorities supported are between 0 and 99, 99 been the highest priority as per the SCHED_FIFO scheduler specifications. If the process is not running with root priviledge, all the threads are run into the SCHED_OTHER ( scheduler 01 ) and have the same priority at 0.

In Windows, the priorities supported are between 0 and 6. The value will be translated into one of the following scheduler defines:

0 - THREAD_PRIORITY_IDLE 1 - THREAD_PRIORITY_LOWEST 2 - THREAD_PRIORITY_BELOW_NORMAL 3 - THREAD_PRIORITY_NORMAL 4 - THREAD_PRIORITY_ABOVE_NORMAL 5 - THREAD_PRIORITY_HIGHEST 6 - THREAD_PRIORITY_TIME_CRITICAL

If you change the thread priorities, it may alterate the stability of the system. For this reason, if you report a bug to Pleora, ensure to clearly mention that you change threads priorities.

See #GetBufferHandlingThreadPriority

Parameters:

aPriority (int, in) – Priority to be set to the conversion threads.

Return type:

PvResult

Returns:

Includes:

class eBUS.PvPipelineEventSink

Bases: object

Observer interface for an observable PvPipeline object

PvPipelineEventSink defines a set of callback methods from a PvPIpeline object to any object implementing this interface.

To receive PvPipeline notifications:

property thisown

The membership flag

__init__()

PvPipeline event sink constructor.

OnBufferCreated(aPipeline, aBuffer)

Called whenever a PvBuffer is allocated by the pipeline.

Can be used to track memory usage or structures used to follow PvBuffer pipeline management.

This method is invoked right after the PvBuffer has been created but before its payload has been allocated.

Parameters:

  • aPipeline (PvPipeline, in) – A pointer to the PvPipeline object.

  • aBuffer (PvBuffer, in) – Pointer to the buffer that was just created.

OnBufferDeleted(aPipeline, aBuffer)

Called whenever a PvBuffer is deleted by the pipeline.

Can be used to track memory usage or structures used to follow PvBuffer pipeline management.

This method is invoked right before the PvBuffer is deleted.

Parameters:

  • aPipeline (PvPipeline, in) – A pointer to the PvPipeline object.

  • aBuffer (PvBuffer, in) – Pointer to the buffer that was just deleted.

OnStart(aPipeline)

PvPipeline event sink OnStart event.

Invoked when the pipeline just before the pipeline starts.

This callback is invoked from the same thread that called PvPipeline.Start.

Parameters:

aPipeline (PvPipeline, in) – A pointer to the PvPipeline object.

OnStop(aPipeline)

PvPipeline event sink OnStop event.

Invoked right after the pipeline has been stopped.

This callback is invoked from the same thread that called PvPipeline.Stop.

Parameters:

aPipeline (PvPipeline, in) – A pointer to the PvPipeline object.

OnReset(aPipeline)

PvPipeline event sink OnReset event.

Invoked after the pipeline has been reset.

This callback is invoked from the same thread that called PvPipeline.Reset.

Parameters:

aPipeline (PvPipeline, in) – A pointer to the PvPipeline object.

OnBufferTooSmall(aPipeline, aReallocAll, aResetStats)

PvPipeline event sink OnBufferTooSmall event.

Invoked when the pipeline retrieve a buffer from the stream object which failed with an operation result set to BUFFER_TOO_SMALL.

The user can set aRealloc all to true in order to force a complete re-allocation of the buffers performed synchronously after the notification is invoked.

If OnBufferTooSmall is not handled to aReallocAll is set to false, the buffer is re-allocated before being queued in the stream object but the other buffers are not affected until they too will fail on BUFFER_TOO_SMALL.

The aResetStats parameter is only considered if aReallocAll is set to true. The statistics do not need to be reset if the buffers are not re-allocated.

This callback is invoked from the pipeline thread.

Parameters:

  • aPipeline (PvPipeline, in) – A pointer to the PvPipeline object.

  • aReallocAll (boolean, in) – If set to true by at least one of the sinks, synchronous buffer re-allocation will be performed.

  • aResetStats (boolean, in) – If set to true by at least one of the sinks, stream statistics are reset.

OnBufferReady(aPipeline)

PvPipeline event sink OnBufferReady event.

Invoked after a buffer has been retrieved from stream and is ready for retrieve

Parameters:

aPipeline (PvPipeline, in) – A pointer to the PvPipeline object.

class eBUS.PvRawData(*args, **kwargs)

Bases: object

Raw data interface to a PvBuffer.

A PvBuffer represents a generic buffer with no specific payload type. If the payload type is raw data, the user can obtain a pointer to a PvRawData buffer interface through PvBuffer.GetRawData.

This PvRawData pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

property thisown

The membership flag

__init__(*args, **kwargs)
GetPayloadLength()

Get the payload length specified in the leader information of this block

If you wish to construct a buffer with payload type “Raw Data”, simply call PvRawData.Alloc or PvRawData.Attach and the payload length field will be set automatically at the time the block is transmitted.

Return type:

int

Returns:

The payload length specified in the leader information of this block

Alloc(aPayloadLength, aMaximumChunkLength=0)

Allocates memory for this PvRawData.

Allocs a PvRawData of specific payload length

Parameters:

  • aPayloadLength (int, in) – The payload length of the raw data, in pixels. See #GetPayloadLength.

  • aMaximumChunkLength (int, in, optional) – Maximum size in bytes to store chunks ( must include extra 64 bits by chunks for headers ).

Return type:

PvResult

Returns:

Includes:

Free()

Frees (de-allocates) the buffer’s internal memory.

See also: Alloc

Attach(self, aRawBuffer, aMaximumChunkLength) → PvResult

Attach this PvRawData to an external memory buffer.

Parameters:

  • aRawBuffer (ndarray, in) – A 1-dimensional python numpy array with dtype np.uint8 to use as a raw buffer.

  • aMaximumChunkLength (int, in) – Maximum size in bytes to store chunks ( must include extra 64 bits by chunks for headers ).

Return type:

PvResult

Returns:

Includes:

Detach(self) → ndarray

Releases an attached memory buffer.

Does nothing other then resetting the memory buffer pointer to NULL.

Return type:

ndarray

Returns:

The previously attached numpy array. See PvRawData.Attach.

See also: PvRawData.Attach

class eBUS.PvResult(*args)

Bases: object

Result information.

The PvResult class provides information about the success or failure of the methods you use.

Most successful methods return PV_OK, however, there are exceptions:

Some methods return immediately, but the ultimate success of the method may not be know for some time after (several seconds or more). These methods return PV_PENDING. Pending operations are considered successful.

To use result codes (best coding practices):

  • Call a method.

  • Test the result for success. Use #IsSuccess, #IsOK, or test against specific PvResultCode values.

property thisown

The membership flag

__init__(*args)

Overload 1:

Constructor.


Overload 2:

Constructor intializing the object to a specific status code.

Parameters:

aCode (int, in) – Code to assign to the PvResult object on construction.


Overload 3:

Constructor intializing the object to a specific status code and OS code.

Parameters:

  • aCode (int, in) – Code to assign to the PvResult object on construction.

  • aOSCode (int, in) – OS code to assign to the PvResult object on construction.


Overload 4:

Constructor initializing the object to a specific status code and description.

Parameters:

  • aCode (int, in) – Code to assign to the PvResult object on construction.

  • aDescription (str, in) – Description to assign to the PvResult object on construction.


Overload 5:

Constructor initializing the object to a specific status code, OS code and description.

Parameters:

  • aCode (int, in) – Code to assign to the PvResult object on construction.

  • aOSCode (int, in) – OS code to assign to the PvResult object on construction.

  • aDescription (str, in) – Description to assign to the PvResult object on construction.


Overload 6:

Copy constructor.

Parameters:

aResult (PvResult, in) – PvResult used to call the copy constructor.

SetCode(aIn)

Assigns a specific error code to this PvResult.

Parameters:

aIn (int, in) – Sets a code for the result.

GetCode()

Get the result code.

Return type:

int

Returns:

The result code.

GetCodeString()

Get the result code in the form of a string.

Return type:

str

Returns:

A string that is the direct translation of the result code.

GetDescription()

Get the result description.

Return type:

str

Returns:

A string that provides human-readable information about the result.

SetDescription(aDescription)

Assigns a specific description to this PvResult.

Parameters:

aDescription (str, in) – Sets a description for the result.

HasDescription()

Returns true if the result has a valid description that can be retrieved with PvResult.GetDescription.

Return type:

boolean

Returns:

True if the result has a valid description.

IsFailure()

Test for a failed result.

Return type:

boolean

Returns:

True if the result is other than PvResult::Code::OK or PvResult::Code::PENDING; otherwise, false.

IsOK()

Test for a successful result

Return type:

boolean

Returns:

True if the result is PvResult::Code::OK; otherwise, false.

IsPending()

Test for a pending result.

Return type:

boolean

Returns:

True if the result is PvResult::Code::PENDING; otherwise, false.

IsSuccess()

Test for a successful result.

Methods for testing result codes include:

  • #IsSuccess (this one)

  • #IsFailure

  • #IsOK

  • #IsPending

Return type:

boolean

Returns:

True if the result is PvResult::Code::OK or PvResult::Code::PENDING; otherwise, false.

GetInternalCode()

Returns the internal error code of the error.

This method can be used to retrieve the internal error code that was mapped to the public error code contained in the PvResult.

The user is not expected to be able to interpret this error code. It can be used in order to provide more information to Pleora support personnel.

Return type:

int

Returns:

Internal error code.

GetOSCode()

Retrieves the internal OS code that may have triggered the error.

The user is not expected to be able to interpret this error code, it can widely vary based on the platform or even API that generated it. It can be used in order to provide more information to Pleora support personnel.

Return type:

int

Returns:

Internal OS code.

class eBUS.PvSessionInfo

Bases: object

Describes a multimedia session (typically an RTP stream) discovered via SAP.

property thisown

The membership flag

property mName
property mAddress
property mPort
property mLocalAddress
__init__()
class eBUS.PvSoftDeviceGEV

Bases: IPvSoftDeviceGEV

Implements a software-based GigE Vision Device with full GVCP and GVSP support.

Basic GigE Vision Device setup:

  • Inherit a class from IPvStreamingChannelSource, implement all virtual pure methods

  • Instantiate an object from your streaming source class

  • Instantiate a PvSoftDeviceGEV object

  • Add your streaming channel to the GigE Vision Device using #AddStream

  • Call PvSoftDeviceGEV.Start, selecting the network interface to bind to

  • Use PvSoftDeviceGEV.GetInfo to set the identity of your GigE Vision Device

  • At this point your GigE Vision Device should be available on the network

A more advanced GigE Vision Device setup:
property thisown

The membership flag

__init__()

Constructor.

GetInfo()

Obtains the information interface of the PvSoftDeviceGEV.

Only available after the PvSoftDeviceGEV has been started.

IPvSoftDeviceGEVInfo is used to set the information strings in the read-only bootstrap registers of the PvSoftDeviceGEV, such as Model Name, Vendor Name, etc.

Return type:

IPvSoftDeviceGEVInfo

Returns:

Information interface of the PvSoftDeviceGEV or NULL if the device is not running.

AddStream(aSource)

Adds a new stream to the PvSoftDeviceGEV.

All streams must be added before starting the PvSoftDeviceGEV.

Parameters:

aSource (IPvStreamingChannelSource, in) – Interface to a user-provided source.

Return type:

PvResult

Returns:

Includes:

SetUserSetCount(aCount)

Sets the number of user-sets supported by the PvSoftDeviceGEV.

The maximum supported user-set count is 256.

Can only be changed before starting the device.

User-sets are all about device-side persistence. The status of the device can be saved or retrieved from some static store on the device. User-sets are first and foremost managed at the register level. The SFNC allowing defines the UserSetFeatureSelector which is populated with feature names. This creates an imperfect but mostly acceptable one-to-one link between Streamable (persistent) GenApi features and the register providing its implementation.

Features marked as Streamable (persistent) when creating the GenICam XML file of the device are used for device-side persistence through user-sets.

Persistent features have the content of the register they directly map to saved to the persistent store of the device. The persistent store is implemented through the Registry on Windows and profile home files on Linux. Hardware implementations could rely on Flash memory to store user-sets.

Most registers are simply persisted as-is: their binary content is simply saved to or loaded from the store.

Some registers have only one address but can contain many values when indexed through device-managed selectors. If those registers are Streamable (persistent) the application must handle the IPvRegisterEventSink.Persist event for the registers and for each possible selector combination call IPvRegisterStore.Persist. For the application the same code is used for both save and load operations, thus the generic “persist” naming.

The SoftDeviceGEV sample shows basic use of user-sets.

Conditional comment: The SoftDeviceGEV3d sample shows how to handle complex multi-selector registers in the context of user-sets. End of conditional comment.

Selected registers handling in pseudo-code:

  • Save current selector of interest values

  • Set selectors to 1st combination

  • Call IPvRegisterStore.Persist with register and unique name suffix representing selector of interest values

  • Set selectors to 2nd combination

  • Call IPvRegisterStore.Persist with register and unique name suffix representing selector of interest values

  • …

  • Restore selector values

The IPvRegisterStore.Persist method loads or saves the register content in the store using the feature name and provided suffix.

On startup the default user-set is always updated in the store from the fresh device status. If the UserSetDefault GenApi feature is assigned to a user-set other than Default, the user-set is automatically loaded on device startup.

The UserSetDefault GenApi feature is special: it is not saved to a user-set but is immediately and automatically persistent to the store whenever changed.

User-sets can be saved and loaded explicitly using the UserSetSelector, UserSetSave, and UserSetLoad GenApi features.

The UserSetFeatureSelector and UserSetFeatureEnable GenApi features can be used to control which features are saved to the user-sets. All features defined as Streamable when creating the GenICam XML file of the device should be available under the UserSetFeatureSelector enum feature.

Parameters:

aCount (int, in) – Count of user-sets supported, in addition to the default user-set.

Return type:

PvResult

Returns:

Includes:

SetUserSetNotify(aUserSetNotify)
Binds in a class which will contain a callback which will be called when the

state of a UsersetLoad/Save changes.

Return type:

PvResult

Returns:

Includes

SetTCPTransportEnabled(aEnabled)

Enables experimental TCP transport.

PvSoftDeviceGEV supports optional, experimental TCP transport for GigE Vision devices. It affects GVCP control, GVCP messaging channel and GVSP streaming.

When TCP is enabled the device still respond to UDP requests as usual. Additional TCP sockets are opened to optionally accept TCP connections from the host.

As long as TCP is not fully ratified by the GigE Vision specification, enabling TCP could and most likely will break GigE Vision compliance. It also means only the eBUS PvDeviceGEV and PvStreamGEV can be used to interact with the device when using TCP transport.

Parameters:

aEnabled (boolean, in) – Toggles TCP support.

Return type:

PvResult

Returns:

PV_OK

SetRTPProtocolEnabled(aEnabled)

Enables the option of using RTP for streaming.

PvSoftDeviceGEV supports optional RTP protocol for GigE Vision devices.

When RTP is enabled it can be selected as the protocol used to data transmission at the stream channel level of the GenApi interface of the device.

RTP supported is not covered by the GigE Vision specification. A GigE Vision Device actively streaming using RTP goes beyond the bounds covered by the GigE Vision standard.

The RTP implementation is however compliant with the RTP RFCs covering the transport of images (RFC 4175) and H.264 data (RFC 6184).

When a stream transmits using the RTP protocol, the stream is announced on a multicast channel (224.2.127.254:9875) using the SAP protocol with a SDP descriptor as required by the DEFSTAN 0082 specification.

Parameters:

aEnabled (boolean, in) – Toggles RTP support.

Return type:

PvResult

Returns:

PV_OK

SetStreamTimestamping(aEnabled)

Enables stream timestamping on all sources. ‘True’ by default.

Buffers are timestamped by the acquisition manager. This method can be called with a ‘False’ value to skip timestamping when placing the buffers into the queue.

This method can be useful in a scenario where the original timestamp of the buffer needs to be preserved, or if the timestamp is updated externally (in the application). Doing so will prevent the acquisition manager to override the timestamp before transmission.

The method does not affect GenICam registers or message channel timestamps.

Parameters:

aEnabled (boolean, in) – Toggles stream timestamping.

Return type:

PvResult

Returns:

PV_OK

SetActionHandler(aActionHandler)
Return type:

PvResult

Returns:

PvResult.

GetRegisterMap()

Obtains the register map interface of the PvSoftDeviceGEV.

Only available after the PvSoftDeviceGEV has been started.

IPvRegisterMap can be used to directly access the register map of the PvSoftDeviceGEV. It is also possible to subscribe to register read/write events using IPvSoftDeviceGEVEventSink.

See IPvSoftDeviceGEVEventSink.OnCreateCustomRegisters for information about adding custom registers to a PvSoftDeviceGEV.

Return type:

IPvRegisterMap

Returns:

Register map interface of the PvSoftDeviceGEV or NULL if the device is not running.

Start(aMACAddress)

Starts the PvSoftDeviceGEV.

Both GVCP and GVSP are operated from a background thread. Even though the Start method returns, the device is running in your process until you call Stop or until the object is destroyed.

Parameters:

aMACAddress (str, in) – MAC address of the interface to bind the PvSoftDeviceGEV to.

Return type:

PvResult

Returns:

Includes:

Stop()

Stops the PvSoftDeviceGEV.

Return type:

PvResult

Returns:

Includes:

GetStatistics()

Obtains the statistics interface of the PvSoftDeviceGEV.

Only available after the PvSoftDeviceGEV has been started.

Return type:

IPvSoftDeviceGEVStatistics

Returns:

Statistics interface of the PvSoftDeviceGEV or NULL if the device is not running.

GetMessagingChannel()

Obtains the messaging channel interface of the PvSoftDeviceGEV.

The IPvMessageChannel interface can be used to send events on the messaging channel when a GigE Vision controller is connected to the PvSoftDeviceGEV and has properly set up a destination for messaging channel events.

See also: IPvMessageChannel

Only available after the PvSoftDeviceGEV has been started.

Return type:

IPvMessageChannel

Returns:

Messaging channel interface of the PvSoftDeviceGEV or NULL if the device is not running.

RegisterEventSink(aEventSink)

Registers an event sink to receive notifications from the PvSoftDeviceGEV.

This method can be called before the PvSoftDeviceGEV is started.

See also: IPvVirtualDeviceEventSink

Parameters:

aEventSink (IPvSoftDeviceGEVEventSink, in) – Pointer to a PvSoftDeviceGEV event sink.

Return type:

PvResult

Returns:

Includes:

UnregisterEventSink(aEventSink)

Unregisters a previously registered event sink.

This method can be called before the PvSoftDeviceGEV is started and after it has been stopped.

Parameters:

aEventSink (IPvSoftDeviceGEVEventSink, in) – Pointer to a PvSoftDeviceGEV event sink.

Return type:

PvResult

Returns:

Includes:

GetGenICamXMLFile() → PvResult, str

Returns the GenICam XML file of the device.

Can be used to retrieve the GenICam XML file of the device after the Start method has been called.

Can be used on success or failure of the Start method.

Return type:

Tuple(PvResult, str)

Returns:

Tuple composed of (result, xmlFile)
  • result representing the outcome:

    • PV_OK

    • STATE_ERROR if the GenICam XML file is not available (likely Start has not been called yet)

  • xmlFile:

    • String where the XML file is copied.

class eBUS.PvStream(*args, **kwargs)

Bases: object

Receive data from a GigE Vision or USB3 Vision transmitter.

This provides a means of opening a connection to the data receiver and obtaining data from it.

property thisown

The membership flag

__init__(*args, **kwargs)
GetQueuedBufferCount()

Get the number of buffers (PvBuffer objects) waiting to be filled with images by the data receiver.

Every call to #QueueBuffer increases the count by one; every call to #RetrieveBuffer reduces the count by one.

Return type:

int

Returns:

The number of buffers (PvBuffer objects).

GetQueuedBufferMaximum()

Get the maximum number of buffers (PvBuffer objects) that can be queued at a time.

Return type:

int

Returns:

Maximum number of buffers (PvBuffer objects).

static CreateAndOpen(*args) → PvResult, PvStream

Dynamically allocates a PvStream of the right type.

This static method takes a string or PvDeviceInfo, creates the right type of PvStream (PvStreamGEV or PvStreamU3V) and opens it.

Objects allocated with CreateAndOpen should be freed with PvStream.Free.

Overload 1:

Parameters:

aDeviceInfo (PvDeviceInfo, in) – The GigE Vision device’s network connectivity information; a PvDeviceInfo object.

Return type:

Tuple[PvResult, PvStream]

Returns:

Tuple composed of (result, pvstream):


Overload 2:

Parameters:

aInfo (str, in) – String identifying the device. You may use one of the following: - GigE Vision devices IP Address. Use the form 192.168.1.1. - USB3 Vision GUID.

Return type:

Tuple[PvResult, PvStream]

Returns:

Tuple composed of (result, pvstream):

static Free(aStream)

Frees an object allocated with CreateAndOpen.

Even though calling delete on a PvStream created with CreateAndOpen should work in most cases, sometime it is necessary to call “delete” in the same context where “new” was called to avoid false positives on memory leaks.

It is a good practice to use this method to free a PvStream allocated with CreateAndOpen.

Parameters:

aStream (PvStream, in) – Pointer to the device object to delete.

Open(*args)
Close()

Close the stream channel receiver.

Return type:

PvResult

Returns:

Includes:

See also: Open

GetType()

Returns whether the object is a GigE Vision or USB3 Vision stream receiver.

Return type:

int

Returns:

Specific object type.

AbortQueuedBuffers()

Abort all pending block requests

Once you’ve aborted pending block requests, they still need to be de-queued. Use #RetrieveBuffer.

Return type:

PvResult

Returns:

Includes:

QueueBuffer(aBuffer)

Queue a buffer to receive a block.

The #QueueBuffer method queues in a buffer (PvBuffer object) to a stream (PvStream object) so it can be filled by the data receiver.

For each buffer you remove (using #RetrieveBuffer), you should queue another (using #QueueBuffer). The maximum number of buffers that can be queued at a given time can be obtained by calling #GetQueuedBufferMaximum. To reduce the risk of missing incoming data, it is recommended that several blocks remain queued and ready to go at any given time. Generally it is recommended that a larger number of buffers remain queued for higher frame rates. Larger block sizes with blocks being streamed at a lower frame rate can afford to allocate fewer buffers to optimize memory usage and reduce potential latency.

Once the stream fills the buffer with a block, retrieve the buffer by calling #RetrieveBuffer.

Parameters:

aBuffer (PvBuffer, in) – A pointer to the buffer to be filled.

Return type:

PvResult

Returns:

Includes:

RetrieveBuffer(aTimeout=4294967295) → PvResult, PvBuffer, PvResult

Attempt to retrieve a queued buffer.

To use this method, see also #QueueBuffer.

The #RetrieveBuffer method blocks until one of the following occurs:

  • The buffer is filled with a block (image or raw data).

  • The retrieve buffer operation times out: it exceeds aTimeout.

  • The acquisition fails (by being aborted, data receiver timeout as defined by ImageTimeout property, etc.)

Once the method returns, you can determine the ultimate success of the image acquisition by testing the operational_result. For example, #RetrieveBuffer may return a result of PV_OK, even if the operation was aborted (by a call to #AbortQueuedBuffers or #Close). In this case, operation_result would be PV_ABORTED.

The result returned contains the RetrieveBuffer operation results and operation_result contains the actual result (or failure) of the data receiver on this buffer. This method can succeed in providing you the oldest buffer but the result of the operation may still be a failure - if acquisition was aborted, incomplete, etc.

Parameters:

aTimeout (int, in) – The maximum time, in ms, to wait for a buffer to be returned by the data receiver. | The default value is 0xFFFFFFFF milliseconds (wait forever)

Return type:

Tuple[PvResult, PvBuffer, PvResult]

Returns:

Tuple composed of (result, pvbuffer, operational_result):

GetChannel()

Get the stream’s Channel property.

Return type:

int

Returns:

The stream’s Channel property.

IsOpen()

Test if the stream is open.

Return type:

boolean

Returns:

True if the stream is opened; otherwise, false.

RegisterEventSink(aEventSink)

Register an event sink used for callbacks.

Parameters:

aEventSink (PvStreamEventSink, in) – A pointer to the event sink.

Return type:

PvResult

Returns:

Includes:

UnregisterEventSink(aEventSink)

Unregister an event sink

Parameters:

aEventSink (PvStreamEventSink, in) – A pointer to the event sink.

Return type:

PvResult

Returns:

Includes:

See also: #RegisterEventSink

GetParameters()

Get the parameters defining how data is received from a GigE Vision transmitter

Return type:

PvGenParameterArray

Returns:

The parameters defining how data is received from a GigE Vision transmitter

class eBUS.PvStreamGEV

Bases: PvStream

Receive data from a GigE Vision.

This provides a means of opening a connection to the data receiver and obtaining data from it.

property thisown

The membership flag

__init__()

Constructor.

Open(*args)

Overload 1:

Begin receiving blocks (images or raw data) unicasted from a GigE Vision transmitter.

See equivalent Open method with aInfo PvString as first parameter for more information.

Parameters:

aDeviceInfo (PvDeviceInfo, in) – Device information as retrieved from a device finder.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Begin receiving blocks (images or raw data) unicasted from a GigE Vision transmitter.

See equivalent Open method with aInfo PvString as first parameter for more information.

Parameters:

  • aDeviceInfo (PvDeviceInfo, in) – Device information as retrieved from a device finder.

  • aLocalPort (int, in) – The local port upon which to begin receiving incoming data. A value of 0 (default) indicates that the local port will be assigned automatically. Call #GetLocalPort afterwards to obtain the port number that was assigned by the system. Set the streaming channel destination address (SCDA) on your GigE Vision transmitter accordingly by calling PvDeviceGEV.SetStreamDestination.

  • aChannel (int, in, optional) – The GigE Vision transmitter’s streaming channel (default 0).

  • aLocalIPAddress (str, in, optional) – Deprecated and ignored.

  • aBuffersCapacity (int, in, optional) – The maximum number of buffers that can be stored simultaneously in the data receiver.

Return type:

PvResult

Returns:

Includes:


Overload 3:

Begin receiving blocks (images or raw data) multicasted from a GigE Vision transmitter.

See equivalent Open method with aInfo PvString as first parameter for more information.

Parameters:

  • aDeviceInfo (PvDeviceInfo, in) – Device information as retrieved from a device finder.

  • aMulticastAddr (str, in) – The multicast IP address to which the receiver subscribes and the GigE Vision transmitter sends data. (Set the streaming channel destination address (SCDA) on your GigE Vision transmitter accordingly by calling PvDeviceGEV.SetStreamDestination.)

  • aDataPort (int, in) – The multicast port to which the receiver subscribes and the GigE Vision transmitter sends data. (Set the streaming channel port (SCP) on your GigE Vision transmitter accordingly by calling PvDeviceGEV.SetStreamDestination.)

  • aChannel (int, in, optional) – The GigE Vision transmitter’s streaming channel (default 0).

  • aLocalIPAddress (str, in, optional) – Deprecated and ignored.

  • aBuffersCapacity (int, in, optional) – The maximum number of buffers that can be stored simultaneously in the data receiver.

Return type:

PvResult

Returns:

Includes:


Overload 4:

Begin receiving blocks (images or raw data) unicasted from a GigE Vision transmitter.

Note that this overload of Open is for receiving blocks that are unicasted from a GigE Vision transmitter to an interface on the same subnet.

To receive multicasted data, refer to the other overload of the other (multicast) Open method.

Parameters:

aInfo (str, in) – The GigE Vision transmitter’s IP address.

Return type:

PvResult

Returns:

Includes:


Overload 5:

Begin receiving blocks (images or raw data) unicasted from a GigE Vision transmitter.

Note that this overload of Open is for receiving blocks that are unicasted from a GigE Vision transmitter to an interface on the same subnet.

To receive multicasted data, refer to the other overload of the other (multicast) Open method.

Parameters:

  • aInfo (str, in) – The GigE Vision transmitter’s IP address.

  • aLocalPort (int, in) – The local port upon which to begin receiving incoming data. A value of 0 (default) indicates that the local port will be assigned automatically. Call #GetLocalPort afterwards to obtain the port number that was assigned by the system. Set the streaming channel destination address (SCDA) on your GigE Vision transmitter accordingly by calling PvDeviceGEV.SetStreamDestination.

  • aChannel (int, in, optional) – The GigE Vision transmitter’s streaming channel (default 0).

  • aLocalIPAddress (str, in, optional) – The local IP address upon which to begin receiving incoming data. An empty string (default) indicates that the local IP address will be assigned automatically. Call #GetLocalIPAddress afterwards to obtain the local IP address that was assigned by the system. Set the streaming channel port number (SCP) on your GigE Vision transmitter accordingly by calling PvDeviceGEV.SetStreamDestination.

  • aBuffersCapacity (int, in, optional) – The maximum number of buffers that can be stored simultaneously in the data receiver.

Return type:

PvResult

Returns:

Includes:


Overload 6:

Begin receiving blocks (images or raw data) multicasted from a GigE Vision transmitter.

Note that this overload of Open is for receiving blocks that are multicasted from a GigE Vision transmitter to a given multicast group.

To receive unicasted data, refer to the other overload of the Open method.

Multicasting is the delivery of data to a group of receivers simultaneously in a single transmission.

The following example illustrates how to multicast data from one transmitter to a given set of receivers:

  • Connect receivers and transmitter to an IGMP compliant switch.

  • The GigE Vision transmitter begins transmitting to a multicast group (i.e. 239.192.1.1:1042).

  • The GigE Vision transmitter has a control channel listening for device discovery requests and packet resend requests on a given IP address (i.e. 169.254.1.1).

  • Receiver applications discover the device and subscribe to the multicast group (call Open( “169.254.1.1”, “239.192.1.1”, 1042 ))

Why does the GigE Vision device address (aIPAddress) need to be specified?

  • In this example, the data is transmitted using the GVSP protocol to a multicast group (239.192.1.1:1042).

  • The receiving application contacts the device (IP address 169.254.1.1) using the GVCP protocol to ensure that it is reachable.

  • In addition to this, packet resend requests are directed from receiver to GigE Vision device using the GVCP control channel.

  • This is by design as per the GigEVision standard.

Multicasting uses the IGMP (Internet Group Management Protocol) and requires an IGMP-compliant switch.
The switch maintains a list of subscribed peers associated with a given multicast group.
Multicast group IP addresses take the form 239.192.*xx*.*yy*.

It is also possible to use multicasting with a non-IGMP compliant switch or network. In that case, the multicast stream is simply broadcasted to every connected entity on the network. It can be OK in controlled environment, but use with caution!

To learn more about IGMPv3, see RFC 3376 at www.ietf.org.

For a complete illustration of how to use this method to receive data multicasted from a GigE Vision transmitter, refer to the following two samples:

  • MulticastMaster - Connects to a GigE Vision device as a controler and tells it to begin streaming to a multicast address.

  • MulticastSlave - Illustrates the use of PvStream multicast Open method by receiving the data the GigE Vision device is transmitting.

Parameters:

  • aInfo (str, in) – The GigE Vision transmitter’s IP address.

  • aMulticastAddr (str, in) – The multicast IP address to which the receiver subscribes and the GigE Vision transmitter sends data. (Set the streaming channel destination address (SCDA) on your GigE Vision transmitter accordingly by calling PvDeviceGEV.SetStreamDestination.)

  • aDataPort (int, in) – The multicast port to which the receiver subscribes and the GigE Vision transmitter sends data. (Set the streaming channel port (SCP) on your GigE Vision transmitter accordingly by calling PvDeviceGEV.SetStreamDestination.)

  • aChannel (int, in, optional) – The GigE Vision transmitter’s streaming channel (default 0).

  • aLocalIPAddress (str, in, optional) – The local IP address upon which the stream object will begin receiving incoming data. An empty string (default) indicates that the local ip address will be assigned automatically.

  • aBuffersCapacity (int, in, optional) – The maximum number of buffers that can be stored simultaneously in the data receiver.

Return type:

PvResult

Returns:

Includes:

GetType()

Returns whether the object is a GigE Vision or USB3 Vision stream receiver.

Return type:

int

Returns:

Specific object type.

GetDataReceiverType()

Returns the type of GigE Vision data receiving used by the stream receiver.

Return type:

int

Returns:

Data receiver type. See PvDataReceiverType Enum.

FlushPacketQueue()

Flushes all non-processed UDP packets from the data receiver.

Should be called before resuming streaming after a pause to ensure that old packets are not processed as new incoming data.

Return type:

PvResult

Returns:

Includes:

GetWaitForFirstPacketOfBlockToStart()

Wait for the first packet of the block to start the stream capture StartStreamOnlyOnPacketIdZero (“streamparameters.html#StartStreamOnlyOnPacketIdZero”) property.

Return type:

boolean

Returns:

The value of the StartStreamOnlyOnPacketIdZero (“streamparameters.html#StartStreamOnlyOnPacketIdZero”) property.

SetWaitForFirstPacketOfBlockToStart(aWaitForFirstPacketOfBlockToStart)

Set the stream’s StartStreamOnlyOnPacketIdZero (“streamparameters.html#StartStreamOnlyOnPacketIdZero”) property.

Parameters:

aWaitForFirstPacketOfBlockToStart (boolean, in) – The value being set.

Return type:

PvResult

Returns:

PV_OK or PV_NOT_SUPPORTED or PV_NOT_CONNECTED

GetLocalPort()

Get the stream’s DataPort (“streamparametersGEV.html#DataPort”) property.

Return type:

int

Returns:

The stream’s DataPort (“streamparametersGEV.html#DataPort”) property.

GetLocalIPAddress()

Get the stream’s LocalIPAddress (“streamparametersGEV.html#LocalIPAddress”) property.

Return type:

str

Returns:

The stream’s LocalIPAddress (“streamparametersGEV.html#LocalIPAddress”) property.

GetMulticastIPAddress()

Get the stream’s MulticastIPAddress (“streamparametersGEV.html#MulticastIPAddress”) property.

Return type:

str

Returns:

The stream’s MulticastIPAddress (“streamparametersGEV.html#MulticastIPAddress”) property.

GetDeviceIPAddress()

Get the IP address of the device this stream receives data from.

Return type:

str

Returns:

IP address of the streaming device.

GetSpecificLocalPort()

Returns the local UDP port requested when opening the stream.

0 is returned if the user did not open the stream requesting a specific local UDP port if if the stream is not opened.

Return type:

int

Returns:

Local UDP port requested when opening the stream.

GetUserModeDataReceiverThreadPriority()

Get the priority of the thread used to run the data receiver user mode

See #SetUserModeDataReceiverThreadPriority for details about the meaning of the values returned

Return type:

int

Returns:

The priority of the thread

SetUserModeDataReceiverThreadPriority(aPriority)

Set the priority of the thread used to run the data receiver user mode

Only applicable if using a user-mode data receiver. The thread priority of a driver-based data receiver cannot be controlled. This thread receives and processes all packets received from the device.

If you change the thread priorities, it may alterate the stability of the system. For this reason, if you report a bug to Pleora, ensure to clearly mention that you change threads priorities.

See #GetUserModeDataReceiverThreadPriority

Parameters:

aPriority (int, in) – See PvPipeline.SetBufferHandlingThreadPriority for description of the supported values

Return type:

PvResult

Returns:

Includes:

GetUserModeSocketRxBufferSize()

Read the current Receive Buffer Size set by the PvStreamGEV that the socket uses. The API is ONLY supported on Linux System in User Mode when eBUS UniversalProForEthernet Driver is not used. PV_NOT_SUPPORTED will be returned if the API is used on Windows.

See PvStreamGEV.SetUserModeBufferSizeRx for details.

Return type:

Tuple(PvResult, int)

Returns:

Tuple composed of (result, bufferSize).

SetUserModeSocketRxBufferSize(aSize)

Set the Receive Buffer Size through socket option SO_RCVBUF by PvStreamGEV.

The API is ONLY supported in User Mode when eBUS UniversalProForEthernet Driver is not used.

The API allows the user to configure the SO_RCVBUF - the size of the buffer the kernel allocates to hold the data arriving into the given socket between the time when it arrives over the network and when it is read by eBUS SDK User Mode Data Receiver.

In case the method was called when eBUS UniversalProForEthernet Driver is used, the value will be ignored.

This API must be called before PvStreamGEV::Open(), otherwise you will receive NETWORK_CONFIG_ERROR. The actual value set can be confirmed by #GetUserModeSocketRxBufferSize after PvStream::Open() returns successfully. And it’s recommended to always call #GetUserModeSocketRxBufferSize to validate the value set.

To configure and confirm the value used by the socket, you should perform this sequence:

On Linux System:

The value allowed is limited by rmem_max defined on your Linux System. If the value set exceeds rmem_max, rmem_max will be used instead, and the method will return INVALID_PARAMETER.

The rmem_max value on your Linux system could be configured by script set_socket_buffer_size.sh provided by eBUS SDK.

In case the value PvStreamGEV.GetUserModeBufferSizeRx retrieved is not what you expected, check the rmem_max setting first.

Note: The kernel doubles the value set by #SetUserModeSocketRxBufferSize (to allow space for bookkeeping overhead) if possible. The retrived value from #GetUserModeSocketRxBufferSize could be doubled, but should not exceed rmem_max * 2.

Note: the set value is not permanent or global, it is only for the current PVStreamGEV instance.

Parameters:

aSize (int, in) – The Receive Buffer Size to use with socket option SO_RCVBUF.

Return type:

PvResult

Returns:

Includes:

SetUserModeRxPacketBufferSize(aSize)

Set ther Receive Packet Buffer Size used by PvStreamGEV.

The API is ONLY supported in User Mode when eBUS UniversalProForEthernet Driver is not used.

In case the method was called on Linux system when eBUS UniversalProForEthernet Driver is used, the value will be ignored.

This API allows the user to increase the max jumbo packet size eBUS SDK supports. The minimum value can be set is 17000, the default value of eBUS SDK, to support all physical NICs. The maximum value can be set is 65500, to support Virtual NICs. eBUS will set the value to min or max for you if the aSize value is out of range.

Note: the set value is not permanent or global, it is only for the current PVStreamGEV instance.

This API must be called before PvStreamGEV::Open(), otherwise you will receive NETWORK_CONFIG_ERROR.

To configure the value, you should perform this sequence:
Parameters:

aSize (int, in) – The Receive Packet Buffer Size to use when using User Mode DataReceiver. Minimum supported value is 17000 bytes, Maximum is 65500 bytes.

Return type:

PvResult

Returns:

Includes:

static IsDriverInstalled(*args)

Test if the specified GigE Vision device is currently reachable through an eBUS driver

Parameters:

  • aIPAddress (str, in) – The GigE Vision transmitter’s IP address.

  • aInstalled (boolean, out) – True if the device is reachable through an eBUS driver; otherwise, false.

  • aLocalIPAddress (str, in, optional) – Deprecated and ignored.

Return type:

PvResult

Returns:

Includes:

class eBUS.PvStreamRTP

Bases: PvStream

Receive data from a RTP transmitter.

This provides a means of opening a connection to the data receiver and obtaining data from it.

property thisown

The membership flag

__init__()

Constructor.

PrepareFor(aWidth, aHeight, aPixelType, aPaddingX=0)

Tells the stream object to expect uncompressed images of a specific format.

Parameters:

  • aWidth (int, in) – The image’s width to receive.

  • aHeight (int, in) – The image’s height to receive.

  • aPixelType (int, in) – The image’s pixel type to receive.

  • aPaddingX (int, in, optional) – The image’s padding to receive.

Return type:

PvResult

Returns:

PV_OK on success.

PrepareForH264()

Tells the stream object to expect an H.264 stream.

Return type:

PvResult

Returns:

PV_OK on success.

ResetPayloadType()

Resets the expected stream attributes to undefined.

Return type:

PvResult

Returns:

PV_OK on success.

Open(*args)

Overload 1:

Opens a stream from a PvDeviceInfo. Not supported with RTP.

Parameters:

aDeviceInfo (PvDeviceInfo, in) – The PvDeviceInfo input.

Return type:

PvResult

Returns:

PV_NOT_SUPPORTED


Overload 2:

Opens a stream from a device info string. Not supported with RTP.

Parameters:

aInfo (str, in) – The device info, formatted as a string.

Return type:

PvResult

Returns:

PV_NOT_SUPPORTED


Overload 3:

Opens the stream from a SDP session info.

Parameters:

  • aSession (PvSessionInfoSDP, in) – The SDP for a given stream.

  • aLocalIpAddress (int, in) – A local IP address to receive from.

  • aLocalPort (int, in, optional) – A local port to receive from.

Return type:

PvResult

Returns:

PV_NOT_SUPPORTED


Overload 4:

Opens the stream object for unicast RTP receiving.

Parameters:

  • aLocalIpAddress (str, in) – A local IP address to receive from.

  • aLocalPort (int, in) – A local port to receive from.

Return type:

PvResult

Returns:

PV_OK on success.


Overload 5:

Opens the stream object for multicast RTP receiving.

Parameters:

  • aMulticastAddress (str, in) – The multicast IP address of the stream.

  • aDataPort (int, in) – The stream port.

  • aLocalIpAddress (str, in) – A local IP address to receive from.

Return type:

PvResult

Returns:

PV_OK on success.

OpenTCP(aServerIpAddress, aServerPort)

Opens the stream object for TCP receiving.

Parameters:

  • aServerIPAddress – The RTP server IP address.

  • aServerPort (int, in) – The RTP server port.

Return type:

PvResult

Returns:

PV_OK on success.

GetType()

Receiver type.

Return type:

int

Returns:

See PvStreamType enum.

GetLocalPort()

Returns the local socket port used by the stream.

Return type:

int

Returns:

Stream local port.

GetLocalIPAddress()

Returns the local IPaddress used by the stream.

Return type:

str

Returns:

Stream local IP address.

GetMulticastIPAddress()

Returns the multicast IP address of the stream.

Return type:

str

Returns:

Stream multipcast IP addres if applicable.

GetTCPServerIPAddress()

Returns the IP address of the server stream.

Only valid in TCP mode.

Return type:

str

Returns:

Server IP address.

GetTCPServerPort()

Returns the port of the stream server.

Only valid in TCP mode.

Return type:

int

Returns:

Server port.

GetThreadPriority()

Returns thread priority of the data receiver thread.

Return type:

int

Returns:

Thread priority.

SetThreadPriority(aPriority)

Set the priority of the thread used to run the data receiver.

If you change the thread priorities, it may alterate the stability of the system. For this reason, if you report a bug to Pleora, ensure to clearly mention that you change threads priorities.

See #GetThreadPriority

Parameters:

aPriority (int, in) – See PvPipeline.SetBufferHandlingThreadPriority for description of the supported values

Return type:

PvResult

Returns:

Includes:

class eBUS.PvStreamU3V

Bases: PvStream

Receive data from a USB3 Vision transmitter.

This provides a means of opening a connection to the data receiver and obtaining data from it.

property thisown

The membership flag

__init__()

Constructor.

Open(*args)

Overload 1:

Begin receiving blocks (images or raw data) unicasted from a USB3 Vision transmitter.

Parameters:

aDeviceInfo (PvDeviceInfo, in) – Device info retrieved from finder for the USB3 Vision to open the stream from.

Return type:

PvResult

Returns:

Includes:


Overload 2:

Begin receiving blocks (images or raw data) unicasted from a USB3 Vision transmitter.

Parameters:

  • aDeviceInfo (PvDeviceInfo, in) – Device info retrieved from finder for the USB3 Vision to open the stream from.

  • aChannel (int, in) – The USB3 Vision transmitter’s streaming channel (default 0).

  • aBuffersCapacity (int, in, optional) – The maximum number of buffers that can be stored simultaneously in the data receiver.

  • aSmallImageThreshold (int, in, optional) – Threashold where the exchange of memory with the driver is making copy to decrease overall overhead due to memory mapping

  • aMaximumNumberOfPendingURB (int, in, optional) – Maximum of pending URBs in the controller at one time

Return type:

PvResult

Returns:

Includes:


Overload 3:

Begin receiving blocks (images or raw data) unicasted from a USB3 Vision transmitter.

Parameters:

aInfo (str, in) – The USB3 Vision GUID transmitter’s U3VGUID

Return type:

PvResult

Returns:

Includes:


Overload 4:

Begin receiving blocks (images or raw data) unicasted from a USB3 Vision transmitter.

Parameters:

  • aInfo (str, in) – The USB3 Vision GUID transmitter’s U3VGUID

  • aChannel (int, in) – The USB3 Vision transmitter’s streaming channel (default 0).

  • aBuffersCapacity (int, in, optional) – The maximum number of buffers that can be stored simultaneously in the data receiver.

  • aSmallImageThreshold (int, in, optional) – Threashold where the exchange of memory with the driver is making copy to decrease overall overhead due to memory mapping

  • aMaximumNumberOfPendingURB (int, in, optional) – Maximum of pending URBs in the controller at one time

Return type:

PvResult

Returns:

Includes:

GetGUID()

Get the stream’s GUID () property.

Return type:

str

Returns:

The stream’s GUID () property.

GetType()

Returns whether the object is a GigE Vision or USB3 Vision stream receiver.

Return type:

int

Returns:

See PvStreamType Enum.

class eBUS.PvStreamingChannelSourceDefault(aWidth=640, aHeight=480, aPixelType=17301505, aBufferCount=16)

Bases: IPvStreamingChannelSource

A default implementation for the IPvStreamingSourceChannelSource interface.

While it is recommended to build your Software GigE Vision Device application with the IPvStreamingSourceChannelSource interface, simple use cases could benefit from using PvStreamingChannelSourceDefault as a starting point.

PvStreamingChannelSourceDefault enforces constant width, height, pixel format, no offset X/Y, no data chunk support, etc.

If you have a simple use case that would only require changing width and height, you could always use PvStreamingChannelSourceDefault as a starting point and only override the width and height methods.

property thisown

The membership flag

__init__(aWidth=640, aHeight=480, aPixelType=17301505, aBufferCount=16)

Default constructor.

Parameters:

  • aWidth (int, in, optional) – Default width of the image source.

  • aHeight (int, in, optional) – Default height of the image source.

  • aPixelType (int, in, optional) – Default pixel type of the image source.

  • aBufferCount (int, in, optional) – Number of buffers to allocate for streaming.

GetWidth()

Returns the current image width.

Your application must implement this method and return the current image width when invoked.

Return type:

int

Returns:

Current image width.

GetHeight()

Returns the current image height.

Your application must implement this method and return the current image height when invoked.

Return type:

int

Returns:

Current image height.

GetOffsetX()

Returns the current image offset X.

Your application must implement this method and return the current image offset X when invoked.

Return type:

int

Returns:

Current image offset X.

GetOffsetY()

Returns the current image offset Y.

Your application must implement this method and return the current image offset Y when invoked.

Return type:

int

Returns:

Current image offset Y.

GetPixelType()

Returns the current pixel type.

Your application must implement this method and return the current image pixel type when invoked.

Return type:

int

Returns:

Current pixel type.

GetWidthInfo()

Returns the stream channel width attributes.

When using the GigE Vision Device as a transmitter, the Width parameter is automatically added to the device’s GenICam XML file. This method is used to query the minimum, maximum, and increment attributes for the Width parameter.

Return type:

Tuple[int, int, int]

Returns:

Tuple composed of the width minimum, maximum and increment.

GetHeightInfo()

Returns the stream channel height attributes.

When using the GigE Vision Device as a transmitter, the Height parameter is automatically added to the device’s GenICam XML file. This method is used to query the minimum, maximum, and increment attributes for the Height parameter.

Return type:

Tuple[int, int, int]

Returns:

Tuple composed of the height minimum, maximum and increment.

GetChunksSize()

Gets the stream channel chunk size attributes.

When using data chunks, it is important to report the chunk data size when queried through this method.

The chunk data size needs to be taken into account when reporting the PayloadSize GenICam parameter to the GigE Vision controller, so it can properly allocate its buffer for streaming without forced buffer re-allocation.

The size reported must for each chunk adds 4 bytes for the chunk ID and another 4 bytes for the chunk length fields. If you have a chunk that is 64 bytes long and it is your only data chunk, you need to report 64 + 4 + 4 (72 bytes) when GetChunksSize is called.

Return type:

int

Returns:

Chunk data size as currently configured.

GetPayloadSize()

Stream channel payload size in bytes. Return zero to have it inferred from width, height and pixel format.

If not using image streams (raw data, multi-part, etc.) use implement the GetPayloadSize method and return the payload size for the current streaming channel source configuration. If GetPayloadSize returns 0 the payload size will be inferred from the width, height, pixel format and data chunk size.

When using multi-part, return the sum of the maximum size of all parts plus data chunk.

When payload size is not zero, the payload size value is simply used as provided. Nothing is added to it, not even data chunk size.

Return type:

int

Returns:

Payload size to use or 0.

GetScanType()

Returns the scan type that is used by the streaming source.

Return PvScanTypeArea if your image source is areascan or PvScanTypeLine if your image source is linescan.

Return type:

int

Returns:

Scan type of the streaming source.

GetChunkModeActive()

Indicates whether the current master chunk mode is active.

The application must implement this method and return the current master chunk mode state. Return false as a hardcoded value if chunks are not supported by the streaming source.

Return type:

boolean

Returns:

True if chunk mode is enabled for this streaming source.

GetChunkEnable(aChunkID)

Returns the current chunk enabled state.

The application must implement this method and return the current chunk enabled state for the specified chunk ID. The streaming source should maintain an enabled/disabled state for each chunk type that it supports.

The application should append the chunk represented by the specified chunk ID if it is enabled and if the master chunk mode (see #GetChunkModeActive) is true.

Parameters:

aChunkID (int, in) – Chunk ID.

Return type:

boolean

Returns:

True if the chunk specified by aChunk ID is enabled for this streaming source.

GetSupportedPixelType(aIndex)

Obtains an index of supported pixel types. Used at PvSoftDeviceGEV.Start time to create the GenICam XML of the device.

This method is used by the PvSoftDeviceGEV to query the application about the supported pixel types for the streaming channel.

The PvSoftDeviceGEV will query the application using this stream interface for all supported pixel types. It will start at index 0 and then increase until something other than PV_OK` is returned.

If the application supports Mono8, BayerRG8, and RGBa8 it needs to handle the request to GetSupportedPixelType, as follows:

  • GetSupportedPixelType( 0 ) -> (PV_OK, PvPixelMono8)

  • GetSupportedPixelType( 1 ) -> (PV_OK, PvPixelBayerRG8)

  • GetSupportedPixelType( 2 ) -> (PV_OK, PvPixelRGBa8)

  • GetSupportedPixelType( 3 ) -> (PV_INVALID_PARAMETER, 0)

Parameters:

aIndex (int, in) – Index of the pixel type to return.

Return type:

Tuple[PvResult, PvPixelType]

Returns:

Tuple composed of (result, aPixelType).
  • result includes:

    • PV_OK if aIndex represents a valid index and aPixelType has been set.

    • PV_INVALID_PARAMETER or any other error code if aIndex is not valid.

  • aPixelType

    • The PvPixelType requested by aIndex. See PvPixelType Enum.

GetSupportedChunk(aIndex)

Returns the indexed supported chunk type. Used at PvSoftDeviceGEV.Start time to create the GenICam XML of the device.

This method is used by the PvSoftDeviceGEV to query the application about the supported chunk types for this streaming channel.

The PvSoftDeviceGEV will query the application through this stream interface for all supported chunk types. It will start at index 0 and then increase until something other than PV_OK is returned.

The information retrieved through this method is used to populate the chunk selector, allowing the GigE Vision controller to enable or disable each chunk type individually.

If the application supports ChunkSample (ID 0x4001) and ChunkHistogram (ID 0x4002) it needs to handle request to GetSupportedChunk as follows:

  • GetSupportedChunk( 0 ) -> (PV_OK, 0x4001, “ChunkSample”)

  • GetSupportedChunk( 1 ) -> (PV_OK, 0x4002, “ChunkHistogram”)

  • GetSupportedChunk( 2 ) -> (PV_INVALID_PARAMETER, 0, )

Parameters:

aIndex (int, in) – Index of the chunk type to return.

Return type:

Tuple[PvResult, int, str]

Returns:

Tuple composed of (result, chunkID, chunkName).
  • result includes:

    • PV_OK if aIndex represents a valid index and aPixelType has been set.

    • PV_INVALID_PARAMETER or any other error code if aIndex is not valid.

  • chunkID:

    • The ChunkID integer.

  • chunkName

    • chunk name in string and should always use the “Chunk” prefix for GenICam SFNC compliance.

SetWidth(aWidth)

Request from the PvSoftDeviceGEV to change the image width.

The PvSoftDeviceGEV will call SetWidth when the Width GenApi parameter or the underlying register is changed by the GigE Vision controller.

To accept the new width, return PV_OK and update your streaming code to use the new width.

Parameters:

aWidth (int, in) – New image width.

Return type:

PvResult

Returns:

Includes:

SetHeight(aHeight)

Request from the PvSoftDeviceGEV to change the image height.

The PvSoftDeviceGEV will call SetHeight when the Height GenApi parameter or the underlying register is changed by the GigE Vision controller.

To accept the new height, return PV_OK and update your streaming code to use the new height.

Parameters:

aHeight (int, in) – New image height.

Return type:

PvResult

Returns:

Includes:

SetOffsetX(aOffsetX)

Request from the PvSoftDeviceGEV to change the image offset X.

To accept the new offset X, return PV_OK and update your streaming code to use the new value.

Parameters:

aOffsetX (int, in) – New image offset X.

Return type:

PvResult

Returns:

Includes:

SetOffsetY(aOffsetY)

Request from the PvSoftDeviceGEV to change the image offset Y.

To accept the new offset Y, return PV_OK and update your streaming code to use the new value.

Parameters:

aOffsetY (int, in) – New image offset Y.

Return type:

PvResult

Returns:

Includes:

SetPixelType(aPixelType)

Request from the PvSoftDeviceGEV to change the image pixel type.

The PvSoftDeviceGEV will call SetPixelType when the PixelType GenApi parameter or the underlying register is changed by the GigE Vision controller.

To accept the new pixel type, return PV_OK and update your streaming code to use the new pixel type.

Parameters:

aPixelType (int, in) – New image pixel type.

Return type:

PvResult

Returns:

Includes:

  • PV_OK when accepting the new pixel type.

  • PV_GENERIC_ERROR or another error code to refuse the new pixel type.

SetChunkModeActive(aEnabled)

Set the master chunk mode active state.

The streaming source should append a specific chunk type to its streaming data when both the #GetChunkModeActive (master chunk mode) and #GetChunkEnable for this specific chunk type are true.

Parameters:

aEnabled (boolean, in) – True to enable chunk mode for this streaming channel, false to disable it.

Return type:

PvResult

Returns:

Includes:

SetChunkEnable(aChunkID, aEnabled)

Sets the chunk enabled state for a specific chunk type.

The streaming source should append a specific chunk type to its streaming data when both the #GetChunkModeActive (master chunk mode) and #GetChunkEnable for this specific chunk type are true.

Parameters:

  • aChunkID (int, in) – Chunk ID of the chunk type to enable or disable.

  • aEnabled (boolean, in) – True to enable the chunk type, false to disable it.

Return type:

PvResult

Returns:

Includes:

OnOpen(aDestIP, aDestPort)

Notification from the PvSoftDeviceGEV that this streaming channel has been opened.

Parameters:

  • aDestIP (str, in) – IP address of the stream destination as a string in the “192.168.138.115” format (SCDA).

  • aDestPort (int, in) – UDP port of the stream destination (SCP).

OnClose()

Notification from the PvSoftDeviceGEV that this streaming channel has been closed.

OnStreamingStart()

Notification that the GigE Vision controller has requested that the device start streaming on this channel.

OnStreamingStop()

Notification that the GigE Vision controller has requested that the device stop streaming on this channel.

AllocBuffer()

Request by the PvSoftDeviceGEV to allocate a PvBuffer.

On initialization, the PvSoftDeviceGEV will call this method, asking the application to allocate buffers that will be used for image acquisition and transmission. The application should return buffers until it has reached the desired number of buffers it wants to use for streaming and then return NULL.

The more buffers you use, the more buffers you can have queued in the application for image acquisition and the more buffers you can leave in the transmission output queue for packet resend. The downside of using more buffers is increased memory usage.

Buffers returned on AllocBuffer calls should be unique: you should not return the same buffer more than once.

A maximum of 64 buffers can be used by one streaming channel of the PvSoftDeviceGEV. If your application does not return NULL on the 64th buffer, AllocBuffer will not be called a 64th time.

Return type:

PvBuffer

Returns:

Pointer to a new PvBuffer that can be used by the PvSoftDeviceGEV’s acquisition manager.

FreeBuffer(aBuffer)

Request by the PvSoftDeviceGEV to free or release a buffer allocated with AllocBuffer.

You should not delete or free any PvBuffer provided by the AllocBuffer method. FreeBuffer will be called for each buffer created with AllocBuffer when PvSoftDeviceGEV.Stop is called.

Parameters:

aBuffer (PvBuffer, in) – Buffer to free.

AbortQueuedBuffers()

Request by the PvSoftDeviceGEV to abort all buffers queued for acquisition.

This method should block until acquisition has been aborted or canceled for all buffers provided by QueueBuffer that have not yet been retrieved with RetrievedBuffer.

When this method returns, it should be possible to call RetrieveBuffer for all aborted buffers.

CreateRegisters(aRegisterMap, aFactory)

When called, the streaming channel source should create its custom registers if they are needed.

To create source-specific custom registers in your application, implement the CreateRegisters method of the IPvStreamingChannelSource interface.

Custom source-specific register creation occurs BEFORE custom source-specific GenApi features creation, inside the PvSoftDeviceGEV.Start call.

If more than one streaming channel source is created from the same class, you must make sure its registers are still unique: RegisterXYZ in Source0 and Source1 should not have the same address. It is also recommended to assign them unique names like RegisterXYZ0 and RegisterXYZ1.

Parameters:

  • aRegisterMap (IPvRegisterMap, in) – The register map of the device.

  • aFactory (IPvRegisterFactory, in) – Register factory used to create the new registers.

CreateGenApiFeatures(aRegisterMap, aFactory)

When called, the streaming channel source should create its custom GenApi parameters if they are needed.

Create GenApi features from this callback if the feature is associated with a streaming channel source. For global-device, non streaming channel source features use IPvSoftDeviceGEVEventSink.OnCreateCustomGenApiFeatures instead.

In a multi-source application, GenApi features created by a streaming channel source will only be available when the SourceSelector is set to the streaming channel source that created the feature.

If FeatureXYX is created by Source0 and Source1 but not by Source2, the feature will only be available in the GenApi interface when SourceSelector is set to Source0 or Source1.

  • MySource0 has Feature0, Feature1, Feature2

  • MySource1 has Feature0, Feature3, Feature4

  • In a GenApi browser with SourceSelector=Source0, Feature0, Feature1, Feature2 are available. Feature3 and Feature4 are disabled.

  • In a GenApi browser with SourceSelector=Source1, Feature0, Feature3, Feature4 are available. Feature1 and Feature2 are disabled.

If integers with the same name are created for more than one source but with source-specific minimum, maximum and increment attributes, these attributes will be handled by GenICam SwissKnife operators in the GenICam XML so they are dynamically adjusted based on the value of SourceSelector. The same applies to float maximum and minimum.

  • MyInteger is created for Source0 with min:0 max:100 increment:4

  • MyInteger is created for Source1 with min:4 max:200 increment:1

  • In a GenApi browser, MyInteger will report min:0 max:100 increment:4 with Source0 is selected

  • In a GenApi browser, MyInteger will report min:4 max:200 increment:1 with Source1 is selected

If enumerations with the same name are created for more than one source but with different enum entries, they will be added to the GenICam XML file of the device in way that the correct enum entries should be available for the enum features based on the current SourceSelector value:

  • MyEnum is created with EE0, EE1, EE2 for Source0

  • MyEnum is created with EE0, EE3, EE4 for Source1

  • In a GenApi browser with SourceSelector=Source0, you would see EE0, EE1, EE2 in the combo box

  • In a GenApi browser with SourceSelector=Source1, you would see EE0, EE3, EE4 in the combo box

Creating features of the same name but different types is not supported. Attempting to do so should have the PvSoftDeviceGEV::Start call failing with an appropriate error description.

GenApi features created for a streaming channel source should use registers unique to this streaming channel source. If you have a source class MySource that creates registers and features, it should still create unique register having their own unique addresses. They should however use the same parameter name. The GenApi parameters created by MySource should use the right register for the source instance. The complexity of overlapping per-source feature name is handled by PvSoftDeviceGEV when creating the GenICam XML file from PvSoftDeviceGEV.Start.

  • For Source0:

    • MySource creates MySourceRegister0 @ 0x20000000 + 0x1000 * source index + 0

    • MySource creates MySourceParameter named “MySourceParameter” for Source0 using MySourceRegister0

  • For Source1:

    • MySource creates MySourceRegister1 @ 0x20000000 + 0x1000 * source index + 4

    • MySource creates MySourceParameter named “MySourceParameter” for Source1 using MySourceRegister1

The exception to this rule is selectors: if selectors are created at the streaming source level they must all use the same register, sharing the same register address.

Custom source-specific GenApi features creation occurs AFTER custom source-specific registers creation, inside the PvSoftDeviceGEV.Start call.

Parameters:

  • aRegisterMap (IPvRegisterMap, in) – The register map of the device.

  • aFactory (IPvGenApiFactory, in) – GenApi factory used to create the new GenApi features.

IsPayloadTypeSupported(aPayloadType)

When called, the streaming source has to return whether the specificed payload type is supported or not.

Return true if the streaming source exlusively or non-exclusively can stream buffers of the specified payload type. A default implementation is provided for this method which returns false.

This method must be implemented and returning true for aPayloadType being equal to PvPayloadTypeMultiPart when multi-part is supported by the streaming source.

See #SetTestPayloadFormatMode and #SetMultiPartAllowed for more information on propertly supporting the multi-part payload type.

Parameters:

aPayloadType (int) – [in] The payload type for which support is queried.

Return type:

boolean

Returns:

Return true if the payload type is supported, false if not.

SetMultiPartAllowed(aAllowed)

Sets whether the streaming source is allowed or not, but not forced, to transmit multi-part data.

Streaming sources supporting multi-part data transmission must support non-multi-part streaming by default. All devices starting in a mode where multi-part is not allowed. The GigE Vision controller must unlock the multi-part capability of a GVSP streaming channel using either the SCCx and SCCFGx bootstrap registers or the GevSCCFGMultiPartEnabled GenApi parameter.

The GevSCCFGMultiPartEnabled GenApi parameter is automatically added to the GenICam XML file of a PvSoftDeviceGEV device when #IsPayloadTypeSupported returns true when prompted with PvPayloadTypeMultiPart.

See #IsPayloadTypeSupported and #SetTestPayloadFormatMode for more information on propertly supporting the multi-part payload type.

Parameters:

aAllowed (boolean) – [in] True if multi-part is allowed.

SetLargeLeaderTrailerEnabled(aEnabled, aMaxMultiPartCount)

Sets whether the streaming source which transmit multi-part data uses large data leader and trailer packets.

Streaming sources using multi-part data transmission without large data leader and trailer enabled only supports up to 10 multi-parts due to the data leader and trailer packet size limitation. Large data leader and data trailer packets can be enabled by configuring the GevSCCFGLargeLeaderTrailerEnabled GenApi parameter to allow more than 10 parts. The large leader and trailer packet size is then set to the value allowed by the SCPSx register.

The GevSCCFGLargeLeaderTrailerEnabled GenApi parameter is automatically added to the GenICam XML file of a PvSoftDeviceGEV device when #IsPayloadTypeSupported returns true when prompted with PvPayloadTypeMultiPart. This parameter will only be available when GevSCCFGMultiPartEnabled is set to true.

Parameters:

  • aEnabled (boolean) – [in] True if Large Leader Trailer is enabled.

  • aMaxMultiPartCount (int) – [in] The number of maximum allowed Multi parts calculated from the value allowed by the SCPSx register.

SetTestPayloadFormatMode(aPayloadType)

When called, the streaming source has to ensure it can stream buffers of the specified payload type.

The GigE Vision Validation Framework has to be able to set the device in a functional streaming mode for some payload types (currently only multi-part with more to come) in order to properly validate the device.

This method must be implemented and for aPayloadType being PvPayloadTypeMultiPart when multi-part is supported by the streaming source. The streaming source must be able to configure itself in a mode where it will be able to stream data for certification with the GigE Vision Validation Framework.

Of course, this method will only be called on a streaming source for payload type that have been reported as supported with #IsPayloadTypeSupported.

How to prepare your multi-source device source for GigE Vision Validation Framework validation:

  • Implement #IsPayloadTypeSupported and return true if aPayloadType is PvPayloadTypeMultiPart.

  • Implement #SetTestPayloadFormatMode
    • If aPayloadType is PvPayloadTypeMultiPart

      • Setup your streaming source for autonomous multi-part streaming if needed

      • Return PV_OK

    • Else if aPayloadType is PvPayloadTypeNone

      • Disable test mode, go back to streaming source normal operation mode

      • Return PV_OK

    • Else

See the SoftDeviceGEVMultiPart C++ sample for an example of how to implement this method, #SetMultiPartAllowed, and #IsPayloadTypeSupported.

Parameters:

aPayloadType (int, in) – Payload type to prepare test for. PvPayloadTypeNone sets the device back in normal operation mode.

Return type:

PvResult

Returns:

Includes:

  • PV_OK on success.

  • Any error code can be returned to indicate failure.

class eBUS.PvString(*args)

Bases: object

String class.

property thisown

The membership flag

__init__(*args)

Overload 1:

Default constructor.


Overload 2:

Copy constructor.

Parameters:

aValue (str, in) – The string you want to initialize this PvString with.


Overload 3:

Constructor.

Parameters:

aValue (string, in) – The string you want to initialize this PvString with.


Overload 4:

Constructor.

Parameters:

  • aValue (string, in) – The string you want to initialize this PvString with.

  • aN (int, in) – The size to resize this PvString with.


Overload 5:

Constructor.

Parameters:

aValue (wchar_t, in) – The string you want to initialize this PvString with.

GetAscii()

Get the string in ASCII format.

Do not store. Copy the string if needed out of the current context.

Return type:

string

Returns:

The string, converted to ASCII.

See also: GetUnicode

GetUnicode()

Get the string in Unicode format.

Do not store. Copy the string if needed out of the current context.

Return type:

wchar_t

Returns:

The string, converted to Unicode.

See also: GetAscii

GetLength()

Get the string’s length.

Return type:

int

Returns:

The length of the string, in characters.

class eBUS.PvSystem

Bases: object

Find interfaces (network adapters or USB host controllers) and devices reachable from this PC

PvSystem finds all interfaces and returns PvInterface objects. PvInterface finds all devices on a specific interface and returns PvDeviceInfo based objects. PvDeviceInfo provides the information required to connect to a GigE Vision or USB3 Vision device.

property thisown

The membership flag

__init__()

Constructor.

Find()

Find all interfaces and GigE Vision, USB3 Vision and Pleora Protocol devices reachable from this system.

This method is blocking and won’t return for the duration set using #SetDetectionTimeout.

Return type:

PvResult

Returns:

Includes:

FindDevice(aDeviceToFind, aDeviceInfo)

Finds devices until a specific device is found.

Performs a standard find operation and keeps listening for answers until a specific device is found.

More than one device can be found and added to the interfaces during this find operation. Do not assume only the device of interest is present in the system/interface data after this method returns.

If the device of interest is found, a pointer to the device info in the interface where the device was found is returned using the aDeviceInfo parameter.

Parameters:

  • aDeviceToFind (str, in) – String representing the device to find. Can be a MAC, IP or device name.

  • aDeviceInfo (PvDeviceInfo, out) – If the device is found, contains a pointer to a PvDeviceInfo about the device requested in aDeviceToFind.

Return type:

PvResult

Returns:

Includes:

SetDetectionTimeout(aTimeout)

Sets the time to search the system devices.

Time the PvSystem.Find methods wait for responses from GigE Vision or Pleora Protocol devices before returning.

GigE Vision devices may wait up to 1 second before answering a discovery request and this detection timeout allows enough time for all discovery answers to come back in.

USB3 Vision devices detection is instant. You can set this timeout to its minimum supported value if you are only interested in detecting USB3 Vision devices.

Pleora Protocol and some GigE Vision devices answer as soon as the discovery request is received. Experimenting with this timeout and discovery stability is a way improving discovery performance. Another would be to stick with the safe, default delay and use the event sink callback to be notified as soon as a device is discovered.

Parameters:

aTimeout (int, in) – Time to search for devices in ms. The default value of 1500 is generally a good value in most situations. Values beyond 100 to 60000 are set to 100 and 60000, respectively.

GetDetectionTimeout()

Get the maximum time to search for GigE Vision devices.

Search here is defined as the time to wait devices to answer after sending a discovery through each interface.

Only applies to Ethernet devices as USB devices enumeration does not include the notion of wait or timeout.

See #SetDetectionTimeout.

Return type:

int

Returns:

See #SetDetectionTimeout.

SetSubnetBroadcastEnabled(aValue)

Sets whether subnet broadcasts are used (or not) when detecting GigE Vision devices.

Parameters:

aValue (boolean, in) – True if subnet broadcasts are to be used when detecting GigE Vision devices.

GetSubnetBroadcastEnabled()

Gets whether subnet broadcasts are used (or not) when detecting GigE Vision devices.

Return type:

boolean

Returns:

True if subnet broadcasts are to be used when detecting GigE Vision devices.

GetGEVSupportedVersion()

Get the version of GigE Vision spec supported by the SDK.

The high 16 bits contain the major version and The low 16 bits the minor version.

Return type:

int

Returns:

GigE Vision spec version supported by the SDK.

GetU3VSupportedVersion()

Get the version of USB3 Vision spec supported by the SDK.

The high 16 bits contain the major version and The low 16 bits the minor version.

Return type:

int

Returns:

USB3 Vision spec version supported by the SDK.

RegisterEventSink(aEventSink)

Register an event sink (for device finding notification).

To use this method, see PvSystemEventSink.

Parameters:

aEventSink (PvSystemEventSink, in) – A pointer to the event sink object.

Return type:

PvResult

Returns:

Includes:

UnregisterEventSink(aEventSink)

Unregister an event sink

To use this method, see PvSystemEventSink.

Parameters:

aEventSink (PvSystemEventSink, in) – A pointer to the event sink object.

Return type:

PvResult

Returns:

Includes:

GetInterfaceCount()

Get the number of interfaces detected on the system

Return type:

int

Returns:

The number of interfaces detected on the system; the range for the PvSystem.GetInterface method.

GetInterface(aIndex)

Get a PvInterface.

Interfaces are ordered in the PvSystem array as provided by the OS.

Parameters:

aIndex (int, in) – The interface’s index in the array; a number ranging from 0 to #GetInterfaceCount-1.

Return type:

PvInterface

Returns:

A pointer to a PvInterface object, or NULL if the index is out of bounds.

GetDeviceCount()

Returns number of device that can be enumerated from PvSystem using GetDeviceInfo.

Return type:

int

Returns:

Device count.

GetDeviceInfo(aIndex)

Returns a pointer to a device of the PvSystem.

The GetDeviceCount and GetDeviceInfo methods of PvSystem are a shortcut for users only interested in retrieving devices without having to handle the interface to device topology.

Parameters:

aIndex (int, in) – Zero-based index of the device info. Valid range is [0 .. GetDeviceCount - 1].

Return type:

PvDeviceInfo

Returns:

Pointer to the requested PvDeviceInfo.

DiscoverSessions()

Scans for active sessions advertised via SAP. This is typically used to discover RTP streams, and is unnecessary to call for GEV and U3V devices.

Return type:

int

Returns:

The number of active sessions currently advertised with SAP.

GetSessionInfo(aIndex, aSessionInfo)

Returns SDP information about an active session (unused by GEV and U3V).

Parameters:

  • aIndex (int, in) – Zero-based index of the session to retrieve information about. Valid range is [0 .. DiscoverSessions() - 1].

  • out] – aSessionInfo If the session is found, fills the PvSessionInfo with session name and connection information.

Return type:

PvResult

Returns:

Includes:

class eBUS.PvUSBHostController

Bases: PvInterface

Represents one USB host controller on a system (the PC)

To use this class, see PvSystem.

property thisown

The membership flag

__init__()

Constructor.

GetVendorID()

Vendor ID of the USB host controller.

Return type:

int

Returns:

Vendor ID.

GetDeviceID()

Device ID of the USB host controller.

Return type:

int

Returns:

Device ID.

GetSubsystemID()

Subsystem ID of the USB host controller.

Return type:

int

Returns:

Subsystem ID.

GetRevision()

Revision of the USB host controller.

Return type:

int

Returns:

Revision of the USB host controller.

GetSpeed()

Speed of the USB host controller.

Even if a USB host controller supports super speed it does not guarantee a device will be connected as super speed. Bad cables or hubs not supporting super speed could force the controller and device to end up being connected at a slower speed.

Return type:

int

Returns:

Speed of the USB host controller.