Parameter Information

ParameterInfo

class fluxEngine.ParameterInfo(rawInfo)

Parameter Information

This class contains information about parameters in various contexts. Most notably it will provide information about parameters required to connect to a device, as well as parameters of a connected device itself.

Objects of this class should never be created directly by the user, but it will be returned by various device-related methods.

class AccessMode(value)

The access mode of a given parameter

The access mode describes whether a parameter may be read from or written to.

NotAvailable = 0

The parameter is not available

This indicates that the parameter can currently neither be read nor written.

ReadOnly = 1

The parameter is read-only

ReadWrite = 3

The parameter may be read from and written to

This is the case for most parameters.

WriteOnly = 2

The parameter is write-only

This is typically only the case for ParameterInfo.Type.Command type parameters.

class EnumerationEntry(name, value, displayName=None)

Enumeration Entry

This structure describes an enumeration entry that is part of an enumeration parameter.

The user should never need to create this structure themselves, rather it is returned by accessors of the ParameterInfo class.

name

The name of the enumeration entry

This will be unique within the enumeration parameter.

Type:

str

value

The value of the enumeration entry

This should be unique within the enumeration parameter, but aliases for the same value may exist. (The first entry in the list is the canonical name.)

Type:

int

displayName

The display name of the enumeration entry

If this is not None this contains a more user-friendly string that describes this entry.

Type:

str or None

effectiveDisplayName()

Get the effective display name of the entry

If the display name is not set, the entry’s name will be returned instead.

Returns:

The effective display name of the entry

Return type:

str

class Parameter(name, type, accessMode, displayName=None)

Complete Parameter Information

This structure contains all of the information of a given parameter collected into a single structure. It is returned by both ParameterInfo.parameter() and ParameterInfo.parameters().

name

The name of the parameter

This will be unique within the parameter information structure.

Type:

str

type

The type of the parameter

Type:

ParameterInfo.Type

accessMode

The access mode of the parameter

The access mode determines if a parameter can be read from or written to – or, in case of commands, if it can be executed.

Type:

ParameterInfo.AccessMode

displayName

The display name of the parameter

If not None this is a more human-readable name of the parameter.

Type:

str or None

shortDescription

A short description of the parameter

If not None this is typically shown in form of a tool-tip when hovering over a parameter.

Type:

str or None

longDescription

A long description of the parameter

Type:

str or None

affectedParameters

A list of affected parameters

If the value of this parameter is changed by the user, this list of parameter names indicates which parameters may also change due to that write. Affected parameters may have a different value, access mode, minmum, maximum or increment when a parameter changes.

The names in this list denote the unique name of each affected parameter, not the display name.

It is not necessary that a change to this parameter actually changes one of the affected parameters, it only indicates that such a change is possible.

Type:

list(str)

defaultValue

The default value of a parameter

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that – though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.)

For parameters describing how to connect to a specific device there may be a default value, and this attribute will contain that value.

If the attribute is None there is no default value present.

If the field is of any other type it will contain the default value depending on the type of the parameter. String and file parameters will have default values in the form of a str object, integer and enumeration parameters will have default values of int type, floating point parameters will have default values of float type, and boolean parameters will have default values of bool type.

Type:

str or int or float or bool or None

unit

The unit of a value

Numeric (integer and floating point) parameters may have a unit associated with them, such as “ms” or “Hz”. If present this will contain that unit.

This will always be None for parameters that do not have a unit (because it is either not set or they are of a type that doesn’t have units).

Type:

str or None

enumerationEntries

The list of available enumeration entries

For ParameterInfo.Type.Enumeration type parameters this will contain a list of all entries in the given enumeration.

Type:

list(ParameterInfo.EnumerationEntry)

minimum

The minimum value

For numeric (integer and floating point) parameters this will contain the lowest value that the parameter accepts.

In all other cases this will be None.

Type:

int or float or None

maximum

The maximum value

For numeric (integer and floating point) parameters this will contain the largest value that the parameter accepts.

In all other cases this will be None.

Type:

int or float or None

increment

The increment value

For ParameterInfo.Type.Integer type parameters this will contain the increment value required to obtain a valid value of this parameter. Specifically, a valid value for the given integer must take the form value = minimum + N * increment, where N is an arbitrary positive integer.

For ParameterInfo.Type.Float type parameters this will give an indication of the increment to use while the user is editing this parameter. If an increment is actually enforced for floating point values, it means that the supplied value will be rounded to the nearest allowed value upon write.

In all other cases this will be None.

Type:

int or float or None

effectiveDisplayName()

Get the effective display name of the parameter

If the display name is not set, the parameter’s name will be returned instead.

Returns:

The effective display name of the parameter

Return type:

str

class Type(value)

The type of parameter

Boolean = 0

Boolean

The parameter can either be True or False.

Command = 6

Command

A command parameter is a parmaeter that can be used to trigger an action on the device.

Enumeration = 3

Enumeration

The parameter can be chosen from a set of predetermined values. Each predetermined value is associated with an integer value as well as a unique name.

File = 5

File

The parameter is the path to a file in the filesystem. The path can be accessed like a string.

Values supplied for this parameters must be of type str (unicode), not of type bytes or any other path-like object.

Float = 2

Floating Point

The parameter is a floating point value. There may be additional limits imposed on the range of the floating point value.

Integer = 1

Integer

The parameter is an integer value. There may be additional limits imposed on the range of the integer value.

String = 4

String

Unknown = -1

Unknown type

This is returned if a specific parameter does not fall into one of the other parameter types.

numParameters()

Return the number of parameters

Returns:

The number of parameters

Return type:

int

parameter(i)

Get all information about a specific parameter

Returns all information about a specific parameter all at once.

If a parameter with that index or name does not exist, an error will be raised.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

