Parameter Information
- 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
- 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.
- 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
- 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
- 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
- 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
- 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)