All information about a specific parameter

Return type:

ParameterInfo.Parameter

parameterAccessMode(i)

Get the access mode of a parameter

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The access mode of the parameter

Return type:

ParameterInfo.AccessMode

parameterAffectedParameters(i)

Get the parameters affected by changes to a parameter

For a given parameter, determine the list of parameters that might change if the value of the chosen parameter changes. For example, when changing the BinningHorizontal parameter of a camera, the value and limits of the OffsetX and Width parameters of that camera may change as a result of the change in binning. The parameters that may be affected by a change in parameter values are listed here.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The names of the parameters that might be affected by changes to the specified parameter

Return type:

list(str)

parameterDefaultValue(i)

Get the default value of a parameter

Returns the default value of a parameter (if available) in the correct type for that specific parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that – though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will raise an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

Note that the default value of an enumeration parameter will be of integer type, indicating the default enumeration value. (The name of the default enumeration entry can then be looked up separately.)

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The default value of the parameter in the approriate type, or None.

Return type:

str or int or float or bool or None

parameterDisplayName(i)

Get the display name of a parameter

A display name is an optional more human-readable name of a parameter.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The display name of the parameter

Return type:

str or None

parameterEffectiveDisplayName(i)

Get the effective display name of a parameter

This will return the parameter’s display name, if set, or otherwise the parameter’s name. This is a convenient accessor to always obtain a name that may be shown to the user, but that will show a more human-readable name if possible.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The effective display name of the parameter

Return type:

str

parameterEnumerationEntryDisplayName(i, j)

Get the display name of an enumeration entry of an enumeration parameter

For a parameter of type ParameterInfo.Type.Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be raised.

Parameters:

• i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

• j (int or str) – Either the index of the enumeration entry (starting at zero, up to one less than the size of the list returned by ParameterInfo.parameterEnumerationEntryNames()), or the name of the enumeration entry.

Returns:

The display name of the enumeration entry

Return type:

str or None

parameterEnumerationEntryEffectiveDisplayName(i, j)

Get the effective display name of an enumeration entry of an enumeration parameter

For a parameter of type ParameterInfo.Type.Enumeration return the effective display name of a specific enumeration entry. This will either be the display name of the entry (if set) or the name of the entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be raised.

Parameters:

• i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

• j (int or str) – Either the index of the enumeration entry (starting at zero, up to one less than the size of the list returned by ParameterInfo.parameterEnumerationEntryNames()), or the name of the enumeration entry.

Returns:

The effective display name of the enumeration entry

Return type:

str

parameterEnumerationEntryNames(i)

Get the names of all enumeration entries of an enumeration parameter

For a parameter of type ParameterInfo.Type.Enumeration return a list of the names of all enumeration entries of that parameter.

If the parameter is not of enumeration type, an error will be raised.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The list of enumeration entry names for that parameter

Return type:

list(str)

parameterEnumerationEntryValue(i, j)

Get the value of an enumeration entry of an enumeration parameter

For a parameter of type ParameterInfo.Type.Enumeration return the value of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be raised.

Parameters:

• i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

• j (int or str) – Either the index of the enumeration entry (starting at zero, up to one less than the size of the list returned by ParameterInfo.parameterEnumerationEntryNames()), or the name of the enumeration entry.

Returns:

The value of the enumeration entry

Return type:

int

parameterIncrement(i)

Get the increment of the parameter

For numeric parameters (ParmaeterInfo.Type.Integer or ParameterInfo.Type.Float) return the largest value that is allowed for the parameter.

For ParameterInfo.Type.Integer type parameters this will contain the increment value required to obtain a valid value of this parameter. Specifically, a valid value for the given integer must take the form value = minimum + N * increment, where N is an arbitrary positive integer.

For ParameterInfo.Type.Float type parameters this will give an indication of the increment to use while the user is editing this parameter. If an increment is actually enforced for floating point values, it means that the supplied value will be rounded to the nearest allowed value upon write.

If the parameter is of the wrong type, an error will be raised.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The increment of the parameter

Return type:

int or float

parameterLongDescription(i)

Get the long description of a parameter

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The long description of the parameter

Return type:

str or None

parameterMaximum(i)

Get the maximum value of the parameter

For numeric parameters (ParmaeterInfo.Type.Integer or ParameterInfo.Type.Float) return the largest value that is allowed for the parameter.

If the parameter is of the wrong type, an error will be raised.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The maximum value of the parameter

Return type:

int or float

parameterMinimum(i)

Get the minimum value of the parameter

For numeric parameters (ParmaeterInfo.Type.Integer or ParameterInfo.Type.Float) return the lowest value that is allowed for the parameter.

If the parameter is of the wrong type, an error will be raised.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The minimum value of the parameter

Return type:

int or float

parameterNames()

Return the list of parameter names

Returns:

The list of parameter names

Return type:

list(str)

parameterShortDescription(i)

Get the short description of a parameter

If set a short description is often displayed in form of a tool-tip to the user.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The short description of the parameter

Return type:

str or None

parameterType(i)

Get the type of a parameter

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The type of the parameter

Return type:

ParameterInfo.Type

parameterUnit(i)

Get the unit of a parameter

Numeric parameters (ParameterInfo.Type.Integer and ParameterInfo.Type.Float) may have a unit assigned to them that describes the physical unit of the parameter, such as “ms” or “Hz.

Parameters:

i (int or str) – Either the index of the parameter (starting at zero, up to one less than the result of ParameterInfo.numParameters()), or the name of the parameter.

Returns:

The unit of the parameter, or None if no unit is set

Return type:

str or None

parameters()

Get all information about all available parameters

Returns:

All information about all available parameters

Return type:

list(ParameterInfo.Parameter)