Document metadata
Device name |
v3scameraap |
|---|---|
Firmware version |
None |
Date |
2026-05-04 |
Crowns
- C
-
- D
- E
-
- F
- G
- H
- I
-
- L
- M
-
- N
- O
-
- P
-
- R
- S
-
- T
- U
- V
- W
CertificateManagement
| This API is experimental |
Short description
The certificate management subsystem bundles all functionality to load, store and renew X.509 certificates and keys in individual stores.
Functions
getCommandHandler()
Short description
Returns a handle for command access (modify) to the store identified by its unique name, returns nothing if name not found or invalid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
name |
STRING |
1 |
Name of store. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
commandHandler |
? |
Return write access handle for the requested store. |
|
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
commandHandler, error = CertificateManagement.getCommandHandler(name)getFactoryHandler()
Short description
Returns a handle for creating elements for the given store.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
name |
STRING |
1 |
Name of store. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
factoryHandler |
? |
Return a factory handle for the requested store. |
|
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
factoryHandler, error = CertificateManagement.getFactoryHandler(name)getQueryHandler()
Short description
Returns a handle for query (read) access to the store identified by its unique name, returns nothing if store not found or invalid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
name |
STRING |
1 |
Name of store. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
queryHandler |
? |
Return read handle for the requested store. |
|
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
queryHandler, error = CertificateManagement.getQueryHandler(name)getStoreNames()
Short description
Returns the names of all available stores.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
names |
STRING |
+ |
Array of store names. |
Sample (auto-generated)
names = CertificateManagement.getStoreNames()CertificateManagement.Certificate
| This API is experimental |
Short description
A X.509v3 based certificate.
Overview
Functions
getCommonNames()
Short description
Returns a list of the set subject alternative names (SAN) and the common name (CN).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificate |
1 |
Certificate object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
names |
STRING |
* |
The set CN and SAN. |
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
names, error = CertificateManagement.Certificate.getCommonNames(certificate)getExpiresOnDate()
Short description
Function to get date and time at which the certificate expires.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificate |
1 |
Certificate object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
expirationTime |
? |
Point of time when the certificate expires. |
|
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
expirationTime, error = CertificateManagement.Certificate.getExpiresOnDate(certificate)getFingerprint()
Short description
Function to get the SHA-256 fingerprint of the certificate.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificate |
1 |
Certificate object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fingerprint |
BINARY |
? |
The SHA-256 fingerprint of the certificate. |
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
fingerprint, error = CertificateManagement.Certificate.getFingerprint(certificate)getIssuedOnDate()
Short description
Function to get date and time at which the certificate has been issued.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificate |
1 |
Certificate object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
issueTime |
? |
Point of time when the certificate has been issued. |
|
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
issueTime, error = CertificateManagement.Certificate.getIssuedOnDate(certificate)getIssuer()
Short description
Return the issuer information stated in the certificate. It is coded as RFC 2253 string.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificate |
1 |
Certificate object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
issuer |
STRING |
? |
The issuer information coded according to RFC2253. |
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
issuer, error = CertificateManagement.Certificate.getIssuer(certificate)getSerialNumber()
Short description
The serial number MUST be a positive integer assigned by the CA to each certificate. It MUST be unique for each certificate issued by a given CA (i.e., the issuer name and serial number identify a unique certificate).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificate |
1 |
Certificate object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
serialNumber |
BINARY |
? |
The serial number of the certificate. |
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
serialNumber, error = CertificateManagement.Certificate.getSerialNumber(certificate)getSubject()
Short description
Return the subject information stated in the certificate. It is coded as RFC 2253 string.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificate |
1 |
Certificate object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
subject |
STRING |
? |
The subject information coded according to RFC2253. |
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
subject, error = CertificateManagement.Certificate.getSubject(certificate)CertificateManagement.CertificateBundle
| This API is experimental |
Short description
An object holding the leaf certificate, all intermediate certificates and the corresponding private key.
Functions
getIntermediateCertificates()
Short description
Returns the contained intermediate certificates of the certificate chain.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificateBundle |
1 |
CertificateBundle object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificate |
+ |
The contained intermediate certificates. |
Sample (auto-generated)
certificate = CertificateManagement.CertificateBundle.getIntermediateCertificates(certificateBundle)getLeafCertificate()
Short description
Returns the contained leaf certificate, which is the last certificate in a possible certificate chain.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificateBundle |
1 |
CertificateBundle object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
leafCertificate |
1 |
The contained leaf certificate. |
Sample (auto-generated)
leafCertificate = CertificateManagement.CertificateBundle.getLeafCertificate(certificateBundle)getUUID()
Short description
Gets the unique ID of the contained certificate bundle
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificateBundle |
1 |
CertificateBundle object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
uuid |
STRING |
1 |
The unique ID of the certificate bundle. |
Sample (auto-generated)
uuid = CertificateManagement.CertificateBundle.getUUID(certificateBundle)CertificateManagement.CommandHandler
| This API is experimental |
Short description
Handle can be used to modify the certificate store.
Overview
Functions
replaceActiveCertificateBundle()
Short description
To replace an active certificate bundle by the given new one.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
commandHandle |
1 |
Store command handle. |
|
certificateBundle |
CONST_OBJECT |
1 |
The certificate bundle that shall be added. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
1 |
return True if certificate bundle has been accepted, if False see error. |
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
result, error = CertificateManagement.CommandHandler.replaceActiveCertificateBundle(commandHandle, certificateBundle)reset()
Short description
This function will reset the whole store which implies deleting of ALL certificates and keys. This action cannot be reverted.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
commandHandle |
1 |
Store command handle. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
1 |
return True if the execution of the command has been successfully. |
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
result, error = CertificateManagement.CommandHandler.reset(commandHandle)CertificateManagement.FactoryHandler
| This API is experimental |
Short description
Handle can be used to create elements for a certificate and key store.
Functions
createCertificateBundleFromDER()
Short description
Creates a new certificate and private key handle with the given certificate in DER format.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
factoryHandle |
1 |
Factory handle. |
|
derCertificate |
BINARY |
1 |
The certificate coded in DER format. |
derKey |
BINARY |
1 |
The private key coded in DER format. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificateBundle |
? |
The new object. |
|
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
certificateBundle, error = CertificateManagement.FactoryHandler.createCertificateBundleFromDER(factoryHandle, derCertificate, derKey)createCertificateBundleFromPEM()
Short description
Creates a new certificate bundle with a unique ID containing the given certificates and the private key.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
factoryHandle |
1 |
Factory handle. |
|
pemCertificate |
STRING |
1 |
The certificate or the certificate chain coded as PEM string. |
pemKey |
STRING |
1 |
The private key coded as PEM string. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificateBundle |
? |
The new object. |
|
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
certificateBundle, error = CertificateManagement.FactoryHandler.createCertificateBundleFromPEM(factoryHandle, pemCertificate, pemKey)CertificateManagement.QueryHandler
| This API is experimental |
Short description
Handler can only be used to query certificate bundles(containing a certificate, an associated certificate chain, and a private key) from the store. Stores may contain active (available) and inactive (blocked or revoked) certificates.
Functions
getActiveCertificateBundleID()
Short description
Returns the ID of the active certificate bundle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
queryHandle |
1 |
QueryHandler handle. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificateBundleID |
STRING |
? |
String in UUID format. |
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
certificateBundleID, error = CertificateManagement.QueryHandler.getActiveCertificateBundleID(queryHandle)getCertificateBundleByID()
Short description
Function to get a certificate bundle by its ID.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
queryHandle |
1 |
QueryHandler handle. |
|
certificateBundleID |
STRING |
1 |
string in UUID format. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
certificateBundle |
? |
If ID could be found, an object containing the requested certificate bundle is being returned. |
|
error |
? |
Returns the cause of error in case of an error. |
Sample (auto-generated)
certificateBundle, error = CertificateManagement.QueryHandler.getCertificateBundleByID(queryHandle, certificateBundleID)Cipher
Cipher.AES
Short description
AES is a variant of the Rijndael block cipher which offers a very high level of security. It is a symmetric-key algorithm, meaning the same key is used for both encrypting and decrypting the data. The algorithm uses a block size of 128 bits and three different key lengths: 128, 192 and 256 bits. AES is included in the ISO/IEC 18033-3 standard.
Functions
decrypt()
Short description
Decrypts AES-encrypted data (OpenAES compatible)
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encryptedData |
BINARY |
1 |
AES encrypted data to be decrypted |
key |
BINARY |
1 |
Decryption key. Has to be 16, 24 or 32 bytes long (= 128, 192 or 256 bits). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
decryptedData |
BINARY |
1 |
Decrypted result. If any encryption stage goes wrong, or an invalid AES key is passed, an empty binary result is returned. |
Sample (auto-generated)
decryptedData = Cipher.AES.decrypt(encryptedData, key)encrypt()
Short description
Encrypts data. The mode of operation is cipher block chaining (CBC). An initialization vector (IV) is generated randomly and stored in a OpenAES-compatible header that is part of the cipher text (return value).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
1 |
Data to be encrypted |
key |
BINARY |
1 |
Encryption key. Has to be 16, 24 or 32 bytes long (= 128, 192 or 256 bits). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encryptedData |
BINARY |
1 |
Encrypted result. If any decryption stage goes wrong, or an invalid AES key is passed, an empty binary result is returned. |
Sample (auto-generated)
encryptedData = Cipher.AES.encrypt(data, key)Cipher.Certificate
Short description
Functionality to work with X.509 certificates, which is an International Telecommunication Union (ITU) standard. An X.509 certificate binds an identity to a public key using a digital signature.
Cipher.Certificate.SigningRequest
Short description
Allows to generate certificate signing requests according to the PKCS #10 specification.
Overview
Functions
addSubjectField()
Short description
Adds a field to the subject of the certificate signing request. The subject of the certificate can consist of multiple fields, each field being a key/value-pair.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Instance handle |
|
subjectField |
STRING |
1 |
Subject field to add |
value |
STRING |
1 |
Value for this subject field |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns 'true' if subjectField could be added successfully. |
Sample
Cipher.Certificate.SigningRequest.addSubjectField(handle, "CN", "myCommonName")create()
Short description
Creates a new certificate signing request instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Instance handle for the certificate signing request. |
Sample
local csr = Cipher.Certificate.SigningRequest.create()encode()
Short description
Encodes the signed certificate signing request into a binary buffer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Instance handle |
|
format |
ENUM |
1 |
Optional passphrase. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
csr |
BINARY |
? |
Returns binary representation of the certificate signing request, or nil on error. |
Sample
local success = Cipher.Certificate.SigningRequest.encode(handle)setKeyPair()
Short description
Sets the public key that will be included in the signing request and the private key that will be used to sign the request.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Instance handle |
|
publicKey |
OBJECT |
1 |
Public key to include in the certificate signing request. |
privateKey |
OBJECT |
1 |
Private key which is used to sign the certificate signing request. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns 'true' if key pair could be loaded successfully. |
Sample
Cipher.Certificate.SigningRequest.setKeyPair(handle, publicKey, privateKey)Cipher.Key
Short description
Represents a key to be used in public-key cryptography, or asymmetric cryptography, that uses pairs of related keys. Each key pair consists of a public key and a corresponding private key.
Overview
Functions
encode()
Short description
Encodes a key into a binary buffer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
key |
OBJECT |
1 |
Instance object to use |
format |
ENUM |
1 |
Optional passphrase. |
passphrase |
STRING |
? |
Optional passphrase. Ignored if this is not a private key. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
buffer |
BINARY |
? |
Returns binary representation of the key, or nil on error. |
Sample
local keyBuf = Cipher.Key.encode(key, "PEM", "mypassphrase")Cipher.RSA
Short description
RSA (Rivest–Shamir–Adleman) is a public-key cryptosystem, that is widely used for secure data transmission. The encryption key is public and distinct from the decryption key, which is kept secret (private).
Overview
Functions
generateKeyPair()
Short description
Generates a RSA key pair and stores the keys in PEM file format.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
size |
INT |
1 |
Length of the modulus in bits. Typical sizes are 2048 or 4096. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
publicKey |
OBJECT |
? |
Generated public key. Nil in case of error. |
privateKey |
OBJECT |
? |
Generated private key. Nil in case of error. |
Sample
local publicKey, privateKey = Cipher.RSA.generateKeyPair(2048)Command
Short description
Command handling functionalities
Command.Client
Short description
A client to connect to a command server and execute SOPAS commands. Command servers can be other devices which speak SOPAS CoLaA, CoLaB or CoLa2. A client can execute single commands on the device and also can store and restore parameters of it. To be able to talk with a device, a ".sopas" file is needed to be specified with the "Command.Client.setDescription" function. A ".sopas" file can be created using SOPAS ET and store a project. The connection to the device must be injected using the "setConnection" function by providing a handle to a connection which is already open and configured. Connections must be CROWNs which have a "transmit" function and an "OnReceive" event, e.g. "TCPIPClient" and "SerialCom". The handling of disconnects can be handled by the user. There is a default timeout for every request of 30 seconds. If the connection is lost or no response is received, the requests return with an error after that time. There is a fix internal maximum CoLa de/serialization buffer size of 64k. Request bigger than this are not possible.
Overview
Functions
backup()
Short description
Stores the parameters of a device to a ".sopas" file. This is useful to backup the parameters of a device to a file to restore it later or to open it in SOPAS ET. If storing fails no file is created at all. The opposite function is "restore" to put all parameters to a device.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
paramFile |
STRING |
1 |
The path to the .sopas file to store to |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful stored the parameters to the file. False if not possible or failed while storing. |
errMsg |
STRING |
? |
If backup fails, this string contains the readable error message about why it failed |
Sample (auto-generated)
success, errMsg = Command.Client.backup(handle, paramFile)changePassword()
Short description
Change the password for a user level. The changePassword method always uses the method set by setLoginMethod. Only works for SECURE_USERLEVEL_V_1_0 and SECURE_USERLEVEL_V_2_0
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
loginUserLevel |
ENUM |
1 |
The user level to login with, must be higher than or equal to changeUserLevel. |
loginPassword |
STRING |
1 |
The current password of loginUserLevel. |
changeUserLevel |
ENUM |
1 |
The user level whose password should be changed, must be lower than or equal to loginUserLevel. |
changedPassword |
STRING |
1 |
The new password for changeUserLevel. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully executed. False if timeout or error |
Sample (auto-generated)
success = Command.Client.changePassword(handle, loginUserLevel, loginPassword, changeUserLevel, changedPassword)close()
Short description
Forces a close from the server. Can be used to shut down the communication and reconfigure the "Command.Client"
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
Sample (auto-generated)
Command.Client.close(handle)create()
Short description
Creates a new Command.Client instance. The client needs to be configured before using the Open()-function.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The new instance |
Sample
-- Create and configure the connection
conHandle = TCPIPClient.create()
TCPIPClient.setIPAddress(conHandle, "192.168.0.1")
TCPIPClient.setPort(conHandle, 2111)
TCPIPClient.connect(conHandle)
assert( TCPIPClient.isConnected(conHandle) ) -- connection handling has to be done by the user of the Command.Client
-- Create, configure and open the client
handle = Command.Client.create()
Command.Client.setDescriptionFile(handle, "resources/myDevice.sopas")
Command.Client.setProtocol(handle, "COLA_A")
Command.Client.setConnection(handle, conHandle)
assert ( Command.Client.open(handle) )
-- Now the ".sopas"-file is loaded and the client is registered at the connection and can be used
-- read a variable from the device
local paramNode = Command.Client.read(handle, "DeviceIdent")
if paramNode then
local devName = Parameters.Node.get(paramNode, "Name")
print("Device name is " .. devName)
endcreateNode()
Short description
Creates a new Parameters.Node with a defined structure for a variable or as method argument. This can be used for write or invoke calls.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
paramName |
STRING |
1 |
The name of the variable or method. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
paramNode |
OBJECT |
? |
The new created not if exists |
Sample (auto-generated)
paramNode = Command.Client.createNode(handle, paramName)deregister()
Short description
This function is used to deregister from any registered event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to deregister from |
callback |
STRING |
1 |
The function name which was registered on the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
Sample (auto-generated)
success = Command.Client.deregister(handle, eventname, callback)disableChangeListener()
Short description
Removes the registration for a variable change
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventName |
STRING |
1 |
The name of the variable. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully disabled. False if was not enabled before, timed out or error |
Sample (auto-generated)
success = Command.Client.disableChangeListener(handle, eventName)enableChangeListener()
Short description
Register for variable change of the device. All incoming changes are directly received after this call, therefore use the "register" function to register for the "OnChanged" event before.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventName |
STRING |
1 |
The name of the variable. |
notifyListenerOnNoChange |
BOOL |
? |
Also call the listener if an event with no data change was received, optional, defaults to false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if already registered, timed out or error |
Sample (auto-generated)
success = Command.Client.enableChangeListener(handle, eventName, notifyListenerOnNoChange)getDevicesFromDescriptionFile()
Short description
Retrieve the names of the devices, that are stored within the description file previously set with setDescriptionFile.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceNames |
STRING |
* |
A vector containing all the found device names. Empty names are also valid values. Nil is returned, if the description file was not set or is not parseable. An Empty vector is empty, if the description file was loaded successfully but does not contain any devices. |
Sample (auto-generated)
deviceNames = Command.Client.getDevicesFromDescriptionFile(handle)getVariantsForDeviceFromDescriptionFile()
Short description
Retrieve all possible variants for a device stored in the previously set with setDescriptionFile.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
deviceName |
STRING |
1 |
The name of the device to get the variants for. Should be a value which was previously returned by getDevicesFromDescriptionFile. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
variantNames |
STRING |
* |
A vector containing all the found variant names. For a device without variants, a vector with a single, emtpy variant name is returned. Nil is returned, if the description file was not set or is not parseable. |
Sample (auto-generated)
variantNames = Command.Client.getVariantsForDeviceFromDescriptionFile(handle, deviceName)invoke()
Short description
Invokes a method on the device and waits until it is finished. If the method has arguments the createNode function can be used to set them and pass to this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
methodName |
STRING |
1 |
The name of the method. |
paramNode |
CONST_OBJECT |
? |
The node value as arguments if the method has arguments |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully executed. False if timeout or error |
paramNode |
OBJECT |
? |
The method return values if the method has return values |
Sample
local methodArg = Command.Client.createNode(handle, "theMethodName")
local bSuccess,methodResults = Command.Client.invoke(handle, "theMethodName", methodArg)login()
Short description
Login to the device using the specified credentials. The login method always uses the method set by setLoginMethod
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
userLevel |
ENUM |
1 |
The user level to login with. |
password |
STRING |
1 |
The password to use to login. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully executed. False if timeout or error |
Sample (auto-generated)
success = Command.Client.login(handle, userLevel, password)logout()
Short description
Logout from the device.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully executed. False if timeout or error |
Sample (auto-generated)
success = Command.Client.logout(handle)open()
Short description
Opens the client with the current configuration and makes usage possible. The configuration values have to be set before calling this function. The open()-function sends no command to device, just loads the configuration and make communication with device possible.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully opened. False if configuration isn’t valid (e.g. wrong description file) |
errMsg |
STRING |
? |
If open fails, this string contains the readable error message about why it failed |
Sample (auto-generated)
success, errMsg = Command.Client.open(handle)read()
Short description
Reads a parameter of the connected device and returns its value
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
varName |
STRING |
1 |
The name of the variable |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
paramNode |
OBJECT |
? |
The copy of the value. Nil if not exists or was not possible to read. |
Sample (auto-generated)
paramNode = Command.Client.read(handle, varName)register()
Short description
This function is used to register for any event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to register to |
callback |
STRING |
1 |
The function name to call on the event occurrence |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if event does not exist. |
Sample (auto-generated)
success = Command.Client.register(handle, eventname, callback)restore()
Short description
Restores the parameters from a ".sopas" file to the device. This is useful to configure the device in a specific state. If restoring fails the device might be in an inconsistent configuration. The variables are only restored which match the current login level. So make sure to login to the device in the wanted userlevel before. Variables which are above the current userlevel are not written. The opposite function is "backup" to get all parameters from a device.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
paramFile |
STRING |
1 |
The path to the .sopas file to restore from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful restored all parameters. False if not possible or failed while restoring. |
errMsg |
STRING |
? |
If restore fails, this string contains the readable error message about why it failed |
Sample (auto-generated)
success, errMsg = Command.Client.restore(handle, paramFile)setAccessMode()
Short description
Sets the access mode to use for every request. It depends on the devices if requests by name is possible or not. Smaller devices might only support requests by index. Default is 'by name'. The value can also be changed on the fly when the client is open.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
accessMode |
ENUM |
1 |
The access mode to use to the device. |
Sample (auto-generated)
Command.Client.setAccessMode(handle, accessMode)setByteOrder()
Short description
Sets the CoLa byte order to use for binary cola protocols (CoLaB,CoLa2). Defaults is 'Big-endian'.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
byteOrder |
ENUM |
1 |
The cola byte order to use to the device. |
Sample (auto-generated)
Command.Client.setByteOrder(handle, byteOrder)setConnection()
Short description
Sets the connection handle to use for talking with the device. The handle can be of any connection CROWN which serves a "transmit" function and an "OnReceive" event. The connection has already to be opened before and can be control by the user. Also make sure that the connection has to be set to no framing which is the default for most connections. The Client does the framing on its own, so check the setFraming function of the connection. If the connection throws too much receive data, there is a queue of 10 packets and everything more than this is thrown away.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
conHandle |
HANDLE |
1 |
The connection handle to use to communicate with the device |
conCrown |
STRING |
? |
Optional crown name to use for the calls on the handle. If not specified, the crown name is detected from the conHandle. |
Sample (auto-generated)
Command.Client.setConnection(handle, conHandle, conCrown)setDescriptionFile()
Short description
Sets the path to the ".sopas" file to use as description for the device to communicate with. A ".sopas" file can be created using SOPAS ET and store a project. Take care that the file needs to be created for the correct device variant. The setDeviceSelector()-function can be used to select a device if there are multiple devices in the ".sopas"-file.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
filePath |
STRING |
1 |
The path to the file to use as description for the device to communicate with |
Sample (auto-generated)
Command.Client.setDescriptionFile(handle, filePath)setDeviceSelector()
Short description
Sets the device selector which should used to define which description to loaded from the ".sopas" description file. Can be left empty (as per default) to load the first description in the file or if there is just one single description in the file. The selector can be a device type name, device variant and/or the location name. Not used selectors could be set to empty string.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
deviceName |
STRING |
1 |
The name of the device to load from the description file. Could be empty string. |
deviceVariant |
STRING |
? |
The variant of the device to load from the description file. Could be empty string. |
locationName |
STRING |
? |
The location name of the device to load from the description file. Could be empty string. |
Sample (auto-generated)
Command.Client.setDeviceSelector(handle, deviceName, deviceVariant, locationName)setLoginMethod()
Short description
Sets the login method that should be used to login to the device. Default is "SECURE_USERLEVEL_V_2_0". Must be called before open is called to have any effect.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
loginMethod |
ENUM |
1 |
The method to login to the device. |
Sample (auto-generated)
Command.Client.setLoginMethod(handle, loginMethod)setProtocol()
Short description
Sets the protocol to use to the device. Default is "CoLa A".
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
protocol |
ENUM |
1 |
The protocol to use to the device. |
Sample (auto-generated)
Command.Client.setProtocol(handle, protocol)setRequestTimeout()
Short description
Sets the timeout in milliseconds for every request like read, write, invokeMethod, enableChangeListener/disableChangeListener and also backup/restore requests. Default is 30 seconds. Maximum is 65 seconds. The value can also be changed on the fly when the client is open. Only for backup/restore requests the timeout needs to be set before callin the open function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
timoutMs |
INT |
1 |
The timeout in ms for every request. Max. 65 seconds. |
Sample (auto-generated)
Command.Client.setRequestTimeout(handle, timoutMs)write()
Short description
Writes a value to a parameter of the connected device. The value can retrieved by reading first or using the createNode function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
varName |
STRING |
1 |
The name of the variable |
paramNode |
CONST_OBJECT |
1 |
The node value to write |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully written. False if parameter was not written. |
Sample (auto-generated)
success = Command.Client.write(handle, varName, paramNode)Events
OnChanged
Short description
Event which is notified if any change listener received a change of a variable. If the event has values, they are provided as a "Parameters.Node" object.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
eventName |
STRING |
1 |
The name of the variable or event which has changed |
paramNode |
OBJECT |
? |
The event value if the event has arguments |
Sample (auto-generated)
function handleOnChanged(eventName, paramNode)
-- Do something
end
Command.Client.register(handle, "OnChanged", "handleOnChanged")Command.Methods
Short description
Provides functionality to implement CoLa command methods of the device.
Functions
add()
Short description
Adds a new method implementation. Every method could only be added once in the system. The added function callback is called if the method is executed. The callback gets the method parameters and also a prepared return parameter objects (if defined any) as function parameters. The callback should set the values on the return parameter object and should return it if successfully executed. If the callback does not return the return value object, there is an error thrown on the CoLa command interface with number 0x14 (internal error) The method parameters and return values are each in a "Parameters.Node"-object. See the sample code for how a callback implementation looks like.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of Command.Methods |
commandName |
STRING |
1 |
The command method name as served on CoLa interface |
funcCallback |
STRING |
1 |
The function name which implements the method. Needs to have a specific signature, read more about in the function documentation. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if added successfully. False if method does not exist or is already added by someone in the system. |
Sample
function callback(paramNode, resultNode)
-- get values from "paramNode" using Parameters.Node-functions
-- set values on "resultNode" using Parameters.Node-functions
-- if successful return the resultNode
return resultNode
end
local bSuccess = Command.Methods.add(handle, "MyMethodName", callback)create()
Short description
Creates a new method handling instance. The methods stay implement as long as this instance exists.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The new Command.Methods instance |
Sample (auto-generated)
handle = Command.Methods.create()Command.Scan
Short description
API to scan for CoLa devices on Ethernet. There is the CoLa Scan protocol used to discover devices in the Ethernet network. The protocol sends UDP broadcast and can therefore also reach devices which are not in the same subnet. This API can be used to find new devices in the network and configure them. This is useful mainly for system controller purposes to e.g. implement hardware-replacement behaviour of connected devices.
Overview
Functions
beep()
Short description
Calls beep function for the selected device. For CoLa2 devices an optional parameter can be specified which sets the time the device will signal the beep command. Default beep time will be 5 seconds. The function will wait for up to 3 seconds for the device to answer the beep request. If no answer was received within this time, the function will return false.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
macAddress |
STRING |
1 |
MAC address of device which should send beep signal |
beepTimeSec |
INT |
? |
Time in seconds device should signal beep command - optional. Default 5 seconds. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if operation was successful |
Sample (auto-generated)
success = Command.Scan.beep(handle, macAddress, beepTimeSec)configure()
Short description
Sets new IP configuration for the selected device which is identified by the MAC address. The configure function will wait for 5 seconds to get a response from the configured device. If no response was received within this time the function will return false. Use the getIPConfigDuration to get the configuration time from the device. The function will return false if no response was received form the device within 5 seconds.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
macAddress |
STRING |
1 |
MAC address of device |
ipAddress |
STRING |
1 |
New IP address of device |
subnetMask |
STRING |
1 |
New subnet mask of device |
defaultGateway |
STRING |
1 |
New default gateway of device |
dhcpEnabled |
BOOL |
1 |
Set if DHCP is enabled on device |
protocolType |
? |
Transport protocol of device. If not specified, attempt to configure via CoLa2 first, then via CoLaA/B. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if operation was successful |
Sample (auto-generated)
success = Command.Scan.configure(handle, macAddress, ipAddress, subnetMask, defaultGateway, dhcpEnabled, protocolType)create()
Short description
Creates a new Command.Scan instance
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The new instance |
Sample (auto-generated)
handle = Command.Scan.create()scan()
Short description
Scans for CoLa devices on the specified network interface(s) and returns a list of devices. The individual objects will provide the currently configured parameters of the corresponding device. The function blocks until the device scan is completed. It is possible to set a time out after which the scan should stop (default is 5 seconds).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
timeOutMs |
INT |
? |
Optional time out after which the scan should stop (in milliseconds). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
OBJECT |
+ |
Returns a vector with device properties for each device found on the network |
Sample (auto-generated)
deviceParameters = Command.Scan.scan(handle, timeOutMs)setInterface()
Short description
Sets the Ethernet interface which should be used to scan for CoLa devices. If no interface is set, the requests are sent on every ethernet interface after each other.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
interface |
ENUM |
1 |
Select Ethernet interface which should be used for scanning. If none was selected network scan will be done on all available network interfaces. |
Sample (auto-generated)
Command.Scan.setInterface(handle, interface)Command.Scan.DeviceInfo
Short description
Contains the device info fields of one device received by the scan function.
Overview
Functions
getAccessMode()
Short description
Returns the CoLa access mode of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
accessMode |
ENUM |
? |
Access mode of device |
Sample (auto-generated)
accessMode = Command.Scan.DeviceInfo.getAccessMode(deviceParameters)getAuxPort()
Short description
Returns the port number of the auxiliary channel (UDP or TCP)
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
auxPortNumber |
INT |
? |
Port number of auxilliary channel |
Sample (auto-generated)
auxPortNumber = Command.Scan.DeviceInfo.getAuxPort(deviceParameters)getDefaultGateway()
Short description
Returns the default gateway of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
gateway |
STRING |
? |
Default gateway of device |
Sample (auto-generated)
gateway = Command.Scan.DeviceInfo.getDefaultGateway(deviceParameters)getDeviceName()
Short description
Returns the name of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceName |
STRING |
? |
Name of device |
Sample (auto-generated)
deviceName = Command.Scan.DeviceInfo.getDeviceName(deviceParameters)getDHCPClientEnabled()
Short description
Returns if the DHCP client of the device is enabled
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isDhcpEnabled |
BOOL |
? |
Returns true if DHCP client is enabled on device |
Sample (auto-generated)
isDhcpEnabled = Command.Scan.DeviceInfo.getDHCPClientEnabled(deviceParameters)getEthernetInterface()
Short description
Returns the enumeration of the ethernet interface to which the device is connected.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
? |
The ethernet interface |
Sample (auto-generated)
ifName = Command.Scan.DeviceInfo.getEthernetInterface(deviceParameters)getFirmwareVersion()
Short description
Returns the firmware version of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
firmwareVersion |
STRING |
? |
Firmware version of device |
Sample (auto-generated)
firmwareVersion = Command.Scan.DeviceInfo.getFirmwareVersion(deviceParameters)getHasDHCPClient()
Short description
Does the device support DHCP?
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hasDHCPClient |
BOOL |
? |
Returns true if device has a DHCP client |
Sample (auto-generated)
hasDHCPClient = Command.Scan.DeviceInfo.getHasDHCPClient(deviceParameters)getIPAddress()
Short description
Returns the IP address of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
? |
IP address of device |
Sample (auto-generated)
ipAddress = Command.Scan.DeviceInfo.getIPAddress(deviceParameters)getIPConfigDuration()
Short description
Returns the IP config duration of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipConfigDuration |
INT |
? |
IP config duration of device, in seconds. |
Sample (auto-generated)
ipConfigDuration = Command.Scan.DeviceInfo.getIPConfigDuration(deviceParameters)getLocationName()
Short description
Returns the location name of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locationName |
STRING |
? |
Location name of device |
Sample (auto-generated)
locationName = Command.Scan.DeviceInfo.getLocationName(deviceParameters)getMACAddress()
Short description
Returns the MAC address of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
mac |
STRING |
? |
MAC address of device |
Sample (auto-generated)
mac = Command.Scan.DeviceInfo.getMACAddress(deviceParameters)getOrderNumber()
Short description
Returns the order number of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
orderNumber |
STRING |
? |
Get order number of device |
Sample (auto-generated)
orderNumber = Command.Scan.DeviceInfo.getOrderNumber(deviceParameters)getProtocolType()
Short description
Returns the transport protocol version of the device. This function can not distinguish between CoLaA/CoLaB.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
protocolType |
ENUM |
? |
Transport protocol of device |
Sample (auto-generated)
protocolType = Command.Scan.DeviceInfo.getProtocolType(deviceParameters)getSerialNumber()
Short description
Returns the serial number of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
serialNumber |
STRING |
? |
Serial number of device |
Sample (auto-generated)
serialNumber = Command.Scan.DeviceInfo.getSerialNumber(deviceParameters)getSubnetMask()
Short description
Returns the subnet mask of the device
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceParameters |
CONST_OBJECT |
1 |
An object that contains device parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
subnetMaks |
STRING |
? |
Subnet mask of device |
Sample (auto-generated)
subnetMaks = Command.Scan.DeviceInfo.getSubnetMask(deviceParameters)Connector
Short description
Contains CROWNs to access connectors at the device
Connector.DigitalIn
Short description
Provides functionality to control a digital input port at the device
Overview
Functions
create()
Short description
Creates a digital input port with the given name, if it exists and is not already in use.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
portName |
ENUM |
1 |
The devices identifier of the digital input port (e.g. DI1) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
? |
Unique handle for the port. Nil if not available or already in use. |
Sample (auto-generated)
handle = Connector.DigitalIn.create(portName)deregister()
Short description
This function is used to deregister from any registered event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
eventname |
STRING |
1 |
The event to deregister from |
callback |
STRING |
1 |
The function name which was registered on the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
Sample (auto-generated)
success = Connector.DigitalIn.deregister(handle, eventname, callback)get()
Short description
Returns the current activation state of the specified input port.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isActive |
BOOL |
1 |
True if input port is active, false if inactive. |
Sample (auto-generated)
isActive = Connector.DigitalIn.get(handle)register()
Short description
This function is used to register for any event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
eventname |
STRING |
1 |
The event to register to |
callback |
STRING |
1 |
The function name to call on the event occurrence |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if event does not exist. |
Sample (auto-generated)
success = Connector.DigitalIn.register(handle, eventname, callback)setDebounceMode()
Short description
The debounce mode to set for this port. Debouncing removes unwanted noise from the input signal to prevent extra activations. The default mode is time based.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
newMode |
ENUM |
1 |
Debounce mode to use. Initial: TIME_MS |
Sample (auto-generated)
Connector.DigitalIn.setDebounceMode(handle, newMode)setDebounceValue()
Short description
Meaning of the value is dependent on the DebounceMode which is set. The default value is zero which means no debouncing at all.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
newValue |
INT |
1 |
The debounce value to use. Is dependent on the DebounceMode which is set. Initial: 0, Min: 0 |
Sample (auto-generated)
Connector.DigitalIn.setDebounceValue(handle, newValue)setLogic()
Short description
Sets the pin inversion of the port to ACTIVE_HIGH or ACTIVE_LOW. Default is ACTIVE_HIGH.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
newLogic |
ENUM |
1 |
ACTIVE_HIGH or ACTIVE_LOW |
Sample (auto-generated)
Connector.DigitalIn.setLogic(handle, newLogic)Events
OnChange
Short description
This event is triggered whenever the input port changes its state. The new state is provided as parameter. If there is a new registration done on this event, the current state is also notified. Please note that there might be state changes missed by the implementation in overload situations and the same state might be notified twice.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
newState |
BOOL |
1 |
The state of the level signal |
Sample (auto-generated)
function handleOnChange(newState)
-- Do something
end
Connector.DigitalIn.register(handle, "OnChange", "handleOnChange")OnChangeStamped
Short description
This event is triggered whenever the input port changes its state. The new state and exact increment and timestamp are provided as parameter. If there is a new registration done on this event, the current state is also notified. Please note that there might be state changes missed by the implementation in overload situations and the same state might be notified twice.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
newState |
BOOL |
1 |
The state of the level signal |
timeOfStateChange |
INT |
1 |
The timestamp in microseconds the state of the signal changed |
incrementOfStateChange |
INT |
1 |
The increment stamp in ticks the state of the signal changed |
Sample (auto-generated)
function handleOnChangeStamped(newState, timeOfStateChange, incrementOfStateChange)
-- Do something
end
Connector.DigitalIn.register(handle, "OnChangeStamped", "handleOnChangeStamped")Connector.DigitalOut
Short description
Provides functionality to control a digital output port at the device
Functions
create()
Short description
Creates a digital output port with the given name, if it exists and is not already in use.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
portName |
ENUM |
1 |
The devices identifier of the digital output port (e.g. DO1) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
? |
Unique handle for the port. Nil if not available or already in use. |
Sample (auto-generated)
handle = Connector.DigitalOut.create(portName)set()
Short description
Sets the port state to the given value. If the port state is not toggled, this function won’t have an effect.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
newState |
BOOL |
1 |
New state of the level signal |
Sample (auto-generated)
Connector.DigitalOut.set(handle, newState)setActivationMode()
Short description
The activation mode to set for this port, so that the port signal is automatically reset after a given time/increment. Default is time based. Please note that this won’t reset the port state.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
value |
ENUM |
1 |
Activation mode to use. Initial: TIME_MS |
Sample (auto-generated)
Connector.DigitalOut.setActivationMode(handle, value)setActivationValue()
Short description
The activation value to set for this port. Meaning of the value is dependent on the ActivationMode which is set. Default is zero which means not automatically reset.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
value |
INT |
1 |
The activation value to use. Is dependent on the ActivationMode which is set. Initial: 0 |
Sample (auto-generated)
Connector.DigitalOut.setActivationValue(handle, value)setLogic()
Short description
Sets the signal logic of the port to ACTIVE_HIGH or ACTIVE_LOW. Default is ACTIVE_HIGH.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
value |
ENUM |
1 |
Signal logic. Initial: ACTIVE_HIGH |
Sample (auto-generated)
Connector.DigitalOut.setLogic(handle, value)setPortOutputMode()
Short description
Sets the hardware driver mode of the port: high-side (PNP), low-side (NPN) or push-pull. Please consult the data sheet of your device to check which modes are supported.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
value |
ENUM |
1 |
Port output mode. Initial: HIGH_SIDE |
Sample (auto-generated)
Connector.DigitalOut.setPortOutputMode(handle, value)Container
Short description
Provides an associative container for storing all kind of CROWN datatypes (like objects, strings, booleans etc.). Read more…
Overview
Detailed description
Each item in the container is identified using a string name as key. An item in the container can represent both, a single value and vectors. You can add items to the container with help of the general purpose add() function.
For retrieval of items you have several options:
-
With the general purpose get() function you can get an item, but have to check the type of the obtained instance manually.
-
With the specialized set of functions like e.g. getConst(), getObject(), and so on, checking the appropriate type of item is done directly.
Internally, the implementation uses a hash map for fast value access. The order of adding items is not relevant. Moreover, access to the container is thread-safe.
Functions
add()
Short description
Adds an item to the container.
Detailed description
The item can be of type float, integer, bool, string or any object. Adding only works with non-const objects, for const-objects use the addConst() function. If an item with the same name already exists in the container, the function returns false. The container itself cannot be added as item. With the optional parameter itemType you can specify the type name explicitly for the item to be added. When specified, an attempt will be made to convert the item to the specified target type.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item. Must not be empty. |
item |
AUTO |
[1+] |
Item to add. Nil is not possible. |
itemType |
ENUM |
? |
Optional target type to convert to. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if successfully added. False, if item already existing or item type not matching. |
Sample (auto-generated)
success = Container.add(container, name, item, itemType)addConst()
Short description
Adds a const-item to the container.
Detailed description
The item can be of type float, integer, bool, string or any object. Objects can be non-const or const and are forced to be const inside the container. If an item with the same name already exists in the container, the function returns false. The container itself cannot be added as item. With the optional parameter itemType you can specify the type name explicitly for the item to be added. When specified, an attempt will be made to convert the item to the specified target type.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item. Must not be empty. |
item |
CONST_AUTO |
[1+] |
Item to add. Nil is not possible. |
itemType |
ENUM |
? |
Optional target type to convert to. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if successfully added. False, if item already existing or item type not matching. |
Sample (auto-generated)
success = Container.addConst(container, name, item, itemType)clear()
Short description
Clears the entire container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
Sample (auto-generated)
Container.clear(container)create()
Short description
Creates a new container.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
Sample (auto-generated)
container = Container.create()exists()
Short description
Checks, if an item with the provided key string exists in the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item to check. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
1 |
True, if container contains item. |
Sample (auto-generated)
result = Container.exists(container, name)get()
Short description
Gets an item from the container.
Detailed description
No type-checking is done on the item to get. The item can be of type integer, float, bool, object etc., or a vector of these types. To get a const-object value, use the getConst() function. Further usage you have to make sure that the returned item is of correct type. With the optional parameter itemType you can specify the type name explicitly for the item to get. When specified and the item type does not match, nil will be returned.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item. |
itemType |
ENUM |
? |
Optional type match for item. If item type not matching, nil is returned. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
item |
AUTO |
[?*] |
Returns item, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
item = Container.get(container, name, itemType)getBool()
Short description
Retrieves a single boolean value from the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
boolValue |
BOOL |
? |
Returns boolean value, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
boolValue = Container.getBool(container, name)getBoolVector()
Short description
Retrieves a vector of booleans from the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
boolVector |
BOOL |
* |
Returns boolean vector, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
boolVector = Container.getBoolVector(container, name)getConst()
Short description
Gets a const-item from the container.
Detailed description
No type-checking is done on the item to get. The item can be of type integer, float, bool, object etc., or a vector of these types. Objects can be non-const or const and are always returned as const-object. Further usage you have to make sure that the returned item is of correct type. With the optional parameter itemType you can specify the type name explicitly for the item to get. When specified and the item type does not match, nil will be returned.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item. |
itemType |
ENUM |
? |
Optional type match for item. If item type not matching, nil is returned. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
item |
CONST_AUTO |
[?*] |
Returns item, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
item = Container.getConst(container, name, itemType)getFloat()
Short description
Retrieves a single floating-point number from the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
number |
FLOAT |
? |
Returns number, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
number = Container.getFloat(container, name)getFloatVector()
Short description
Retrieves a vector of floating-point numbers from the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
numberVector |
FLOAT |
* |
Returns number vector, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
numberVector = Container.getFloatVector(container, name)getInt()
Short description
Retrieves a single integer number from the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
number |
INT |
? |
Returns number, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
number = Container.getInt(container, name)getIntVector()
Short description
Retrieves a vector of integer numbers from the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
numberVector |
INT |
* |
Returns number vector, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
numberVector = Container.getIntVector(container, name)getObject()
Short description
Retrieves a single object from the container. This only works for non-const objects.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
object |
OBJECT |
? |
Returns object, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
object = Container.getObject(container, name)getObjectConst()
Short description
Retrieves a single const-object from the container. This also works if the object inside the container is non-const.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
constObject |
CONST_OBJECT |
? |
Returns const-object, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
constObject = Container.getObjectConst(container, name)getObjectConstVector()
Short description
Retrieves a vector of const-objects from the container. This also works if the object vector inside the container is non-const.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
objectConstVector |
CONST_OBJECT |
* |
Returns const-object vector, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
objectConstVector = Container.getObjectConstVector(container, name)getObjectVector()
Short description
Retrieves a vector of objects from the container. This only works for non-const object vectors.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
objectVector |
OBJECT |
* |
Returns object vector, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
objectVector = Container.getObjectVector(container, name)getSize()
Short description
Returns the number of items in the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
size |
INT |
1 |
Number of items in container. |
Sample (auto-generated)
size = Container.getSize(container)getString()
Short description
Retrieves a single string from the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
string |
STRING |
? |
Returns string, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
string = Container.getString(container, name)getStringVector()
Short description
Retrieves a vector of strings from the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
stringVector |
STRING |
* |
Returns string vector, if retrieval was successful, otherwise nil. |
Sample (auto-generated)
stringVector = Container.getStringVector(container, name)getType()
Short description
Returns the type definition of the underlying type of item from the enum, as a string .
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item to check. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
type |
ENUM |
? |
Type name, as string. Nil, if type name is not found. |
Sample (auto-generated)
type = Container.getType(container, name)isEmpty()
Short description
Checks, if the container is empty.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
1 |
True, if container is empty. |
Sample (auto-generated)
result = Container.isEmpty(container)isSingle()
Short description
Checks, if the item with the provided key string is a single instance, in opposite to a vector-valued instance.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item to check. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
1 |
True, if a single instance. False, if a vector instance or not existing. |
Sample (auto-generated)
result = Container.isSingle(container, name)isType()
Short description
Checks, if the item with the specified key string is of the specified type.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item to check. |
type |
ENUM |
1 |
Type name to compare against. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
? |
True, if queried type. False, if type is wrong. Nil, if key name not existing. |
Sample (auto-generated)
result = Container.isType(container, name, type)isVector()
Short description
Checks, if the item with the provided key string is a vector-valued instance, in opposite to a single instance.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item to check. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
1 |
True, if a vector-valued instance. False, if a single instance or not existing. |
Sample (auto-generated)
result = Container.isVector(container, name)list()
Short description
Gets a list of all key names in the container, in alphabetical order.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
item |
STRING |
+ |
String vector with names of all items, in alphabetical order. |
Sample (auto-generated)
item = Container.list(container)remove()
Short description
Removes an item from the container. If there is no item with the provided key string, nothing is done and false is returned.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item to remove. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if item existed and was removed. False, if item did not exist. |
Sample (auto-generated)
success = Container.remove(container, name)toString()
Short description
Returns a string representation of the content of the container.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
description |
STRING |
1 |
User-friendly description of the container. |
Sample (auto-generated)
description = Container.toString(container)update()
Short description
Updates an existing item in the container.
Detailed description
The item can be of type float, integer, bool, string or any object. Updating only works with non-const objects, for const-objects use the updateConst() function. If an item with the name does not exist in the container, the function returns false. If the existing item has a different type than specified, the function returns false. The container itself cannot be set as item. With the optional parameter itemType you can specify the type name explicitly for the item to be updated. When specified, an attempt will be made to convert the item to the specified target type.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item. Must not be empty. |
item |
AUTO |
[1+] |
Item to update. Nil is not possible. |
itemType |
ENUM |
? |
Optional target type to convert to. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if successfully updated. False, if item not existing or item type not matching. |
Sample (auto-generated)
success = Container.update(container, name, item, itemType)updateConst()
Short description
Updates an existing const-item in the container.
Detailed description
The item can be of type float, integer, bool, string or any object. Objects can be non-const or const and are forced to be const inside the container. If an item with the name does not exist in the container, the function returns false. If the existing item has a different type than specified, the function returns false. The container itself cannot be set as item. With the optional parameter itemType you can specify the type name explicitly for the item to be updated. When specified, an attempt will be made to convert the item to the specified target type.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
container |
1 |
Object instance |
|
name |
STRING |
1 |
Name of the item. Must not be empty. |
item |
CONST_AUTO |
[1+] |
Item to update. Nil is not possible. |
itemType |
ENUM |
? |
Optional target type to convert to. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if successfully updated. False, if item not existing or item type not matching. |
Sample (auto-generated)
success = Container.updateConst(container, name, item, itemType)Conveyor
Short description
Provides functionality for conveyor-based applications. Most of the functions are based on the concept of increment count. Absolute increment count values range from 0 to 65535. Wraparound occurs when the maximum value is exceeded or when the increment goes below the minimum value.
Overview
Functions
distanceToIncrement()
Short description
Calculates the increment value from a given distance value according to current resolution. If the result is bigger than the maximum increment value, the modulo function is used.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
distance |
INT |
1 |
The distance in micrometer as positive integer value. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
increment |
INT |
1 |
The increment value. The increment count is always between 0 and 65535. |
Sample (auto-generated)
increment = Conveyor.distanceToIncrement(distance)getCountDirection()
Short description
Get current conveyor count direction.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
countDirection |
ENUM |
1 |
Current count direction (up or down). |
Sample (auto-generated)
countDirection = Conveyor.getCountDirection()getCurrentIncrement()
Short description
Retrieve the current increment count value.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
increment |
INT |
1 |
Current increment value. The increment count is always between 0 and 65535. |
Sample (auto-generated)
increment = Conveyor.getCurrentIncrement()getIncrementUpdateTimeout()
Short description
Gets the increment update inactivity timeout after which the speed is reset to 0.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timeoutMs |
INT |
1 |
Timeout in milliseconds or 0 if the internal calculation is used. |
Sample (auto-generated)
timeoutMs = Conveyor.getIncrementUpdateTimeout()getPrescaler()
Short description
Get the prescaler value for the increment input.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
prescaler |
INT |
1 |
The current value for the prescaler |
Sample (auto-generated)
prescaler = Conveyor.getPrescaler()getResolution()
Short description
Get the current resolution value.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resolution |
INT |
1 |
The resolution in micrometer/increment. |
Sample (auto-generated)
resolution = Conveyor.getResolution()getSpeed()
Short description
Get the current conveyor speed.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
speed |
INT |
1 |
The conveyor speed in millimeter/second. |
Sample (auto-generated)
speed = Conveyor.getSpeed()getSpeedThreshold()
Short description
Get the threshold that defines the minimum percentage of speed change to current speed required for the conveyor speed to be updated.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
threshold |
FLOAT |
1 |
The threshold in percentage. |
Sample (auto-generated)
threshold = Conveyor.getSpeedThreshold()getTransportMode()
Short description
Get current conveyor transport mode.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
transportMode |
ENUM |
1 |
Current transport mode direction (forward or backward). |
Sample (auto-generated)
transportMode = Conveyor.getTransportMode()increaseCurrentIncrement()
Short description
Increases the current absolute increment count value by 1. Only works if the setSource-function is set to "LOCAL" increment source (which is the default). If the value is 65535 and it is increased, there is a wraparound to 0.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if the increment has been successfully increased. |
Sample (auto-generated)
success = Conveyor.increaseCurrentIncrement()incrementToDistance()
Short description
Calculates the distance value from a given increment value according to current resolution.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
increment |
INT |
1 |
The increment value. The increment count is always between 0 and 65535. Values outside of this range are not allowed. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
distance |
INT |
1 |
The distance in micrometer as positive integer value. |
Sample (auto-generated)
distance = Conveyor.incrementToDistance(increment)setCurrentIncrement()
Short description
Set the current absolute increment count value. Only works if the setSource-function is set to "LOCAL" increment source (which is the default).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
increment |
INT |
1 |
The absolute increment value which is to be set. It must be within the range 0 to 65535. Values outside of this range are not allowed. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if the increment has been successfully set. |
Sample (auto-generated)
success = Conveyor.setCurrentIncrement(increment)setIncrementUpdateTimeout()
Short description
Sets the increment update inactivity timeout after which the speed is reset to 0. This only affects the internal speed calculation and only works if the increment is still updated.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timeoutMs |
INT |
1 |
Timeout in milliseconds or 0 to use the internal calculation (which uses 50 * lastUpdateInterval). |
Sample (auto-generated)
Conveyor.setIncrementUpdateTimeout(timeoutMs)setPrescaler()
Short description
Prescaler value for the increment input. If greater than 1 all increment values are scaled with this factor. This can be used if the incoming values need a higher resolution than the increment should have. Default is 1.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
prescaler |
INT |
1 |
The new prescaler value. Default is 1. Needs to be greater than zero. |
Sample (auto-generated)
Conveyor.setPrescaler(prescaler)setResolution()
Short description
Set the desired resolution value.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resolution |
INT |
1 |
The resolution in micrometer/increment. |
Sample (auto-generated)
Conveyor.setResolution(resolution)setSource()
Short description
Select the increment source to be used for updating the system increment. Set this to value "LOCAL" so that the "setCurrentIncrement" function works. Otherwise the increment is set by the source which is set to this function. Default is set to the "LOCAL" increment source.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
source |
ENUM |
1 |
The increment source |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if the source has been selected successfully, false if not. |
Sample (auto-generated)
success = Conveyor.setSource(source)setSpeedThreshold()
Short description
Set the threshold that defines the minimum percentage of speed change to current speed required for the conveyor speed to be updated.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
threshold |
FLOAT |
1 |
The new threshold in percentage. Default is 5%. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if the speed threshold has been set successfully, false if not. |
Sample (auto-generated)
success = Conveyor.setSpeedThreshold(threshold)Events
OnConveyorCountDirectionChanged
Short description
The event which is triggered when the conveyor changes it’s count direction. There are two count modes, counting up or backward.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
countDirection |
ENUM |
1 |
Current count direction (up or down). |
Sample (auto-generated)
function handleOnConveyorCountDirectionChanged(countDirection)
-- Do something
end
Script.register("Conveyor.OnConveyorCountDirectionChanged", "handleOnConveyorCountDirectionChanged")OnConveyorStarted
Short description
The event which is triggered when the conveyor belt starts from a standstill.
Sample (auto-generated)
function handleOnConveyorStarted()
-- Do something
end
Script.register("Conveyor.OnConveyorStarted", "handleOnConveyorStarted")OnConveyorStopped
Short description
The event which is triggered when the conveyor belt stops.
Sample (auto-generated)
function handleOnConveyorStopped()
-- Do something
end
Script.register("Conveyor.OnConveyorStopped", "handleOnConveyorStopped")OnConveyorTransportModeChanged
Short description
The event which is triggered when the conveyor changes it’s transport mode. There are two physical transport modes, running forward (default) or backward. This is the physical behavior and independend from increment counting direction!.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
transportMode |
ENUM |
1 |
Current transport mode direction (forward or backward). |
Sample (auto-generated)
function handleOnConveyorTransportModeChanged(transportMode)
-- Do something
end
Script.register("Conveyor.OnConveyorTransportModeChanged", "handleOnConveyorTransportModeChanged")Conveyor.Timeout
Short description
Allows to register a timeout based on relative increment changes, both as increment count and increment distance.
Functions
create()
Short description
Creates a new conveyor timeout object.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the conveyor timeout object. |
Sample (auto-generated)
handle = Conveyor.Timeout.create()deregister()
Short description
This function is used to deregister from any registered event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to deregister from |
callback |
STRING |
1 |
The function name which was registered on the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
Sample (auto-generated)
success = Conveyor.Timeout.deregister(handle, eventname, callback)register()
Short description
This function is used to register for any event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to register to |
callback |
STRING |
1 |
The function name to call on the event occurrence |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if event does not exist. |
Sample (auto-generated)
success = Conveyor.Timeout.register(handle, eventname, callback)startCount()
Short description
Starts an increment count timeout with the specified increment count relative to the current one.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the conveyor timeout object. |
increment |
INT |
1 |
The relative increment count after which the timeout should occur. Value must be between 0 and 32767 |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if the timeout has been successfully started. False if timeout already running or increment count is out of range. |
Sample (auto-generated)
success = Conveyor.Timeout.startCount(handle, increment)startDistance()
Short description
Starts an increment distance timeout with the specified distance relative to the current one.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the conveyor timeout object. |
distance |
INT |
1 |
The relative increment distance in millimeter after which the timeout should occur. Value must be between 0 and INT32_MAX or the from-distance-calculated increment max. of 32767. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if the timeout has been successfully started. False if timeout already running or distance count is out of range. |
Sample (auto-generated)
success = Conveyor.Timeout.startDistance(handle, distance)stop()
Short description
Stops a pending increment timeout.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the conveyor timeout object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if the timeout has been successfully stopped. False if it was not running before. |
Sample (auto-generated)
success = Conveyor.Timeout.stop(handle)Events
OnExpired
Short description
The event which is triggered when the timeout occurs.
Sample (auto-generated)
function handleOnExpired()
-- Do something
end
Conveyor.Timeout.register(handle, "OnExpired", "handleOnExpired")Database
Short description
Database access functionality. Currently, only device internal SQLite DB access is possible, but the API is designed in a way so it can be extended to access external DBs in future. For SQL type Database access, see API 'Database.SQL'.
Database.Expressions
Short description
Expression evaluation on top of SQL data bases. 'Expressions' are a small domain-specific language (DSL) based on XML. Goal is fast string, numeric or boolean value formatting by combining several data base values, together with some formatting options, to a single- or array result (formerly known as 'EvalConditions' or 'StringFormatting', but more powerful). The DSL is easy enough to be passed to some GUI, so it is suitable for operator use (not just programmer!). The API is rather coarse because most of the work is done below the API. For detailed information about the XML formats used, please look up the provided .dtd files. They contain the XML format, suitable for an XML editor, as well as sample snippets. Expressions are manually triggered and work on the data set of a data base at the point of evaluation. The data base may be locked from concurrent access until the evaluation has finished. Expression evaluation imposes some limits on the underlying data base, which must be followed, to make it work: - Each DB table used together with expressions must have a primary key of type 'INT' which is never 'null' and has the name 'Id' (upper case 'I', lower case 'd') - The supported data types are 'INT', 'REAL', 'TEXT' only. - Boolean values can be emulated by prefixing them with 'bool'. Database columns starting with 'bool' are interpreted as booleans (0=false, all other values=true) and must be of type 'INT' - Parent-child relationship from tables to other tables must be done with foreign keys in the child referring to the 'Id' of the parent table. The naming of these foreign keys must be 'ForeignTableName' concatenated with 'Id', for example 'ObjectId' - 1:1 as well as n:1 child-parent relationships are possible A valid database scheme might look like this (Example in SQLite SQL dialect): PRAGMA foreign_keys = ON; create table Object(Id int primary key not null, Duration int, Triggerlength int); create table Code(Id int primary key not null, Content text, Position int, Codetype text, Dimension int, boolValidity int, ObjectId int references Object on delete cascade); create index CodeIndex on Code(ObjectId) create table Code1D(Id int primary key not null, Expenditureunknown int, Expenditurestd int, Expendituresmartfwd int, Expendituresmartbwd int, CodeId int references Code on delete cascade); create index Code1DIndex on Code1D(CodeId) create table Code2D(Id int primary key not null, Xsize int, Ysize int, CodeId int references Code on delete cascade); create index Code2DIndex on Code2D(CodeId) The 'on delete cascade' and the 'PRAGMA foreign_keys' are optional and useful for the programmer to provide a more consistent database which also cleans-up itself (children are removed when the parent table entry dies). The 'create index' statements help speeding-up SQL queries done by the internal implementation for parent-child relationships. In the shown example, the Object table relates to n Code-tables, so querying Code items for ObjectId will occur often. Thus, the index is created on that foreign key. For more information on SQLite index creation, see tutorial: http://www.sqlitetutorial.net/sqlite-index/ The order in which the API functions have to be called is: - create() — to be called once - bind() — to assign the expression to a DB instance - registerFunction() — optionally - parse() — To generate the expression out of the DSL XML description - evaluate() — To evaluate the expression on the data base - getResult() — To retrieve the results of the evaluation Note that evaluate() and getResult() are trimmed for speed and repeated calling. All other functions should be called at configuration time, not at normal operation mode.
Overview
Functions
bind()
Short description
Binds the expressions object to a data base instance.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
db |
HANDLE |
1 |
The data base handle |
rootRelation |
STRING |
1 |
The primary SQL table/relation from where to start evaluation. This is the uppermost table of a parent-child relationship (in the example shown in description of the Database.Expressions API, this is the 'Object' table |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
true if the binding was successful, false otherwise |
Sample
success = expr:bind(myDB, "Root")clear()
Short description
Removes all parsed expressions from the pool, to make it ready for another 'parse()' call. Does not affect registered functions or DB binding.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
Sample (auto-generated)
Database.Expressions.clear(handle)clearResults()
Short description
Clears the results of a specified- or of all expressions, so that evaluation result of a future evaluation can not depend on any previous one. After calling, the getResults() call will return nil or an empty list for the specified condition.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
exprName |
STRING |
? |
Name of the expression to clear results. When empty or omitted, all results are cleared. |
Sample (auto-generated)
Database.Expressions.clearResults(handle, exprName)create()
Short description
Creates a new Expressions object. Multiple expression objects may be parsed into that "pool" object, to be evaluated together at one point in time.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The newly created object |
Sample
handle = Database.Expressions.create()evaluate()
Short description
Evaluates expressions on the current data set(s) stored in the DB
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
key |
AUTO |
1 |
Primary key of the outermost relation to be evaluated |
exprNames |
STRING |
[?*] |
Optional: Name(s) of the expressions to be evaluated. When not specified, all expressions will be evaluated |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
'true' when the evaluation was successful, 'false' otherwise |
Sample (auto-generated)
success = Database.Expressions.evaluate(handle, key, exprNames)getMetaInfo()
Short description
Returns meta-information about the expressions set-up so a GUI can use it for displaying the correct items.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
format |
1 |
In what format the meta-info should be delivered |
|
metaInfo |
1 |
What meta-info to obtain |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
'true' in case the meta-info could be obtained, 'false' otherwise (for example, when the expressions object was not correctly bound to the database instance |
metaInfo |
STRING |
? |
The meta-info string if success is true |
metaInfoDtd |
STRING |
? |
The corresponding DTD in case XML has been used |
Sample (auto-generated)
success, metaInfo, metaInfoDtd = Database.Expressions.getMetaInfo(handle, format, metaInfo)getNames()
Short description
Returns the names of all expressions currently existing in the pool
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
names |
STRING |
* |
Names of the expressions |
Sample (auto-generated)
names = Database.Expressions.getNames(handle)getPossibleEvaluationContexts()
Short description
Returns an array of data base relation names on which the passed expression can be evaluated on. This can be the 'root' relation set with the bind() call or any other relation which relates directly or indirectly to the root in a parent-child manner. When the 'root' relation is not one of the results, this means that the expression can’t be evaluated on its own but only by iteration inside of another expression.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
exprName |
STRING |
1 |
Name of the expression to get the type from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
relationNames |
STRING |
* |
An array of relation names. When the expression doesn’t exist, an empty array will be returned |
Sample (auto-generated)
relationNames = Database.Expressions.getPossibleEvaluationContexts(handle, exprName)getResults()
Short description
Returns the last evaluation result(s) by expression name
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
exprName |
STRING |
1 |
Name of the expression to retrieve the results from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
results |
AUTO |
[?*] |
An array of results. May be empty, one result or multiple ones, depending on the expression. When an expression with the name 'exprName' does not exist, no value is returned, which will result in a 'nil' value for the caller. |
Sample (auto-generated)
results = Database.Expressions.getResults(handle, exprName)getTypeByName()
Short description
Returns the type of one expression in the pool
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
exprName |
STRING |
1 |
Name of the expression to get the type from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
type |
1 |
Returns the type. When the expression does not exist, 'INVALID' is returned |
Sample (auto-generated)
type = Database.Expressions.getTypeByName(handle, exprName)parse()
Short description
Parses an XML description that contains one or more expressions. Overwrites already parsed expressions having the same 'exprName' (see return values)
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
content |
STRING |
1 |
The XML string which is parsed into the expression. Must be valid UTF-8 based XML conforming to the 'exprs.dtd' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
true when the parsing succeeded, false in case of errors (please look at the logging console for more info) |
Sample (auto-generated)
success = Database.Expressions.parse(handle, content)registerFunction()
Short description
Registers a custom user-defined function that can afterwards be used in the expression XML as if it was a pre-defined function. That function will then also be present in the GUI for operator use. When that function needs a context, such as an OOP this-pointer/reference, a constructor function may be passed as well. The returned values of that constructor call are then held as long as the expression exists and passed as first parameter(s) to each function invocation at point of the 'evaluate()' call. This way, a context can be passed to the function. The constructor function, if existent, is called each time a parse() call is triggered and the results of that call are held internally.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The expression instance |
retTypes |
1 |
What kind of value(s) that function returns. This can be a single value or multiple values |
|
name |
STRING |
1 |
Name of the function as it should appear in the GUI. That name may be different from the actual function name passed by the 'func' parameter. The name needs to have the form [a-z][A-Z][0-9]_+, so upper-, lower case characters, numbers and underscore are allowed (no spaces). The first character should not be a number |
description |
STRING |
1 |
Description (and usage) string shown in the GUI when that function is shown to the operator |
func |
STRING |
1 |
The function which is executed under that name. That function needs to return either a single value or an array of values, according to the 'retTypes' parameter, and gets a values passed as parameters (see examples). The first parameters passed are the values returned by the 'constructor' function, if passed. |
constructor |
STRING |
? |
Optional constructor function that is used to set-up an environment or context, for example a prepared DB statement, at the point where the expression is parsed, prior to evaluation. This function can return values, and all these returned values are stored internally and later passed to the function 'func' as first parameters. For example, a 'this' object may be returned, which is later passed as first parameter, to support OOP. |
ctorParam0 |
AUTO |
[?*] |
Optional parameter passed to the 'constructor' function |
ctorParam1 |
AUTO |
[?*] |
Optional secondary parameter passed to the 'constructor' function |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
true when the function has been registered successfully, false otherwise (for example, when a function with that name already exists) |
Sample
function f() return {1,2,3} end
expression:registerFunction("NUMERIC", "func", "Some very useful function delivering 3 values", f)
-- or a more complicated function involving OOP and constructor:
function g(self, param) return self:returnValues(param) end -- 'self' is a kind of this-pointer created by the constructor function
function constructorForG(databaseHandle) --[[ create some handle type, assign database and return it: ]] return instance; end
expression:registerFunction("moreComplexFunc", "Function calling the data base and returning some values out of it", g, constructorForG, dbHandle) -- 'dbHandle' is the parameter to the constructor function 'constructorForG'Database.SQL
Short description
General SQL database access (Relational Databases). Specific functions for specific databases can be found in sub-crowns, such as Database.SQL.SQLite
Database.SQL.SQLite
Short description
Bindings to built-in SQLite database. A SQLite-3 database (for exact version info, please call Database.SQL.SQLite.getVersion()) is integrated in the firmware and can be used via this API, together with the more generic Database.SQL.* API. SQLite is either statically or dynamically linked to the firmware and does not need external binaries installed in the device. Also, access to SQLite is direct (task context-wise), meaning that the overhead is minimal. The SQLite API highly corresponds to the C API of SQLite, which can be found here: https://www.sqlite.org/docs.html The database is transaction safe when used with a Windows/Linux file system in case the fsync() and other synchonization primitives works correctly on that OS. The basic guarantees can be found on the page https://www.sqlite.org/atomiccommit.html Please take indexing of important table columns into consideration. See tutorial http://www.sqlitetutorial.net/sqlite-index/ Please also read the docu about parameter bindings: https://www.sqlite.org/lang_expr.html#varparam https://www.sqlite.org/c3ref/bind_parameter_name.html https://www.sqlite.org/c3ref/bind_blob.html The most important changes using the CROWN API are: - Every array or placeholder indexing is zero based, not one-based, to correspond to the CROWN guidelines. That means when a placeholder (?) is bound to a value, the first placeholder has index zero, the next one index one and so on - A reset() call on a prepared statement also invokes the underlying clearBindings()-function - There is additional support for storing CROWN object types in the DB. So, when using a particular CROWN function, please also look-up the corresponding documentation in the internet (for example sqlite-doc-3170000.zip). A hint to which function is used below the API is attached to each function/event documentation. An important extension is the binding of CROWN objects. Binding can be done in two different modes: - SERIALIZED: The object is transformed into a stream of bytes or characters and then stored as a BLOB or TEXT field in the data base. JSON and MessagePack are supported as formats. The object in memory is not referenced to any more when put into the DB - MAP_TO_ID: A reference to the object is held in a local cache (in this documentation, it is called the 'object cache') and is mapped to an integer ID which is stored in the database instead of the object. This mode only makes sense for in-memory database with fast object look-up. For the mode MAP_TO_ID, the creation of the IDs that are stored in the DB is done automatically and it is ensured that IDs are unique. IDs in the positive range of a 64 bit integer are used. When an object is bound twice (or more) to a DB field, two (or more) distinct IDs are created for the same object, and the object is also held as long all of the IDs referring to it exist. To also remove an object from the cache when getting it, use the 'MAP_FROM_ID_AND_REMOVE' mode. Further supplied functions to manipulate the cache are getObjectIds(), getObject(), setObject() and removeObject(). When you fear or encounter that the object cache grows unpredictably, you can optionally use the 'garbage collection' feature which is a manually triggered mark-and-sweep kind of collection. It works by querying the DB for all object IDs that are stored in the DB. Then, it walks over the object cache to find objects that have IDs that are not existent in the DB any more. Those objects are then removed from the cache. To use garbage collection, use the addGarbageCollectionStatement() and collectGarbage() APIs. Please make sure that every DB field referring to object IDs is added with addGarbageCollectionStatement(), else, the GC will leave unused objects in the cache (leaks). It is up to the responsibility of the API user to take care of that. See also the sample of the 'addGarbageCollectionStatement()' API. Also, the 'collectGarbage()' function is not automatically triggered, so there is the need to manually call that. However, when the DB is closed, the object cache is cleared out entirely.
Overview
Functions
addGarbageCollectionStatement()
Short description
Optionally needed when Database.SQL.Statement.bindObject() should be called in future with bindingMode=MAP_TO_ID and when there is need for cleaning-up the object cache periodically. It adds a SQL statement to retrieve object IDs from the DB for objects that are still considered to be in use by the client (which should NOT be removed by the collector). The function can be called multiple times to add multiple statements to the collector. See also collectGarbage() function. The statements are all discarded when a 'close()' call is done on the DB, so, when re-opening a DB, the calls to this function may need to be repeated. Has no direct mapping to an SQLite API, but uses the API 'prepare()' call and holds the created statement objects internally.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
sql |
STRING |
1 |
The SQL statement which returns a single column of type 'int' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Whether the collection statement could be added |
Sample
handle:addGarbageCollectionStatement("select ObjId from Images")
handle:addGarbageCollectionStatement("select ObjId from PointClounds")
handle:addGarbageCollectionStatement("select ObjId from Scans")
-- See also sample of collectGarbage() for a more complete scenarioclose()
Short description
Closes an open database. This is an optional operation since expiring an open Database.SQL.SQLite handle closes the underlying database automatically. Calls the C API 'sqlite3_close()'
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
Sample
success = handle:close()collectGarbage()
Short description
Can be used in conjunction with prior 'addGarbageCollectionStatement()' calls to remove objects from the object cache which have an ID that does not exist in the DB any more. Only needed if the MAP_TO_ID mapping is used somewhere and if it is not clear if all the objects are removed with 'MAP_FROM_ID_AND_REMOVE'. This function needs to be manually triggered to do the clean-up, probably when there is enough time for doing that, since it might be an expensive operation depending on the size of the DB. It executes all SQL statements added by addGarbageCollectionStatement() to get all object IDs which should be retained. Then, it walks through the object cache to remove all objects that have IDs that are not part of the 'retain' list (IDs that are not part of the sql results). Note that when no statement has been added with 'addGarbageCollectionStatement', the function won’t clean up and report an error instead. This operation uses the 'Statement' API internally and thus has no direct SQLite equivalent
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
numOfObjectsRemoved |
INT |
1 |
Number of objects collected |
numOfObjectsTotal |
INT |
1 |
Number of objects that existed in the cache before collection |
Sample
handle:addGarbageCollectionStatement("select ObjId from Images") -- To clean-up images in cache
handle:addGarbageCollectionStatement("select ObjId from PointClounds") -- To clean-up point clouds in cache
handle:addGarbageCollectionStatement("select ObjId from Scans") -- To clean-up scans in cache
local query = handle:prepare("insert into Images values(?)")
local img = Image.create(...)
query:bindObject(0, "MAP_TO_ID", img) -- Fill the 'ObjId' field
query:step() -- Inserts the image to the cache and stores an ID into the DB
handle:exec("delete from Images") -- Removes all Image IDs from the database, but the cache still contains the actual Image objects
handle:collectGarbage() -- Retains PointClouds and Scans, but removes the temporary image stored in the cachecreate()
Short description
Creates a new device internal SQLite database instance. The database is not open yet, so a call to one of the various open…() functions is needed to be able to work with a database.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
Sample
handle = Database.SQL.SQLite.create()execute()
Short description
Executes one or more SQL statements/queries without retrieving results. This is particularly useful to set-up the database after creating it. Multiple statements/queries can be passed by inserting semicolon (';') separators. Calls the C API 'sqlite3_exec()'
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
query |
STRING |
1 |
The SQL query to execute. You can use placeholders. Multiple queries may be specified by finishing each of them with a semicolon. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Whether the operation was successful. In case of error, the getErrorMessage() function can be called to get extended error information |
Sample
success = handle:execute("create table MyTable(Id int primary key not null)")getErrorMessage()
Short description
Returns error message for the last error. Calling this function when no error occured results in a random string, so only call it in error cases. The error strings usually come from SQL API 'sqlite3_errmsg()' calls, but these calls are done at the point where errors occur and the error string is cached until this API is called.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
errorMessage |
STRING |
1 |
Error message or an empty string if there was no error. |
Sample
errorMessage = handle:getErrorMessage()getObject()
Short description
Returns an object in the cache by its ID. When the ID is not a valid ID, a 'nil' value is returned instead.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
id |
INT |
1 |
The object ID that should be used for look-up |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
obj |
OBJECT |
? |
The returned object |
Sample
obj = handle:getObject(id)getObjectIds()
Short description
Returns the IDs of all objects in the object cache (see collectGarbage() or bindObject()).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ids |
INT |
* |
The object ids |
Sample
ids = handle:getObjectIds()getVersion()
Short description
Returns the version number of the SQLite implementation in the firmware as string. Calls the underlying 'sqlite3_libversion()' C API
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
versionString |
STRING |
1 |
The version string, for example '3.17.0' |
Sample
print(handle:getVersion())openFile()
Short description
Opens a database to work on a device file. Calls the underlying C API 'sqlite3_open_v2()'. In case of error, 'false' is returned, the database is closed immediately and may be re-opened again.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
filename |
STRING |
1 |
Path to the database file to open. |
openmode |
ENUM |
1 |
How to open the database |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if database was opened successfully, false if not. When false is returned, the database is closed and ready to be opened again. |
Sample
success = handle:openFile("public/sample.db", "READ")openMemory()
Short description
Opens an fast in-memory database for read/write access. Calls the underlying C APIs 'sqlite3_open()' and 'sqlite3_exec()' to pass 'PRAGMA page_size' and 'PRAGMA max_page_count' to limit the RAM usage to the passed 'size' parameter. In case of error, the database is closed immediately and may be re-opened.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
size |
INT |
1 |
Size of the in-memory DB in number of bytes. A size smaller than 512 bytes is not possible, and the size is enlarged to be a multiple of 512 bytes. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if database was opened successfully, false if not. When false is returned, the database is closed and ready to be opened again. |
Sample
success = handle:openMemory(1048576)prepare()
Short description
Creates a prepared SQL statement. Prepared statements get pre-compiled inside the DB and can be execute faster when used multiple times, so this one should be prefered over the 'exec()' API for repeated calls on a huge amount of data. Calls the C APIs 'sqlite3_prepare_v2()' and for destruction 'sqlite3_finalize()'.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
query |
STRING |
1 |
The SQL query to execute. Placeholders can be freely inserted according to the SQLite language (see bind…() and getColumn…() API |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
statement |
HANDLE |
? |
The prepared statement object. When the query has errors, no statement is created. getErrorMessage() can be called to get extended error information in case no statement has been returned. |
Sample
statement = handle:prepare("select * from MyTable where name = ?")removeObject()
Short description
Removes an object plus its ID from the object cache. Please make sure that the particular ID is not used inside the DB.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
id |
INT |
1 |
The object ID that should be removed |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if object could be removed, false when ID is invalid |
Sample
handle:removeObject(id)setObject()
Short description
Replaces an object in the cache. When the ID is not a valid ID or the passed object is a 'nil' value, an error is message is printed out.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Database instance |
id |
INT |
1 |
The object ID that should be used for look-up |
obj |
OBJECT |
1 |
The object to set |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if object could be set, false when ID is invalid |
Sample
handle:setObject(id, obj)Database.SQL.Statement
Short description
Pre-compiled prepared statements generated by a SQL-like DB. This CROWN is designed to work with any kind of SQL database, as long as the device supports it. The Statement data type has no constructor but it needs to be created by a factory, for example 'Database.SQL.SQLite.prepare()'. Since the Statements can be created by any SQL DB, the underlying API calls may differ. For SQLite binding, the used SQLite API is annotated, so the equivalent SQLite documentation can be looked up.
Overview
Functions
bind()
Short description
Binds multiple values to multiple placeholders at once. Only index-based, not named, placeholders are possible. Each bound value can either be a single value or an array of values. They are bound in order of occurrence and when an array is used, the values are extracted from the array and bound one after another with increasing index. That enables binding of an unlimited number of values and reduces call overhead. A pre-requisite for convenient usage of this function is a DB design where the columns are sorted by type, for instance 'create table Tab(int, int, real, real, string)'. Because of binding of Lua to CROWN subsystem, there is an ambiguity between data of type 'string' and 'binary' when using interfaces with type 'auto'. When lua strings are passed through this function, such as { "Hello", "World!" }, they are by default converted to string by this function and bound as 'TEXT' values, and there is an error when the strings aren’t valid UTF-8 data. If that behavior should be changed to 'BLOB' binary binding, one can pass the string '$blob' as the first element of the array. It will be used as a kind of 'pragma' switch to bind all following values of the array as 'BLOB' data. For example, a call local offset = 0 statement:bind(offset, {"$blob", "\x01\x02", "\x03"}) binds 2 values: At index 0, a BLOB with content [0x01,0x02] is bound, and at index 1, one BLOB with content [0x03] is bound. The string '$blob' will not be inserted into the DB at all because it is used as indicator only. Accordingly, the magic string '$text' will leave the content to be interpreted as string values and bound to a DB 'TEXT' field. The '$text' pragma is redundant but can document the intention of the user. For numeric values, the same problem with int/float ambiguity arises, but in that case, it is determined at runtime if all values in the array are integers, and then the values are bound like 'bindInt' when this is the case. That will also work when the target is a REAL column, because the DB will do the INT-to-REAL conversion as needed. Full usage example for a DB table with design 'create table Tab(int, int, real, string, string, blob), which are 6 values of 4 different types: local offset = 0 bind(offset, {4711, 42}, 3.14, {"$text", "Hello", "World!"}, {"$blob", "\x01\x02\x03" })
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
offset |
INT |
1 |
Binding offset. A value of 0 means binding from index 0 upwards. Only when multiple bind() calls are necessary, this must be the offset of the previous bind() call |
values0 |
AUTO |
[?*] |
Value(s) to bind, see description of the function |
values1 |
AUTO |
[?*] |
Value(s) to bind, see description of the function |
values2 |
AUTO |
[?*] |
Value(s) to bind, see description of the function |
values3 |
AUTO |
[?*] |
Value(s) to bind, see description of the function |
values4 |
AUTO |
[?*] |
Value(s) to bind, see description of the function |
values5 |
AUTO |
[?*] |
Value(s) to bind, see description of the function |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if value was bound, false if not. false is also return in case of string binding with invalid UTF-8 data |
Sample
statement:bind(offset, {4711, 42}, 3.14, {"$text", "Hello", "World!"}, {"$blob", "\x01\x02\x03" })bindBlob()
Short description
Binds a binary (array of bytes, binary large object [BLOB]) value to a placeholder. When using integer indexes they start with zero (not one, like in SQLite!) Binding using indexes is more performant than using string-based placeholders, which need additional look-up. Conversion takes place according to the rules of the particular DB. In case SQLite is used, the SQLite API 'sqlite3_bind_blob()' and optionally (for named placeholders) 'sqlite3_bind_parameter_index()' is called.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
indexOrKey |
AUTO |
1 |
Index of the placeholder to bind, or name of the placeholder to bind (int or string) |
value |
BINARY |
1 |
Value to bind to the placeholder. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if value was bound, false if not. |
Sample
-- index based:
blob = "Some binary-interpreted data"
statement:bindBlob(0, blob)
-- string based:
statement:bindBlob("$MyNamedPlaceholder", blob)bindDouble()
Short description
Binds a floating point value to a placeholder. When using integer indexes they start with zero (not one, like in SQLite!) Binding using indexes is more performant than using string-based placeholders, which need additional look-up. Conversion takes place according to the rules of the particular DB. In case SQLite is used, the SQLite API 'sqlite3_bind_double()' and optionally (for named placeholders) 'sqlite3_bind_parameter_index()' is called.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
indexOrKey |
AUTO |
1 |
Index of the placeholder to bind, or name of the placeholder to bind (int or string) |
value |
FLOAT |
1 |
Value to bind to the placeholder. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if value was bound, false if not. |
Sample
-- index based:
statement:bindDouble(0, 3.14)
-- string based:
statement:bindDouble("$MyNamedPlaceholder", 3.14)bindInt()
Short description
Binds an integer value to a placeholder. When using integer indexes they start with zero (not one, like in SQLite!) Binding using indexes is more performant than using string-based placeholders, which need additional look-up. Conversion takes place according to the rules of the particular DB. In case SQLite is used, the SQLite API 'sqlite3_bind_int64()' and optionally (for named placeholders) 'sqlite3_bind_parameter_index()' is called.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
indexOrKey |
AUTO |
1 |
Index of the placeholder to bind, or name of the placeholder to bind (int or string) |
value |
INT |
1 |
Value to bind to the placeholder. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if value was bound, false if not. |
Sample
-- index based:
statement:bindInt(0, 4711)
-- string based:
statement:bindInt("$MyNamedPlaceholder", 4711)bindNull()
Short description
Binds a null value to a placeholder. This does only work for SQL columns which aren’t 'not null'. When using integer indexes they start with zero (not one, like in SQLite!) Binding using indexes is more performant than using string-based placeholders, which need additional look-up. Conversion takes place according to the rules of the particular DB. In case SQLite is used, the SQLite API 'sqlite3_bind_null()' and optionally (for named placeholders) 'sqlite3_bind_parameter_index()' is called.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
indexOrKey |
AUTO |
1 |
Index of the placeholder to bind, or name of the placeholder to bind (int or string) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if value was bound, false if not. |
Sample
-- index based:
statement:bindNull(0)
-- string based:
statement:bindNull("$MyNamedPlaceholder")bindObject()
Short description
Binds a CROWN object. There are two modes available: 1. Serialization to BLOB/TEXT or 2. Mapping to an integer ID and storing that ID together with the reference in a cache instead. For the first mode, choose either SQL TEXT data type in case a text-based format, such as JSON, is chosen, or SQL BLOB in case a binary format, such as MessagePack, is used. The second mode needs an SQL INT data type. It may require periodic garbage collection by calling the Database.SQL.collectGarbage() function (see description of the Database.SQL.SQLite API) and is only useful for fast object access without serialization involved, together with in-memory databases. So, the SERIALIZED option should be preferred since it does not require manual clean-up. Also, the 2nd option does not make the actual objects persistent; it just caches them in RAM temporarily. In case SQLite is used, the API functions 'sqlite3_bind_text()' is used for text-based serialization, the function 'sqlite3_bind_blob()' for binary serialization and 'sqlite3_bind_int64()' in case of ID mapping
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
indexOrKey |
AUTO |
1 |
Index of the placeholder to bind, or name of the placeholder to bind (int or string) |
bindingMode |
ENUM |
1 |
Binding mode |
value |
OBJECT |
1 |
Value to bind to the placeholder. |
dataFormat |
ENUM |
? |
Serialization format of object in case bindingMode is set to SERIALIZE. When not specified, JSON is used as default, like in Object.save() |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if value was bound, false if not. |
Sample
-- index based:
obj = Image.create(...)
statement:bindObject(0, "SERIALIZE", obj, "JSON")
-- string based:
statement:bindObject("$MyNamedPlaceholder", "SERIALIZE", obj, "JSON")bindText()
Short description
Binds a string value to a placeholder. When using integer indexes they start with zero (not one, like in SQLite!) Binding using indexes is more performant than using string-based placeholders, which need additional look-up. Conversion takes place according to the rules of the particular DB. In case SQLite is used, the SQLite API 'sqlite3_bind_text()' and optionally (for named placeholders) 'sqlite3_bind_parameter_index()' is called.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
indexOrKey |
AUTO |
1 |
Index of the placeholder to bind, or name of the placeholder to bind (int or string) |
value |
STRING |
1 |
Value to bind to the placeholder. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if value was bound, false if not. |
Sample
-- index based:
statement:bindText(0, "Hi, there!")
-- string based:
statement:bindText("$MyNamedPlaceholder", "Hi, there!")getColumnBlob()
Short description
Returns a result column byte-array/BLOB value. In case of SQLite, 'sqlite3_column_bytes()' and 'sqlite3_column_blob()' is called
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
index |
INT |
1 |
Index of the column |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ret |
BINARY |
1 |
The value |
Sample
while (statement:step() == "ROW") do
local myBinary = statement:getColumnBlob(0)
endgetColumnDouble()
Short description
Returns a result column as floating point value. In case of SQLite, 'sqlite3_column_double()' is called
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
index |
INT |
1 |
Index of the column |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ret |
FLOAT |
1 |
The value |
Sample
while (statement:step() == "ROW") do
local myFloat = statement:getColumnDouble(0)
endgetColumnInt()
Short description
Returns a result column as integer value. In case of SQLite, 'sqlite3_column_int64()' is called
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
index |
INT |
1 |
Index of the column |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ret |
INT |
1 |
The value |
Sample
while (statement:step() == "ROW") do
local myInt = statement:getColumnInt(0)
endgetColumnObject()
Short description
Retrieves a CROWN object by either de-serialization of the stored BLOB or retrieving the ID and mapping from the object cache. For information on which SQL data type to choose in which scenario, please look-up the documentation of 'bindObject()'. In case SQLite is used, the SQLite API function 'sqlite3_column_type()' is used to dis-ambiguate the types, followed by either 'sqlite3_column_bytes()'/'sqlite3_column_blob()', 'sqlite3_column_text()' or 'sqlite3_column_int64()' depending on the row type
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
index |
INT |
1 |
Index of the column |
gettingMode |
ENUM |
1 |
Getting mode. See enum description |
dataFormat |
ENUM |
? |
Serialization format of object in case bindingMode is set to SERIALIZE. When not specified, JSON is used as default, like in Object.load() |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ret |
OBJECT |
? |
The object, when it could be de-serialized or mapped, or no value if there was an error with the mapping or de-serialization |
Sample
while (statement:step() == "ROW") do
local myObj = statement:getColumnObject(0, "DESERIALIZE", "JSON")
endgetColumns()
Short description
Retrieves multiple columns at once, equivalent to the multi-value 'bind()' function. The function needs a description string that denotes which columns should be retrieved by which way and into which target data type, and if they should be retrieved as single value or as an array of values. The syntax of that string is 'crownType:singleIntegerIndex' or 'crownType:[array of integer indexes separated by comma]' or 'crownType:[beginRange-endRange]' More than one of those statements can be passed, using a semicolon ';' as separator. The first variant fetches a single value from a single column, the second one fetches multiple values from multiple columns and returns them packed as one array value. The third one fetches 0..n values, where the begin and the end of the range (inclusive) is specified with a dash. So, the expresssion [1,2,3,4] and [1-4] are equal, but the second form might be slightly faster due to less parsing overhead and should be prefered for getting a lot of values at once. crownType can be one of: 'int', 'float', 'string', 'binary', 'bool'. Treatement of 'bool' is special: The value is extracted as SQL INT value and then converted to bool (0=false, all other values=true) Otherwise, 'int' refers to INTEGER columns, 'float' to REAL columns, 'string' to TEXT columns and 'binary' to BLOB. Other types are not possible because there is no direct SQL mapping, so to extract other types, such as 'object', please use a separate 'getColumnObject' call. Example to get column 0 as int and column 1 and 2 as string array: myInt, myStrings = statement:getColumns("int:0;string:[1,2]") Note that the returned 'myStrings' is an array of length 2. Both forms can be combined by separating them with semicolons ';', as shown in the example. A maximum of 7 distinct values can be returned. But when packing multiple values into an array (as with 'type:[index,…]'), this restriction can be circumvented. When the function fails for whatever reason, no values are returned, resulting in 'nil' values for the script programmer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
getMode |
STRING |
1 |
Information on how to retrieve the values. For syntax, see description of the function. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
results0 |
AUTO |
[?*] |
Either a single value or an array of values as mentioned in the 'getMode' parameter. No value/'nil' in case of error |
results1 |
AUTO |
[?*] |
Either a single value or an array of values as mentioned in the 'getMode' parameter. No value/'nil' in case of error |
results2 |
AUTO |
[?*] |
Either a single value or an array of values as mentioned in the 'getMode' parameter. No value/'nil' in case of error |
results3 |
AUTO |
[?*] |
Either a single value or an array of values as mentioned in the 'getMode' parameter. No value/'nil' in case of error |
results4 |
AUTO |
[?*] |
Either a single value or an array of values as mentioned in the 'getMode' parameter. No value/'nil' in case of error |
results5 |
AUTO |
[?*] |
Either a single value or an array of values as mentioned in the 'getMode' parameter. No value/'nil' in case of error |
results6 |
AUTO |
[?*] |
Either a single value or an array of values as mentioned in the 'getMode' parameter. No value/'nil' in case of error |
Sample
myInt, myStrings = statement:getColumns("int:0;string:[1,2]")getColumnsAsString()
Short description
Retrieves all result colums, converts them to string and concatenates them with vertical bars. This is very convenient for debugging or logging to catch all results regardless of type and order.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ret |
STRING |
1 |
All columns, formatted as string, separated by vertical bars |
Sample
while (statement:step() == "ROW") do
local allColumns = statement:getColumnsAsString()
print("The result columns are: " .. allColumns)
endgetColumnText()
Short description
Returns a result column as string value. In case of SQLite, 'sqlite3_column_text()' is called
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
index |
INT |
1 |
Index of the column |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ret |
STRING |
1 |
The value |
Sample
while (statement:step() == "ROW") do
local myString = statement:getColumnText(0)
endgetColumsForLuaTable()
Short description
Retrieves all result columns, converts them to lua table string. This string can be converted to a lua table"
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ret |
STRING |
1 |
All columns are formatted to a table string |
Sample
while (statement:step() == "ROW") do
local tableString = statement:getColumsForLuaTable()
print("The result columns are: " .. tableString)
endgetErrorMessage()
Short description
Retrieves error message for the last error of the statement. Calling this function without having an actual error results in a random string. Only meaningful to be called when the last 'bind…()', 'get…()', 'step()' or 'reset()' functions returned either an error code or the boolean 'false' In case of SQLite, the SQLite API 'sqlite3_errstr()' is called or the error string is formatted by the abstraction code in case it is no general SQL error
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
errorMessage |
STRING |
1 |
The last error message |
Sample
errorMessage = statement:getErrorMessage()isColumnNull()
Short description
Checks if a column contains the SQL 'null' value. In case of SQLite, 'sqlite3_column_type()' is called and compared against 'SQLITE_NULL'
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
index |
INT |
1 |
Index of the column |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if column value is NULL, false if not. |
Sample
while (statement:step() == "ROW") do
local isNull = statement:isColumnNull(0)
endreset()
Short description
Resets the statement to its original state and clears all placeholder bindings. Must be called after usage of the statement ('step()' calls) and before re-using the statement. In case SQLite is used, the SQLite API 'sqlite3_reset()' together with 'sqlite3_clear_bindings()' is used.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if statement was reset and is ready for new execution, false if not. |
Sample
statement:bindInt(...) -- bind placeholders (optionally)
statement:step() -- make use of the statement
statement:reset() -- make statement ready for another usagestep()
Short description
Executes the statement, which means applying the place-holder bindings and retrieving a cursor to the first of the result rows. This call is meant to be executed in a while- or repeat-until loop to catch all rows of the result data set. For SQLite, multiple, implementation-defined API functions are called.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The handle of the Statement instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ret |
1 |
Result of executing the statement |
Sample
-- without error handling (simple while loop)
while (statement:step() == "ROW") do
local result1 = statement:getColumnInt(0)
-- retrieve other results...
end
-- with error handling (more complicated but catches more subtle cases):
local stepResult = nil
repeat
stepResult = checkDB:step()
if stepResult == "ROW" then
local result1 = statement:getColumnInt(0)
end
until (stepResult ~= "ROW")
if (stepResult == "ERROR") then
local errorString = statement:getErrorMessage()
print("An error has occurred while retrieving results: " .. errorString)
endDateTime
Short description
Provides functions to get date and time, as well as conversion routines. Read more…
Overview
Detailed description
The object only has a valid time, if the device supports it. Otherwise, time since boot up will be returned.
Functions
calcDayOfWeek()
Short description
Calculates the weekday in the current time zone, as integer (Sunday=0, Monday=1, Tuesday=2, …, Saturday=6).
Detailed description
The returned value can be used as a key for a table, mapping the values to strings, if desired (see the example). The return value is a number, because of different country-specific requirements: In some countries, Sunday is the first day of the week, in some others Monday is. Also, the names of the days may differ. The convention Sunday=0, Monday=1 is derived from the standard C library-convention of weekday numbers. For invalid Unix time input, the function returns nil.
Sample
The following example creates two arrays that map English and German weekdays to returned integer numbers:
local dayStrEnglish = {} -- English day names
dayStrEnglish[0] = "Sun"
dayStrEnglish[1] = "Mon"
dayStrEnglish[2] = "Tue"
dayStrEnglish[3] = "Wed"
dayStrEnglish[4] = "Thu"
dayStrEnglish[5] = "Fri"
dayStrEnglish[6] = "Sat"
local dayStrGerman = {} -- German day names
dayStrGerman[0] = "So"
dayStrGerman[1] = "Mo"
dayStrGerman[2] = "Di"
dayStrGerman[3] = "Mi"
dayStrGerman[4] = "Do"
dayStrGerman[5] = "Fr"
dayStrGerman[6] = "Sa"
local currentDayAsNumber = DateTime.calcDayOfWeek(DateTime.getUnixTime())
local currentDayInEnglish = dayStrEnglish[currentDayAsNumber]
local currentDayInGerman = dayStrGerman[currentDayAsNumber]Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
unixUTCTime |
INT |
1 |
Total of seconds since the Unix Epoch on January 1st, 1970 in UTC (Coordinated Universal Time). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dayNr |
INT |
? |
Number of the current weekday or nil, in case of invalid input. |
Sample (auto-generated)
dayNr = DateTime.calcDayOfWeek(unixUTCTime)calcLocalFromUTC()
| This API is deprecated |
Short description
Converts Unix time to local time and generates a string, similar to getDateTime(). This function is deprecated, please use formatUnixTime() instead.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
unixUTCTime |
INT |
1 |
Total of seconds since the Unix Epoch on January 1st, 1970 in UTC (Coordinated Universal Time). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dateTime |
STRING |
? |
Format: "Jan..Dec dd yyyy hh:mm:ss" or nil, for invalid Unix time input. |
Sample (auto-generated)
dateTime = DateTime.calcLocalFromUTC(unixUTCTime)convertTimestamp()
Short description
Returns the individual parts (day, month, year, hour, minute, second, millisecond) of the time, which is calculated from the input timestamp since bootup, in milliseconds.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timestamp |
INT |
1 |
Input timestamp. |
asUTC |
BOOL |
? |
True, to return UTC. False, to convert to local time. Default: false |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
day |
INT |
1 |
Day |
month |
INT |
1 |
Month |
year |
INT |
1 |
Year |
hour |
INT |
1 |
Hour |
minute |
INT |
1 |
Minute |
second |
INT |
1 |
Second |
millisecond |
INT |
1 |
Millisecond |
Sample (auto-generated)
day, month, year, hour, minute, second, millisecond = DateTime.convertTimestamp(timestamp, asUTC)convertUnixTime()
Short description
Returns the individual components (day, month, year, hour, minute, second) of an input in Unix time format.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
unixTime |
INT |
1 |
Unix time. |
asUTC |
BOOL |
? |
True, to return UTC. False, to convert to local time. Default: false |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
day |
INT |
1 |
Day |
month |
INT |
1 |
Month |
year |
INT |
1 |
Year |
hour |
INT |
1 |
Hour |
minute |
INT |
1 |
Minute |
second |
INT |
1 |
Second |
Sample (auto-generated)
day, month, year, hour, minute, second = DateTime.convertUnixTime(unixTime, asUTC)create()
Short description
Returns the current date and time as DateTime object, which can be serialized and used as input parameter for other functions.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dateTime |
1 |
Current date and time, as DateTime object. |
Sample (auto-generated)
dateTime = DateTime.create()createFromTimestamp()
Short description
Returns the DateTime object, according to the input timestamp, in milliseconds since bootup.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timestamp |
INT |
1 |
Input timestamp. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dateTime |
1 |
DateTime object, according to the input timestamp. |
Sample (auto-generated)
dateTime = DateTime.createFromTimestamp(timestamp)createFromUnixTime()
Short description
Returns the DateTime object, according to Unix time (number of seconds since the Unix Epoch on January 1st, 1970, in UTC). Milliseconds are set to 0.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
unixTime |
INT |
1 |
Unix time. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dateTime |
1 |
DateTime object, according to Unix time. |
Sample (auto-generated)
dateTime = DateTime.createFromUnixTime(unixTime)formatTimestamp()
Short description
Generates a string, similar to getDateTime(), for the time that is calculated from the input timestamp since bootup, in milliseconds.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timestamp |
INT |
1 |
Input timestamp. |
asUTC |
BOOL |
? |
True, to return UTC. False, to convert to local time. Default: false |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dateTime |
STRING |
? |
Format: "Jan..Dec dd yyyy hh:mm:ss.msecs", or nil for invalid timestamp input. |
Sample (auto-generated)
dateTime = DateTime.formatTimestamp(timestamp, asUTC)formatUnixTime()
Short description
Generates a string for the input Unix time, similar to getDateTime().
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
unixTime |
INT |
1 |
Total of seconds since the Unix Epoch on January 1st, 1970 in UTC (Coordinated Universal Time). |
asUTC |
BOOL |
? |
True, to return UTC. False, to convert to local time. Default: false |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dateTime |
STRING |
? |
Format: "Jan..Dec dd yyyy hh:mm:ss" or nil, for invalid Unix time input. |
Sample (auto-generated)
dateTime = DateTime.formatUnixTime(unixTime, asUTC)getDate()
Short description
Returns the current date, in format "Jan..Dec dd yyyy".
Detailed description
The function only provides a valid date, if the device supports it. Otherwise, date is provided since boot up.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
date |
STRING |
1 |
Format: "Jan..Dec dd yyyy". |
Sample (auto-generated)
date = DateTime.getDate()getDateTime()
Short description
Returns the current date, plus the time in format "Jan..Dec dd yyyy hh:mm:ss.msecs".
Detailed description
The result of the function is identical to concatenating the strings returned by getDate() and getTime() with a space delimiter between. Otherwise, calling getDateTime() is atomic and therefore also works, when date/time overflows. This may be important because two calls to getDate and getTime are not guaranteed to fit together, because some time could pass by between the calls.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
datetime |
STRING |
1 |
Format: "Jan..Dec dd yyyy hh:mm:ss.msecs". |
Sample (auto-generated)
datetime = DateTime.getDateTime()getDateTimeValuesLocal()
Short description
Returns the individual components (day, month, year, hour, minute, second, millisecond) of the system time, in local time format.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
day |
INT |
1 |
Day |
month |
INT |
1 |
Month |
year |
INT |
1 |
Year |
hour |
INT |
1 |
Hour |
minute |
INT |
1 |
Minute |
second |
INT |
1 |
Second |
millisecond |
INT |
1 |
Millisecond |
Sample (auto-generated)
day, month, year, hour, minute, second, millisecond = DateTime.getDateTimeValuesLocal()getDateTimeValuesUTC()
Short description
Returns the individual components (day, month, year, hour, minute, second, millisecond) of the system time, in UTC (Coordinated Universal Time).
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
day |
INT |
1 |
Day |
month |
INT |
1 |
Month |
year |
INT |
1 |
Year |
hour |
INT |
1 |
Hour |
minute |
INT |
1 |
Minute |
second |
INT |
1 |
Second |
millisecond |
INT |
1 |
Millisecond |
Sample (auto-generated)
day, month, year, hour, minute, second, millisecond = DateTime.getDateTimeValuesUTC()getTime()
Short description
Returns the current time, in format "hh:mm:ss.msecs".
Detailed description
The function only provides a valid time, if the device supports it. Otherwise, time is provided since boot up.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
time |
STRING |
1 |
Format: "hh:mm:ss.msecs". |
Sample (auto-generated)
time = DateTime.getTime()getTimestamp()
Short description
Returns the system timestamp since bootup, in milliseconds.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timestamp |
INT |
1 |
Timestamp, in milliseconds. |
Sample (auto-generated)
timestamp = DateTime.getTimestamp()getTimestampMicroseconds()
Short description
Returns the system timestamp since bootup, in microseconds.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timestamp |
INT |
1 |
Timestamp, in microseconds. |
Sample (auto-generated)
timestamp = DateTime.getTimestampMicroseconds()getTimestampOfContextMicroseconds()
Short description
Returns the processing timestamp of the current app-context, in microseconds.
Detailed description
This timestamp only increases if the current app-context performs processing. Therefore, the timestamp can be used to measure the processing time of the current app-context, independent of other apps or system services, which might interrupt the current app-context during processing. The precision of this timestamp depends on the underlying operating system.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timestamp |
INT |
1 |
Timestamp of current app-context, in microseconds. |
Sample (auto-generated)
timestamp = DateTime.getTimestampOfContextMicroseconds()getTimeZone()
Short description
Returns the currently set time zone, in IANA tz database format.
Detailed description
The function queries the underlying operating system for the current time zone and returns the corresponding string. When the time zone is not available, or could not be translated into the IANA format, or is not implemented on the operating system, an empty string will be returned. When using DateTime.setTimeZone(), the returned string of this function may differ from one set before, because the IANA format allows various synonyms for time zones. However, it is assured that the returned string describes a time zone that is a synonym for the last one passed to setTimeZone(), even if it is different. The result may be for example "Europe/Vienna", even when "Europe/Berlin" was passed to setTimeZone(), because both cities are located in the same time zone.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timeZone |
STRING |
1 |
Currently set time zone or an empty string, if getting is not possible. |
utcOffset |
INT |
1 |
Difference, in minutes, from current time zone to UTC. Ranges from -720 to +840. |
Sample (auto-generated)
timeZone, utcOffset = DateTime.getTimeZone()getUnixTime()
Short description
Returns the current time as the total of seconds since the Unix Epoch on January 1st, 1970 in UTC (Coordinated Universal Time).
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
unixtime |
INT |
1 |
Unix time |
Sample (auto-generated)
unixtime = DateTime.getUnixTime()getUnixTimeMilliseconds()
Short description
Returns the current time as the total of milliseconds since the Unix Epoch on January 1st, 1970 in UTC (Coordinated Universal Time).
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
unixtime |
INT |
1 |
Unix time in milliseconds |
Sample (auto-generated)
unixtime = DateTime.getUnixTimeMilliseconds()isTimeSet()
Short description
Returns whether the system time has been set since bootup (by NTP or some other service), so that the getDate()/getTime() functions deliver reliable results.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isSet |
BOOL |
1 |
True, when system date was set at least once since bootup. |
Sample (auto-generated)
isSet = DateTime.isTimeSet()setDateTime()
Short description
Sets the system time in either UTC (Coordinated Universal Time) or in local time.
Detailed description
The system behavior might be affected if changing the time too often, so use with care. It is rather recommended using an NTPClient.
|
Please take care when setting local time (not UTC) to an interval, where daylight saving time changes to non-daylight saving time (mostly in autumn). The results can be undefined (ambiguous values), when setting to that time interval, because the time interval repeats a second time during the transition (for example 2:59:58, 2:59:59, 2:00:00, 2:00:01, …, 2:59:58, 2:59:59, 3:00:00). |
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
year |
INT |
1 |
Year to set, range: 1970..2105 |
month |
INT |
1 |
Month to set, range: 1..12 |
day |
INT |
1 |
Day to set, range: 1..31 |
hour |
INT |
1 |
Hour to set, range: 0..23 |
minute |
INT |
1 |
Minute to set, range: 0..59 |
second |
INT |
1 |
Second to set, range: 0..59 |
asUTC |
BOOL |
? |
True, to set in UTC. False, to set in local time. Default: false |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if time was set successfully. |
Sample (auto-generated)
success = DateTime.setDateTime(year, month, day, hour, minute, second, asUTC)setTimeZone()
Short description
Sets the time zone of the system.
Detailed description
The time zone is encoded in IANA tz database format. A current list can be looked up in the Wikipedia article List of tz database time zones. Time zones do not change the system clock, which always runs in UTC, but they change how dates and times are interpreted in a locally dependent way. The functions getDateTime(), getDate() and getTime() will return different values when the time zone has changed.
|
Time zones are subject to political changes. Therefore, time zones of some countries may change even if that is rather unlikely. Not each operating system supports each time zone. So, always check the return code of this function. If calling the function is not successful, you may need another compatible time zone name, or you will need to update your device’s firmware to fit to new zones. The Windows version of this function uses a mapping provided by the Unicode Consortium (search for "zone tzid table"). Hence, the IANA names can be used universally for each underlying operating system. |
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timeZoneString |
STRING |
1 |
Time zone-string, in IANA tz database format. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if time zone was set successfully. |
Sample (auto-generated)
success = DateTime.setTimeZone(timeZoneString)toString()
Short description
Provides a user-friendly formatted string of a DateTime object (UTC time, according to the ISO 8601 time representation). Example: 1970-01-01T00:00:00.000Z
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dateTime |
1 |
DateTime object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
str |
STRING |
1 |
User-friendly formatting of DateTime object. |
Sample (auto-generated)
str = DateTime.toString(dateTime)EncoderData
Short description
Provides access to encoder data information like increment, local increment, time stamp and speed. Local increment could contain e.g. the value of a high resolution encoder which is connected directly to a sensor.
Overview
Functions
create()
Short description
Creates a new instance of the EncoderData object.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the instance. |
Sample (auto-generated)
handle = EncoderData.create()getIncrement()
Short description
Get the system increment value from the EncoderData object.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
CONST_OBJECT |
1 |
Input data to get the system increment from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
increment |
INT |
1 |
Returns the system increment value. |
Sample (auto-generated)
increment = EncoderData.getIncrement(encoderdata)getLocalIncrement()
Short description
Get the local encoder position value from the EncoderData object. This could be e.g. the value of a high resolution encoder which is connected directly to a sensor.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
CONST_OBJECT |
1 |
Input data to get the encoder position from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
localincrement |
INT |
1 |
Returns the local encoder position value. |
Sample (auto-generated)
localincrement = EncoderData.getLocalIncrement(encoderdata)getSpeed()
Short description
Returns the speed in [m/s] from the EncoderData object.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
CONST_OBJECT |
1 |
Input data to get the speed value from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
speed |
FLOAT |
1 |
Returns the speed value in [m/s]. |
Sample (auto-generated)
speed = EncoderData.getSpeed(encoderdata)getTimestamp()
Short description
Returns the system timestamp since bootup in microseconds.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
CONST_OBJECT |
1 |
Input data to get the time stamp from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timestamp |
INT |
1 |
Returns the time stamp value (in microseconds). |
Sample (auto-generated)
timestamp = EncoderData.getTimestamp(encoderdata)getTimestampUnixTimeMilliseconds()
Short description
Returns timestamp as the total of milliseconds since the Unix Epoch on January 1st, 1970 in UTC (Coordinated Universal Time).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
CONST_OBJECT |
1 |
Handle to the instance. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timestamp |
INT |
1 |
Timestamp as Unix time in milliseconds. |
Sample (auto-generated)
timestamp = EncoderData.getTimestampUnixTimeMilliseconds(encoderdata)setIncrement()
Short description
Sets the system increment value of the EncoderData object.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
OBJECT |
1 |
Input data to get the system increment from. |
increment |
INT |
1 |
System increment value. |
Sample (auto-generated)
EncoderData.setIncrement(encoderdata, increment)setLocalIncrement()
Short description
Sets the local encoder position value of the EncoderData object. This could be e.g. the value of a high resolution encoder which is connected directly to a sensor.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
OBJECT |
1 |
Input data to get the encoder position from. |
localincrement |
INT |
1 |
Local encoder position value. |
Sample (auto-generated)
EncoderData.setLocalIncrement(encoderdata, localincrement)setSpeed()
Short description
Sets the speed in [m/s] of the EncoderData object.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
OBJECT |
1 |
Handle to the instance. |
speed |
FLOAT |
1 |
Speed value in [m/s]. |
Sample (auto-generated)
EncoderData.setSpeed(encoderdata, speed)setTimestamp()
Short description
Sets the system timestamp since bootup in microseconds.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
OBJECT |
1 |
Input data to get the time stamp from. |
timestamp |
INT |
1 |
Time stamp value (in microseconds). |
Sample (auto-generated)
EncoderData.setTimestamp(encoderdata, timestamp)setTimestampUnixTimeMilliseconds()
Short description
Sets timestamp as the total of milliseconds since the Unix Epoch on January 1st, 1970 in UTC (Coordinated Universal Time).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
OBJECT |
1 |
Handle to the instance. |
timestamp |
INT |
1 |
Timestamp as Unix time in milliseconds. |
Sample (auto-generated)
EncoderData.setTimestampUnixTimeMilliseconds(encoderdata, timestamp)toString()
Short description
Get a string representation of the EncoderData.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
encoderdata |
CONST_OBJECT |
1 |
Input data to get the origin from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
str |
STRING |
1 |
String representation of the EncoderData |
Sample (auto-generated)
str = EncoderData.toString(encoderdata)Engine
Short description
Provides functionality to control the AppEngine of the device and use the AppEngine framework.
Overview
Functions
checkForAllServed()
Short description
Checks if all APIs in the device manifest are served and lists the not served ones in a warning log.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
allServed |
BOOL |
1 |
Returns true if all APIs are served. False if there is one or more APIs which are not served. |
Sample (auto-generated)
allServed = Engine.checkForAllServed()getAppInfo()
Short description
Returns additional information about a specific app.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
appName |
STRING |
1 |
The name of the app |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
appInfo |
OBJECT |
? |
Object containing additional information about the app |
Sample (auto-generated)
appInfo = Engine.getAppInfo(appName)getAppPosition()
Short description
Returns the position of specific app.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
appName |
STRING |
1 |
The name of the app |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
? |
The name of the file |
lineNumber |
INT |
? |
Return the line number |
Sample (auto-generated)
fileName, lineNumber = Engine.getAppPosition(appName)getCrownAsXML()
Short description
Returns the manifest xml snippet of the specified CROWN as xml string. Sub-CROWNs are NOT included. Output string starts and ends with the "crown" xml tag. The name of the crown is only the sub-crown name and NOT the full qualified crown name. E.g. requested crown name is "NameA.NameB.NameC", output xml crown name is only "NameC".
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
crownName |
STRING |
1 |
The full CROWN name to return the manifest |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
manifestXml |
STRING |
? |
The manifest xml snippet of the CROWN or nil if CROWN does not exist |
Sample (auto-generated)
manifestXml = Engine.getCrownAsXML(crownName)getCrowns()
Short description
Returns the list of all crowns which are available in the engine as vector sorted alphabetically. The domain filter like 'ctrl-flow' can be specified, to only return CROWNs which are relevant for the specified domain. The CROWN can also be relevant if there is just one function or event specified as include. Available domain filters: - ctrl-flow - data-flow - script - remote - java
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
domainFilter |
STRING |
? |
If specified, only returns the crowns which have an include specified to the domain like 'ctrl-flow' and no exclude is defined to it. See manifest scheme for all available include-domains. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
crownVector |
STRING |
+ |
The sorted vector for all full-qualified crown names |
Sample (auto-generated)
crownVector = Engine.getCrowns(domainFilter)getCurrentAppName()
Short description
Get the name of the app from which this function is called.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
name |
STRING |
? |
The name of the app or nil if app context is not available. |
Sample (auto-generated)
name = Engine.getCurrentAppName()getCurrentAppVersion()
Short description
Get the version of the app from which this function is called.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
version |
STRING |
? |
The version of the app or nil if app context is not available. |
Sample (auto-generated)
version = Engine.getCurrentAppVersion()getEnumValues()
Short description
Returns all enum values of an enum defined in the manifest as a vector sorted alphabetically.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enumName |
STRING |
1 |
The full CROWN enum name to return its values |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enumVals |
STRING |
* |
The sorted vector of enum values or nil if enum does not exist |
Sample
local enumValTable = Engine.getEnumValues("Log.Level")getFirmwareVersion()
Short description
Returns the device firmware version of this AppEngine device. This version is useful for a unique identification of the device firmware and its capabilities like AppEngine services and APIs.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
firmwareVersion |
STRING |
1 |
The device firmware version of this engine |
Sample (auto-generated)
firmwareVersion = Engine.getFirmwareVersion()getPartNumber()
Short description
Returns the device part number of this engine.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
partNumber |
STRING |
1 |
The device part number of this engine |
Sample (auto-generated)
partNumber = Engine.getPartNumber()getProductID()
Short description
Returns the product ID of this engine. The product ID has the form of an URI that can be used to retrieve information about the device, following DIN SPEC 91406 and IEC 61406.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
productID |
STRING |
1 |
The product ID of this engine |
Sample (auto-generated)
productID = Engine.getProductID()getSerialNumber()
Short description
Returns the device serial number of this engine as string.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
serialNumber |
STRING |
1 |
The device serial number of this engine as string |
Sample (auto-generated)
serialNumber = Engine.getSerialNumber()getTypeCode()
Short description
Returns the device type code of this engine.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
typeCode |
STRING |
1 |
The device type code of this engine |
Sample (auto-generated)
typeCode = Engine.getTypeCode()getTypeName()
Short description
Returns the device type name of this engine.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
typeName |
STRING |
1 |
The device type name of this engine |
Sample (auto-generated)
typeName = Engine.getTypeName()getVersion()
Short description
Returns the AppEngine version of this device. This version is useful to identify the possibilities of the underlying device programmable services like app services, webserver etc. This version can NOT be used to get to know which APIs in which version are on the device. For the concrete device, AppEngine services and API versions, the Engine.getFirmwareVersion needs to be used.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
engineVersion |
STRING |
1 |
The AppEngine version of this device |
Sample (auto-generated)
engineVersion = Engine.getVersion()isEmulator()
Short description
This function return true if the current engine is just an emulator engine and not a real device.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isEmulator |
BOOL |
1 |
True if the current device is an emulator |
Sample (auto-generated)
isEmulator = Engine.isEmulator()listApps()
Short description
Returns the names of all apps currently in the engine.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
appList |
STRING |
+ |
List of app names |
Sample (auto-generated)
appList = Engine.listApps()reboot()
Short description
Reboots the device over power cycle directly. Function will NOT return on target hardware. On the emulator the function always returns and logs a warning that reboot is not possible on emulator. This function can only be used after the "Engine.OnStarted" event has been notified to prevent endless reboot loops in global scope. Before the event the function call is ignored. During the first 30 seconds after the "Engine.OnStarted" event, the reboot action keeps pending, so that an endless reboot loop is prevented. Every 5 seconds there is a log that a reboot is pending, so that the app developer has time to connect and stop the apps.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
reason |
STRING |
? |
Optional string describing the reason for reboot |
Sample (auto-generated)
Engine.reboot(reason)reloadApps()
Short description
Reloads all applications of the AppEngine. Function will not return on target hardware and directly reloads. On the emulator the function may return. This function can be used to reset all applications and start them again like if rebooting but without full powercycle. This function can only be used after the "Engine.OnStarted" event has been notified to prevent endless reload loops in global scope.
Sample (auto-generated)
Engine.reloadApps()Events
OnStarted
Short description
Startup event of the application which is notified once after startup after all apps have been fully loaded. This should be used by apps which are dependent on other apps to make sure that everything is fully loaded. The event is also notified if the apps are reloaded externally or over the Engine.reloadApps function.
Sample (auto-generated)
function handleOnStarted()
-- Do something
end
Script.register("Engine.OnStarted", "handleOnStarted")Engine.AppInfo
Short description
Provides API to access the information of an app.
Overview
Functions
getName()
Short description
Getter for the name of the app
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
appInfoObject |
CONST_OBJECT |
1 |
Object instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
name |
STRING |
1 |
The name of the app. |
Sample (auto-generated)
name = Engine.AppInfo.getName(appInfoObject)getPriority()
Short description
Reporting the priority level of the app
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
appInfoObject |
CONST_OBJECT |
1 |
Object instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
priority |
ENUM |
1 |
The priority of the app. |
Sample (auto-generated)
priority = Engine.AppInfo.getPriority(appInfoObject)getVersion()
Short description
Getter for the version of the app
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
appInfoObject |
CONST_OBJECT |
1 |
Object instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
version |
STRING |
1 |
The version of the app. |
Sample (auto-generated)
version = Engine.AppInfo.getVersion(appInfoObject)hasPages()
Short description
Report if an app has a "pages" app component (web-based user interface).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
appInfoObject |
CONST_OBJECT |
1 |
Object instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hasPages |
BOOL |
1 |
Indicate if an app has pages or not. |
Sample (auto-generated)
hasPages = Engine.AppInfo.hasPages(appInfoObject)Engine.AsyncFunction
Short description
Executes a CROWN function call in an underlying separate thread. Please note that this does not work for Lua based functions, have a look into the "Script.startScript" documentation for this use case. There is one thread per AsyncFunction instance. Multiple launches on an AsyncFunction instance are queued up and executed after each other. This is useful to execute functions in parallel to better benefit from multiple cores available on the target hardware. Every function launch returns a Future-handle which identifies the function call. The results can be retrieved by calling the blocking function "wait" on the Future-handle or by registering to the event "OnFinished" to retrieve the function results asynchronously.
See also
Functions
create()
Short description
Creates a new instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the new instance |
Sample
-- Create a simple async function call to a handle-based function and wait for its result:
asyncHandle = Engine.AsyncFunction.create()
asyncHandle:setFunction("Algo.function", algoHandle)
futureHandle = asyncHandle:launch(p1, p2, p3)
r1, r2, r3 = futureHandle:wait()deregister()
Short description
This function is used to deregister from any registered event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to deregister from |
callback |
STRING |
1 |
The function name which was registered on the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
Sample (auto-generated)
success = Engine.AsyncFunction.deregister(handle, eventname, callback)launch()
Short description
Starts a new call on the async handle with the specified parameters. This function directly returns a handle to an Engine.AsyncFunction.Future instance. Use this Future instance to wait for the function to be completed and get their result. Alternatively register to the "OnFinished" event to get the future objects notified there for each completed call. Multiple calls can be spawned at once. They are executed after each other.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
param1 |
AUTO |
[?*] |
First parameter for the async function call (optional) |
param2 |
AUTO |
[?*] |
Second parameter for the async function call (optional) |
param3 |
AUTO |
[?*] |
Third parameter for the async function call (optional) |
param4 |
AUTO |
[?*] |
Fourth parameter for the async function call (optional) |
param5 |
AUTO |
[?*] |
Fifth parameter for the async function call (optional) |
param6 |
AUTO |
[?*] |
Sixth parameter for the async function call (optional) |
param7 |
AUTO |
[?*] |
Seventh parameter for the async function call (optional) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
futureHandle |
HANDLE |
? |
The future handle to wait for the result of the async function call. Can be nil if there was an internal error while launching the function call or no function was set. |
Sample (auto-generated)
futureHandle = Engine.AsyncFunction.launch(handle, param1, param2, param3, param4, param5, param6, param7)register()
Short description
This function is used to register for any event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to register to |
callback |
STRING |
1 |
The function name to call on the event occurrence |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if event does not exist. |
Sample (auto-generated)
success = Engine.AsyncFunction.register(handle, eventname, callback)setFunction()
Short description
Sets the target CROWN function name to call in the async function call execution. If the CROWN function is handle based, the handle can be passed as second parameter to this function, so that it is automatically set as first parameter for every function call. The handle is held as long as the AsyncFunction exists.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
functionName |
STRING |
1 |
The function name which is called by this async function instance |
functionHandle |
HANDLE |
? |
The optional handle which is automatically set as first parameter to every function call. The handle is held as long as the AsyncFunction exists. |
Sample
-- Static function:
Engine.AsyncFunction.setFunction(handle, "Algo.function")
-- Handle based function:
Engine.AsyncFunction.setFunction(handle, "Algo.function", algoHandle)setPriority()
Short description
Sets the priority of the task running the async function. This function is only callable before calling the "launch" function for the first time. If not explicitly set, the priority of the script that calls the function is used. In case of the app main script, this is the app priority.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
priority |
1 |
Priority of the task running the async function |
Sample (auto-generated)
Engine.AsyncFunction.setPriority(handle, priority)Events
OnFinished
Short description
This event is triggered on every function async call completion. The future handle is passed as parameter to get the function result. This is useful to receive the function results asynchronously instead of using the blocking Future.wait function.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
futureHandle |
HANDLE |
1 |
The future object identifying the function call |
Sample (auto-generated)
function handleOnFinished(futureHandle)
-- Do something
end
Engine.AsyncFunction.register(handle, "OnFinished", "handleOnFinished")Engine.AsyncFunction.Future
Short description
Is returned by the Engine.AsyncFunction.launch function to control the async function execution like to wait for the result. To cancel a queued up function execution, call the abandon function.
Overview
Functions
abandon()
Short description
Throws the async function execution and its result away. If the function execution is still queued, it will not be executed. If it is currently already running, the result of it will be abandoned.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Sample (auto-generated)
Engine.AsyncFunction.Future.abandon(handle)isFailed()
Short description
If the function call is finished, this function can be used to check, if there was an error calling the function asynchronously. A fail might happen, if the function to be called was not valid (not served) or the function parameters/return values were not correct.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isFailed |
BOOL |
1 |
True if the function execution was failed. False if called successfully or not finished. |
Sample (auto-generated)
isFailed = Engine.AsyncFunction.Future.isFailed(handle)isFinished()
Short description
Can be used to poll if the async function execution is finished.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isFinished |
BOOL |
1 |
True if the function execution is finished. False if not. |
Sample (auto-generated)
isFinished = Engine.AsyncFunction.Future.isFinished(handle)wait()
Short description
Blocks and waits until the corresponding async function call finishes with optional timeout. Returns the result values of the function which was called asynchronously.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
timeoutMs |
INT |
? |
The time in ms to wait for the function call to finish |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result1 |
AUTO |
[?*] |
First result of the async function call (optional) |
result2 |
AUTO |
[?*] |
Second result of the async function call (optional) |
result3 |
AUTO |
[?*] |
Third result of the async function call (optional) |
result4 |
AUTO |
[?*] |
Fourth result of the async function call (optional) |
result5 |
AUTO |
[?*] |
Fifth result of the async function call (optional) |
result6 |
AUTO |
[?*] |
Sixth result of the async function call (optional) |
result7 |
AUTO |
[?*] |
Seventh result of the async function call (optional) |
Sample (auto-generated)
result1, result2, result3, result4, result5, result6, result7 = Engine.AsyncFunction.Future.wait(handle, timeoutMs)Engine.Event
Short description
This is a generic block to map to an flow input or output event. It can register to events so that it can be used as input block, or it can notify an event so that it can be used as output block. It supports level and dirac signals.
Overview
Functions
create()
Short description
Creates a new instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the new instance |
Sample (auto-generated)
handle = Engine.Event.create()notify()
Short description
Notifies the specified event name. The event has to be added by the user to the manifest.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
|
signal |
BOOL |
1 |
The level/Dirac signal which triggers the event notify. |
Sample (auto-generated)
Engine.Event.notify(handle, signal)setEventName()
Short description
Name of the event to which the block registers to (OnEvent-event) or which the block notifies (notify-function). The event has to exist in the manifest in both cases. If it is a level-based event, it must have one bool parameter declared in the manifest. If it is a dirac-based event, it must have no parameter declared in the manifest.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
|
eventName |
STRING |
1 |
Sample (auto-generated)
Engine.Event.setEventName(handle, eventName)Events
OnEvent
Short description
Register to the specified event name and provides its occurrences as signal. If the event has no bool parameter, it is a dirac event. if the event has a bool parameter, it is a level event.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
signal |
BOOL |
1 |
The level/Dirac signal which is triggered by every event occurrence. If registered event has a bool parameter, the value is provided as level. |
Sample (auto-generated)
function handleOnEvent(signal)
-- Do something
end
Engine.Event.register(handle, "OnEvent", "handleOnEvent")Engine.EventBinding
Short description
Serves a new event and allows binding to an existing event including mapping the parameters to the new event notify. This is useful e.g. to bind handle based events to a static events and allow registration to them from a Flow block, but still configure it conveniently from a script.
Functions
bindParameters()
Short description
Adds parameter binding definitions. Could be called several times and adds them to the already bound ones. If not called at all, the parameters are directly mapped. The binding is specified from the registered event to the binding served event. A binding definition could be a position info or any other fix value. A position binding definition is done as string with a "$" as prefix like "$1". A position binding definition could be also the manifest parameter name of the served event. A fix value binding could be any CROWN type. If it should be a string starting with "$", then the first $ needs to be escaped to don’t be interpreted as position binding.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
binding1 |
AUTO |
[1+] |
One binding definition |
binding2 |
AUTO |
[?*] |
Second binding definition (optional) |
binding3 |
AUTO |
[?*] |
Third binding definition (optional) |
binding4 |
AUTO |
[?*] |
Fourth binding definition (optional) |
binding5 |
AUTO |
[?*] |
Fifth binding definition (optional) |
binding6 |
AUTO |
[?*] |
Sixth binding definition (optional) |
binding7 |
AUTO |
[?*] |
Seventh binding definition (optional) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if binding was correctly specified and is added |
Sample
-- Maps to the target event:
-- second parameter of the event notify as first parameter
-- first parameter of the event notify as second parameter
-- integer value "1" as third parameter
-- content of Lua variable "obj"
-- boolean value "true"
Engine.EventBinding.bindParameters(handle, "$2", "$1", 1, obj, true)clearParameterBindings()
Short description
Clears all before added parameter binding definitions which were added using the bindParameters function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Sample (auto-generated)
Engine.EventBinding.clearParameterBindings(handle)create()
Short description
Creates a new instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the new instance |
Sample
-- Create a simple binding to a handle-based event binding:
handle = Engine.EventBinding.create()
handle:setEvent("Provider.OnSomeEvent", providerHandle) -- The providerHandle is the handle to the sample provider "Provider.OnSomeEvent"
-- Serve the new event. After that the event is directly active and will be notified if the bound event is notified:
handle:serve("MyCrown.OnMyEvent")getNotifyFunction()
Short description
Returns the function name which is served and can be called to trigger manually a notify on the served event. This function name is also used internally to register at the bound event. Might be useful to trigger event notifies manually.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
servedFunction |
STRING |
? |
The function name of the function to notify the event. |
Sample (auto-generated)
servedFunction = Engine.EventBinding.getNotifyFunction(handle)serve()
Short description
Serves a new event with the binding and returns true if successfully served. After this call the event can be registered by others and might get directly notified. If a event name is specified, the event must be available in the manifest. If no event name is specified, it generates an unique one and returns it. This is useful to directly bind a event notify without having it in the manifest.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
serveEventName |
STRING |
? |
The event name including the crown name which should be served by this binding |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successfully served. False if already served by someone else |
genServedEventName |
STRING |
? |
If no event name was specified as parameter, a generated unique one is returned |
Sample (auto-generated)
success, genServedEventName = Engine.EventBinding.serve(handle, serveEventName)setEvent()
Short description
Sets the bound event name to register to. If the event is handle based, the handle can be passed as second parameter to this function, so that the binding is done on the event on that handle. If a handle is set, the bindParameters function operates only on the event parameters after the handle. The handle is held as long as the EventBinding exists.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
eventName |
STRING |
1 |
The event name which is used for registration |
eventHandle |
HANDLE |
? |
The optional handle on which the event should be registered. The handle is held as long as the EventBinding exists. |
Sample
-- Static event:
Engine.EventBinding.setEvent(handle, "Provider.OnEvent")
-- Handle based event:
Engine.EventBinding.setEvent(handle, "Provider.OnEvent", providerHandle)Engine.FunctionBinding
Short description
Serves a new function and allows binding to an existing function including mapping the parameters and results to the target function call. This is useful e.g. to bind handle based function to a static function and allow calling them from a Flow block, but still configure it conveniently from a script.
Overview
Functions
bindParameters()
Short description
Adds parameter binding definitions. Could be called several times and adds them to the already bound ones. If not called at all, the parameters are directly mapped. The binding is specified from the binding served function to the target function. A binding definition could be a position info or any other fix value. A position binding definition is done as string with a "$" as prefix like "$1". A position binding definition could be also the manifest parameter name of the served function. A fix value binding could be any CROWN type. If it should be a string starting with "$", then the first $ needs to be escaped to don’t be interpreted as position binding.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
binding1 |
AUTO |
[1+] |
One binding definition |
binding2 |
AUTO |
[?*] |
second binding definition (optional) |
binding3 |
AUTO |
[?*] |
third binding definition (optional) |
binding4 |
AUTO |
[?*] |
fourth binding definition (optional) |
binding5 |
AUTO |
[?*] |
fifth binding definition (optional) |
binding6 |
AUTO |
[?*] |
sixth binding definition (optional) |
binding7 |
AUTO |
[?*] |
seventh binding definition (optional) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if binding was correctly specified and is added |
Sample
-- Maps to the target function:
-- second parameter of the function call as first parameter
-- first parameter of the function call as second parameter
-- integer value "1" as third parameter
-- content of Lua variable "obj"
-- boolean value "true"
Engine.FunctionBinding.bindParameters(handle, "$2", "$1", 1, obj, true)bindResults()
Short description
Adds result binding definitions. Could be called several times and adds them to the already bound ones. If not called at all, the parameters are directly mapped. The binding is specified from the target function to the binding served function. A binding definition could be a position info or any other fix value. A position binding definition is done as string with a "$" as prefix like "$1". A position binding definition could be also the manifest result name of the target function. A fix value binding could be any CROWN type. If it should be a string starting with "$", then the first $ needs to be escaped to don’t be interpreted as position binding.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
binding1 |
AUTO |
[1+] |
One binding definition |
binding2 |
AUTO |
[?*] |
Second binding definition (optional) |
binding3 |
AUTO |
[?*] |
Third binding definition (optional) |
binding4 |
AUTO |
[?*] |
Fourth binding definition (optional) |
binding5 |
AUTO |
[?*] |
Fifth binding definition (optional) |
binding6 |
AUTO |
[?*] |
Sixth binding definition (optional) |
binding7 |
AUTO |
[?*] |
Seventh binding definition (optional) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if binding was correctly specified and is added |
Sample
Engine.FunctionBinding.bindResults(handle, "$2", "$1", 1, obj, true)clearParameterBindings()
Short description
Clears all before added parameter binding definitions which were added using the bindParameters function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Sample (auto-generated)
Engine.FunctionBinding.clearParameterBindings(handle)clearResultBindings()
Short description
Clears all previously added result binding definitions which were added using the bindResults function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Sample (auto-generated)
Engine.FunctionBinding.clearResultBindings(handle)create()
Short description
Creates a new instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the new instance |
Sample
-- Create a simple binding to a handle-based function binding and register it at a provider:
handle = Engine.FunctionBinding.create()
handle:setFunction("Algo.process", algoHandle) -- The algoHandle is the handle to the sample function "Algo.process"
success, genServedFuncName = handle:serve()
-- register the handle function at a provider:
SomeProvider.register(provHandle, "OnSomeEvent", genServedFuncName)lock()
Short description
Locks all further function calls and makes them return instead of calling the target function. This is useful e.g. to reconfigure handle which is bound to the function call. Attention: Take care to keep the locking time as short as possible.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Sample (auto-generated)
Engine.FunctionBinding.lock(handle)serve()
Short description
Serves a new function with the binding and returns true if successfully served. After this call the function can be called by others. If a function name is specified, the function must be available in the manifest. If no function name is specified, it generates an unique one and returns it. This is useful to directly bind a function call without having it in the manifest.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
serveFuncName |
STRING |
? |
The function name including the crown name which should be served by this binding |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successfully served. False if already served by someone else |
genServedFuncName |
STRING |
? |
If no function name was specified as parameter, a generated unique one is returned |
Sample (auto-generated)
success, genServedFuncName = Engine.FunctionBinding.serve(handle, serveFuncName)setFunction()
Short description
Sets the target function name to call. If the function is handle based, the handle can be passed as second parameter to this function, so that it is automatically set as first parameter for every function call. If a handle is set, the bindParameters function operates only on the function parameters after the handle, so the handle is implicitly added every time. The handle is held as long as the FunctionBinding exists.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
functionName |
STRING |
1 |
The function name which is called by this binding |
functionHandle |
HANDLE |
? |
The optional handle which is automatically set as first parameter to every function call. The handle is held as long as the FunctionBinding exists. |
Sample
-- Static function:
Engine.FunctionBinding.setFunction(handle, "Algo.function")
-- Handle based function:
Engine.FunctionBinding.setFunction(handle, "Algo.function", algoHandle)unlock()
Short description
Sets the target function to call.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Sample (auto-generated)
Engine.FunctionBinding.unlock(handle)Engine.SyncEvent
Short description
Registers for the specified event and queues up all event occurrences. The user can synchronously wait for the event occurrence and their event parameters. There is an internal queue used which queues all events up. This is useful if the user needs to get the status of an event at a specified position during processing.
Overview
Functions
clear()
Short description
Clears all currently queued events. Pay attention that directly during returning from this function there might be events already added again.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Sample (auto-generated)
Engine.SyncEvent.clear(handle)close()
Short description
Closes the internal queue and removes the registrations on the event. All currently queued events are discarded.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Sample (auto-generated)
Engine.SyncEvent.close(handle)create()
Short description
Creates a new instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the new instance |
Sample
-- Create a simple sync event and wait for it
handle = Engine.SyncEvent.create()
handle:setEvent("Provider.OnEvent", provHandle)
handle:open()
r1, r2, r3 = handle:wait()getSize()
Short description
Returns the current number of queued calls. Pay attention that directly during returning from this function there might be events already added again.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
queueSize |
INT |
1 |
The current number of queues which are queued in the internal queue |
Sample (auto-generated)
queueSize = Engine.SyncEvent.getSize(handle)open()
Short description
Opens the internal queue by registering for the event which was set before. If no event was set, the returned function name can be used to register to events or throw notifications manually with that function. After this call, the events are received and queued internally.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if successfully registered and opened. False, if e.g. the event handle was not valid and registering was not possible or the event name was not valid. |
enqueueFunctionName |
STRING |
? |
If successfully opened, the function name is returned here to manually enqueue to the event queue or register at further events. |
Sample (auto-generated)
success, enqueueFunctionName = Engine.SyncEvent.open(handle)poll()
Short description
Polls and returns the event parameters if there is already an event queued. Returns nothing if there was no event queued. Since a successful call returning no parameters can not be distinguished from an unsuccessful call, the getSize() function may be used before calling this function to check if there is an event queued.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result1 |
AUTO |
[?*] |
First result of the async function call (optional) |
result2 |
AUTO |
[?*] |
Second result of the async function call (optional) |
result3 |
AUTO |
[?*] |
Third result of the async function call (optional) |
result4 |
AUTO |
[?*] |
Fourth result of the async function call (optional) |
result5 |
AUTO |
[?*] |
Fifth result of the async function call (optional) |
result6 |
AUTO |
[?*] |
Sixth result of the async function call (optional) |
result7 |
AUTO |
[?*] |
Seventh result of the async function call (optional) |
Sample (auto-generated)
result1, result2, result3, result4, result5, result6, result7 = Engine.SyncEvent.poll(handle)setDiscardIfFull()
Short description
Sets the behaviour for adding events to the queue if the queue is full. Per default the oldest element is discarded. To discard the newest to be added element, call this function with parameter true.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
bDiscardIfFull |
BOOL |
1 |
Set to true to discard the newest item which is currently added instead of discarding the oldest element |
Sample (auto-generated)
Engine.SyncEvent.setDiscardIfFull(handle, bDiscardIfFull)setEvent()
Short description
Sets the event name to register to. If the event is handle based, the handle can be passed as second parameter to this function, so that the event is registered at the handle. The handle is held as long as the SyncEvent exists. This function is also optional. If not called, the user can directly use the open function and use the returned function name to manually enqueue to the queue or register manually at events.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
eventName |
STRING |
1 |
The event name which is used for registration |
eventHandle |
HANDLE |
? |
The optional handle on which the event should be registered. The handle is held as long as the SyncEvent exists. |
Sample
-- Static event:
Engine.SyncEvent.setEvent(handle, "Provider.OnEvent")
-- Handle based event:
Engine.SyncEvent.setEvent(handle, "Provider.OnEvent", providerHandle)setMaxQueueSize()
Short description
Sets the maximum queue size of the internal event queue. Per default the queue is set to infinite size (=0). If the max queue size is reached, the oldest element is discarded per default. To change that behaviour use the setDiscardIfFull-Function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
maxQueueSize |
INT |
1 |
The max number of events to queue. Per default 0 (=infinite) |
Sample (auto-generated)
Engine.SyncEvent.setMaxQueueSize(handle, maxQueueSize)wait()
Short description
Blocks and waits until there is an event in the queue with optional timeout. Returns the parameter values of the event which was called received. If there is already an event queued, this function directly returns. To distinguish between a successfull call returning nothing and a timeout, the waitWasTimeout() function can be used.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
timeoutMs |
INT |
? |
The time in ms to wait for the function call to finish. If this is not set or 0, the function call will wait forver. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result1 |
AUTO |
[?*] |
First result of the async function call (optional) |
result2 |
AUTO |
[?*] |
Second result of the async function call (optional) |
result3 |
AUTO |
[?*] |
Third result of the async function call (optional) |
result4 |
AUTO |
[?*] |
Fourth result of the async function call (optional) |
result5 |
AUTO |
[?*] |
Fifth result of the async function call (optional) |
result6 |
AUTO |
[?*] |
Sixth result of the async function call (optional) |
result7 |
AUTO |
[?*] |
Seventh result of the async function call (optional) |
Sample (auto-generated)
result1, result2, result3, result4, result5, result6, result7 = Engine.SyncEvent.wait(handle, timeoutMs)waitWasTimeout()
Short description
Returns if the last wait() call finished because of a timeout. This can be used to distinguish between a successfull wait() call returning nothing and a timeout (which also returns nothing).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
wasTimeout |
BOOL |
1 |
True, if the last wait() call returned because of a timeout. False, if the last wait() call was successful or if no wait() call was executed yet. |
Sample (auto-generated)
wasTimeout = Engine.SyncEvent.waitWasTimeout(handle)Engine.WebServer
Short description
Provides functions for managing the engine’s embedded webserver.
Overview
Functions
getCrownEndpointWhitelist()
| This API is deprecated |
Short description
Get the current whitelist of allowed prefixes for calls on the CROWN endpoint of the engine’s embedded webserver..
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
whitelist |
STRING |
[?*] |
The currently active whitelist. |
Sample (auto-generated)
whitelist = Engine.WebServer.getCrownEndpointWhitelist()getPort()
Short description
Returns the used TCP port number.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
port |
INT |
1 |
The port number as integer. |
Sample (auto-generated)
port = Engine.WebServer.getPort()isCrownEndpointEnabled()
Short description
Check whether the CROWN endpoint of the engine’s embedded webserver is enabled.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
True if enabled. |
Sample (auto-generated)
enabled = Engine.WebServer.isCrownEndpointEnabled()isCrownFileEndpointEnabled()
Short description
Check whether the CROWN file endpoint of the engine’s embedded webserver is enabled.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
True if enabled. |
Sample (auto-generated)
enabled = Engine.WebServer.isCrownFileEndpointEnabled()isCrownFileEndpointReadOnly()
Short description
Check whether the CROWN file endpoint of the engine’s embedded webserver is in read only mode.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
readOnly |
BOOL |
1 |
True if read only mode is enabled. |
Sample (auto-generated)
readOnly = Engine.WebServer.isCrownFileEndpointReadOnly()isEnabled()
Short description
Check whether the webserver is enabled.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
True if enabled. |
Sample (auto-generated)
enabled = Engine.WebServer.isEnabled()setCrownEndpointEnabled()
Short description
Enable or disable the CROWN endpoint of the engine’s embedded webserver.
Detailed description
|
Affected HTTP URLs:
Affected WebSocket URLs:
|
|
Not affected URLs:
|
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
True to enable, false to disable. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if setting could be applied successfully. |
Sample (auto-generated)
success = Engine.WebServer.setCrownEndpointEnabled(enabled)setCrownEndpointWhitelist()
| This API is deprecated |
Short description
Set a whitelist of allowed prefixes for requests on the CROWN endpoint of the engine’s embedded webserver.
Detailed description
The entries of the whitelist are considered as string prefixes: If the given full function or event name for a request starts with any of the string prefixes in the whitelist, the request is allowed.
|
Affected HTTP URLs:
Affected WebSocket URLs:
|
|
Not affected HTTP URLs:
Not affected WebSocket URLs:
|
Examples:
-- Allow access to a specific set of CROWNs, functions and events only
Engine.WebServer.setCrownEndpointWhitelist({
"DateTime", -- Allowed all functions and events starting with prefix "DateTime"
"Engine.getVersion",
"MyApp.doSomething"
"MyApp.OnSomeEvent"
})-- Block access to everything by setting an empty whitelist
Engine.WebServer.setCrownEndpointWhitelist({})-- Disable the whitelist, all requests are allowed.
Engine.WebServer.setCrownEndpointWhitelist(nil)|
Calling Engine.WebServer.setCrownEndpointWhitelist() will automatically remove any authorizations previously set with the crown method Engine.WebServer.CrownEndpoint.addAuthorization. |
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
whitelist |
STRING |
[?*] |
List of prefixes. Nil to disable the whitelist and allow all requests. Initial: nil |
Sample (auto-generated)
Engine.WebServer.setCrownEndpointWhitelist(whitelist)setCrownFileEndpointEnabled()
Short description
Enable or disable the CROWN file endpoint of the engine’s embedded webserver.
Detailed description
|
Affected HTTP URLs:
|
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
True to enable, false to disable. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if setting could be applied successfully. |
Sample (auto-generated)
success = Engine.WebServer.setCrownFileEndpointEnabled(enabled)setCrownFileEndpointReadOnly()
Short description
Set CROWN file endpoint of the engine’s embedded webserver to read only mode.
Detailed description
In read only mode, only HTTP GET requests are processed. HTTP PUT requests are rejected.
|
Affected HTTP URLs:
|
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
readOnly |
BOOL |
1 |
True to enable read only mode, false to disable. Initial: false |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if setting could be applied successfully. |
Sample (auto-generated)
success = Engine.WebServer.setCrownFileEndpointReadOnly(readOnly)setEnabled()
Short description
Enable or disable the engine’s embedded webserver. If disabled the device page will not be accessible any more. REST and websocket communication is no longer possible.
Detailed description
|
This function does not affect the ports that are provided by the ReverseProxy CROWN API. ReverseProxy has a separate function ReverseProxy.setEnabled that can be used to disable the reverse proxy ports. If Engine.WebServer is disabled, but ReverseProxy still enabled, users will get a HTTP status code 502 (Service Unavailable) on the reverse proxy ports. |
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
True to enable, false to disable. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if setting could be applied successfully. |
Sample (auto-generated)
success = Engine.WebServer.setEnabled(enabled)Engine.WebServer.CrownEndpoint
Short description
Provides functions for managing Crown access in the engine’s embedded webserver.
Functions
addAuthorization()
Short description
Set a minimum required user level for calling a specific crown, function or set of subcrowns.
Detailed description
An Authorization is a user level restriction on calling methods via REST from a specified Crown or Sub-Crown. The user level defines the minimum user level required to execute any method within the Crown. If an Authorization user level is defined for a Crown it implicitly applies to all Sub-Crowns unless another Authorization is defined for a specific Sub-Crown. Once a single Authorization has been defined, authorizations are considered to have been "enabled" meaning that all Crowns lacking a defined authorization are blocked (except for Crowns which are Sub-Crowns of an authorized Crown).
|
Authorizations are an extension of the legacy concept of the whitelist. Calling the deprecated legacy crown method Engine.Webserver.setCrownEndpointWhitelist is the equivalent of calling addAuthorization whereby each element of the whitelist is given a default user level authorization of "Run" with the additional caveat that calling Engine.Webserver.setCrownEndpointWhitelist will first automatically remove all existing authorizations. |
|
Affected HTTP URLs:
Affected WebSocket URLs:
|
|
Not affected HTTP URLs:
Not affected WebSocket URLs:
|
Examples:
-- Allow access to a specific set of CROWNs, functions and events only, restricted by userlevel
Engine.Webserver.CrownEndpoint.addAuthorization("DateTime", "SERVICE", true) -- All functions and events starting with prefix "DateTime" require a minimum user level of "Service".
Engine.Webserver.CrownEndpoint.addAuthorization("DateTime", "MAINTENANCE", true) -- All functions and events starting with prefix "DateTime" require a minimum user level of "Maintenance".
Engine.Webserver.CrownEndpoint.addAuthorization("DateTime", "OPERATOR", false) -- This will not work, because the allowOverride parameter was set to false. This means that existing userlevel of "Maintenance" will not be altered.-- How Engine.Webserver.CrownEndpoint.addAuthorization and Engine.Webserver.setCrownEndpointWhitelist are related
Engine.Webserver.CrownEndpoint.addAuthorization("DateTime", "SERVICE", true) -- All functions and events starting with prefix "DateTime" require a minimum user level of "Service".
Engine.Webserver.CrownEndpoint.addAuthorization("DateTime.convertTimestamp", "MAINTENANCE", true) -- DateTime.convertTimestamp requires a minimum user level of "Maintenance"
Engine.Webserver.CrownEndpoint.addAuthorization("DigitalLogic", "MAINTENANCE", true) -- Crown DigitalLogic and all subcrowns are given a minimum user level requirement of "Maintenance"
-- The setCrownEndpointWhitelist legacy function overrides all authorizations to preserve backwards compatibility
Engine.Webserver.setCrownEndpointWhitelist({"DateTime", "DateTime.convertTimestamp"}) -- "DateTime" and "DateTime.convertTimestamp" now have user level requirements "Run" and the authorization for "DigitalLogic" has been implicitly removedSee also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
crown |
STRING |
1 |
Name of crown or function to be authenticated. |
userLevel |
ENUM |
? |
Minimum user level to be set for the crown. If not set or unknown, the default is user level RUN. |
allowOverwrite |
BOOL |
? |
Allow replacing an entry without first calling remove explicitly. If not set, the default is true. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if authorization was added. |
Sample (auto-generated)
success = Engine.WebServer.CrownEndpoint.addAuthorization(crown, userLevel, allowOverwrite)getAuthorizedCrowns()
Short description
Get a list of the currently authorized crowns and their respective minimum user levels. If a specific crown name is provided the authorized user level of only that crown is returned.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
crown |
STRING |
? |
Name of the crown, function of subcrown. If not set or empty, all added crowns are returned. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
crowns |
STRING |
[?*] |
The currently active authorized crowns. |
userLevels |
STRING |
[?*] |
The corresponding user level for each entry. |
Sample (auto-generated)
crowns, userLevels = Engine.WebServer.CrownEndpoint.getAuthorizedCrowns(crown)removeAuthorization()
Short description
Remove user level authorization from crown, function or subcrowns.
Detailed description
Delete a previously specified Authorization. Note that if other Authorizations continue to exist then the Crown whose Authorization has been removed will no longer be accessible, regardless of the logged in user level, until a new Authorization is added via addAuthorization.
|
Affected HTTP URLs:
Affected WebSocket URLs:
|
|
Not affected HTTP URLs:
Not affected WebSocket URLs:
|
Examples:
Engine.Webserver.CrownEndpoint.addAuthorization("DateTime", "SERVICE") -- All functions and events starting with prefix "DateTime" require a minimum user level of "Service"
Engine.Webserver.CrownEndpoint.removeAuthorization("DateTime") -- DateTime no longer has an Authorization associated with itSee also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
crown |
STRING |
1 |
Name of the crown, function of subcrown. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the name was found and authorization checking has been removed. |
Sample (auto-generated)
success = Engine.WebServer.CrownEndpoint.removeAuthorization(crown)Engine.WebServer.CrownFileEndpoint
Short description
Provides functions for managing File Crown endpoints in the engine’s embedded webserver.
Functions
getReadAccess()
Short description
Get the minimum required user level for reading from a file.
Detailed description
Get the current minimum user level required for read access.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
userLevel |
ENUM |
1 |
The user level required for file read access. |
Sample (auto-generated)
userLevel = Engine.WebServer.CrownFileEndpoint.getReadAccess()getWriteAccess()
Short description
Get the minimum required user level for writing to a file.
Detailed description
Get the current minimum user level required for write access.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
userLevel |
ENUM |
1 |
The user level required for file write access. |
Sample (auto-generated)
userLevel = Engine.WebServer.CrownFileEndpoint.getWriteAccess()setReadAccess()
Short description
Set a minimum required user level for reading from a file.
Detailed description
Set a minimum user level for file read access via HTTP. Changing this user level can be done freely with subsequent calls to setReadAccess.
|
Affected HTTP URLs:
|
Examples:
-- Allow access to a specific set of CROWNs, functions and events only, restricted by userlevel
Engine.Webserver.CrownFileEndpoint.setWriteAccess(Engine.WebServer.Service) -- Reading from a file requires a logged in user level of at least "Service"Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
userLevel |
ENUM |
1 |
User level to be set |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if setting could be applied successfully. |
Sample (auto-generated)
success = Engine.WebServer.CrownFileEndpoint.setReadAccess(userLevel)setWriteAccess()
Short description
Set a minimum required user level for writing to a file.
Detailed description
Set a minimum user level for file write access via HTTP. Changing this user level can be done freely with subsequent calls to setWriteAccess.
|
Affected HTTP URLs:
|
Examples:
Engine.Webserver.CrownFileEndpoint.setWriteAccess(Engine.Webserver.Service) -- Writing to a file requires a logged in user level of at least "Service"Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
userLevel |
ENUM |
1 |
User level to be set |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if setting could be applied successfully. |
Sample (auto-generated)
success = Engine.WebServer.CrownFileEndpoint.setWriteAccess(userLevel)Ethernet
Short description
Encapsulates functionality related to Ethernet interface configuration and manipulation.
Functions
getHostname()
Short description
Get the hostname of the device.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
name |
STRING |
1 |
The current hostname. |
Sample (auto-generated)
name = Ethernet.getHostname()ping()
Short description
Send and receive single ping packet to network ip addresses to check if the address is reachable. The function blocks until the answer is received or timeout is reached.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
1 |
The IP address as string e.g. '192.168.0.10' |
timeoutMs |
INT |
? |
Timeout to try to ping in milliseconds. Default 1000ms. Maximum of 5000ms is allowed. Bigger number is cropped. |
ifName |
ENUM |
? |
One of the available interfaces. Empty for all interfaces using routing table (Default). |
payloadSizeBytes |
INT |
? |
Size of the ping packet payload. Default 32 bytes. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if target response received within timeout |
responseTimeMs |
INT |
? |
The time in milliseconds until the response was received. Only returned if there was a response. |
Sample
local bReachable = Ethernet.ping("192.168.0.1")resolveHostName()
Short description
Resolves a DNS-name to an IP-address and returns the IP-address.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hostName |
STRING |
1 |
The DNS-name to resolve. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ip |
STRING |
1 |
The IP-address represented by the DNS-name. |
Sample
local ip = Ethernet.resolveHostName("sick.com")resolveIPAddress()
Short description
Resolves an IP-address to a DNS-name and returns the hostname.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ip |
STRING |
1 |
The IP address to resolve. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hostName |
STRING |
1 |
The resolved hostname. |
Sample
local hostname = Ethernet.resolveIPAddress("8.8.8.8")setHostname()
Short description
Set the hostname of the device. Use the function Parameters.apply afterwards to apply the setting.
Detailed description
The address configuration does not take effect immediately: The function Parameters.apply must to be used to actually apply the configuration and to activate the changes.
|
These settings are not stored permanently, so they get lost on a reboot or power-cycle of the device. The function Parameters.savePermanent can be used to make these settings permanent. |
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
name |
STRING |
1 |
The hostname to set. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the hostname was set successfully, false if not (e.g. hostname syntax is invalid according to RFC 1123). |
Sample (auto-generated)
success = Ethernet.setHostname(name)Ethernet.Diagnosis
Short description
Provides functionality to get low-level diagnostic information related to Ethernet interfaces and the TCP/IP-stack of the device.
Overview
Functions
getArpCache()
Short description
Get a human-readable list showing the ARP Cache mapping of all known Ethernet MAC addresses to the respective IP Addresses.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
arpCache |
STRING |
1 |
The ARP cache status of the device. |
Sample (auto-generated)
arpCache = Ethernet.Diagnosis.getArpCache()getBridgeStatus()
Short description
Get a human-readable list showing the status of all configured Ethernet bridge interfaces on the device.
Detailed description
|
On Linux-based devices, this corresponds to the output of the command |
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bridgeStatus |
STRING |
1 |
The Ethernet bridge status of the device. |
Sample (auto-generated)
bridgeStatus = Ethernet.Diagnosis.getBridgeStatus()getDnsConfig()
Short description
Gets a human-readable version of the current DNS configuration of the device.
Detailed description
|
On Linux-based devices, this corresponds to the content of the file |
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
content |
STRING |
1 |
The DNS configuration of the device. |
Sample (auto-generated)
content = Ethernet.Diagnosis.getDnsConfig()getInterfaceStatistics()
Short description
Gets a human-readable list of interface statistics about a Ethernet interface.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The name of the interface |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
interfaceStatistics |
STRING |
1 |
Statistics about the interface. |
Sample (auto-generated)
interfaceStatistics = Ethernet.Diagnosis.getInterfaceStatistics(ifName)getInterfaceStatus()
Short description
Gets a human-readable list of all network interfaces of the device and their associated properties.
Detailed description
|
On Linux-based devices, this corresponds to the output of the command |
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
interfaceStatus |
STRING |
1 |
List of all network interfaces. |
Sample (auto-generated)
interfaceStatus = Ethernet.Diagnosis.getInterfaceStatus()getRoute()
Short description
Gets a human-readable route to the destination address.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
destination |
STRING |
1 |
The destination address. |
ifName |
ENUM |
? |
Force the output device on which this packet will be routed. |
oneLine |
BOOL |
? |
If true, the output is printed in a single line (default false). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if route could be successfully determined. |
route |
STRING |
1 |
The route to the destination address. |
Sample (auto-generated)
success, route = Ethernet.Diagnosis.getRoute(destination, ifName, oneLine)getRoutingTable()
Short description
Gets a human-readable string containing the current routing table of the device.
Detailed description
|
On Linux-based devices, this corresponds to the output of the command |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
routingTable |
STRING |
1 |
The routing table of the device. |
Sample (auto-generated)
routingTable = Ethernet.Diagnosis.getRoutingTable()getSocketStatus()
Short description
Gets a human-readable list containing the status of all TCP and UDP sockets on the device.
Detailed description
|
On Linux-based devices, this corresponds to the output of the command |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
socketStatus |
STRING |
1 |
List of TCP and UDP sockets. |
Sample (auto-generated)
socketStatus = Ethernet.Diagnosis.getSocketStatus()traceroute()
Short description
Returns a human-readable list of the network route to destination
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
destination |
STRING |
1 |
IP-Address or name of destination |
basePort |
INT |
? |
Base UDP port number used in probes (Default 33434) |
maxTTL |
INT |
? |
Maximum number of hops (Default 30) |
timeoutMs |
INT |
? |
Time to wait for response in milliseconds (Default 3000 ms) |
useICMPecho |
BOOL |
? |
Use ICMP echo instead of UDP datagrams (Default false) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
route |
STRING |
1 |
The result of the traceroute command |
Sample (auto-generated)
route = Ethernet.Diagnosis.traceroute(destination, basePort, maxTTL, timeoutMs, useICMPecho)Ethernet.DNS
Short description
Provides functionality to configure DNS and hostname resolving settings.
Overview
Functions
addHostsEntry()
Short description
Adds a mapping of IP address to hostname.
Detailed description
If a mapping for the given ipAddress already exists, the mapping is overwritten with the new hostname(s).
|
This setting is not stored permanently and gets lost on a reboot or power-cycle of the device. |
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
1 |
IP address of the host. |
canonicalHostname |
STRING |
1 |
Fully-qualified hostname (including domain name) to associate with the given IP address. |
aliases |
STRING |
[?*] |
Further, possibly shorter hostnames to associate with the given IP address |
Sample (auto-generated)
Ethernet.DNS.addHostsEntry(ipAddress, canonicalHostname, aliases)getHostsEntries()
Short description
Gets the list of IP address to hostname mappings that is used to resolve hostnames before issuing a resolve request to the nameservers.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddresses |
STRING |
* |
IP address of the host. |
hostnames |
STRING |
* |
Hostname to associate with the given IP address. This string may contain multiple hostnames (aliases), separated by tab character. |
Sample (auto-generated)
ipAddresses, hostnames = Ethernet.DNS.getHostsEntries()getNameservers()
Short description
Gets the list of nameservers that are used to resolve hostnames to IP addresses on the system.
Detailed description
This function lists the overall list of configured nameservers, regardless if they were added via the function setNameservers or received from a DHCP server.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
nameservers |
STRING |
* |
List of IP addresses of nameservers. |
Sample (auto-generated)
nameservers = Ethernet.DNS.getNameservers()getResolveAttempts()
Short description
Gets the number of overall attempts to reach the nameservers per request.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
attempts |
INT |
1 |
Number of attempts. |
Sample (auto-generated)
attempts = Ethernet.DNS.getResolveAttempts()getResolveTimeout()
Short description
Gets the amount of time to wait for a response from a single nameserver before switching to a different nameserver.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timeout |
INT |
1 |
Timeout in seconds. |
Sample (auto-generated)
timeout = Ethernet.DNS.getResolveTimeout()getSearchList()
Short description
Gets the search list that contains local domain suffixes that are used to resolve local hostnames (without any dots in the hostname).
Detailed description
On resolving such hostnames, the domain suffixes are appended in the order listed until a match is found.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
searchList |
STRING |
* |
List of domain suffixes to add to local hostnames. |
Sample (auto-generated)
searchList = Ethernet.DNS.getSearchList()removeHostsEntry()
Short description
Removes a mapping of IP address to hostname.
Detailed description
|
This function can only remove mappings that were previously created using the function addHostsEntry. |
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
1 |
IP address of the host. |
Sample (auto-generated)
Ethernet.DNS.removeHostsEntry(ipAddress)setNameservers()
Short description
Sets the list of nameservers that are used to resolve hostnames to IP addresses on the system.
Detailed description
If the list contains multiple entries, the nameservers are queried in the order listed. Later entries are only used if all nameservers from previous entries are not reachable.
Ethernet interfaces that are configured to receive address settings via DHCP may also receive nameserver settings from a DHCP server. This function can not be used to change or remove nameservers that were configured via DHCP, but nameservers that are added using this function take precedence before nameservers that are added via DHCP.
|
This setting is not stored permanently and gets lost on a reboot or power-cycle of the device. |
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
nameservers |
STRING |
[?*] |
List of IP addresses of nameservers. |
Sample (auto-generated)
Ethernet.DNS.setNameservers(nameservers)setResolveAttempts()
Short description
Sets the number of overall attempts to reach the nameservers per request.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
attempts |
INT |
? |
Number of attempts. Initial: 2; Min: 1; Max: 5 |
Sample (auto-generated)
Ethernet.DNS.setResolveAttempts(attempts)setResolveTimeout()
Short description
Sets the amount of time to wait for a response from a single nameserver before switching to a different nameserver.
Detailed description
|
This setting is not stored permanently and gets lost on a reboot or power-cycle of the device. |
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timeout |
INT |
? |
Timeout in seconds. Initial: 5; Min: 1; Max: 30. |
Sample (auto-generated)
Ethernet.DNS.setResolveTimeout(timeout)setSearchList()
Short description
Gets the search list that contains local domain suffixes that are used to resolve local hostnames (without any dots in the hostname).
Detailed description
On resolving such hostnames, the domain suffixes are appended in the order listed until a match is found.
|
This setting is not stored permanently and gets lost on a reboot or power-cycle of the device. |
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
searchList |
STRING |
[?*] |
List of domain suffixes to add to local hostnames. |
Sample (auto-generated)
Ethernet.DNS.setSearchList(searchList)Ethernet.Interface
Short description
Provides functionality to configure Ethernet interfaces and monitor their status.
Overview
Functions
applyAddressConfig()
Short description
Applies any changes to the Ethernet interface address configuration previously done using the function Ethernet.Interface.setAddressConfig.
Detailed description
|
It is possible to apply the config for all interfaces at once by setting parameter |
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface to apply the address config on, or ALL to apply on all interfaces at once. |
Sample (auto-generated)
Ethernet.Interface.applyAddressConfig(ifName)getAddressConfig()
Short description
Returns the current address configuration of the specified ethernet interface.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface to get the config from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dhcpEnabled |
BOOL |
? |
True if DHCP is enabled. Nil if interface is currently a bridged interface or if the interface does not exist. |
ipAddress |
STRING |
? |
The IP address of the specified interface. Nil if interface is currently a bridged interface or if the interface does not exist. |
subnetMask |
STRING |
? |
The subnet mask of the specified interface. Nil if interface is currently a bridged interface or if the interface does not exist. |
gateway |
STRING |
? |
The IP address of the gateway of the specified interface. Nil if interface is currently a bridged interface or if the interface does not exist. |
Sample (auto-generated)
dhcpEnabled, ipAddress, subnetMask, gateway = Ethernet.Interface.getAddressConfig(ifName)getInterfaces()
Short description
Gets a list of all available Ethernet interfaces of the device.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
* |
List of all available Ethernet interfaces. |
Sample (auto-generated)
ifName = Ethernet.Interface.getInterfaces()getLinkSpeed()
Short description
Gets the current speed of the Ethernet link.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface to get the speed from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
linkSpeed |
STRING |
? |
The current speed (1000FD,100FD/HD,10FD/HD) of the specified interface. Nil if interface is currently a bridged interface or if the interface does not exist. |
Sample (auto-generated)
linkSpeed = Ethernet.Interface.getLinkSpeed(ifName)getMACAddress()
Short description
Returns the MAC address of the of the specified Ethernet interface.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface to get the MAC address from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
macAddress |
STRING |
? |
The MAC address of the specified interface. Notation is six groups of two hexadecimal digits separated by hyphens, e.g. '01-23-45-67-89-AB'. Nil if interface is currently a bridged interface or if the interface does not exist. |
Sample (auto-generated)
macAddress = Ethernet.Interface.getMACAddress(ifName)isBridge()
Short description
Checks whether the specified Ethernet interface is a bridge interface.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface to get the link state from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isBridge |
BOOL |
? |
True if the interface is a bridge interface which was created via Ethernet.Bridge. Nil if interface does not exist |
Sample (auto-generated)
isBridge = Ethernet.Interface.isBridge(ifName)isBridged()
Short description
Checks whether the specified Ethernet interface is a currently bridged (part of a bridge interface).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface to get the link state from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isBridged |
BOOL |
? |
True if the interface is a bridged interface which was added to a bridge interface created via Ethernet.Bridge. Nil if interface does not exist |
Sample (auto-generated)
isBridged = Ethernet.Interface.isBridged(ifName)isLinkActive()
Short description
Returns the current link state of the specified Ethernet interface.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface to get the link state from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
linkActive |
BOOL |
? |
True if there is currently a link up, false if the link is down. Nil if interface is currently a bridged interface or if the interface does not exist. |
Sample (auto-generated)
linkActive = Ethernet.Interface.isLinkActive(ifName)setAddressConfig()
Short description
Sets the address configuration of the specified Ethernet interface.
Detailed description
The address configuration does not take effect immediately: The function Ethernet.Interface.applyAddressConfig must to be used to actually apply the configuration and to activate the changes.
Before Ethernet.Interface.applyAddressConfig is called, the device still uses the previous address configuration.
|
This function can not change the configuration of bridge interfaces that were created using Ethernet.Bridge, or of interfaces that currently being bridged by an enabled Ethernet.Bridge. |
|
These settings are not stored permanently, so they get lost on a reboot or power-cycle of the device. The function Parameters.savePermanent can be used to make these settings permanent. |
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface to get the config from |
dhcpEnabled |
BOOL |
1 |
True if address configuration should be retrieved from a DHCP server for this interface, other parameters must be omitted in this case. |
ipAddress |
STRING |
? |
The IP address of the specified interface. Must be nil if parameter dhcpEnabled is true. |
subnetMask |
STRING |
? |
The subnet mask of the specified interface. Must be nil if parameter dhcpEnabled is true. |
gateway |
STRING |
? |
The IP address of the gateway of the specified interface. Optional. Must be nil if parameter dhcpEnabled is true. |
Sample (auto-generated)
Ethernet.Interface.setAddressConfig(ifName, dhcpEnabled, ipAddress, subnetMask, gateway)Events
OnAddressConfigChanged
Short description
This event is notified every time the address configuration of an Ethernet interface changes.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface of which the address changed. |
dhcpEnabled |
BOOL |
1 |
True if DHCP is enabled. |
ipAddress |
STRING |
1 |
The IP address of the interface. |
subnetMask |
STRING |
1 |
The subnet mask of the interface. |
gateway |
STRING |
1 |
The IP address of the gateway of the specified interface. |
Sample (auto-generated)
function handleOnAddressConfigChanged(ifName, dhcpEnabled, ipAddress, subnetMask, gateway)
-- Do something
end
Script.register("Ethernet.Interface.OnAddressConfigChanged", "handleOnAddressConfigChanged")OnInterfaceAdded
Short description
This event is notified every time an Ethernet interface is added to the device.
Detailed description
|
This event is also notified when an instance of Ethernet.Bridge is enabled |
See also
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface that was added. |
Sample (auto-generated)
function handleOnInterfaceAdded(ifName)
-- Do something
end
Script.register("Ethernet.Interface.OnInterfaceAdded", "handleOnInterfaceAdded")OnInterfaceRemoved
Short description
This event is notified every time an Ethernet interface is removed from the device
Detailed description
|
This event is also notified when an instance of Ethernet.Bridge is disabled or the instance is destroyed. |
See also
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface that was removed. |
Sample (auto-generated)
function handleOnInterfaceRemoved(ifName)
-- Do something
end
Script.register("Ethernet.Interface.OnInterfaceRemoved", "handleOnInterfaceRemoved")OnLinkActiveChanged
Short description
This event is notified every time a link is established or lost on a Ethernet interface.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ifName |
ENUM |
1 |
The interface of which the link active state changed. |
linkActive |
BOOL |
1 |
True if there is currently a link up, false if the link is down. |
Sample (auto-generated)
function handleOnLinkActiveChanged(ifName, linkActive)
-- Do something
end
Script.register("Ethernet.Interface.OnLinkActiveChanged", "handleOnLinkActiveChanged")Ethernet.PTP
Short description
Provides Precision Time Protocol (PTP) Version 2 functionality according to IEEE 1588-2008 in master- or slave-role. The purpose of the PTP protocol is to synchronize the clocks of devices throughout a network. A device can act in two different roles, master or slave. A PTP master acts as a source of time information in the network and distributes its system clock. A PTP slave receives the time which is distributed by a PTP master in the network. It synchronizes the system clock to this received time. The configuration settings of a PTP instance become active at the moment when it is enabled using the enable-function. If the configuration settings are changed using the set-functions while the instance is already enabled, the instance needs to be re-enabled for the settings to become active.
See also
Overview
Functions
create()
Short description
Creates a new PTP instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
Sample (auto-generated)
handle = Ethernet.PTP.create()deregister()
Short description
This function is used to deregister from any registered event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
eventname |
STRING |
1 |
The event to deregister from |
callback |
STRING |
1 |
The function name which was registered on the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
Sample (auto-generated)
success = Ethernet.PTP.deregister(handle, eventname, callback)disable()
Short description
Disables PTP.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
Sample (auto-generated)
Ethernet.PTP.disable(handle)enable()
Short description
Enables PTP. If PTP is already enabled or enabling fails, the function will return false. At least one Ethernet interface has to be selected using the function PTP.setInterface, otherwise PTP can not be enabled. In any case it is strongly recommended to evaluate the actual state with getPortState() to react on it in the app.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if enabling PTP was successful. |
Sample (auto-generated)
success = Ethernet.PTP.enable(handle)getPortState()
Short description
Gets the current PTP Port State.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
portState |
ENUM |
1 |
Port State. |
Sample (auto-generated)
portState = Ethernet.PTP.getPortState(handle)getSupportedTimestampingMethod()
Short description
Get the supported timestamping method(s) for the selected interface(s) (SOFTWARE or KERNEL or HARDWARE). Note: Ethernet bridge interfaces can only use SOFTWARE.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
methods |
STRING |
* |
Timestamping method; nil if no timestamping is supported |
Sample (auto-generated)
methods = Ethernet.PTP.getSupportedTimestampingMethod(handle)isEnabled()
Short description
Returns true if PTP is enabled.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
True, if PTP is enabled. |
Sample (auto-generated)
enabled = Ethernet.PTP.isEnabled(handle)register()
Short description
This function is used to register for any event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
eventname |
STRING |
1 |
The event to register to |
callback |
STRING |
1 |
The function name to call on the event occurrence |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if event does not exist. |
Sample (auto-generated)
success = Ethernet.PTP.register(handle, eventname, callback)setDelayDetection()
Short description
Set the PTP delay detection method: end to end (default) or peer to peer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
mode |
1 |
The delay detection to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if set delay detection was successful. |
Sample (auto-generated)
success = Ethernet.PTP.setDelayDetection(handle, mode)setInterface()
Short description
Set the interface(s) which should be bound to PTP.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
interface |
ENUM |
[1+] |
The interface(s) to configure the PTP for. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, if set interface(s) was successful. |
Sample (auto-generated)
success = Ethernet.PTP.setInterface(handle, interface)setMode()
Short description
Set the PTP mode (AUTO, SLAVE or MASTER).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
mode |
ENUM |
1 |
The PTP mode to used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, set PTP mode was successful. |
Sample (auto-generated)
success = Ethernet.PTP.setMode(handle, mode)setTimestampingMethod()
Short description
Set the PTP timestamping method (AUTO, SOFTWARE or KERNEL).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of PTP. |
mode |
1 |
The PTP timestamping method to be used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True, set PTP timestamping method was successful. |
Sample (auto-generated)
success = Ethernet.PTP.setTimestampingMethod(handle, mode)Events
OnError
Short description
The OnError event which is thrown when PTP reports any error messages.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
errorMessage |
STRING |
1 |
Message which describes the specific error that occurred. |
Sample (auto-generated)
function handleOnError(errorMessage)
-- Do something
end
Ethernet.PTP.register(handle, "OnError", "handleOnError")OnLog
Short description
The OnLog event which is thrown when PTP reports any diagnostic log messages.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
logMessage |
STRING |
1 |
Message which describes the event that occurred. |
Sample (auto-generated)
function handleOnLog(logMessage)
-- Do something
end
Ethernet.PTP.register(handle, "OnLog", "handleOnLog")FieldBus
Short description
Provides field bus access. This API is intended for field bus slave devices and allows them exchange data with a PLC. It works for all field bus protocols like PROFINET, EtherNet/IP and EtherCAT. Read more…
Overview
Detailed description
FieldBus
How to enable the field bus functionality or select a specific protocol is also device specific. Some devices offer these settings via the SOPAS Engineering Tool. There is no possibility to select the protocol via this API. To integrate the device into PLC projects you need an appropriate device description file. These are available via the SICK support portal. - PROFINET: GSDML file - EtherNet/IP: EDS file - EtherCat: ESI file Devices which implement this API offer two independent ways to communicate process data with a PLC: - For each direction (output from PLC to device and input from device to PLC), there is a field "ControlBits" with a length of 16 bits. These fields can be used freely by your application, there is no predefined meaning for the individual bits. - The rest of the cyclic process data can be used in two different modes: - In Confirmed Messaging mode, it is used as a transfer channel for the SICK Confirmed Messaging protocol. This protocol allows to send arbitrary strings in both directions. The protocol can also handle strings that are longer than the size of the cyclic process data. This works by splitting them up in several fragments which are transferred and acknowledged sequentially. To use this channel from the PLC side, SICK offers ready-to-use function blocks for Confirmed Messaging for various PLCs. - In Raw mode, the user receives and sets the process data directly without any protocol.
FieldBus status
The FieldBus.Status reflects the current state of the communication between the fieldbus-PLC and the underlying Fieldbus-Stack. Also refer to the state table and transition graph.
The current status can actively be retrieved by FieldBus.getStatus.
Any status change is reported by the event FieldBus.OnStatusChanged.
| State | Description |
|---|---|
Initial state if the fieldbus handle is created in mode 'EXPLICIT_OPEN'. |
|
State indicating that the fieldbus handle is currently opening the fieldbus stack. Either due to using 'AUTOMATIC_OPEN' mode upon handle creation or due to explicitly applying FieldBus.open to a CLOSED handle. |
|
Upon successfully OPENING the stack, this state is eventually being reached. |
|
The fieldbus has been opened successfully, it is running w/o major errors, a PLC-connection has been ONLINE previously, but currently there is no process data communication active. |
|
At least one process data connection to a PLC is active, meaning the process data is being exchanged currently. |
|
An error has occurred and the fieldbus may not work. |
Functions
close()
Short description
Stops communication to the field bus
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
Sample
FieldBus.close(busHandle)create()
Short description
Creates a new instance. This can fail if field bus functionality is disabled in the device. Some devices offer a switch to enable and select the type of field bus via the SOPAS Engineering Tool.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
mode |
ENUM |
? |
Optional create mode. Default is 'AUTOMATIC_OPEN'. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
? |
The new FieldBus. nil if FieldBus is disabled. |
Sample
busHandle = FieldBus.create()deregister()
Short description
This function is used to deregister from any registered event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to deregister from |
callback |
STRING |
1 |
The function name which was registered on the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
Sample (auto-generated)
success = FieldBus.deregister(handle, eventname, callback)getHandshakeMode()
Short description
Returns current mode (Activate/Inactive) of "CONFIRMED_MESSAGING" and the retransmission of packages.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handshakeMode |
BOOL |
1 |
Status of Handshake Mode. True for Active, False for Inactive. |
Sample
local mode = FieldBus.getHandshakeMode(busHandle)getInfo()
Short description
Returns various information about the fieldbus, its components and internals in JSON string format. Some depend on the currently configured fieldbus protocol.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fieldbusInfo |
STRING |
1 |
JSON formatted string providing the information of the fieldbus component. |
Sample
fieldbusInfo = FieldBus.getInfo(busHandle)getStatus()
Short description
Gets the current status of the fieldbus communication.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
status |
ENUM |
1 |
The current status. |
Sample (auto-generated)
status = FieldBus.getStatus(handle)open()
Short description
Starts the communication to the field bus. This function only has to be called when the handle was created with CreateMode "EXPLICIT_OPEN". Otherwise, open is done automatically on handle create.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
Sample
FieldBus.open(busHandle)readControlBitsIn()
Short description
Gets the current value of the control bits transmitted to the PLC
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
controlBitsIn |
INT |
1 |
the control bits |
Sample
local controlBitsIn = FieldBus.readControlBitsIn(busHandle)readControlBitsOut()
Short description
Gets the current value of the control bits received from the PLC
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
controlBitsOut |
INT |
1 |
the control bits |
Sample
local controlBitsOut = FieldBus.readControlBitsOut(busHandle)register()
Short description
This function is used to register for events from the FieldBus
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
|
eventname |
STRING |
1 |
The event to register to |
callback |
STRING |
1 |
Function name to call when an event occurs |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if event does not exist. |
Sample
FieldBus.register(handle, 'OnNewData', callback)setMode()
Short description
Sets the transmission mode. It only works, if the Fieldbus.create function has been called with the parameter "EXPLICIT_OPEN". Default is "CONFIRMED_MESSAGING". See also Fieldbus.CreateMode enumeration.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
mode |
ENUM |
1 |
Transmission mode |
Sample
FieldBus.setMode(busHandle, "RAW")transmit()
Short description
Transmits data through the field bus to the PLC.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
data |
BINARY |
1 |
The data which is to be transmitted. Up to 4094 bytes can be transmitted with a single call. If the size is larger, only the first 4094 bytes will be transmitted. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
numberOfBytesTransmitted |
INT |
1 |
Number of bytes transmitted; 0 if transmit failed. |
Sample
bytesTransmitted = FieldBus.transmit(busHandle, "Hello PLC")writeControlBitsIn()
Short description
Sets and transmits the value of the control bits to the PLC
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The FieldBus handle |
controlBits |
INT |
1 |
The control bits to write |
bitMask |
INT |
1 |
The bitmask to use |
Sample
FieldBus.writeControlBitsIn(busHandle, controlBits, bitMask)Events
OnControlBitsOutChanged
Short description
This event is thrown when the control bits set by the PLC have changed.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ctrlBits |
INT |
1 |
ctrl bits out |
Sample (auto-generated)
function handleOnControlBitsOutChanged(ctrlBits)
-- Do something
end
FieldBus.register(handle, "OnControlBitsOutChanged", "handleOnControlBitsOutChanged")OnInputSizeChanged
Short description
This event is thrown when the size of the FieldBus input frame buffer changes.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
size |
INT |
1 |
New size of the fieldbus input frame buffer. |
Sample (auto-generated)
function handleOnInputSizeChanged(size)
-- Do something
end
FieldBus.register(handle, "OnInputSizeChanged", "handleOnInputSizeChanged")OnNewData
Short description
This event is thrown when new data has been received from the PLC through the field bus.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
1 |
Sample (auto-generated)
function handleOnNewData(data)
-- Do something
end
FieldBus.register(handle, "OnNewData", "handleOnNewData")OnOutputSizeChanged
Short description
This event is thrown when the size of the FieldBus output frame buffer changes.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
size |
INT |
1 |
New size of the fieldbus output frame buffer. |
Sample (auto-generated)
function handleOnOutputSizeChanged(size)
-- Do something
end
FieldBus.register(handle, "OnOutputSizeChanged", "handleOnOutputSizeChanged")OnStatusChanged
Short description
This event is thrown when the state of the FieldBus communication changes.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
status |
ENUM |
1 |
New state of the fieldbus communication. |
Sample (auto-generated)
function handleOnStatusChanged(status)
-- Do something
end
FieldBus.register(handle, "OnStatusChanged", "handleOnStatusChanged")FieldBus.Config
Short description
Global configuration for the FieldBus API. This is handle independent.
Overview
Functions
getProtocol()
Short description
Gets the protocol used.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
protocol |
ENUM |
? |
The current protocol used. |
Sample (auto-generated)
protocol = FieldBus.Config.getProtocol()setProtocol()
Short description
Sets the fieldbus protocol to be used. This parameter is not stored permanently. The procotol is always undefined until this function is called. The protocol used is evaluated at the time either the FieldBus.create(AUTOMATIC_OPEN) or the FieldBus.open function is executed. After that, the protocol cannot be changed anymore until the handle created by FieldBus.create has been destroyed or after the FieldBus.close function has been called.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
protocol |
ENUM |
1 |
The protocol to be used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the Protocol could be set successfully. False otherwise. |
Sample (auto-generated)
success = FieldBus.Config.setProtocol(protocol)FieldBus.Config.EtherNetIP
Short description
EtherNet/IP configuration.
Overview
Functions
getAddressingMode()
Short description
Gets the addressing mode used for the ip-address assignment. This value corresponds to the attribute 3, 'Configuration control', in the TCP/IP object.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
addressingMode |
1 |
Current addressing mode for the ip parameters. |
Sample (auto-generated)
addressingMode = FieldBus.Config.EtherNetIP.getAddressingMode()getInterfaceConfig()
Short description
Gets the IP data used in the EtherNet/IP network. This value corresponds to the attribute 5, 'Interface configuration', in the TCP/IP object.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
1 |
Current IP address. |
netmask |
STRING |
1 |
Current subnet mask. |
gateway |
STRING |
1 |
Currently active ateway address. |
nameServer |
STRING |
1 |
Current primary name server. |
nameServer2 |
STRING |
1 |
Current secondary name server. |
domainName |
STRING |
1 |
Current default domain name. |
Sample (auto-generated)
ipAddress, netmask, gateway, nameServer, nameServer2, domainName = FieldBus.Config.EtherNetIP.getInterfaceConfig()getLinkStatus()
Short description
Returns Link Status of the specified port.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
port |
ENUM |
1 |
The interface to get the Link Status from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
linkStatus |
BOOL |
? |
The Link Status of the specified interface. False if the port does not exist. |
Sample (auto-generated)
linkStatus = FieldBus.Config.EtherNetIP.getLinkStatus(port)getMACAddress()
Short description
Returns the MAC address of the of current fieldbus implementation.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
macAddress |
STRING |
? |
The MAC address of the specified interface. Notation is six groups of two hexadecimal digits separated by hyphens, e.g. '01-23-45-67-89-AB'. Nil if interface is currently a bridged interface or if the interface does not exist. |
Sample (auto-generated)
macAddress = FieldBus.Config.EtherNetIP.getMACAddress()setAddressingMode()
Short description
Sets the addressing mode for the ip-address assignment. This value corresponds to the attribute 3, 'Configuration control', in the TCP/IP object. If set to STATIC, you also need to set valid address values using the function setInterfaceConfig.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
addressingMode |
1 |
Addressing mode for the ip parameters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.EtherNetIP.setAddressingMode(addressingMode)setInterfaceConfig()
Short description
Sets the IP data. This value corresponds to the attribute 5, 'Interface configuration', in the TCP/IP object.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
1 |
IP address. |
netmask |
STRING |
1 |
Subnetmask. |
gateway |
STRING |
? |
Gateway IP address. |
nameServer |
STRING |
? |
Primary name server. |
nameServer2 |
STRING |
? |
Secondary name server. |
domainName |
STRING |
? |
Default domain name. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.EtherNetIP.setInterfaceConfig(ipAddress, netmask, gateway, nameServer, nameServer2, domainName)Events
OnAddressingModeChanged
Short description
This event is notified when the addressing mode of the EtherNet/IP adapter has changed.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
addressingMode |
1 |
Addressing mode for the ip parameters. |
Sample (auto-generated)
function handleOnAddressingModeChanged(addressingMode)
-- Do something
end
Script.register("FieldBus.Config.EtherNetIP.OnAddressingModeChanged", "handleOnAddressingModeChanged")OnFieldbusStorageRequest
Short description
This event is thrown when the fieldbus (stack) needs to store data permanently, for example address data or device name. The implementation of this event is mandatory since the fieldbus (stack) needs to store fieldbus specific data permanently which will be loaded after restart. This is a requirement to pass the certification tests. See the component’s documentation for an example implementation.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
storageHandle |
HANDLE |
1 |
Object containing the data to be saved or loaded |
Sample (auto-generated)
function handleOnFieldbusStorageRequest(storageHandle)
-- Do something
end
Script.register("FieldBus.Config.EtherNetIP.OnFieldbusStorageRequest", "handleOnFieldbusStorageRequest")OnInterfaceConfigChanged
Short description
This event is notified when the address of the EtherNet/IP adapter has changed.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
1 |
IP address. |
netmask |
STRING |
1 |
Subnetmask. |
gateway |
STRING |
1 |
Gateway IP address. |
nameServer |
STRING |
? |
Primary name server. |
nameServer2 |
STRING |
? |
Secondary name server. |
domainName |
STRING |
? |
Default domain name. |
Sample (auto-generated)
function handleOnInterfaceConfigChanged(ipAddress, netmask, gateway, nameServer, nameServer2, domainName)
-- Do something
end
Script.register("FieldBus.Config.EtherNetIP.OnInterfaceConfigChanged", "handleOnInterfaceConfigChanged")OnLinkActiveChanged
Short description
This event is notified when the physical link status has changed.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
port |
ENUM |
1 |
Addressing mode for the ip parameters. |
linkActive |
BOOL |
1 |
True if link is up, otherwise it is down |
Sample (auto-generated)
function handleOnLinkActiveChanged(port, linkActive)
-- Do something
end
Script.register("FieldBus.Config.EtherNetIP.OnLinkActiveChanged", "handleOnLinkActiveChanged")FieldBus.Config.ProfinetIO
Short description
Profinet IO configuration.
Overview
Functions
applyConfig()
Short description
Applies the address data, previously set. Notice that the PLC and/or the fieldbus decides if and when the data is stored permanently and may override your changes. The function applyConfig may lead in some implementations to a reboot of the communication controller. The application may however want to store the data permanently. In that case, use this function carefully so that you do not lose any changes or store unwanted temporary data.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.ProfinetIO.applyConfig()getDapImDescriptor()
Short description
Gets the descriptor (a.k.a. 'comment') as used for the DAP’s (device access point) I&M3 data.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
descriptor |
STRING |
1 |
Descriptor of this I&M3 data. |
Sample (auto-generated)
descriptor = FieldBus.Config.ProfinetIO.getDapImDescriptor()getDapImHardwareRev()
Short description
Gets the hardware revision as used for the DAP (device access point) used in the I&M0 data.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hardwareRev |
INT |
1 |
Hardware revision of this I&M0 data. |
Sample (auto-generated)
hardwareRev = FieldBus.Config.ProfinetIO.getDapImHardwareRev()getDapImInstallDate()
Short description
Gets the installation date as used for the DAP’s (device access point) I&M2 data.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
installDate |
STRING |
1 |
Installation date of this I&M2 data. |
Sample (auto-generated)
installDate = FieldBus.Config.ProfinetIO.getDapImInstallDate()getDapImSoftwareRev()
Short description
Gets the software revision for the DAP (device access point) used in the I&M0 data.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
swRevPrefix |
STRING |
1 |
Prefix character of the software revision of this I&M0 data. |
swRevFuncEnhancement |
INT |
1 |
Functional enhancement identifier of the software revision of this I&M0 data. |
swRevBugFix |
INT |
1 |
Bug fix identifier of the software revision of this I&M0 data. |
swRevInternalChange |
INT |
1 |
Internal change identifier of the software revision of this I&M0 data. |
Sample (auto-generated)
swRevPrefix, swRevFuncEnhancement, swRevBugFix, swRevInternalChange = FieldBus.Config.ProfinetIO.getDapImSoftwareRev()getDapImTagFunction()
Short description
Gets the function tag (a.k.a. 'plant designation') as used for the DAP’s (device access point) I&M1 data.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
tagFunction |
STRING |
1 |
Function tag of this I&M1 data. |
Sample (auto-generated)
tagFunction = FieldBus.Config.ProfinetIO.getDapImTagFunction()getDapImTagLocation()
Short description
Gets the location tag (a.k.a. 'location identifier') as used for the DAP’s (device access point) I&M1 data.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
tagLocation |
STRING |
1 |
Location tag of this I&M1 data. |
Sample (auto-generated)
tagLocation = FieldBus.Config.ProfinetIO.getDapImTagLocation()getDeviceName()
Short description
Gets the name of the device in the Profinet network. This value will be applied after calling the function ProfinetIO.Device.applyConfig.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceName |
STRING |
1 |
Device name to be applied. Needs to be a valid Profinet device name, otherwise the value will be rejected. |
remanent |
BOOL |
1 |
True if the network configuration tool set the current IP address settings permanently, that is, it will be reloaded after a restart of the device. |
Sample (auto-generated)
deviceName, remanent = FieldBus.Config.ProfinetIO.getDeviceName()getInterfaceConfig()
Short description
Gets the device’s IP data used in the Profinet network. The values will be applied after calling the function ProfinetIO.Device.applyConfig.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
1 |
Currently active (applied) IP address. |
subnetMask |
STRING |
1 |
Currently active (applied) subnet mask. |
gateway |
STRING |
1 |
Currently active (applied) gateway address. |
remanent |
BOOL |
1 |
True if the network configuration tool set the current IP address settings permanently, that is, it will be reloaded after a restart of the device. |
Sample (auto-generated)
ipAddress, subnetMask, gateway, remanent = FieldBus.Config.ProfinetIO.getInterfaceConfig()getLinkStatus()
Short description
Returns Link Status of the specified port.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
port |
ENUM |
1 |
The interface to get the Link Status from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
linkStatus |
BOOL |
? |
The Link Status of the specified interface. False if the port does not exist. |
Sample (auto-generated)
linkStatus = FieldBus.Config.ProfinetIO.getLinkStatus(port)getMACAddress()
Short description
Returns the MAC address of the specified port.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
port |
ENUM |
1 |
The interface to get the MAC address from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
macAddress |
STRING |
? |
The MAC address of the specified interface. Notation is six groups of two hexadecimal digits separated by hyphens, e.g. '01-23-45-67-89-AB'. Nil if the port does not exist. |
Sample (auto-generated)
macAddress = FieldBus.Config.ProfinetIO.getMACAddress(port)setDapImDescriptor()
Short description
Sets the descriptor (comment) for the DAP’s (device access point) I&M3 data. The value will take effect on the fieldbus immediately, but is only stored permanently after calling the function storeDapImData.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
descriptor |
STRING |
1 |
Descriptor to use for this I&M3 data. String with 54 visible characters. Will be filled with blanks automatically if shorter. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.ProfinetIO.setDapImDescriptor(descriptor)setDapImInstallDate()
Short description
Sets the installation date for the DAP’s (device access point) I&M2 data. The value will take effect on the fieldbus immediately, but is only stored permanently after calling the function storeDapImData.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
installDate |
STRING |
1 |
Installation date to use for this I&M2 data. String encoding the date and time (optional) in accordance with ISO 8601, thus in the format 'YYYY-MM-DD[ HH:MM:SS]'. Will be filled with blanks automatically if time is omitted. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.ProfinetIO.setDapImInstallDate(installDate)setDapImTagFunction()
Short description
Sets the function tag (a.k.a. 'plant designation') forthe DAP’s (device access point) I&M1 data. The value will take effect on the fieldbus but only stored permanently after calling the function storeDapImData.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
tagFunction |
STRING |
1 |
Function tag to use for this I&M1 data. String with 32 visible characters. Will be filled with blanks automatically if shorter. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.ProfinetIO.setDapImTagFunction(tagFunction)setDapImTagLocation()
Short description
Sets the location tag (a.k.a. 'location identifier') forthe DAP’s (device access point) I&M1 data. The value will take effect on the fieldbus but only stored permanently after calling the function storeDapImData.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
tagLocation |
STRING |
1 |
Location tag to use for this I&M1 data. String with 22 visible characters. Will be filled with blanks automatically if shorter. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.ProfinetIO.setDapImTagLocation(tagLocation)setDeviceName()
Short description
Sets the name of the device in the Profinet network. This value will be applied after calling the function ProfinetIO.applyConfig.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceName |
STRING |
1 |
Device name to be applied. Needs to be a valid Profinet device name, otherwise the value will be rejected. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred or the name is invalid. |
Sample (auto-generated)
success = FieldBus.Config.ProfinetIO.setDeviceName(deviceName)setInterfaceConfig()
Short description
Sets the device’s IP data used in the Profinet network. The values will be applied after calling the function ProfinetIO.Device.applyConfig.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
1 |
IP address to be applied. Needs to be a valid IP address. |
netmask |
STRING |
1 |
Subnet mask to be applied. |
gateway |
STRING |
? |
Address of the gateway to be applied. Needs to be a valid IP address. Optional argument. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.ProfinetIO.setInterfaceConfig(ipAddress, netmask, gateway)storeConfig()
Short description
Stores the address data, previously applied with the function applyConfig.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.ProfinetIO.storeConfig()storeDapImData()
Short description
Stores the current values of the I&M data of the DAP permanently.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample (auto-generated)
success = FieldBus.Config.ProfinetIO.storeDapImData()Events
OnDeviceNameChanged
Short description
This event is notified when the name of the device has changed.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
deviceName |
STRING |
1 |
Currently active name of the device |
remanent |
BOOL |
1 |
True if the network configuration tool sets the current name of the device permanently, that is, it will be reloaded after a restart of the device. |
Sample (auto-generated)
function handleOnDeviceNameChanged(deviceName, remanent)
-- Do something
end
Script.register("FieldBus.Config.ProfinetIO.OnDeviceNameChanged", "handleOnDeviceNameChanged")OnFieldbusStorageRequest
Short description
This event is thrown when the fieldbus (stack) needs to store data permanently, for example address data or device name. The implementation of this event is mandatory since the fieldbus (stack) needs to store fieldbus specific data permanently which will be loaded after restart. This is a requirement to pass the certification tests. See the component’s documentation for an example implementation.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
storageHandle |
HANDLE |
1 |
Object containing the data to be saved or loaded |
Sample (auto-generated)
function handleOnFieldbusStorageRequest(storageHandle)
-- Do something
end
Script.register("FieldBus.Config.ProfinetIO.OnFieldbusStorageRequest", "handleOnFieldbusStorageRequest")OnInterfaceConfigChanged
Short description
This event is notified when the address, that is, the interface configuration, of the device has changed.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ipAddress |
STRING |
1 |
Currently active (applied) IP address |
subnetMask |
STRING |
1 |
Currently active (applied) subnet mask |
gateway |
STRING |
1 |
Currently active (applied) gateway address |
remanent |
BOOL |
1 |
True if the network configuration tool sets the current IP address settings permanently, that is, it will be reloaded after a restart of the device. |
Sample (auto-generated)
function handleOnInterfaceConfigChanged(ipAddress, subnetMask, gateway, remanent)
-- Do something
end
Script.register("FieldBus.Config.ProfinetIO.OnInterfaceConfigChanged", "handleOnInterfaceConfigChanged")OnLinkActiveChanged
Short description
This event is notified when the physical link status has changed.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
port |
ENUM |
1 |
Port the event is signaled for |
linkActive |
BOOL |
1 |
True if link is up, otherwise it is down |
Sample (auto-generated)
function handleOnLinkActiveChanged(port, linkActive)
-- Do something
end
Script.register("FieldBus.Config.ProfinetIO.OnLinkActiveChanged", "handleOnLinkActiveChanged")FieldBus.StorageRequest
Overview
Functions
getData()
Short description
Gets the data received in the StorageRequest. This data should be saved for example to a file if the StorageRequest is of the type SAVE.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Storage handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
1 |
Data of the StorageRequest |
Sample
data = StorageRequest.getData(storageHandle)getOperation()
Short description
Gets the type of the current StorageRequest, e.g. LOAD or SAVE.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Storage handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
operation |
ENUM |
1 |
Operation type |
Sample
operation = StorageRequest.getOperation(storageHandle)notifyResult()
Short description
Notifies the result of the operation. For example, if a SAVE operation failed, the application shall notify a result with 'false'.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Storage handle |
success |
BOOL |
1 |
True if the data could be saved or loaded. False if an error occurred. |
Sample
StorageRequest.notifyResult(storageHandle, true)setData()
Short description
Sets the data to the StorageRequest. This function is used in a LOAD operation to send the data back to the component that sent the StorageRequest. This data is usually loaded from a file.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Storage handle |
data |
BINARY |
1 |
Data from the application |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful. False if an error occurred. |
Sample
StorageRequest.setData(storageHandle, data)File
Short description
Provides file operation functions. Read more…
Overview
Detailed description
The application has access to different folders on the filesystem of the device.
There are the following app related paths:
-
The "resources" folder is read-only and can be used to read app resources like parameter files, images etc.
-
The "private" directory can be used to store persistent app data privately. This data is backup-ed together with the app.
-
The "public" directory can be used for shared access with other applications. All applications have access to this folder.
The "private" and "public" folders should only be used as persistent storage and NOT to continuously process data.
ATTENTION: The underlying hardware could get broken if overused! Consider to use API functions which don’t use files or use the ram filesystem mounted drive of the device.
Additionally it is possible to access the mounted drives of a device. Which mounted drives are available is defined by the device in a CROWN enum named "MountedDrives". E.g. there could be a path "/usb/0" for the first USB drive, or "/sdcard/0" for the first SD Card drive.
Functions
close()
Short description
Closes a file identified by a handle. If not explicitly called, the file is automatically closed on destruction of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle of an opened file. |
Sample (auto-generated)
File.close(handle)copy()
Short description
Copies the specified file or full path to another file or path. If the target file exists, it is overwritten. If the target path exists, it is integrated in the target structure.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileSourcePath |
STRING |
1 |
Path to copy from |
fileTargetPath |
STRING |
1 |
Path to copy to |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful, false if source path does not exist or cannot overwrite new files. |
Sample
local success = File.copy("/private/sourcefile.txt", "/private/targetfile.txt")del()
Short description
Deletes a file or folder specified by a path. The path must start with "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). Deleting the "public", "private" or mounted drive itself is not allowed and returns false. Their contents can be deleted by iterating on their elements.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
1 |
Path to the file/folder that is to be deleted |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful |
Sample
local success = File.del("/private/myfile.txt")exists()
Short description
Checks if the given path or file exists. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
1 |
Path to the file/folder that is to be checked |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
1 |
True if successful |
Sample
local bExists = File.exists("/private/myfile.txt")extractPathElements()
Short description
Splits the specified path string into its elements path, file basename and file extension.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filePath |
STRING |
1 |
Path string to extract from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
path |
STRING |
1 |
Path of the file |
basename |
STRING |
1 |
Base name of the file |
extension |
STRING |
1 |
File extension of the file |
Sample
local path, basename, extension = File.extractPathElements("/private/thefile.txt")getDiskFree()
Short description
Returns the remaining space of a specific path.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
path |
STRING |
1 |
The name of the path to get the free space from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
freeBytes |
INT |
? |
Number of available bytes in the path. |
Sample
local free = File.getDiskFree("/public")getDiskUsage()
Short description
Returns the usage of a specific path.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
path |
STRING |
1 |
Path to get the usage from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
usedBytes |
INT |
? |
Number of bytes used in the path. |
Sample
local usage = File.getDiskUsage("/public")getPath()
Short description
Returns the path of the file handle with which it was opened.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle of an opened file. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filePath |
STRING |
? |
Path to the file that was opened. Nil if file handle is not open. |
Sample (auto-generated)
filePath = File.getPath(handle)getPermissions()
Short description
Returns the permissions of a file. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
1 |
The path to the file |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
read |
BOOL |
? |
Read permission of the file. Nil on failure. |
write |
BOOL |
? |
Write permission of the file. Nil on failure. |
execute |
BOOL |
? |
Execute permission of the file. Nil on failure. |
Sample (auto-generated)
read, write, execute = File.getPermissions(fileName)getTimestamps()
Short description
Returns the creation time, last modification time and last access time of a file. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
1 |
The path to the file |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
creationTime |
INT |
1 |
Creation time of the file (Unix time). 0 if not supported or on failure. |
lastModificationTime |
INT |
1 |
Last modification time of the file (Unix time). 0 if not supported or on failure. |
lastAccessTime |
INT |
1 |
Last access time of the file (Unix time). 0 if not supported or on failure. |
Sample (auto-generated)
creationTime, lastModificationTime, lastAccessTime = File.getTimestamps(fileName)isdir()
Short description
Checks if the given path is a folder. The path must start with "resources", "public", "private"or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
1 |
Path to the file/folder |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
1 |
True if successful |
Sample
local isDir = File.isdir("/private/myfile.txt")list()
Short description
Lists all files and subdirectories in the specified directory non-recursively. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). Returns a list of file and directory names in the specified path.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filePath |
STRING |
1 |
Path to the folder to list |
filter |
STRING |
? |
A string to filter the results of the listing. Wildcards can be used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
list |
STRING |
* |
List of file and directory names. Nil if specified filePath does not exist or is not a directory. |
Sample
local fileList = File.list("/private/", "*.png")listRecursive()
Short description
Lists all files and subdirectories in the specified directory recursively (without empty folders). The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). Returns a list of file and directory names in the specified path.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filePath |
STRING |
1 |
Path to the folder to list |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
list |
STRING |
* |
List of file and directory names including the relative path to the specified directory. Nil if specified filePath does not exist or is not a directory. |
Sample
local fileList = File.listRecursive("/private/")mkdir()
Short description
Creates a new folder specified by a path. The path must start with "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
1 |
Path to the folder that is to be created |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful or folder already exists. False if not possible or is already a file. |
Sample
local success = File.mkdir("/private/myfolder")move()
Short description
Moves the specified file or full path to another file or path. If the target file exists, it is overwritten. If the target path exists, it is integrated in the target structure. If moving fails, parts of the source path may still exist, and the target path may be inconsistent or incomplete.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileSourcePath |
STRING |
1 |
Path to move from |
fileTargetPath |
STRING |
1 |
Path to move to |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful, false if source path does not exist or cannot overwrite new files. |
Sample
local success = File.move("/private/sourcefile.txt", "/private/targetfile.txt")open()
Short description
Opens a file specified by a path and mode.
Detailed description
The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
The mode specifies if it is for reading or writing and if it is in ASCII or binary mode (standard POSIX modes). The file is created if it does not exist and is opened for writing.
Returns a handle if successful, which needs to be used for further file functions.
Open for reading might fail if the file does not exist or is already opened for writing. Open for writing might fail if the file is already opened for reading or writing, or if the "resources" folder is opened for writing (which is read-only).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filePath |
STRING |
1 |
Path to the file that is to be opened |
mode |
STRING |
1 |
Use "r" or "rb" for reading, "w" or "wb" for writing, "a" or "ab" for append; "b" means binary, without "b" the OS could change control characters like CR or LF. Same syntax like in C fopen() |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
? |
An indicator for accessing the file. Returns nil on failure. |
Sample
local handle = File.open("/private/myfile.txt", "wb")position()
Short description
Returns the current position of the file pointer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle of an opened file. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
position |
INT |
1 |
Current position of the file pointer. |
Sample (auto-generated)
position = File.position(handle)read()
Short description
Reads data from a file identified by a handle. The number of bytes to read can be specified. Continuous calls to read continue to read at the current position. If a read returns a binary of size 0, then there is no more data to read.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle of an opened file. |
length |
INT |
? |
Number of bytes to read. Read the whole file if not specified or zero. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
? |
Data which was read from the file. Is nil if the file isn’t opened. Binary size is 0 if there is nothing more to read. |
Sample (auto-generated)
data = File.read(handle, length)seek()
Short description
Places the file pointer at the specified position. The next read will start at this position.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle of an opened file. |
position |
INT |
1 |
Position to jump to in the file. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if seeking in the file was successful. |
Sample (auto-generated)
success = File.seek(handle, position)size()
Short description
Returns the size of a file in bytes. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
1 |
Path to the file |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileSize |
INT |
1 |
Size of file in bytes |
Sample
local fileSize = File.size("/private/myfile.txt")write()
Short description
Writes to a file identified by a handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle of an opened file. |
data |
BINARY |
1 |
Data to write into the file |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the data was successfully written to the file. |
Sample (auto-generated)
success = File.write(handle, data)File.Archive
Short description
Contains functionality to pack/unpack files as an archive.
File.Archive.ZIP
Short description
File Archive functionality to work with ZIP files. Read more…
Overview
Detailed description
An archiver instance works with one ZIP archive at a time. To handle multiple ZIPs at a time, create multiple instances of the archiver. Loaded or added files must exist and are kept locked by this API until the handle is destroyed or close function is called. Both inflated and deflated ZIP archives can be read. ZIP file writing supports only inflated archives.
Functions
add()
Short description
Adds a file or whole directory from the filesystem to the archive. The specified file needs to exist and is locked until this class loads another zip file or the close() function is called. If there is already a file or folder with that archive path, it is overwritten.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
sourceFilePath |
STRING |
1 |
Path to the file or directory which should be added. E.g. '/private/sourceFile.txt' |
archiveFilePath |
STRING |
1 |
Path in the archive to which the file or directory should be added. Must be a full file path including file name. Sub-directories are created automatically. Existing file is overwritten. Pass empty string to add to root directory of the archive. E.g. 'archiveFolder/archiveFile.txt' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully added the file. False if the file does not exist. |
Sample
local success = File.Archive.ZIP.add(handle, "/private/sourceFile.txt", "archiveFolder/archiveFile.txt")create()
Short description
Creates a new ZIP archive instance to work on archives.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Sample (auto-generated)
handle = File.Archive.ZIP.create()del()
Short description
Deletes a file or whole directory (including added files all sub-directories) from the archive. If the archive is afterwards saved or serialized, the specified archive path will not be part of it.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
archiveFilePath |
STRING |
1 |
Path in the archive which should be deleted. E.g. 'archiveFolder/archiveFile.txt' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deleted the file or folder. False if there was nothing found in the archive path to delete. |
Sample
local success = File.Archive.ZIP.del(handle, "archiveFolder/archiveFile.txt")deserialize()
Short description
Loads a zip archive from the specified binary buffer. This is useful if zip file is already present in memory, so that it does not need to be stored to file to load it. E.g. if the zip file content is directly received from a TCPIP client or similar.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
archiveBuffer |
BINARY |
1 |
Binary buffer containing the whole archive. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully loaded the zip. False if the buffer content is not valid or no zip file. |
Sample (auto-generated)
success = File.Archive.ZIP.deserialize(handle, archiveBuffer)extract()
Short description
Extracts a file from the archive to the filesystem.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
archiveFilePath |
STRING |
1 |
Path in the archive from which the file or directory should be extracted. E.g. 'archiveFolder/archiveFile.txt'. Pass empty string to extract whole archive. |
targetFilePath |
STRING |
1 |
Path to the file or directory which should be extracted to. Sub-directories are created automatically. E.g. '/private/targetFile.txt' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully extracted the file. False if the file does not exist or could not extracted to the target path or password does not work on the file. |
Sample
local success = File.Archive.ZIP.extract(handle, "archiveFolder/archiveFile.txt", "/private/targetFile.txt")getComment()
Short description
If an archive is loaded, return the current comment set on the loaded archive. If the setComment function was used, it still returns the comment of the loaded archive and not the one which is newly set.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
comment |
STRING |
? |
The comment text is set on the loaded archive. Nil if there is no loaded archive. |
Sample (auto-generated)
comment = File.Archive.ZIP.getComment(handle)list()
Short description
Lists the content from the current loaded archive. The paths are relative and therefore don’t start with a leading "/".
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
content |
STRING |
+ |
List of file paths in the current loaded archive |
Sample (auto-generated)
content = File.Archive.ZIP.list(handle)load()
Short description
Loads a zip archive from the specified file. The loaded file will be locked until this class loads another zip file or the close() function is called. If loading fails, a previously loaded zip file state is cleared.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
sourceFilePath |
STRING |
1 |
Path to the zip file that is to be loaded. E.g. '/private/load.zip' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully loaded the zip. False if file does not exist or is no zip file. |
Sample
local success = File.Archive.ZIP.load(handle, "/private/load.zip")mkdir()
Short description
Creates an empty folder. If there is already a file or folder with that archive path, it is overwritten. Remember that files to be added don’t need a folder to be created first, so this function is only if there should be an empty folder in the archive. If it is a sub path, it creates the whole folder.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
archiveFilePath |
STRING |
1 |
Path in the archive which should be created as folder. E.g. 'archiveFolder/newFolder' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully created the new folder. |
Sample
local success = File.Archive.ZIP.mkdir(handle, "archiveFolder/newFolder")read()
Short description
Extracts a single file from the archive and returns it as binary buffer. This is useful if the file needs to be in memory so that it could be directly used for further processing. E.g. if the zip file is directly sent to TCPIP client or similar.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
archiveFilePath |
STRING |
1 |
Path in the archive from which the file or directory should be extracted. E.g. 'archiveFolder/archiveFile.txt' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileBuffer |
BINARY |
? |
Binary buffer containing the zip file. Nil on error if file does not exist or password does not work on the file. |
Sample
local buffer = File.Archive.ZIP.read(handle, "archiveFolder/archiveFile.txt")save()
Short description
Saves the current zip file state to the specified file path. Any existing file is overwritten.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
targetFilePath |
STRING |
1 |
Path to which the zip file is saved. E.g. '/private/save.zip' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully saved the zip file to the filesystem |
Sample
local success = File.Archive.ZIP.save(handle, "/private/save.zip")serialize()
Short description
Returns the current zip file state as content of a binary buffer. This is useful if the zip file needs to be in memory, so that it could be directly used for further processing. E.g. if the zip file content is directly sent to TCPIP client or similar.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
archiveBuffer |
BINARY |
1 |
Binary buffer containing the whole archive. The buffer could be empty on error. |
Sample (auto-generated)
archiveBuffer = File.Archive.ZIP.serialize(handle)setComment()
Short description
Sets the global archive comment text used for saving/serializing the archive.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
comment |
STRING |
1 |
The comment text which is set on the archive |
Sample (auto-generated)
File.Archive.ZIP.setComment(handle, comment)setCompression()
Short description
Sets the compression level to use for adding/writing new files to the archive. The deflate compression method is used. If not called, the default level is just to store the files without compression. The function can be called between add/write calls to change the compression level used for files. If not called before the last set value is used implicitly. Files, which are loaded from an existing archive, keep their compression and cannot be changed (Need to be removed and added again).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
complevel |
ENUM |
1 |
The level used for compression |
Sample
File.Archive.ZIP.setCompression(handle, "BEST")setPassword()
Short description
Sets the password used for decryption/encryption during accessing and writing the archive. Only the load/save and deserialize/serialize functions use the current set password. If not called, there is no password used. The password is globally set for all operations for the whole archive content. It is NOT possible to set passwords per file. Also if the to be loaded file uses different passwords per file, it currently isn’t possible to be loaded.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
password |
STRING |
1 |
Sets the password used for accessing and writing the archive. If empty, not password is used. |
Sample (auto-generated)
File.Archive.ZIP.setPassword(handle, password)test()
Short description
Fully tests and verifies the currently loaded archive. Needs some time and fully reads the file.
Detailed description
-
Tests if the set password works with all files
-
Reads all content and verifies their CRC32 checksums
-
Verifies the file infos and the central directory
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
valid |
BOOL |
? |
True if the archive is valid. False if one validation step has failed or no archive is loaded. |
Sample (auto-generated)
valid = File.Archive.ZIP.test(handle)write()
Short description
Adds a single file from the specified binary buffer. This is useful if the file is already present in memory, so that it does not need to be stored to a file to add it. E.g. if the zip file is directly received from a TCPIP client or similar. If there is already a file or folder with that archive path, it is overwritten.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
fileBuffer |
BINARY |
1 |
Binary buffer containing the zip file. |
archiveFilePath |
STRING |
1 |
Path in the archive to which the file or directory should be added. Must be a full file path including file name. Sub-directories are created automatically. Existing file is overwritten. E.g. 'archiveFolder/archiveFile.txt' |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully added the file. |
Sample
local success = File.Archive.ZIP.write(handle, buffer, "archiveFolder/archiveFile.txt")FTPClient
Short description
Provides FTP/FTPS/SFTP client functionality. Supports plain FTP, FTPS (FTP over SSL) and SFTP (SSH File Transfer Protocol). FTPS can be configured to be used in explicit or implicit mode. The specific protocol can be selected using the function FTPClient.setSecurityProtocol. Important note: If your application design requires FTP connections to be kept open in idle mode you must use the setKeepAliveInterval() function to enable keep-alive. Otherwise the internal connection is closed, resulting in an unnecessary reconnect when performing the next active operation.
Keywords
Ethernet
See also
Overview
Functions
cd()
Short description
Change the current directory on the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
directory |
STRING |
1 |
Directory to change to. Can be a relative or absolute path in FTP path notation. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if directory has been changed successfully, false if an error occurred |
Sample
success = FTPClient.cd(handle, "/absolute/path")connect()
Short description
Connect to a FTP server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
login |
STRING |
1 |
User name for login. |
password |
STRING |
1 |
Login password. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if connection is established, false if an error occurred |
Sample
success = FTPClient.connect(handle, "user", "password")create()
Short description
Creates a new FTP client instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
Sample
handle = FTPClient.create()deregister()
Short description
This function is used to deregister from any registered event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to deregister from |
callback |
STRING |
1 |
The function name which was registered on the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
Sample (auto-generated)
success = FTPClient.deregister(handle, eventname, callback)disconnect()
Short description
Disconnect an open connection to a FTP server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if connection is closed, false if an error occurred |
Sample
success = FTPClient.disconnect(handle)get()
Short description
Download a file from the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
filename |
STRING |
1 |
Target name of the file to download. Can be a relative or absolute path in FTP path notation. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if the file has been downloaded successfully, false if an error occurred. |
data |
BINARY |
1 |
Content of the file. |
Sample
success, data = FTPClient.get(handle, "/path/to/file")getFile()
Short description
Download a file from the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
remoteSource |
STRING |
1 |
Target name of the file to download. Can be a relative or absolute path in FTP path notation. |
localDestination |
STRING |
1 |
Destination path of the file to download. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if the file has been downloaded successfully, false if an error occurred. |
Sample
success = FTPClient.getFile(handle, "/path/to/file", "private/file")getLastError()
Short description
Get information about the last FTPClient method invocation. Returns error code and error text. In case communication with an FTP server has taken place, the FTP server code is delivered as code. This might be a error code or a success code. See https://en.wikipedia.org/wiki/List_of_FTP_server_return_codes. In case a libcurl error occurs it is returned as negative value. See https://curl.haxx.se/libcurl/c/libcurl-errors.html
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
errorCode |
INT |
1 |
Error code of the FTP server |
errorText |
STRING |
1 |
Additional information on the error |
Sample
errorCode, errorText = FTPClient.getLastError(handle)isConnected()
Short description
Returns whether the FTP client is connected to a server
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
connectStatus |
BOOL |
1 |
Is true if the connection exists |
Sample
connectStatus = FTPClient.isConnected(handle)list()
Short description
List the content of a directory on the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
directory |
STRING |
1 |
Directory to list. Can be a relative or absolute path in FTP path notation. |
onlyNames |
BOOL |
? |
If true (default), the FTP command NLST is used and only the names of the directory entries are returned. If false, the FTP command LIST is used instead. LIST returns additional information about each file, but the format is server-specific. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if directory has been listed successfully, false if an error occurred |
directoryEntries |
STRING |
* |
List of directory entries. |
Sample
success, directoryEntries = FTPClient.list(handle, "/absolute/path")mkdir()
Short description
Create a directory on the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
directory |
STRING |
1 |
Directory to create. Can be a relative or absolute path in FTP path notation. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if directory has been created successfully, false if an error occurred |
Sample
success = FTPClient.mkdir(handle, "/absolute/path")put()
Short description
Upload a file to the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
filename |
STRING |
1 |
Target name of the file to upload. Can be a relative or absolute path in FTP path notation. |
data |
BINARY |
1 |
Content of the file to upload. |
appendMode |
BOOL |
? |
Append mode. If true, the data is appended to the file if it already exists, otherwise the file is created. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if the file has been uploaded successfully, false if an error occurred. |
Sample
success = FTPClient.put(handle, "/path/to/file", data)putFile()
Short description
Upload a file to the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
remoteDestination |
STRING |
1 |
Target name of the file to upload. Can be a relative or absolute path in FTP path notation. |
localSource |
STRING |
1 |
Source path of the file to upload. |
appendMode |
BOOL |
? |
Append mode. If true, the data is appended to the file if it already exists, otherwise the file is created. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if the file has been uploaded successfully, false if an error occurred. |
Sample
success = FTPClient.putFile(handle, "/path/to/file", "resources/file")register()
Short description
This function is used to register for any event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to register to |
callback |
STRING |
1 |
The function name to call on the event occurrence |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if event does not exist. |
Sample (auto-generated)
success = FTPClient.register(handle, eventname, callback)rename()
Short description
Rename a file on the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
filenameFrom |
STRING |
1 |
File to rename. Can be a relative or absolute path in FTP path notation. |
filenameTo |
STRING |
1 |
New filename. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if the file has been renamed successfully, false if an error occurred. |
Sample
success = FTPClient.rename(handle, "fileOld.txt", "fileNew.txt")rm()
Short description
Remove a file on the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
filename |
STRING |
1 |
File to remove. Can be a relative or absolute path in FTP path notation. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if the file has been removed successfully, false if an error occurred. |
Sample
success = FTPClient.rm(handle, "file.txt")rmdir()
Short description
Remove a directory on the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
directory |
STRING |
1 |
Directory to remove. Can be a relative or absolute path in FTP path notation. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if directory has been removed successfully, false if an error occurred |
Sample
success = FTPClient.rmdir(handle, "/absolute/path")setCABundle()
Short description
Only relevant if FTPS is selected as security protocol, otherwise ignored. Configures the certificate authority bundle to be used for verifying server certificates.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTPClient. |
bundleFile |
STRING |
1 |
Path to a certificate bundle in PEM format. |
Sample
FTPClient.setCABundle(handle, "private/CA.pem")setClientCertificate()
Short description
Only relevant if FTPS is selected as security protocol, otherwise ignored. Enables client authentication. A client certificate and a private key must be provided. The passphrase for the private key is optional. Supported file formats are PEM, DER and PKCS#12 (depending on SSL engine) for the client certificate and PEM and DER for the private key. The format is selected by inspecting the extension of the provided file. If no valid extension is specified the engine defaults to PEM format.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTPClient. |
certificateFile |
STRING |
1 |
Path to a certificate file in PEM/DER/PKCS#12 format. |
keyFile |
STRING |
1 |
Path to file containing the client’s private key in PEM/DER format. |
passphrase |
STRING |
? |
Optional passphrase for the private key. |
Sample
FTPClient.setClientCertificate(handle, "private/cert.pem", "private/privateKey.pem", "mypassphrase")setConnectTimeout()
Short description
Configures the connect/accept timeout.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
timeoutMs |
INT |
1 |
Timeout for connect/accept in milliseconds. Default is 5000ms. |
Sample
FTPClient.setConnectTimeout(handle, 1000)setHostnameVerification()
Short description
Only relevant if FTPS is selected as security protocol, otherwise ignored. Enables/disables hostname verification. This can be useful if the site to connect to uses a different host name than what is mentioned in the server certificate commonName (or subjectAltName) fields. Disabling this verification makes the connection less secure.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTPClient. |
enabled |
BOOL |
1 |
True to enable hostname verification, false to disable. Default is enabled. |
Sample
FTPClient.setHostnameVerification(handle, false)setInterface()
Short description
Sets the interface to use for connecting.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
ifName |
ENUM |
1 |
One of the available interfaces |
Sample
FTPClient.setInterface(handle, "ETH1")setIpAddress()
Short description
Configures the ip address to connect to.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
ipAddress |
STRING |
1 |
IP address of the server. |
Sample
FTPClient.setIpAddress(handle, "192.168.0.20")setKeepAliveInterval()
Short description
Activates sending of keep-alive commands with a given time period. A time periode of 0 disables sending of keep-alive commands. Can be executed before or during a FTP connection. If the connection is found to be not working anymore, the event FTPClient.OnDisconnected is notified. This does not enable keep-alive on TCP level. Instead, a command is sent periodically to the server to make sure the connection still works. For FTP(S), this is the NOOP command. For SFTP, the content of the directory "/" is listed. If used in combination with the ResponseTimeout, the ResponseTimeout has to be bigger than the KeepAliveIntervall. Otherwise it could lead to the connection being lost. The ResponseTimeout will be adapted appropriately if needed.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
sec |
INT |
1 |
Time periode in seconds. |
Sample
FTPClient.setKeepAliveInterval(handle, 30)setLocalPortRange()
Short description
Configures the local source port range to use for outgoing TCP connections. If this function is not used, the default behavior is to select a free local source port automatically. Do not use this function unless the network environment makes it necessary, e.g. if a firewall which has such a rule is in place.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
portRangeFrom |
INT |
1 |
Beginning of port range for local ports. |
portRangeTo |
INT |
1 |
End of port range for local ports. |
Sample
FTPClient.setLocalPortRange(handle, 49150, 65535)setMode()
Short description
Sets the transfer mode for following file transfers. This setting is ignored if SFTP is selected as security protocol.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
mode |
ENUM |
1 |
Transfer mode that is to be set. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if mode has been set successfully, false if an error occurred |
Sample
success = FTPClient.setMode(handle, "binary")setPassiveMode()
Short description
Enable or disable the FTP passive mode. This can be done before connecting to a FTP server. Disabled passive mode is the default setting of the FTPClient. This setting is ignored if SFTP is selected as security protocol.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
state |
BOOL |
1 |
True set passive mode. False set active mode |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if the operation was successful. If false, use getLastError for more details on the error |
Sample
success = FTPClient.setPassiveMode(handle, true)setPeerVerification()
Short description
Only relevant if FTPS is selected as security protocol, otherwise ignored. Enables/disables peer verification. This can be useful when connecting to a site that is not using a certificate signed by one of the certs in the CA bundle. Disabling this verification makes the connection A LOT LESS SECURE.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTPClient. |
enabled |
BOOL |
1 |
True to enable peer verification, false to disable. Default is enabled. |
Sample
FTPClient.setPeerVerification(handle, false)setPort()
Short description
Configures the port to connect to. If not specified, the default behavior is to use the correct default port depending on the selected SecurityProtocol. The default ports are: FTP and FTPS_EXPLICIT: 21. FTPS_IMPLICIT: 990. SFTP: 22.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
port |
INT |
1 |
Port for connection. |
Sample
FTPClient.setPort(handle, 1234)setResponseTimeout()
Short description
Configures the amount of time the FTP server is allowed to take to send a response for a FTP command. If used in combination with the KeepAliveIntervall, the ResponseTimeout has to be bigger than the KeepAliveIntervall. Otherwise it could lead to the connection being lost. The ResponseTimeout will be adapted appropriately if needed.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
timeoutMs |
INT |
1 |
Timeout to wait for command response from server in milliseconds. Default is 5000ms. |
Sample (auto-generated)
FTPClient.setResponseTimeout(handle, timeoutMs)setSecurityProtocol()
Short description
Sets the security protocol to use.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTPClient. |
protocol |
ENUM |
1 |
Security protocol and mode to use. Default is none (plain FTP without TLS). To use FTPS, a certificate authority bundle needs to be configured. See function setCABundle. To use SFTP, it is recommended to provide a known_hosts file using the function setSSHKnownHostsFile. |
Sample
FTPClient.setSecurityProtocol(handle, "FTPS_EXPLICIT")setSSHKeyFile()
Short description
Set the client private key to use for authentication via SSH. Only relevant if SFTP is selected as security protocol, otherwise ignored.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTPClient. |
privateKeyFile |
STRING |
1 |
Path to file containing the client private key in OpenSSH private key format (PKCS#1). |
passphrase |
STRING |
? |
Optional passphrase for the private key. |
publicKeyFile |
STRING |
? |
Path to to file containing the client public key in OpenSSH Public Key Format (RFC 4253). Optional, because the public key can be calculated from the private key. This parameter can be used to explicitly specify the public key, which is useful in case the automatic calculation does not work as expected. |
Sample
FTPClient.setSSHKeyFile(handle, "private/cert.pem", "private/privateKey.pem", "mypassphrase")setSSHKnownHostsFile()
Short description
Only relevant if SFTP is selected as security protocol, otherwise ignored. Sets the SSH known hosts file to use for SFTP connections. If such a file is specified, FTPClient will only allow connections to servers that are known and present in that file. If the file is not specified, the server identity will not be checked in any way. Important Note: The supported Hostkey Types are: ssh-rsa, ssh-dss.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTPClient. |
keyFile |
STRING |
? |
Location of the SSH known_hosts file. The known_hosts file should use the OpenSSH file format. Supported Hostkey Types: ssh-rsa, ssh-dss. |
Sample
FTPClient.setSSHKnownHostsFile(handle, "resources/known_hosts")setTransmitTimeout()
Short description
Configures the transmit timeout.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
timeoutMs |
INT |
1 |
Timeout for transmits in milliseconds. Default is 5000ms. |
Sample
FTPClient.setTransmitTimeout(handle, 5000)setVerbose()
Short description
Tell the FTPClient to print log messages during the transfer. This includes the debug output of the curl library This method must be called before connecting to the FTP server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP client |
state |
BOOL |
1 |
True set the FTPClient in verbose state |
Sample
FTPClient.setVerbose(handle, true)Events
OnDisconnected
Short description
Event that is thrown when the FTPServer disconnects the connection. This is event is only notified when the function setKeepAliveInterval is used.
See also
Sample (auto-generated)
function handleOnDisconnected()
-- Do something
end
FTPClient.register(handle, "OnDisconnected", "handleOnDisconnected")FTPServer
Short description
Provides FTP server functionality. Create a new FTP server instance by calling the create function first. You may set the server port and the maximum number of connections via the setServerPort and setMaxConnections functions. Default is 21 for the server port and 10000 connections. Users may be added or removed using the addUser and removeUser functions. Login names must be unique per FTP server instance. Please note that you must add at least one user, even if you want anonymous login. Leave the password empty in that case. The data port range for PASV mode may be set with the setDataPortRange function. Several other parameters can be changed using the associated set functions, but meaningful default values have been selected already. Start the server using the start function and stop it (if needed) by calling stop.
Keywords
Ethernet
See also
Overview
Functions
addUser()
Short description
Add a user account
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
login |
STRING |
1 |
Login name for the user account |
password |
STRING |
1 |
Password for the user account. Leave empty to not check the password. |
startDirectory |
STRING |
1 |
Root directory for the user account. Only paths relative to the app home directory are allowed. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if user was added, false if an error occurred |
Sample
success = FTPServer.addUser(handle, "anonymous", "", "public")create()
Short description
Creates a new FTP server instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
Sample
handle = FTPServer.create()deregister()
Short description
This function is used to deregister from any registered event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to deregister from |
callback |
STRING |
1 |
The function name which was registered on the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
Sample (auto-generated)
success = FTPServer.deregister(handle, eventname, callback)register()
Short description
This function is used to register for any event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to register to |
callback |
STRING |
1 |
The function name to call on the event occurrence |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if event does not exist. |
Sample (auto-generated)
success = FTPServer.register(handle, eventname, callback)removeUser()
Short description
Remove a user account
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
login |
STRING |
1 |
Login name of the user account which is to be removed |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if user was removed, false if an error occurred |
Sample
success = FTPServer.removeUser(handle, "anonymous")setCheckPassDelay()
Short description
Configure the forced delay between subsequent login attempts in milliseconds
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
delay |
INT |
1 |
Delay between subsequent login attempts in milliseconds. Default is 500. |
Sample
FTPServer.setCheckPassDelay(handle, 5000)setDataPortRange()
Short description
Set the range of data ports available for PASV mode port selection
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
rangeBegin |
INT |
1 |
First port of range (inclusive). |
rangeEnd |
INT |
1 |
Last port of range (inclusive). |
Sample
FTPServer.setDataPortRange(handle, 5000, 6000)setInterface()
Short description
Sets the interface to use for connecting.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
ifName |
ENUM |
1 |
One of the available interfaces |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if interface was set successfully, false if an error occurred |
Sample
FTPServer.setInterface(handle, "ETH1")setMaxConnections()
Short description
Configures the maximum number of connections allowed on the control port.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
connections |
INT |
1 |
Maximum number of connections that is allowed. Default is 10000. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if max connections were set successfully, false if an error occurred |
Sample
success = FTPServer.setMaxConnections(handle, 100)setServerPort()
Short description
Configure the port number for the FTP server’s control connection.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
port |
INT |
1 |
Number of the port to listen on. Default is 21. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true if server port was set successfully, false if an error occurred |
Sample
success = FTPServer.setServerPort(handle, 33)setTransferBufferSize()
Short description
Sets the size of the transfer buffer used for data connections
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
bufferSize |
INT |
1 |
Buffer size for data connection transfers. Default is 32768. |
Sample
FTPServer.setTransferBufferSize(handle, 10000)start()
Short description
Start the FTP server
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true when the FTP server is running, false if an error occurred. |
Sample
success = FTPServer.start(handle)stop()
Short description
Stop the FTP server
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the FTP server |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Is true when the FTP server has been stopped successfully, false if an error occurred. |
Sample
FTPServer.stop(handle)Events
OnStore
Short description
The event which is triggered after a file has been uploaded.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
1 |
The name of the file that has been uploaded. |
filePath |
STRING |
1 |
The path where the file has been put. |
Sample (auto-generated)
function handleOnStore(fileName, filePath)
-- Do something
end
FTPServer.register(handle, "OnStore", "handleOnStore")GevImageConnector
Short description
Access to the GigEVision device component to stream images
Overview
Functions
addImage()
Short description
Add a list of 3 images ("distance_u16", "intensity_u16", "states_b16") to be send via GigEVision, the order is important!
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to be used. |
images |
[1+] |
The images to be send |
|
sensorData |
CONST_OBJECT |
[1+] |
additional data belonging to the images |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
return |
STRING |
1 |
Returns true on success |
Sample
local bSuccess = GevImageConnector.addImage(handle, [image1, image2, ..], [sensorData1, sensorData2, ..])create()
Short description
Create a new GevImageConnector instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
? |
The instance handle of the GevImageConenctor. Currently, it is only possible to create a single instance handle. Fails with return value nil when another instance handle already exists. |
Sample
handle = GevImageConnector.create()Hash
Short description
Namespace for different kinds of hash algorithms.
Hash.CRC32
Short description
CRC32 (cyclic redundancy check) algorithm, producing a fixed-length 32-bit hash value. Read more…
Detailed description
Two possibilities for usage:
-
Use the calculate()-function to calculate a single hash.
-
Create a handle: For multiple incremental calculations, useful if the input data is fragmented.
There are two result options:
-
Default is as bytes in a binary buffer
-
Alternative is as hex-ASCII values in a string
Functions
calculate()
Short description
Convenience function to do a single hash calculation in one function call. The hash result is returned as byte buffer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
1 |
Input data to calculate the hash from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hash |
BINARY |
1 |
Hash result as byte buffer with size of 4 bytes |
Sample (auto-generated)
hash = Hash.CRC32.calculate(data)calculateHex()
Short description
Convenience function to do a single hash calculation in one function call. The hash result is returned as hex-ASCII string.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
1 |
Input data to calculate the hash from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hash |
STRING |
1 |
Hash result as hex-ASCII string with size of 8 characters |
Sample (auto-generated)
hash = Hash.CRC32.calculateHex(data)create()
Short description
Creates a new instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Sample (auto-generated)
handle = Hash.CRC32.create()getHashValue()
Short description
Returns the current hash value as byte buffer. The current hash value is based on the data which was added before with calls to the update()-function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hash |
BINARY |
1 |
Hash result as byte buffer with size of 4 bytes |
Sample (auto-generated)
hash = Hash.CRC32.getHashValue(handle)getHashValueHex()
Short description
Returns the current hash value as hex-ASCII string. The current hash value is based on the data which was added before with calls to the update()-function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hashString |
STRING |
1 |
Hash result as hex-ASCII string with size of 8 characters |
Sample (auto-generated)
hashString = Hash.CRC32.getHashValueHex(handle)update()
Short description
Update the hash object with the specified data. This function can be called multiple times e.g. if not all data is currently available.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
data |
BINARY |
1 |
Input data to calculate the hash from |
Sample (auto-generated)
Hash.CRC32.update(handle, data)Hash.MD5
Short description
MD5 message-digest algorithm, producing a 128-bit hash value. Read more…
Detailed description
Two possibilities for usage:
-
Use the calculate()-function to calculate a single hash.
-
Create a handle: For multiple incremental calculations, useful if the input data is fragmented.
There are two result options:
-
Default is as bytes in a binary buffer
-
Alternative is as hex-ASCII values in a string
Functions
calculate()
Short description
Convenience function to do a single hash calculation in one function call. The hash result is returned as byte buffer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
1 |
Input data to calculate the hash from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hash |
BINARY |
1 |
Hash result as byte buffer with size of 16 bytes |
Sample (auto-generated)
hash = Hash.MD5.calculate(data)calculateHex()
Short description
Convenience function to do a single hash calculation in one function call. The hash result is returned as hex-ASCII string.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
1 |
Input data to calculate the hash from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hash |
STRING |
1 |
Hash result as hex-ASCII string with size of 32 characters |
Sample (auto-generated)
hash = Hash.MD5.calculateHex(data)create()
Short description
Creates a new instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Sample (auto-generated)
handle = Hash.MD5.create()getHashValue()
Short description
Returns the current hash value as byte buffer. The current hash value is based on the data which was added before with calls to the update()-function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hash |
BINARY |
1 |
Hash result as byte buffer with size of 16 bytes |
Sample (auto-generated)
hash = Hash.MD5.getHashValue(handle)getHashValueHex()
Short description
Returns the current hash value as hex-ASCII string. The current hash value is based on the data which was added before with calls to the update()-function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hashString |
STRING |
1 |
Hash result as hex-ASCII string with size of 32 characters |
Sample (auto-generated)
hashString = Hash.MD5.getHashValueHex(handle)update()
Short description
Update the hash object with the specified data. This function can be called multiple times e.g. if not all data is currently available.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
data |
BINARY |
1 |
Input data to calculate the hash from |
Sample (auto-generated)
Hash.MD5.update(handle, data)Hash.SHA256
Short description
SHA-2 (Secure Hash Algorithm 2) algorithm, producing a 256-bit hash value. Read more…
Detailed description
Two possibilities for usage:
-
Use the calculate()-function to calculate a single hash.
-
Create a handle: For multiple incremental calculations, useful if the input data is fragmented.
There are two result options:
-
Default is as bytes in a binary buffer
-
Alternative is as hex-ASCII values in a string
Functions
calculate()
Short description
Convenience function to do a single hash calculation in one function call. The hash result is returned as byte buffer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
1 |
Input data to calculate the hash from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hash |
BINARY |
1 |
Hash result as byte buffer with size of 32 bytes |
Sample (auto-generated)
hash = Hash.SHA256.calculate(data)calculateHex()
Short description
Convenience function to do a single hash calculation in one function call. The hash result is returned as hex-ASCII string.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
data |
BINARY |
1 |
Input data to calculate the hash from |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hash |
STRING |
1 |
Hash result as hex-ASCII string with size of 64 characters |
Sample (auto-generated)
hash = Hash.SHA256.calculateHex(data)create()
Short description
Creates a new instance.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Sample (auto-generated)
handle = Hash.SHA256.create()getHashValue()
Short description
Returns the current hash value as byte buffer. The current hash value is based on the data which was added before with calls to the update()-function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hash |
BINARY |
1 |
Hash result as byte buffer with size of 32 bytes |
Sample (auto-generated)
hash = Hash.SHA256.getHashValue(handle)getHashValueHex()
Short description
Returns the current hash value as hex-ASCII string. The current hash value is based on the data which was added before with calls to the update()-function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hashString |
STRING |
1 |
Hash result as hex-ASCII string with size of 64 characters |
Sample (auto-generated)
hashString = Hash.SHA256.getHashValueHex(handle)update()
Short description
Update the hash object with the specified data. This function can be called multiple times e.g. if not all data is currently available.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
data |
BINARY |
1 |
Input data to calculate the hash from |
Sample (auto-generated)
Hash.SHA256.update(handle, data)HTTPClient
Short description
Provides HTTP/HTTPS client functionality.
Overview
Functions
create()
Short description
Creates a HTTPClient handle.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
Sample
handle = HTTPClient.create()execute()
Short description
Execute a HTTP/HTTPS request synchronously
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
request |
OBJECT |
1 |
Instance handle of the request to execute. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
response |
CONST_OBJECT |
1 |
Instance handle of the response. |
Sample
HTTPClient.execute(handle)setAuthCredentials()
Short description
Enable HTTP Basic authentication method with username and password.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
username |
STRING |
1 |
Username for HTTP authentication. |
password |
STRING |
1 |
Password for HTTP authentication. |
Sample (auto-generated)
HTTPClient.setAuthCredentials(handle, username, password)setCABundle()
Short description
Configures the certificate authority bundle to be used for verifying server certificates.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
bundleFile |
STRING |
1 |
Path to a certificate bundle in PEM format. |
Sample
HTTPClient.setCABundle(handle, "private/CA.pem")setClientCertificate()
Short description
Enables client authentication. A client certificate and a private key must be provided. The passphrase for the private key is optional. Supported file formats are PEM, DER and PKCS#12 (depending on SSL engine) for the client certificate and PEM and DER for the private key. The format is selected by inspecting the extension of the provided file. If no valid extension is specified the engine defaults to PEM format.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
certificateFile |
STRING |
1 |
Path to a certificate file in PEM/DER/PKCS#12 format. |
keyFile |
STRING |
1 |
Path to file containing the client’s private key in PEM/DER format. |
passphrase |
STRING |
? |
Optional passphrase for the private key. |
Sample
HTTPClient.setClientCertificate(handle, "private/cert.pem", "private/privateKey.pem", "mypassphrase")setCookieSession()
Short description
Enables/disables starting of a new cookie session. For new cookie sessions, all session cookies loaded via function setCookieStore are discarded.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
discard |
BOOL |
1 |
True to discard session cookies, false to use them. Default is false. |
Sample (auto-generated)
HTTPClient.setCookieSession(handle, discard)setCookieStore()
Short description
Enables cookie handling and configures a file to be used as local cookie storage. Received cookies are stored in the file and when performing a request, valid cookies matching the server domain will be read from it.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
cookieFile |
STRING |
1 |
Path to file where the client’s cookies should be stored. |
Sample
HTTPClient.setCookieStore(handle, "private/cookies.txt")setFollowLocation()
Short description
Enables/disables following redirect of HTTP responses with HTTP status code 3xx.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
enabled |
BOOL |
1 |
True to enable HTTP redirection, false to disable. Default is disabled. |
Sample (auto-generated)
HTTPClient.setFollowLocation(handle, enabled)setHostnameVerification()
Short description
Enables/disables hostname verification. This can be useful if the site to connect to uses a different host name than what is mentioned in the server certificate commonName (or subjectAltName) fields. Disabling this verification makes the connection less secure.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
enabled |
BOOL |
1 |
True to enable hostname verification, false to disable. Default is enabled. |
Sample
HTTPClient.setHostnameVerification(handle, false)setInterface()
Short description
Sets the interface to be used for connecting.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
|
ifName |
ENUM |
1 |
One of the available interfaces. |
Sample
HTTPClient.setInterface(handle, "ETH1")setLocalPortRange()
Short description
Configures the local source port range to use for outgoing TCP connections. If this function is not used, the default behavior is to select a free local source port automatically. Do not use this function unless the network environment makes it necessary, e.g. if a firewall which has such a rule is in place.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient |
portRangeFrom |
INT |
1 |
Beginning of port range for local ports. |
portRangeTo |
INT |
1 |
End of port range for local ports. |
Sample
HTTPClient.setLocalPortRange(handle, 49150, 65535)setPeerVerification()
Short description
Enables/disables peer verification. This can be useful when connecting to a site that is not using a certificate signed by one of the certs in the CA bundle. Disabling this verification makes the connection A LOT LESS SECURE.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
enabled |
BOOL |
1 |
True to enable peer verification, false to disable. Default is enabled. |
Sample
HTTPClient.setPeerVerification(handle, false)setProxy()
Short description
Configures a proxy server to be used for the HTTP connections.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
url |
STRING |
1 |
Proxy URL in the format [protocol]://[hostname], e.g. http://my-proxy.domain.de |
port |
INT |
1 |
Proxy port number |
Sample
HTTPClient.setProxy(handle, "http://my.proxy", 8080)setProxyAuth()
Short description
Configures the proxy authentification settings to be used for the HTTP connections.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
username |
STRING |
1 |
Username for the proxy. |
password |
STRING |
1 |
Password for the proxy. |
Sample
HTTPClient.setProxyAuth(handle, "username", "password")setTimeout()
Short description
Sets the timeout for execution of HTTP requests in milliseconds. Default is 5000 milliseconds. If a host name is used instead of an IP address, the time needed to resolve the hostname via DNS is not subject to the timeout.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
timeout |
INT |
1 |
Timeout in milliseconds. |
Sample
HTTPClient.setTimeout(handle, 5000)setVerbose()
Short description
Enables/disable the verbose mode which prints a lot of debug information on the console during the execution of a request.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle of the HTTPClient. |
enabled |
BOOL |
1 |
True to enable verbose mode, false to disable. Default is disabled. |
Sample
HTTPClient.setVerbose(handle, true)HTTPClient.Request
Short description
Encapsulates the properties of a HTTP/HTTPS request.
Overview
Functions
addHeader()
Short description
Adds a header field to the request. There may be multiple header fields with the same key.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
OBJECT |
1 |
The request object. |
key |
STRING |
1 |
Key of the header field. |
value |
STRING |
1 |
Value of the header field. |
Sample (auto-generated)
HTTPClient.Request.addHeader(request, key, value)create()
Short description
Creates a request object.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
OBJECT |
1 |
The request object. |
Sample (auto-generated)
request = HTTPClient.Request.create()getContentBuffer()
Short description
Gets the content payload buffer if set.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
CONST_OBJECT |
1 |
The request object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
content |
BINARY |
? |
Binary or string containing the payload, or nil of not set. |
Sample (auto-generated)
content = HTTPClient.Request.getContentBuffer(request)getContentFile()
Short description
Gets the content file path if set.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
CONST_OBJECT |
1 |
The request object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
file |
STRING |
? |
Path to a file with the content that should be transferred as HTTP request payload, or nil of not set. |
Sample (auto-generated)
file = HTTPClient.Request.getContentFile(request)getContentType()
Short description
Gets the content type.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
CONST_OBJECT |
1 |
The request object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
contentType |
STRING |
1 |
Content mime-type specifier as described in RFC 2045/2046. |
Sample (auto-generated)
contentType = HTTPClient.Request.getContentType(request)getMethod()
Short description
Gets the HTTP method to be used.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
CONST_OBJECT |
1 |
The request object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
method |
ENUM |
1 |
Method type to be used. |
Sample (auto-generated)
method = HTTPClient.Request.getMethod(request)getPort()
Short description
Gets the port to be used for connecting to the HTTP server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
CONST_OBJECT |
1 |
The request object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
port |
INT |
1 |
Port to connect to. 0 means default is used: 80 for HTTP and 443 for HTTPS. |
Sample (auto-generated)
port = HTTPClient.Request.getPort(request)getURL()
Short description
Gets the URL of the HTTP server which is to be contacted.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
CONST_OBJECT |
1 |
The request object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
url |
STRING |
1 |
URL in the format [protocol]://[hostname]. The protocol can be 'http' or 'https'. |
Sample (auto-generated)
url = HTTPClient.Request.getURL(request)setContentBuffer()
Short description
Sets the content payload from a buffer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
OBJECT |
1 |
The request object. |
content |
BINARY |
1 |
Binary or string containing the payload. The payload format must match the mime-type configured as content type. |
Sample (auto-generated)
HTTPClient.Request.setContentBuffer(request, content)setContentFile()
Short description
Sets the content payload from a file.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
OBJECT |
1 |
The request object. |
file |
STRING |
1 |
Path to a file with the content that should be transferred as HTTP request payload. |
Sample (auto-generated)
HTTPClient.Request.setContentFile(request, file)setContentType()
Short description
Sets the content type.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
OBJECT |
1 |
The request object. |
contentType |
STRING |
1 |
Content mime-type specifier as described in RFC 2045/2046. |
Sample (auto-generated)
HTTPClient.Request.setContentType(request, contentType)setMethod()
Short description
Sets the HTTP method to be used.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
OBJECT |
1 |
The request object. |
method |
ENUM |
1 |
Method type to be used. |
Sample (auto-generated)
HTTPClient.Request.setMethod(request, method)setPort()
Short description
Sets the port to be used for connecting to the HTTP server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
OBJECT |
1 |
The request object. |
port |
INT |
1 |
Port to connect to. Defaults to 80 for HTTP and 443 for HTTPS. |
Sample (auto-generated)
HTTPClient.Request.setPort(request, port)setURL()
Short description
Sets the URL of the HTTP server which is to be contacted.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
request |
OBJECT |
1 |
The request object. |
url |
STRING |
1 |
URL in the format [protocol]://[hostname]. The protocol can be 'http' or 'https'. |
Sample (auto-generated)
HTTPClient.Request.setURL(request, url)HTTPClient.Response
Short description
Encapsulates a HTTP response.
Overview
Functions
getContent()
Short description
Retrieves the content payload of the response as binary.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
response |
CONST_OBJECT |
1 |
The response object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
content |
BINARY |
1 |
Content payload as binary. |
Sample (auto-generated)
content = HTTPClient.Response.getContent(response)getContentType()
Short description
Retrieves the Content-Type property of the content sent by the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
response |
CONST_OBJECT |
1 |
The response object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
contentType |
STRING |
1 |
Mime-type describing the content type of the response payload. |
Sample (auto-generated)
contentType = HTTPClient.Response.getContentType(response)getError()
Short description
Retrieves the error message describing the cause of the failure. If the request was successful (getSuccess() == true) this property is an empty string.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
response |
CONST_OBJECT |
1 |
The response object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
message |
STRING |
1 |
Error message describing the cause of the failure or an empty string if the request was successful. |
Sample (auto-generated)
message = HTTPClient.Response.getError(response)getErrorDetail()
Short description
Retrieves an informational message describing the details of the error.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
response |
CONST_OBJECT |
1 |
The response object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
message |
STRING |
1 |
Error message describing details of the failure. |
Sample (auto-generated)
message = HTTPClient.Response.getErrorDetail(response)getHeaderKeys()
Short description
Retrieves the list of header keys in the response.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
response |
CONST_OBJECT |
1 |
The response object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
headerKeys |
STRING |
* |
List of header keys. |
Sample (auto-generated)
headerKeys = HTTPClient.Response.getHeaderKeys(response)getHeaderValues()
Short description
Retrieves the values for a given header entry in the response. There may be multiple values for a single entry.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
response |
CONST_OBJECT |
1 |
The response object. |
key |
STRING |
1 |
Key of the entry to retrieve. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the key exists, false if not. |
value |
STRING |
* |
The values of the header entry or an empty list if the key didn’t exist. |
Sample (auto-generated)
success, value = HTTPClient.Response.getHeaderValues(response, key)getStatusCode()
Short description
Retrieves the HTTP status code returned by the server.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
response |
CONST_OBJECT |
1 |
The response object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
statusCode |
INT |
1 |
HTTP status code as specified in RFC 2616. |
Sample (auto-generated)
statusCode = HTTPClient.Response.getStatusCode(response)getSuccess()
Short description
Checks if the request was successful.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
response |
CONST_OBJECT |
1 |
The response object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the request was successful, false if not. Refer to the getError() and getErrorDetail() methods in case of failure. |
Sample (auto-generated)
success = HTTPClient.Response.getSuccess(response)HumiditySensorCrown
| This API is experimental |
Short description
Returns the current value of the Humidity Sensor.
Overview
Functions
getHumidity()
Short description
Returns the current humidity in %.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
humidity |
INT |
1 |
The humidity in %. |
Sample
humidity = HumiditySensorCrown.getHumidity()getHumidityPrecise()
Short description
Returns the current humidity with a higher precision in %.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
humidity |
FLOAT |
1 |
The humidity in %. |
Sample
humidity = HumiditySensorCrown.getHumidityPrecise()Image
Short description
Object for images, height maps, distance maps and similar data sampled on a regularly spaced grid. The samples are referred to as pixels whose values can be represented using different types such as unsigned integers (e.g., uint8, uint16), signed integers (e.g., int8, int16), floats (e.g., float32, float64) or RGB24 (3 times uint8 for the red, green and blue channels). The locations of the regular grid points can be described in physical world units, typically in millimeters, using the so-called image world coordinate system. The image world coordinate system is left-handed and aligned with the image axes, with the x-axis pointing from left to right, and a y-axis pointing from top towards bottom, and the origin at the upper left pixel. As the coordinate system is left-handed, positive rotations are specified clock-wise. The image coordinate system is specified as a world origin coordinate of the upper left pixel (pixel center) and a pixel size (e.g., in millimeters) in the x- and y-dimensions. The image world origin and pixel size are provided as meta data in the Image object. For regular gray scale/reflectance images captured by a 2D camera, the default world origin and pixel size are (0,0) and (1,1) respectively, so that the pixel index and image world coordinate system are the same. For height map and depth maps for which pixel values represent ranges in the physical world, there is also a scale factor available from raw pixel value to a physical world unit (typically millimeter). For compact notation, this scaling factor is referred to as pixel size in the z-dimension, and there is also a corresponding world origin in the z-dimension. The Image object meta data also has a 'missing data' flag that indicates if the value 0 is a reserved number representing the absence of measurement rather than the actual numeric value 0. Algorithms will then try to ignore missing data pixels in calculations instead of using the actual value 0. The missing data flag is only supported for unsigned integer types (uint8, uint16, etc) and not for signed types (int16, float32, etc.)
Overview
Functions
abs()
Short description
Computes the absolute value of each pixel. Image world coordinate system handling: The operation is not implemented for images with z-origin different from 0.0. The image metadata from the input image is copied to the output image. Missing data handling: There is no special handling of missing data as the value 0 remains 0 after the operation.
Keywords
arithmetic, magnitude, absolute
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
The absolute value image. |
Sample
result = Image.abs(image)absInplace()
Short description
Inplace version of the Image.abs function that modifies the input image. See base function for full documentation.
Keywords
arithmetic, magnitude, absolute
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
A reference to the result image. |
Sample
Image.absInplace(image)add()
Short description
Adds two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.
Keywords
arithmetic, sum
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. |
|
image2 |
1 |
The second source image. |
Sample
result = Image.add(image1, image2)addConstant()
Short description
Adds a constant value to all pixels in the image. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, the constant is interpreted in image world coordinate units, e.g., millimeters, and is rescaled to a raw pixel value using the z-pixelsize and z-origin of the image. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
arithmetic, level, plus, offset
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
constant |
FLOAT |
[1+] |
The constant interpreted in image world units (z-origin and z-pixelsize taken into account). A vector with three values (r, g, b) must be given if the input image is an RGB image. |
Sample
result = Image.addConstant(image, constant)addConstantInplace()
Short description
Inplace version of Image.addConstant function which modifies the input image. See base function for full documentation.
Keywords
arithmetic, level, plus, offset
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
constant |
FLOAT |
[1+] |
The constant interpreted in image world units (z-origin and z-pixelsize taken into account). A vector with three values (r, g, b) must be given if the input image is an RGB image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resultReference |
? |
Reference to the sum image. |
Sample
Image.addConstantInplace(image, constant)addInplace()
Short description
Inplace version of the Image.add function which modifies the first input image to contain the sum of the input images. See base function for full documentation.
Keywords
arithmetic, sum
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. This image is overwritten with the sum. |
|
image2 |
1 |
The second source image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.addInplace(image1, image2)addNoise()
Short description
Adds a uniform noise value in the range [a,b] to all pixels in the image. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a heightmap, distance or range image, the noise interval parameters [a,b] are interpreted in image world coordinate units, e.g., millimeters, and is rescaled to a raw pixel value using the z-pixelsize and z-origin of the image. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
random, uniform, white
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
a |
FLOAT |
1 |
Lower interval limit interpreted in image world units (z-origin and z-pixelsize taken into account). |
b |
FLOAT |
1 |
Upper interval limit interpreted in image world units (z-origin and z-pixelsize taken into account). |
randSeed |
INT |
? |
Random seed, optional. Default value is 0. |
Sample
result = Image.addNoise(image, 10, 100, 0)addNoiseInplace()
Short description
Inplace version of the Image.addNoise function that modifies the input image. See base function for full documentation.
Keywords
random, uniform, white
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
|
a |
FLOAT |
1 |
Lower interval limit interpreted in image world units (z-origin and z-pixelsize taken into account). |
b |
FLOAT |
1 |
Upper interval limit interpreted in image world units (z-origin and z-pixelsize taken into account). |
randSeed |
INT |
? |
Random seed, optional. Default value is 0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resultReference |
? |
A reference to the result image. |
Sample
Image.addNoiseInplace(image, 10, 100, 0)addPlane()
Short description
Adds the value of a plane function (Shape3D) to every pixel in an image. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. Image world coordinate system handling: The plane is interpreted in world space and added to the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
gradient, ramp
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
plane |
1 |
The plane to add, must be a Shape3D plane. |
|
region |
CONST_OBJECT |
? |
Region of the image where the plane should be added, default is the full image. An empty region or nil are interpreted as the full image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resultImage |
? |
The image with the added plane. Nil if an error occurred. |
Sample
resultImage = Image.addPlane(image, plane, region)addPlaneInplace()
Short description
Inplace version of the Image.addPlane function which modifies the input image by adding the value of a given plane. See base function for full documentation.
Keywords
gradient, ramp
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. This image is overwritten with the result image. |
|
plane |
1 |
The plane to add, must be a Shape3D plane. |
|
region |
CONST_OBJECT |
? |
Region of the image where the plane should be added, default is the full image. An empty region or nil are interpreted as the full image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.addPlaneInplace(image, plane, region)addPolynomial()
Short description
Adds the value of a 2nd order polynomial to every pixel in an image. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients. Image world coordinate system handling: The polynomial is interpreted in world space and added to the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
quadratic
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
region |
CONST_OBJECT |
? |
Region of the image where the polynomial is to be added, default is the full image. An empty region or nil are interpreted as the full image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resultImage |
? |
The image with the added polynomial. Nil if an error occurred. |
Sample
resultImage = Image.addPolynomial(image, polynomial, region)addPolynomialInplace()
Short description
Inplace version of the Image.addPolynomial function which modifies the input image by adding the value of a given polynomial. See base function for full documentation.
Keywords
quadratic
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. This image is overwritten with the result image. |
|
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
region |
CONST_OBJECT |
? |
Region of the image where the polynomial is to be added, default is the full image. An empty region or nil are interpreted as the full image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.addPolynomialInplace(image, polynomial, region)adjustOriginZ()
Short description
Adjusts the image z-origin to the given value in world coordinates, changing the raw pixel values such that the represented world coordinate values stays the same. Adjusting the z-origin to -10.0 will allow unsigned types to represent world-coordinate values from -10.0 and larger. Pixel values outside the range of the image type will be clamped. To set a new origin without changing the raw pixel values, offsetting the world coordinate values, see Image.setOriginZ. Image world coordinate system handling: The operation keeps pixel values in the world coordinate system constant, unless underflow or overflow occurs. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The input image image. |
|
newOriginZ |
FLOAT |
1 |
New origin in z-direction for image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resultImage |
? |
The image with the adjusted origin. Nil if an error occurred. |
Sample
resultImage = Image.adjustOriginZ(image, newOriginZ)adjustOriginZInplace()
Short description
Inplace version of the Image.adjustOriginZ function that modifies the input image. See base function for full documentation.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The input image image. |
|
newOriginZ |
FLOAT |
1 |
New origin in z-direction for image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resultImage |
? |
The image with the adjusted origin. Nil if an error occurred. |
Sample
resultImage = Image.adjustOriginZInplace(image, newOriginZ)aggregate()
Short description
Reduce an image to a profile along one spatial dimension, either rows or columns. If ROW is specified the aggregation will be in this direction. For a full image this produces a profile of the same length as the height of the input image. Missing data is handled and the delivered profile is in world coordinate units.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Image to aggregate. |
|
type |
1 |
The aggregation method. |
|
direction |
1 |
The direction to aggregate along. |
|
region |
CONST_OBJECT |
[?*] |
One or more optional regions. For each region one profile is returned. If unset one profile is returned for the whole image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
aggregate |
[?*] |
Profile(s) holding the combined data. Nil on failure. |
Sample
local aggregate = Image.aggregate(image, "SUM", "ROW")applyColormap()
Short description
Render an image into an RGB target image in the same way as the View.addImage function would. Image world coordinate system handling: The image content is converted and the coordinate system preserved except for the value dimensions. The value dimension is scaled according to the input parameters. Input RGB images are not supported. Missing data handling: Missing data values in the input will always be represented as a gray value independent of color map and datatype.
Keywords
paint, colorize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render into the output image. |
|
colormap |
CONST_OBJECT |
1 |
Provide the color map to use when converting the image. |
minZ |
FLOAT |
? |
The minimum world unit value in the source image that will be represented by the color map. |
maxZ |
FLOAT |
? |
The maximum world unit value in the source image that will be represetned by the color map. |
samples |
INT |
? |
The resolution of the color map. Default is 256 colors. |
invert |
BOOL |
? |
Select if the color map should be inverted. Eg. swapping all colors so that the first color is used last. |
Sample
image = Image.applyColormap(image, colormap, min, max)bilateral()
Short description
Applies a bilateral filter to an image. The bilateral filter is similar to a Gauss filter but it also adaptively modifies the filter kernel to avoid smoothing over image boundaries. Image world coordinate system handling: The kernel size in the range/z-dimension is interpreted in world scale, e.g., millimeters, it is internally divided by the z-pixelsize to get raw pixel value thresholds. The output image inherits the image world coordinates. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.
Keywords
edge preserving, filter, gauss, sigma, denoise
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, float32 and rgb24. |
|
kernelSizeSpatialPix |
INT |
1 |
Size of the kernel in pixels, must be positive and odd. |
kernelSizeRange |
FLOAT |
1 |
Range of intensity values that affect the filtering, must be positive. |
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
Sample
filteredImage = Image.bilateral(image, kernelSizeSpatialPix, kernelSizeRange)binarize()
Short description
Applies a threshold interval (lowerThreshold, upperThreshold) to the image to create a binary image. It is possible to binarize only a specified region. This function produces an image output, to directly produce a PixelRegion output use the threshold() function instead. Image world coordinate system handling: The input threshold values are interpreted in image world coordinates, i.e., they are converted to raw pixel thresholds within the function using the z-origin and z-pixelsize. As the output image is binary the output z-origin is set to 0 and the z-pixelsize to 1. The output image inherits the image world coordinates in the xy-dimensions. Missing data handling: Missing data pixels are set to background, i.e., to 0 in the output image. The output image has its missing data flag turned off regardless of the flag of the input image.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32 and float64. |
|
lowerThreshold |
FLOAT |
1 |
Lower threshold for the binarization in image world coordinates, i.e., the z-pixel size and origin are used so that the threshold is interpreted in millimeters in case the image is a height map/distance/range image. |
upperThreshold |
FLOAT |
? |
Upper threshold for the binarization in world coordinates. Optional, defaults to max value of the pixel type. |
outputValue |
INT |
? |
Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255. |
region |
CONST_OBJECT |
? |
Optional region of interest to consider when binarizing, values outside are set to zero. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
binarizedImage |
? |
Binarized image of pixel type uint8. |
Sample
thresholdImage = Image.binarize(image, lowerThreshold, upperThreshold, outputValue, region)binarizeAdaptive()
Short description
Applies an adaptive filter to the image to create a binary image. A pixel is set in the binary output image if the value is significantly larger than the average value in a surrounding region of specified size. The threshold is set as a delta value how much larger the pixel value must be in world coordinates, i.e, the delta threshold value is scaled internally with the pixel size in the z-dimension. In its base form, bright objects on dark background are found. There is a parameter to instead find dark objects on a bright background.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, currently only uint8 format is supported. |
|
deltaThresholdWorld |
FLOAT |
1 |
Threshold value, all pixels with a value higher than the mean in the surrounding region plus this threshold is set to outputValue |
kernelSizePix |
INT |
1 |
Size of the kernel in number of pixels, must be odd and greater than one. |
findBright |
BOOL |
? |
Set to true to find bright objects on dark background. Set to false to find dark objects on a bright background. Optional, default is true. |
outputValue |
INT |
? |
Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255. |
region |
CONST_OBJECT |
? |
Optional region of interest. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
binarizedImage |
? |
Adaptively binarized image. |
Sample
filteredImage = Image.binarizeAdaptive(image, deltaThresholdWorld, kernelSizePix, findBright, outputValue, region)binarizeCompare()
Short description
Binarizes an image by pixelwise comparison with a reference image. All pixels with a value greater than or equal to the corresponding reference image value are included in the binary output image. An optional margin (positive or negative) may be provided, adjusting the reference image values prior to the comparison. A larger positive margin results in fewer included pixels. The optional flag findBright may be set to false, returning the region where the image is lower/darker than the reference image. A region of interest can be provided, limiting the processing to that region. The images must be of the same pixel type and be of equal size. This function gives an Image object as output, to get a PixelRegion output use thresholdCompare instead. Image world coordinate system handling: To allow for an efficient comparison, the z-pixelsizes of the input images must be equal but the z-offsets may differ. The margin parameter is interpreted in image world coordinates, e.g., as a millimeter margin if the input is a range image. The output image inherits x,y-origin and x,y-pixelsizes but the z-origin is set to 0 and z-pixelsize to 1. Missing data handling: Missing data pixels are excluded from the output.
Keywords
adaptive, background, foreground, segmentation
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image to binarize. |
|
referenceImage |
1 |
Reference image to compare the input image with. |
|
marginWorld |
FLOAT |
? |
Optional offset of the reference image. Default value is 0. |
findBright |
BOOL |
? |
Optional flag indicating if pixels brighter/higher or darker/lower than the reference image should be included. Default is true, returning brighter pixels. |
outputValue |
FLOAT |
? |
Optional value for pixels in the output image mask, default 255. |
regionOfInterest |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. The default region is the entire image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
maskImage |
? |
Image containing all pixels passing the comparison operation. |
Sample
maskImage = Image.binarizeCompare(image, referenceImage, marginWorld, findBright, outputValue, regionOfInterest)binarizePlane()
Short description
Applies a threshold interval (lowerThreshold, upperThreshold) relative to the given plane to create a binary image from a height map. The threshold values accounts for world coordinates (pixel size and origin in the z-dimension) if applicable. It is possible to binarize only a specified region. The thresholds may both be negative or positive, allowing selecting values strictly below or above the reference. This function produces an image output, to directly produce a PixelRegion output use the thresholdPlane function instead. Image world coordinate system handling: The plane is interpreted in world space which is compared with the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the output image mask has the same pixel size and origin in x,y as the input image. Along the value axis z, the pixel size and origin are reset to unit and zero respectively. Missing data handling: No pixels marked as missing are included in the output mask. The missing data flag of the output mask image is cleared.
Keywords
adaptive, background, foreground, segmentation, binarize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, uint32, int8, int16, int32, float32 and float64. |
|
lowerThreshold |
FLOAT |
1 |
Lower threshold for the binarization in image world coordinates, i.e., the z-pixel size and origin are used so that the threshold is interpreted in millimeters in case the image is a height map/distance/range image. |
upperThreshold |
FLOAT |
1 |
Upper threshold for the binarization in world coordinates. |
plane |
1 |
The plane to which the lower and upper thresholds are related. The shape should be a plane. |
|
outputValue |
INT |
? |
Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255. |
region |
CONST_OBJECT |
? |
Optional region of interest to consider when binarizing, values outside are set to zero. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
binaryImage |
? |
Binarized image of pixel type uint8. |
Sample
binaryImage = Image.binarizePlane(image, lowerThreshold, upperThreshold, plane, outputValue, region)binarizePolynomial()
Short description
Applies a threshold interval (lowerThreshold, upperThreshold) relative to the given 2nd order polynomial to create a binary image. The threshold values accounts for world coordinates (pixel size and origin in the z-dimension) if applicable. It is possible to binarize only a specified region. The thresholds may both be negative or positive, allowing selecting values strictly below or above the reference. This function produces an image output, to directly produce a PixelRegion output use the thresholdPolynomial function instead. The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients. Image world coordinate system handling: The polynomial is interpreted in world space which is compared with the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the output image mask has the same pixel size and origin in x,y as the input image. Along the value axis z, the pixel size and origin are reset to unit and zero respectively. Missing data handling: No pixels marked as missing are included in the output mask. The missing data flag of the output mask image is cleared.
Keywords
adaptive, background, foreground, segmentation, binarize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. |
|
lowerThreshold |
FLOAT |
1 |
Lower threshold for the binarization in image world coordinates, i.e., the z-pixel size and origin are used so that the threshold is interpreted in millimeters in case the image is a height map/distance/range image. |
upperThreshold |
FLOAT |
1 |
Upper threshold for the binarization in world coordinates. |
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
outputValue |
INT |
? |
Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255. |
region |
CONST_OBJECT |
? |
Optional region of interest to consider when binarizing, values outside are set to zero. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
binaryImage |
? |
Binarized image of pixel type uint8. |
Sample
binaryImage = Image.binarizePolynomial(image, lowerThreshold, upperThreshold, polynomial, outputValue, region)bitShift()
Short description
Bit shifts all pixel values in an image of unsigned integer type. This is a fast way of multiplying or dividing (integer division) image values with powers of two. Negative shift length is used for division. Note that there are no overflow or underflow checks for this operation! The operation is performed correctly both for raw pixel values and world pixel values. There is a slight difference when shifting using positive values compared to a real multiplication when going out of bounds. The bitshift operation simply drops the most significant bit. For an image of uint8 and a pixel value of 255 this would mean that shifting once with a positive value would shift in one zero and thus producing a lower value than before (254). Ex. 1111 1111 << 0 (uint8 255) 1111 1110 << 0 (uint8 254) 1111 1100 (uint8 252) As can be seen the behavior is not the ideal once the limit of the data type is reached. To avoid this problem use a sufficiently large image data type, or to get the a saturating behavior, see Image.multiplyConstant. Image world coordinate system handling: If the image has a non-zero z-origin, the z-origin of the returned image is adjusted in order to keep the operation valid both for raw- and world pixels. All other origin values and all pixel sizes are respected and copied to the returned image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, additional pixels may be marked as missing.
Keywords
arithmetic, divide, scale, multiply
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
shifts |
INT |
1 |
The shift length in number of bits, each positive shift corresponds to multiplying with two. Each negative shift corresponds to division with two. |
Sample
result = Image.bitShift(image, shifts)bitShiftInplace()
Short description
Inplace version of Image.bitShift function which modifies the input image. See base function for full documentation.
Keywords
arithmetic, divide, multiply
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
|
shifts |
INT |
1 |
The shift length in number of bits, each positive shift corresponds to multiplying with two. Each negative shift corresponds to division with two. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.bitShiftInplace(image, shifts)blur()
Short description
Blurs an image using a constant normalized box filter kernel. Image world coordinate system handling: The box filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.
Keywords
box, boxcar, convolve, denoise, filter, smooth
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
|
kernelSizePix |
INT |
[1+] |
Size of the kernel, must be positive. Two values, {xsize ysize}, can be given to create an anisotrophic kernel. |
region |
CONST_OBJECT |
? |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false. |
preserveDetails |
BOOL |
? |
Optional flag to reduce detail loss. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
smoothImage |
? |
Output image blurred by the blur filter. Same type as input image. |
Sample
smoothImage = Image.blur(image, kernelSizePix)canny()
Short description
Applies Canny edge detection to find edges in an image. The Canny edge detection works with a dual threshold procedure: first strong edges are found using a high threshold value. A second lower threshold also detects weaker edges in the image, and the weaker edges that are connected with the stronger edges are kept in the output edge image. A non-maximum suppression operation is also applied to obtain 1-pixel wide edge responses. The Canny function currently only operates on uint8 images. Image world coordinate system handling: The input thresholds are interpreted in world scale, e.g., millimeters, they are internally divided by the z-pixelsize to get raw pixel value thresholds. The output image inherits the image world coordinates in the x,y-dimensions, but the z-pixelsize is set to 1 and the z-origin to 0. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.
Keywords
derivative, gradient, edge
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Currently only uint8 pixel type is supported. |
|
thresholdHigh |
FLOAT |
1 |
First/high threshold to find strong edges, for example a value of 100. |
thresholdLow |
FLOAT |
1 |
Second/low threshold for finding weaker edges connected with the strong edges, for example a value of 50. |
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
Sample
cannyImage = Image.canny(image, thresholdHigh, thresholdLow)clamp()
Short description
Clamps the pixel values to an interval [maxValue, minValue]. An optional region may be provided, limiting the processing to only that region. Pixels outside the region are left in an undefined state. Image world coordinate system handling: The [maxValue, minValue] parameters are interpreted as expressed in image world coordinate units, i.e., the clamp limits are scaled internally from world (millimeter) units to raw pixel values using the origin and pixelsize in the z-dimension. The image metadata from the input image is copied to the output image. Missing data handling: A missing data pixel in the input image results in a missing data pixel in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image. Setting the optional fillMissingData flag, missing data pixels will be set to the minimum clamp value. If this flag is set, the output image will have its missing data flag cleared.
Keywords
arithmetic, limit, clip
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
minValueWorld |
FLOAT |
1 |
The minimum value to clamp to interpreted in image world units (z-origin and z-pixelsize taken into account). |
maxValueWorld |
FLOAT |
1 |
The maximum value to clamp to in image world units (z-origin and z-pixelsize taken into account). |
region |
CONST_OBJECT |
? |
Optional region to process. Default is the entire image. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
Sample
result = Image.clamp(image, minValue, maxValue, region, fillMissingData)clampInplace()
Short description
Inplace version of the Image.clamp function that modifies the input image. See base function for full documentation.
Keywords
arithmetic, limit, clip
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
|
minValueWorld |
FLOAT |
1 |
The minimum value to clamp to interpreted in image world units (z-origin and z-pixelsize taken into account). |
maxValueWorld |
FLOAT |
1 |
The maximum value to clamp to in image world units (z-origin and z-pixelsize taken into account). |
region |
CONST_OBJECT |
? |
Optional region to process. Default is the entire image. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.clampInplace(image, minValue, maxValue, region, fillMissingData)clampPlane()
Short description
Clamps image pixel values to a plane from below, i.e., values are raised to the plane. In case of overflow, the value is instead clamped to the maximal representable value. A partial region of operation may be selected, reducing the processing time. All pixels outside the region are left in an undefined state. Image world coordinate system handling: The plane is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: By default, a missing data pixel in the input image generates a missing data pixel in the output image. If the fillMissingData flag is set to true, all pixels with missing data will be set to the plane value and the missing data flag of the output image will be cleared. In that case, the full range of raw pixel values may be used.
Keywords
limit, clip
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to clamp. |
|
plane |
1 |
The plane to clamp to, must be a Shape3D plane. |
|
region |
CONST_OBJECT |
? |
Optional region where clamping should be performed, default is the full image. An empty region or nil are interpreted as the full image. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
clampedImage |
? |
The clamped image. Nil if an error occurred. |
Sample
clampedImage = Image.clampPlane(image, plane, region, fillMissingData)clampPlaneInplace()
Short description
Inplace version of the Image.clampPlane function that modifies the input image. See base function for full documentation.
Keywords
limit, clip
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to clamp. This image is overwritten with the result image. |
|
plane |
1 |
The plane to clamp to, must be a Shape3D plane. |
|
region |
CONST_OBJECT |
? |
Optional region where clamping should be performed, default is the full image. An empty region or nil are interpreted as the full image. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.clampPlaneInplace(image, plane, region, fillMissingData)clampPolynomial()
Short description
Clamps image pixel values to a 2nd order polynomial from below, i.e., pixel values are raised to the polynomial. In case of overflow, the value is instead clamped to the maximal representable value. A partial region of operation may be selected, reducing the processing time. All pixels outside the region are left in an undefined state. The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients. Image world coordinate system handling: The polynomial is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: By default, a missing data pixel in the input image generates a missing data pixel in the output image. If the fillMissingData flag is set to true, all pixels with missing data will be set to the polynomial value and the missing data flag of the output image will be cleared. In that case, the full range of raw pixel values may be used.
Keywords
limit, clip
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to clamp. |
|
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
region |
CONST_OBJECT |
? |
Optional region where clamping is to be performed, default is the full image. An empty region or nil are interpreted as the full image. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
clampedImage |
? |
The clamped image. Nil if an error occurred. |
Sample
clampedImage = Image.clampPolynomial(image, polynomial, region, fillMissingData)clampPolynomialInplace()
Short description
Inplace version of the Image.clampPolynomial function that modifies the input image. See base function for full documentation.
Keywords
limit, clip
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to clamp. This image is overwritten with the result image. |
|
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
region |
CONST_OBJECT |
? |
Optional region where clamping is to be performed, default is the full image. An empty region or nil are interpreted as the full image. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.clampPolynomialInplace(image, polynomial, region, fillMissingData)clone()
Short description
Returns a duplicated instance of the input image. New memory to copy all pixel data is allocated.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
clone |
1 |
The new cloned image object. |
Sample (auto-generated)
clone = Image.clone(image)concatenate()
Short description
Concatenates two images or all images in a list. Image world coordinate system handling: The image world coordinate system is used to update the output image origin. The new origin depends on how each image is placed in relation to the previous image (direction), the different possibilities are: - ABOVE (Oxout, Oyout, Ozout) = (OxFirstImage, OyFirstImage-sum(imageHeight*imagePixelSizeY), OzFirstImage) - BELOW (Oxout, Oyout, Ozout) = (OxFirstImage, OyFirstImage, OzFirstImage) - RIGHT (Oxout, Oyout, Ozout) = (OxFirstImage, OyFirstImage, OzFirstImage) - LEFT (Oxout, Oyout, Ozout) = (OxFirstImage-sum(imageWidth*imagePixelSizeX), OyFirstImage, OzFirstImage) Where sum() indicates the sum of the written characteristics for all images except FirstImage, which here indicates either image1 (in the case of two separate input images) or the first image in the image1 list. All input images must have the same pixel size, inherited by the output image. For directions ABOVE and BELOW, the images must have the same width, while for directions RIGHT and LEFT they must have the same height. Missing data handling: The output image missing data flag is inherited from image1, or from the first image in image1 in the case of it being a list.
Keywords
union, join
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
[1+] |
Image or list of images. |
|
image2 |
? |
Optional second image, should only be set if image1 is a single image. |
|
direction |
? |
The direction of the concatenation, i.e. where to place each image in relation to the previous image. Default is to the right of the previous image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageOut |
? |
The concatenated image. |
Sample
local imageOut = Image.concatenate(image1, image2, "ABOVE")convolve()
Short description
Calculates the cross correlation of the input image with the selected kernel. Please note that although the filter is named convolve a cross correlation is calculated and not a convolution. If a convolution is required it can be achieved by rotating the kernel. The result of the cross correlation is cropped so that the output image has the same size as the input image. If the complete cross correlation output is required please pad the input image according to the kernel size. The pad function also allows to specify what border type to use. Border handling is so that the image values outside the image ROI are reflections of the values inside the ROI. Image world coordinate system handling: The convolve filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to relate ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels or toggle the missing data flag prior to calling this function.
Keywords
correlation, convolution
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32 and float64. |
|
kernel |
1 |
Input kernel matrix. |
|
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Pixel values outside the region are undefined. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
convolvedImage |
? |
Convolved output image. Nil on failure. |
Sample
convolvedImage = Image.convolve(image, kernel)create()
Short description
Creates a new image of a certain size and pixel type.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
width |
INT |
1 |
The image width in pixels. |
height |
INT |
1 |
The image height in pixels. |
type |
ENUM |
1 |
The pixel type, for example UINT8, INT16, FLOAT64. |
Sample (auto-generated)
image = Image.create(width, height, type)createFromMemory()
Short description
Creates a new image of a certain size and pixel type by copying the data of a binary buffer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
buffer |
BINARY |
1 |
The buffer containing the raw image data. |
width |
INT |
1 |
The image width in pixels. |
height |
INT |
1 |
The image height in pixels. |
type |
ENUM |
1 |
The pixel type, for example UINT8, INT16, FLOAT64. |
Sample (auto-generated)
image = Image.createFromMemory(buffer, width, height, type)crop()
Short description
Crops a subpart of an image, specified in pixel coordinates. A cropped image is a clone of the source data.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to crop. |
|
x |
INT |
1 |
The x position of the top-left corner of the cropped image in the source image. |
y |
INT |
1 |
The y position of the top-left corner of the cropped image in the source image. |
width |
INT |
1 |
The width of the cropped image. |
height |
INT |
1 |
The height of the cropped image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageCropped |
? |
Cropped image or nil on error. |
Sample (auto-generated)
imageCropped = Image.crop(image, x, y, width, height)cropRectify()
Short description
Crops the region defined by a rotated rectangle or a closed polyline, and also rotates/transforms the cropped image patch to become axis-aligned. The size of the output image is determined automatically to obtain approximately the same pixel resolution as the input image has unless one of the options to adjust the output size is used. If the crop region extends outside the input image borders, the corresponding pixels in the output image get the value 0. It’s possible to make the image smaller while maintaining the aspect ratio by setting only the scale parameter. A value below 1 will result in a smaller image. By setting either the width or the height parameter that side of the output image will be exactly this size. The other side will be scaled accordingly to maintain the aspect ratio. If both are set aspect ratio is not maintained. For a Shape Rectangle type region input, the function crops and rotates the content within the rectangle to a new image. The rotation of the input rectangle is reversed so that the output is defined by a zero-degree-rotated rectangle with the same width and height as the input rectangle. For a Shape Polyline type region input, it is a requirement that the polyline has exactly 4 points and that it encloses a convex region, e.g., it must not self-intersect. The function then crops the defined region and applies a homography transform to transform the content into an axis-aligned bounding box. The order of the four points in the polyline is relevant. The following mapping from points in the polyline to corners in the output image patch is made: - 1st point maps to upper left corner - 2nd point maps to upper right corner - 3rd point maps to lower right corner - 4th point maps to lower left corner. The transform from the input shape (Rectangle or Polyline region) and the output image is also provided. With this transform it is possible to map features, e.g., points, from the input image to the cropped image, and vice versa with the inverse of the transform. The transform is of rigid type when possible and of homography type otherwise. Image world coordinate system handling: New x,y pixel sizes are calculated, based on the input shape and input image. For example, a 90 degree rotated rectangle as a shape would just swap the pixel sizes in x and y in the output image. For non-rectangular shapes the average pixel sizes in the x,y-dimensions are used. Missing-data handling: For images with the missing data flag set, missing data aware sampling will be used and the output image will also set its missing data flag. Values being sampled outside of the image will get the value 0.
Keywords
align, box, homography, rectangle, rotate, transform, warp, cut
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to crop. |
|
shape |
1 |
Input Shape defining the region to crop. Must either be of Rectangle type or of Polyline type with 4 points enclosing a convex region with an area greater than 1. |
|
scale |
FLOAT |
? |
The relative scaling of the output image compared to the input. Default is 1. If width or height are set they override this parameter. |
width |
INT |
? |
The output width of the cropped image. |
height |
INT |
? |
The output height of the cropped image. |
interpolation |
ENUM |
? |
The resampling method. Default is LINEAR for images without missing data, and NEAREST for images with missing data. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageCropped |
? |
Cropped and rectified image. |
|
transform |
? |
Transformation from the input shape to the new image. The transform is of rigid type for a Rectangle shape input and of homography type otherwise. |
Sample
imageCropped, transform = Image.cropRectify(image, shape)cropRegion()
Short description
Crops the region defined by the bounding box of an input pixelregion. Optionally, padding around the bounding box can also be specified in order to extend it. The pixelregion bounding box is defined by the limits of its non-empty pixels. If the pixelregion contains values outside of the input image the intersection of the pixelregion with the image region is used. The output cropped pixelregion is a copy of the region corresponding to the padded pixelregion bounding box (crop region). The cropped image contains a copy of the values inside the crop region. The image size is equal to the size of the crop region, the pixel size is the same as the input image and the image origin value is equal to the top left corner of the crop region. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the origin changes to the value of the top left corner of the crop region. Missing-data handling: The missing data information is kept from the input image.
Keywords
bounding box, cut
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to crop |
|
region |
CONST_OBJECT |
1 |
Input region to crop around. The crop region is defined by the bounding box of the region. |
paddingPix |
INT |
? |
How much padding around the bounding box of the region that should be added in pixels. Optional, default value is 0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageCropped |
? |
The cropped image. Returns nil if the input padded pixelregion bounding box does not overlap with the input image. |
|
regionCropped |
? |
The region corresponding to the input pixelregion bounding box plus padding if used. Returns nil if the input padded pixelregion bounding box does not overlap with the input image. |
Sample
imageCropped, regionCropped = Image.cropRegion(image, region)deinterlace()
Short description
Deinterlaces an image which is assumed to be interlaced such that every Nth row belongs to the same channel. The output will be a vector of N images, one per channel. Image world coordinate system handling: All output images inherits the image world coordinate system of the input image, with the exception that the pixel size in Y will have been multiplied by the number of channels, to compensate for the fact that one step in the Y-direction in the output images corresponds to N steps in the input image. Missing data handling: The missing data flag is inherited from the input image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image with N interlaced channels. |
|
numChannels |
INT |
1 |
The number of channels in the image. The image height must be evenly divisible by this number. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
OBJECT |
* |
Vector containing the deinterlaced images. |
Sample
result = Image.deinterlace(image, numChannels)demosaic()
Short description
Bayer pattern demosaicing. Only UINT8 and UINT32 is supported. If an UINT32 image, each pixel (32bit) comes from 2x2 pixels with RGGB, where R is the least significant bits.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputImage |
1 |
Input bayer image must be of type UINT8 or UINT32. Anything else is not supported! |
|
desiredMode |
ENUM |
1 |
The desired demosaic mode according to pixel order |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputImage |
1 |
Output image, either RGB24 or UINT8 depending on the selected mode. |
Sample (auto-generated)
outputImage = Image.demosaic(inputImage, desiredMode)difference()
Short description
Computes the pixel-wise difference between two images, using a configurable difference operator. The images must be of equal size and pixel type, and have the same pixel size and origin in the z-dimension. Difference operators: ABS: Absolute difference, |image1 - image2|. SQUARE: Squared difference, (image1 - image2)^2. Return image type: The return image type for all integer image types is unsigned. For SQUARE difference operator, a larger integer type is returned, e.g. UINT16 if the input is INT8. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.
Keywords
arithmetic, minus, subtract
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. |
|
image2 |
1 |
The second source image. |
|
differenceMode |
ENUM |
? |
The type of difference operator to be used. Default is ABS. |
Sample
result = Image.difference(image1, image2, "SQUARE")distanceTransform()
Short description
Applies the distance transform operation on the input image. Each pixel in the output image gives the approximate Euclidean distance to the closest background pixel (value = 0) in the input image. Typically the input image is a binarized image with 0:s representing the background and some other value (e.g. 1 or 255) representing the foreground. Currently only the uint8 pixel type is supported. Image world coordinate system handling: The image world coordinate system is not considered in this function. The distances in the output image are in pixel units, i.e., not scaled with the world pixel sizes in x and y. The output image inherits the image world coordinate system of the input image in the x,y dimensions, but the z-origin is set to 0 and the z-pixelsize is set to 1 regardless of the input values. Missing data handling: The function does not consider the missing data flag of the input image. The missing data flag of the output will be set to false, i.e., no missing data.
Keywords
chamfer, manhattan, skeleton, euclidean
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, expected to be binary. Only uint8 type supported. |
|
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
distanceImage |
? |
Distance image with approximate Euclidean distance values, float32 type. |
Sample
distanceImage = Image.distanceTransform(image)divide()
Short description
Divides two images pixelwise. The images must be of equal size and pixel type. A division-by-zero leads to a 0 in the output image. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate value. The second image is treated as a unit-less modifier and it must therefore have a standard image world coordinate system with pixel sizes all equal to 1 and origins equal to 0. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. In case of an underflow in the arithmetic, raw pixel values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
arithmetic, ratio
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. |
|
image2 |
1 |
The second source image. |
Sample
result = Image.divide(image1, image2)divideInplace()
Short description
Inplace version of the Image.divide function which modifies the first input image to contain the ratio of the input images. See base function for full documentation.
Keywords
arithmetic, ratio
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. This image is overwritten with the image ratio. |
|
image2 |
1 |
The second source image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.divideInplace(image1, image2)drawPixelRegion()
Short description
Render one or several PixelRegions into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The View.PixelRegionDecoration object is used to set the color of the rendered regions. Image world coordinate system handling: The input PixelRegion is interpreted in raw pixel coordinates, the image world coordinate system is not considered. Missing data handling: This function does not use the missing data flag.
Keywords
display, fill, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the region(s) into. Supported image types are UINT8 and RGB. |
|
regions |
CONST_OBJECT |
[1+] |
The region(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the region(s) are to be rendered. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. |
Sample
image = Image.drawPixelRegion(image, regions, decoration)drawPixelRegionInplace()
Short description
Inplace version of the Image.drawPixelRegion function which modifies the input image. See base function for full documentation.
Keywords
display, fill, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the region(s) into. Supported image type is RGB. |
|
shapes |
CONST_OBJECT |
[1+] |
The region(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the region(s) are to be rendered. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. Reference to input image. |
Sample
image = Image.drawPixelRegionInplace(image, regions, decoration)drawPoint()
Short description
Render the position of one or several points into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. to RGB. The View.ShapeDecoration object is used to set graphical properties. The following parameters in the ShapeDecoration object are supported: - The LineColor property is used to set the color of the points. - The PointType property is used to render points as circles or crosses. - The PointSize property is used to set the size of the rendered points. Image world coordinate system handling: The points coordinates are interpreted as world coordinates. That is, the coordinate system of the image is used to place the points properly. Missing data handling: This function does not use the missing data flag.
Keywords
display, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the point(s) into. Supported image types are UINT8 and RGB. |
|
points |
[1+] |
The points (2D) that are to be rendered in the image. |
|
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the point(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. |
Sample
image = Image.drawPoint(image, points, decoration)drawPointCloud()
Short description
Render one or several pointclouds into an image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The x- and y- coordinates of each point in the pointcloud are used to place each point into the image world coordinate system. Points are rendered using the information in the PointCloudDecoration object. The following properties in the PointCloudDecoration object are supported: - The ZRange or IntensityRange parameters: If there is a ZRange set, the colors of the rendered points will be based on the z-values. Otherwise the intensity component of each point is used, either using the IntensityRange parameter or using the default range for intensity colors which is 0 to 1. - The PointSize parameter. Image world coordinate system handling: The world coordinate system of the image if respected and each point in the pointcloud is drawn at the corresponding image position. Missing data handling: This function does not use the missing data flag.
Keywords
display, fill, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the point clouds(s) into. Supported image types are UINT8 and RGB. |
|
pointcloud |
CONST_OBJECT |
[1+] |
The point clouds(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the point clouds(s) are to be rendered. Not all properties of the PointCloudDecoration object are supported, see the main function description. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. |
Sample
image = Image.drawPointCloud(image, pointcloud, decoration)drawPointCloudInplace()
Short description
Inplace version of the Image.drawPointCloud function which modifies the input image. See base function for full documentation.
Keywords
display, fill, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the point clouds(s) into. Supported image type is RGB. |
|
pointcloud |
CONST_OBJECT |
[1+] |
The point clouds(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the point clouds(s) are to be rendered. Not all properties of the PointCloudDecoration object are supported, see the main function description. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. |
Sample
image = Image.drawPointCloudInplace(image, pointcloud, decoration)drawPointInplace()
Short description
Inplace version of the Image.drawPoint function which modifies the input image. See base function for full documentation.
Keywords
display, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the point(s) into. Supported image type is RGB. |
|
points |
[1+] |
The points (2D) that are to be rendered in the image. |
|
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the point(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. Reference to input image. |
Sample
image = Image.drawPointInplace(image, points, decoration)drawProfile()
Short description
Render one or several profiles into an image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. For profiles with 1D coordinates the coordinate vector is mapped to the x-axis of the image and the value vector to the y-axis. Each sample in the profile is then drawn in the image world coordinate system. For profiles with 2D coordinates the value vector is discarded and the profile is drawn on its coordinates in the image world coordinate system. Note: This function differs from the View.addProfile function in that it does not provide the full graph plotting functionality as a dedicated graph viewer does, e.g., coordinate axes, background grids etc. are not rendered with the drawProfile function. Color and line width properties are controlled using the View.GraphDecoration object. The two properties used for this are the GraphColor and DrawSize properties in the GraphDecoration object. No other properties in the GraphDecoration are currently supported. Image world coordinate system handling: The world coordinate system of the image if respected and each profile is drawn at the corresponding image position. Missing data handling: This function does not use the missing data flag.
Keywords
display, fill, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the profile(s) into. Supported image types are UINT8 and RGB. |
|
profiles |
[1+] |
The profile(s) that are to be rendered in the image. |
|
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the profiles(s) are to be rendered. The DrawSize (line width) and GraphColor (line color) properties are supported. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. |
Sample
image = Image.drawProfile(image, profiles, decoration)drawProfileInplace()
Short description
Inplace version of the Image.drawProfile function which modifies the input image. See base function for full documentation.
Keywords
display, fill, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the profile(s) into. Supported image type is RGB. |
|
profiles |
[1+] |
The profile(s) that are to be rendered in the image. |
|
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the profiles(s) are to be rendered. The DrawSize (line width) and GraphColor (line color) properties are supported. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. |
Sample
image = Image.drawProfileInplace(image, profiles, decoration)drawShape()
Short description
Render the position of one or several shapes into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The View.ShapeDecoration object is used to set graphical properties. The following parameters in the ShapeDecoration object are supported: - The LineColor property is used to set the border color of the rendered shape. - The FillColor property is used to set the fill color of the rendered shape. - The LineWidth property is used to set width of the border. Image world coordinate system handling: The shape coordinates are interpreted as world coordinates. That is, the coordinate system of the image is used to place the shapes properly. Missing data handling: This function does not use the missing data flag.
Keywords
display, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the shape(s) into. Supported image types are UINT8 and RGB. |
|
shapes |
[1+] |
The shape(s) that are to be rendered in the image. |
|
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the shape(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. |
Sample
image = Image.drawShape(image, shapes, decoration)drawShapeInplace()
Short description
Inplace version of the Image.drawShape function which modifies the input image. See base function for full documentation.
Keywords
display, overlay, paint, plot, print, render, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the shape(s) into. Supported image type is RGB. |
|
shapes |
[1+] |
The shape(s) that are to be rendered in the image. |
|
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the shape(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
RGB image with rendered overlay. Reference to input image. |
Sample
image = Image.drawShapeInplace(image, shapes, decoration)drawText()
Short description
Renders text into an image by modifying the pixel values. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. Not all features of the TextDecoration input are supported. Features that are supported are the following: * Position - Fully supported. * Color - Does not support opacity. * Size - Approximately matching to viewer settings. * Font family - SANSSERIF and SERIF are supported, MONOSPACE is unsupported. * Font weight - Fully supported, but does not exactly match viewer behavior. * Horizontal alignment - Full support apart from JUSTIFY, but does not exactly match viewer behavior. * Vertical alignment - Fully supported, but does not exactly match viewer behavior Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The font position will adjust to the image coordinate system, but the font size will only scale with the y-resolution. Missing data handling: This function does not use the missing data flag.
Keywords
characters, display, draw, letters, overlay, paint, plot, print, render, write, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the text into. This image is overwritten with the rendered text. Supported image types are UINT8 and RGB. |
|
text |
STRING |
1 |
The characters that cannot be rendered using the specified font are replaced by question marks. |
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the text should be rendered. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
RGB image with rendered overlay. |
Sample
result = Image.drawText(image, text, decoration)drawTextInplace()
Short description
Inplace version of the Image.drawText function that modifies the input image. See base function for full documentation.
Keywords
characters, display, draw, letters, overlay, paint, plot, print, render, write, rasterize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the text into. This image is overwritten with the rendered text. Supported image type is RGB. |
|
text |
STRING |
1 |
The characters that cannot be rendered using the specified font are replaced by question marks. |
decoration |
CONST_OBJECT |
1 |
A decorator that describes how the region(s) should be rendered. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
RGB image with rendered overlay. Reference to input image. |
Sample
result = Image.drawTextInplace(image, text, decoration)edgeStrength()
Short description
Calculates the edge strength using the maximum of the central differences (the diagonal directions are also considered). Image world coordinate system handling: The origin and pixel size of the output image is set the same as for the input image, except that the output image z origin will always be zero. And, if the output type is 'squared', then the output image pixelSizeZ is inputPixelSizeZ*inputPixelSizeZ. Missing data handling: The output image missing data flag is the same as the input, and the pixels that contain missing data will be kept. If the current pixel is not missing data but some of its neighbors (used to calculate the edge strength) are considered to have the value of zero. This function only accepts missing data images of types: uint8, uint16 and uint32.
Keywords
convolve, derivative, gradient, edge
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, uint32, int8, int16, int32, float32 and float64. |
|
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the edge strength is only calculated within this region. This can save a lot of computation time, if the region is small. The image values outside the region will be set to zero. |
step |
INT |
? |
Difference step in pixels (used to calculate the edge strength), must be greater than or equal to 1. The default value is 1. |
squared |
BOOL |
? |
Select edge strength output value is squared or not. The faster alternative is to use the squared output, because internally a square root calculation is avoided. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageEdgeStrength |
? |
Output image with the edge strength or edge strength squared. If the input image is of type: uint8, int8, uint16 or int16 the result is uint32. If the input image is of type: uint32 or int32 the result is uint64. If the input image is of type: float32 or float64 the result is float64. |
Sample
imageEdgeStrength = Image.edgeStrength(image)equalizeHistogram()
Short description
Applies histogram equalization to an image.
Keywords
contrast, intensity, normalize, stretch, scale
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Only uint8 type supported. |
|
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
equalizedImage |
? |
Equalized image |
Sample
equalizedImage = Image.equalizeHistogram(image)exp()
Short description
Applies the natural exponential to the value at each pixel. The output will be an image of type FLOAT32 (or FLOAT64 in case the input is already FLOAT64). Image world coordinate system handling: The z-scale of the image is considered. The image metadata from the input image is copied to the output image except for the z-scale and z-origin, values are instead stored in world coordinates directly. Missing data handling: Missing data is not supported and the missing data flag must be toggled off.
Keywords
arithmetic, cube, exp, exponent, inverse, invert, logarithm, power, sqr, sqrt, square, exponential
See also
Sample
result = Image.exp(image)extractColumnProfile()
Short description
Extracts profile(s) from an image column(s). The number of samples in the profile is always the same as the number of pixels between the start and end row (end position is included). Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The image column to extract from is provided as a zero-based integer pixel coordinate. The coordinate representation in the generated Profile object will be of implicit 2D or 1D type. Default is 2D, where the start point is the (x,y) world coordinates of the first extracted pixel in the image column and the delta vector the spacing between pixels in the y-dimension. Optionally, 1D coordinates can be returned, in which case the sample coordinates are set to the y-coordinates of the sampled pixels. Missing data handling: Valid data flags are enabled in the output profile if and only if the image contains missing data. Points sampled on missing data pixels are marked as invalid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. All pixel types are supported. |
|
column |
INT |
[1+] |
The column(s) to extract as a profile. |
startRow |
INT |
? |
The first row index to extract. If no index is given 0 will be used. |
stopRow |
INT |
? |
The last row index extract. If no index is given the image height-1 will be used. |
sampleCoordinates1D |
BOOL |
? |
If set to true, the output profile will have implicit 1D coordinates, keeping only the y-coordinates of the sample points. Default is false, generating implicit 2D sample coordinates. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
profile |
[?*] |
Sampled profile, or nil if unsuccessful. |
Sample
local profile = Image.extractColumnProfile(image, column, startRow, stopRow)extractEdgeProfile()
Short description
Samples an edge relative to a polyline. The sampling is done by placing a number of probe lines along the polyline. The probe lines are placed orthogonal to each segment of the polyline. If an edge point is not found along a given probe line, the corresponding sample in the output profiles is marked as invalid. The distance between each probe line along the polyline is min(pixelSizeX, pixelSizeY). Coordinate system handling: The sample coordinates in the edgeDistance profile are the 1D distances along the polyline, in world coordinates. The sample coordinates in the edgeStrength profile are the positions of the found edges in the image, in world coordinates. Missing data handling: Edges between data and missing data are valid in images with missing data.
Keywords
line segment, sample
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. All pixel types are supported. |
|
polyLine |
1 |
Polyline to sample along, in world coordinates. |
|
maxDistance |
FLOAT |
? |
Maximum distance to edge from polyline in world units. Optional, default 10.0. |
contrastThreshold |
FLOAT |
? |
Edge strength threshold. Optional, no threshold is default. |
selection |
? |
Edge selection criteria. See Image.ShapeFitter.setSelection() for details. Default: STRONGEST. |
|
polarity |
? |
Edge polarity. See Image.ShapeFitter.setPolarity() for details. Default: ANY. |
|
side |
ENUM |
? |
Edge side. See Image.ShapeFitter.setSide() for details. Default: CENTER. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
edgeDistance |
? |
Profile with distances to edges in world coordinates, or nil if unsuccessful. |
|
edgeStrength |
? |
Profile with edge strength, or nil if unsuccessful. |
Sample
local edgeDistances, edgeStrength = Image.extractEdgeProfile(image, polyLine, maxDistance, contrastThreshold, selection, polarity, side, edgeDistance, edgeStrength)extractProfile()
Short description
Samples image values evenly along a contour defined by a 2D Shape object and generates a Profile object. Supported shape types are line segment, arc, circle and polyline. Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The coordinate representation in the generated Profile object will be of implicit type if the contour shape allows it. For example, coordinates along a line segment contour can be represented using the implicit start + delta vector representation. For more complex contours such as a circle, an explicit coordinate representation is used in the Profile object where all the sample points are stored as individual entries. If the contour shape is closed, e.g., a circle, the closed flag in the Profile is also set. Missing data handling: Valid data flags are enabled in the output profile if and only if the image has missing data activated. Points sampled on missing data are marked as invalid. Points sampled outside the image are marked as invalid. In the latter case and if the image does not have missing data activated, the valid flags of the generated profile are set accordingly but are not enabled.
Keywords
line segment, sample
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. All pixel types are supported. |
|
shape |
[1+] |
The shape, or a list of shapes to sample along. Supported shapes are line segment, arc, circle and polyline. |
|
sampleCount |
INT |
1 |
The number of samples to take, evenly spaced along the input shape. |
interpolation |
ENUM |
? |
Interpolation method, NEAREST or LINEAR. Default is NEAREST. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
profile |
[?*] |
Generated Profile object or a list of Profile objects. Nil if unsuccessful. |
Sample
local profile = Image.extractProfile(image, shape, sampleCount, interpolation)extractRowProfile()
Short description
Extracts profile(s) from an image row(s). The number of samples in the profile is always the same as the number of pixels between the start and end column (end position is included). Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The image row to extract from is provided as a zero-based integer pixel coordinate. The coordinate representation in the generated Profile object will be of implicit 2D or 1D type. Default is 2D, where the start point is the (x,y) world coordinates of the first extracted pixel in the image row and the delta vector the spacing between pixels in the x-dimension. Optionally, 1D coordinates can be returned, in which case the sample coordinates are set to the x-coordinates of the sampled pixels. Missing data handling: Valid data flags are enabled in the output profile if and only if the image contains missing data. Points sampled on missing data pixels are marked as invalid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. All pixel types are supported. |
|
row |
INT |
[1+] |
The row(s) to extract as a profile, zero-based. |
startColumn |
INT |
? |
The first column index to extract, zero-based. If no index is given 0 will be used. |
stopColumn |
INT |
? |
The last column index extract, zero-based. If no index is given the image width-1 will be used. |
sampleCoordinates1D |
BOOL |
? |
If set to true, the output profile will have implicit 1D coordinates, keeping only the x-coordinates of the sample points. Default is false, generating implicit 2D sample coordinates. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
profile |
[?*] |
Sampled profile(s), or nil if unsuccessful. |
Sample
local profile = Image.extractRowProfile(image, row, startColumn, stopColumn, sampleCoordinates1D)fillRegion()
Short description
Set all pixels within the given region(s) in the target image to a specific value in world coordinates. The pixels outside the input region keep their original values. A new image with updated values is returned, and the input image is left unchanged. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. If the value parameter is outside the image value range it will be clamped to the closest valid value. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is kept in the output image, but the pixels in the fill region will be updated with non missing data.
Keywords
inpaint, flood
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputImage |
1 |
Input image. |
|
region |
CONST_OBJECT |
[1+] |
The region(s) to fill. |
value |
FLOAT |
[1+] |
World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputImage |
? |
Result image or nil if operation failed. |
Sample
outputImage = Image.fillRegion(inputImage, region, value)fillRegionInplace()
Short description
Inplace version of the Image.fillRegion function that modifies the input image. See base function for full documentation.
Keywords
inpaint, flood
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. This image is overwritten with the result image. |
|
region |
CONST_OBJECT |
[1+] |
The region(s) to fill. |
value |
FLOAT |
[1+] |
World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.fillRegionInplace(image, region, value)findColumnMax()
Short description
Extract the position of the brightest values in each column of an image. The methods employed does not only find one bright pixel but uses the neighborhood of each pixel to find a robust subpixel positions of the peak. In reality the line is typically created by a laser projector and this function is used for laser triangulation, although it may be used in other ways. Detection can be improved by providing an axis aligned rectangle shape for the region to search in. This both helps with performance and noise suppression as points outside of the region will be omitted from consideration. The intensity threshold determines how bright a column has to be to give a value in the output profile. Setting the intensity threshold too high removes detections completely. The certainty threshold determines what certainty is required for the valid flag of the profile to be true. Setting the certainty threshold high will still give detections, but will mark the concerned entries as invalid. Image world coordinate system handling: The x-axis origin and pixel size are not used. Each column will generate one coordinate in the output profile. The y-axis origin and pixel size are used to decide the final values of the profile. The z-axis origin and pixel size are not used. The max is found in raw coordinates. Missing data handling: Missing data is not supported.
Keywords
laser, triangulation, peak
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image in which to do the detection. Must be of type UINT8. |
|
region |
? |
Axis aligned rectangle to look in during detection. |
|
method |
ENUM |
? |
Select the method to use. Defaults to HI3D if unset. |
intensityThreshold |
FLOAT |
? |
Select a intensity threshold for a point to be detected. Defaults to 0 if unset. Normal values are between 0 and 50, but depends on light conditions. |
certaintyThreshold |
FLOAT |
? |
Select a certainty threshold for discarding points after detection. Defaults to 0 is unset. Normal values are between 0 and 50. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
profile |
? |
The detected max per column as a profile. Nil on failure. |
|
certainty |
? |
An estimate of the line certainty per point. Can in some cases be used as an approximation of object intensity. For a typical UINT8 the values are normally in the range between 0 and 255, but are not strictly upper bounded. |
Sample
local profile, certainty = Image.findColumnMax(image)findGlobalThreshold()
Short description
Get the global threshold of the image values within the specified region. This threshold can be used to separate pixels into two classes, foreground and background. The Otsu’s method was used to compute the threshold, the key idea is to use a histogram to minimize the intra-class intensity variance. If the image supports missing data, pixels marked as missing are not included in the histogram. If a pixel-world mapping is specified, the histogram is computed using world coordinates. If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. See also Image.getHistogram.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32 and float64. |
|
binCount |
INT |
? |
Number of bins. Uses 256 bins as default. For images types larger than 8-bit is useful to use more bins than 256. The maximum number of bins is 1000000. |
minValue |
FLOAT |
? |
Minimum of the value range to cover. Uses an automatic range if omitted. |
maxValue |
FLOAT |
? |
Maximum of the value range to cover. Uses an automatic range if omitted. |
region |
CONST_OBJECT |
? |
Optional region of interest. Region specifying which parts of the image to include in the histogram. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
threshold |
FLOAT |
? |
The global threshold to separate foreground ( >= threshold) and background. |
Sample
threshold = Image.findGlobalThreshold(image, 256, 0, 255)findLineSegments()
Short description
Finds line segments in an image. Returns a list of 2D line segments represented as a Shape type. An empty list is returned when no line segments were found during an otherwise successful call. This function is currently limited to uint8 pixel type images. Image world coordinate system handling: The output Shape line segments are expressed using the image world coordinate system in the xy-dimensions. The z-dimension is not used in this function. Missing data handling: This function does not support images with missing data. Fill in missing data before hand, using e.g., missingDataSetAll.
Keywords
edge, hough
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Support currently limited to uint8 pixel type. |
|
scale |
FLOAT |
? |
The scale of the image that will be used to find the lines. Accepted values are strictly larger than zero and smaller or equal to one. Optional, default is 0.8. |
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
lineSegments |
* |
The detected line segments in image world coordinates, or nil on failure. |
Sample
lineSegments = Image.findLineSegments(image)findLocalExtrema()
Short description
Finds local extreme points (minima or maxima) in an image. A point is a local maxima if it is larger than all points within a neighborhood of the specified size. An optional contrast threshold level can be defined that sets a required value difference between the local maxima and the smallest value in the neighborhood. For local plateaus, where several pixels have the same value, the top left pixel is reported. An absolute threshold can be specified, if so, point values must exceed the threshold value to be reported. Local minima are detected similarly. Early stopping is used, the neighborhood is only searched until it is clear that the pixel at hand is not an extremal point, starting with the four closest neighbor pixels. The function thus runs faster on smooth images. The absoluteThreshold can also be used to speed up the processing, only considering pixels larger (smaller) than the threshold. The entire neighborhood must fit within the image around extreme points e.g. if neighborhoodSize = 5, no extreme points will be detected closer than three pixels from the image border. Image world coordinate system handling: The thresholds are specified in world values, taking z-origin and pixel size into account. The output pixel region is defined on the pixel grid of the image. Missing data handling: This function does not handle missing data. Remove missing data before calling this function.
Keywords
maxima, min, minima, max
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, uint32, int8, int16, float32 and float64. |
|
extremaType |
ENUM |
1 |
Which type of extrema to look for. MIN or MAX. |
neighborhoodSize |
INT |
? |
The neighborhood size, width and height in pixels. Must be odd and >= 3. Default is 3. |
contrastThreshold |
FLOAT |
? |
Required height of the peak/valley (world coordinate value difference between the extreme point and surrounding points). Set to zero to disable (default). |
contrastDifferenceMode |
? |
Determines how the difference between the extreme point and the surrounding points is calculated. Default is ONE, at least one point in the neighborhood should differ more than contrastThreshold from the local extremal point. |
|
absoluteThreshold |
FLOAT |
? |
Absolute threshold, extremal points must be above (maxima) or below (minima) this value to be included in the output. By default, this threshold is not used. |
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
extremaRegion |
? |
PixelRegion with local extrema points. |
Sample
local extremaRegion = Image.findLocalExtrema(image, extremaType, neighborhoodSize, contrastThreshold, contrastDifferenceMode, absoluteThreshold, region)flyingPixelFilter()
Short description
Removes pixels around edges in the image. Internally, the filter runs a sobel filter on the image and removes pixels where edges are found. Use the threshold parameter to adjust the sensitivity.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to be converted. |
|
threshold |
INT |
1 |
The value threshold. Reducing the value will increase the filter sensitivity. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
convertedImage |
? |
Returns the converted image or nil. |
Sample
local convertedImage = Image.flyingPixelFilter(image, threshold)fourierTransform()
Short description
Calculates the discrete fourier transform of the input image. Image world coordinate system handling: The output images get the same x,y,z-origin and x,y,z-pixelsize as the input image. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to transform. Supported image types are: uint8, uint16, int8, int16, int32, float32 and float64. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
realImage |
? |
Output image with the real part of the complex frequency response. Image type is float32 for input types unless float64 for input float64. |
|
imaginaryImage |
? |
Output image with the imaginary part of the complex frequency response. The resulting output type is float32 for all input types expect for type float64 that outputs also a float64. |
Sample
realImage, imaginaryImage = Image.fourierTransform(image)fourierTransformInverse()
Short description
Calculates the inverse discrete fourier transform of the two images representing the real and imaginary part of the frequency spectrum. Input images must both be either float32 or float64. Image world coordinate system handling: The output images get the same x,y,z-origin and x,y,z-pixelsize as the input image. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
realImage |
1 |
The real image to inverse transform. |
|
imaginaryImage |
1 |
The imaginary image to inverse transform. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageOut |
? |
Output image. Same type as input images. |
Sample
imageOut = Image.fourierTransformInverse(imageRe, imageIm)gauss()
Short description
Applies a Gaussian filter to smooth an image. Image world coordinate system handling: The Gaussian filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.
Keywords
blur, convolve, denoise, filter, smooth
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
|
kernelSizePix |
INT |
[1+] |
Size of the kernel, must be positive and odd. Two values, {xsize ysize}, can be given to create an anisotrophic kernel. |
region |
CONST_OBJECT |
? |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false. |
gaussianFilterType |
ENUM |
? |
Optional selection of which algorithm to use for Gaussian smoothing. Default is dependent on the filter size, a Gaussian kernel is used for small filters and an IIR approximation is used for large filters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
smoothImage |
? |
Output image smoothed by the Gaussian filter. Same type as input image. |
Sample
smoothImage = Image.gauss(image, kernelSizePix)getChannelMax()
Short description
Find the pixelwise maximum value for all input images. The returned result are two images, the first contains the index of the image in which the maximum was found and the second contains all maxima. This operation can be useful create a label image from a set of score images. Image world coordinate system handling: The output images will use the x and y coordinates of the first input image and ignore the rest. The z coordinate systems must match across all input images and the output image will share this coordinate system. Missing data handling: Missing data is not allowed.
Keywords
index, label, max, score, segmentation
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imagevector |
+ |
Vector of at least two images of equal size and type. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
index |
1 |
Index image pointing to the image in imagevector containing the highest value. |
|
value |
1 |
Image containing the maximum across all images. |
Sample
local index, value = Image.getChannelMax(imagevector)getChannelMin()
Short description
Find the pixelwise minimum value for all input images. The returned result are two images, the first contains the index of the image in which the minimum was found and the second contains all minima. Image world coordinate system handling: The output images will use the x and y coordinates of the first input image and ignore the rest. The z coordinate systems must match across all input images and the output image will share this coordinate system. Missing data handling: Missing data is not allowed.
Keywords
index, label, min, score, segmentation
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imagevector |
+ |
Vector of at least two images of equal size and type. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
index |
1 |
Index image pointing to the image in imagevector containing the lowest value. |
|
value |
1 |
Image containing the minimum across all images. |
Sample
local index, value = Image.getChannelMin(imagevector)getChannelSoftmax()
Short description
Performs a pixelwise softmax operation over all input images. The pixelwise sum over all returned images will be 1 in all positions. By using a softmax operation, the pixel values are normalized to a probability distribution. The softmax operation is defined as: softmax(x) = exp(x) / sum(exp(x)), where x is a vector of values. Image world coordinate system handling: The output image will use the x and y coordinates of the first input image and ignore the rest. Input world coordinates in the z-dimension are treated on a per image basis. The normalized output image will have origin 0 and pixel size 1 in the z-dimension. Missing data handling: Missing data is not allowed.
Keywords
normalization, probability, score, softmax, segmentation
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imagevector |
+ |
Vector of at least two images of equal size and type. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
softmax |
+ |
Vector of softmax corrected images. |
Sample
local softmax = Image.getChannelSoftmax(imagevector)getFlatness()
Short description
Calculates a flatness measure for each pixel in an image. A pixel with a value close to zero means approximate coplanarity with its neighbors. The algorithm fits a plane to a local neighborhood around each pixel and gives out the maximum deviation from the plane over all pixels in the neighborhood. There is a fast and slow method for the plane fitting, where the slower method uses all pixels in the neighborhood to estimate the plane and the fast method only uses the border values in the neighborhood. Smoothing the input image first using a blur, gauss or median filter can sometimes be advisable. Image world coordinate system handling: Every pixel in the flatness image stores the maximum distance to the fitted plane in world units evaluated on the all pixels under the neighborhood. Missing data handling: Missing data is accepted, but partly ignored. All pixels that are missing data in the input image will get a negative planarity measure (corresponding to 1 z-pixelsize ). For pixels neighboring missing data the missing data positions are allowed to influence the flatness evaluation, possibly inflating the flatness measure.
Keywords
planar, planarity, roughness, structure, surface
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. |
|
neighborhoodSize |
INT |
? |
The size of the neighborhood in pixels. Must be positive and odd. Default value is 13 pixels. |
fast |
BOOL |
? |
Faster central difference estimate (true) or slower least squares fit (false). Default is true. |
pixelRegion |
CONST_OBJECT |
? |
Optional pixelregion specifying where in the image to perform the operation. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
flatness |
? |
A FLOAT32 image with flatness estimates. |
Sample
flatness = Image.getFlatness(image, neighborhoodSize)getFlatRegion()
Short description
Find approximately flat regions in an image, typically a heightmap or distance image. The algorithm fits a plane to a local neighborhood around each pixel. If all pixel values / z-values in the neighborhood deviate less than a user-specified threshold from the fitted plane, the central pixel is considered to be in a flat region. There is a fast and slow method for the plane fitting, where the slower method uses all pixels in the neighborhood to estimate the plane and the fast method only uses the border values in the neighborhood. Smoothing the input image first using a blur, gauss or median filter can sometimes be advisable. Image world coordinate system handling: Every position in the output region will have a maximum distance to the fitted plane in world units evaluated on the all pixels under the kernel that is lower than the threshold supplied. Missing data handling: Missing data is accepted, but partly ignored. No pixels that are missing in the input will be part of the output region. For pixels neighboring missing data the missing data positions are allowed to influence the flatness evaluation, possibly breaking the flatness constraint.
Keywords
planar, planarity, roughness, structure, surface
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. |
|
threshold |
FLOAT |
1 |
Distance tolerance from the locally fitted plane in world units, e.g., millimeters. If all pixels in the neighborhood deviate less than the threshold the central pixel is classified as flat. The Image.getFlatness function can give an indication of possible threshold values. |
neighborhoodSize |
INT |
? |
The size of the neighborhood in pixels. Must be positive and odd. Default value is 13 pixels. |
fast |
BOOL |
? |
Faster central difference estimate (true) or slower least squares fit (false) for the plane fitting. Default is true. |
pixelRegion |
CONST_OBJECT |
? |
Optional pixelregion specifying where in the image to perform the operation. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
? |
The resulting region of flat pixels. |
Sample
outputRegion = Image.getFlatRegion(image, threshold, neighborhoodSize)getHeight()
Short description
Returns the height of an image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to get the height of. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
height |
INT |
1 |
Height of the image in pixels. |
Sample (auto-generated)
height = Image.getHeight(image)getHistogram()
Short description
Get a histogram of the image values. If the image supports missing data, pixels marked as missing are not included in the histogram. The histogram is computed using world coordinates (z-axis offset and scaling have influence). If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. Pixels with values outside the interval are not counted. See also Image.PixelRegion.getHistogram.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, specifying values to use in the histogram. |
|
binCount |
INT |
? |
Number of bins. Uses 32 bins as default. |
minValue |
FLOAT |
? |
Minimum of the value range to cover. Uses an automatic range if omitted. |
maxValue |
FLOAT |
? |
Maximum of the value range to cover. Uses an automatic range if omitted. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
histogram |
FLOAT |
* |
Histogram, represented as a vector of floats. |
binCenters |
FLOAT |
* |
The center of each histogram bin in the input value range. |
Sample
histogram, centers = Image.getHistogram(image, 64)getLocalMean()
Short description
Get the mean pixel value within a circular neighborhood of a point. By default, a reference plane z=0 is used. Another reference plane may be provided, giving the mean difference from that plane. When using multiple points, point neighborhoods which are empty or have no valid data are reported as having mean value NaN. Image world coordinate system handling: Image world coordinate system values are used. Missing data handling: Missing data pixels are not included.
Keywords
average, statistics, mean
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
points |
[1+] |
Input 2D point or 2D point list in world coordinates |
|
neighborhoodRadius |
FLOAT |
[1+] |
Input radius or radius list in world coordinates. If points is a single value neighborhoodRadius must also be a single value. |
referenceSurface |
? |
Reference plane, defines the zero level in world coordinates. Default is the plane z=0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
mean |
FLOAT |
[?*] |
Mean value or list of mean values. Nil on error |
Sample
mean = Image.getLocalMean(image, points, neighborhoodRadius, referenceSurface)getLocalMedian()
Short description
Get the median value of the pixels within a circular neighborhood of a point, a special case of Image.getPercentiles. The median is derived from a histogram and it is approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0. When using multiple points, point neighborhoods which are empty or have no valid data are reported as having median value NaN. Image world coordinate system handling Image world coordinate system values are used. Missing data handling: Missing data pixels are not included.
Keywords
percentile, statistics
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
points |
[1+] |
Input 2D point or 2D point list in world coordinates |
|
neighborhoodRadius |
FLOAT |
[1+] |
Input radius or radius list in world coordinates. If points is a single value neighborhoodRadius must also be a single value. |
referenceSurface |
? |
Zero-reference 3D surface plane for pixel world coordinate values. Optional, default is the plane z=0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
median |
FLOAT |
[?*] |
The approximate median. |
Sample
median = Image.getLocalMedian(image, points, neighborhoodRadius, referenceSurface)getLocalStatistics()
Short description
Get pixel value statistics within a circular neighborhood of a point. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided, basing the statistics on deviations from that surface. If the statistics can not be calculated, nil is returned. A vector of points can be provided, in which case four vectors of statistics are returned, one entry for each input point. When using multiple points, point neighborhoods which are empty or have no valid data are reported as having all values NaN. Image world coordinate system handling: Image world coordinate system values are used. Missing data handling: Missing data pixels are not included.
Keywords
average, max, mean, statistics, min
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
points |
[1+] |
Input 2D point or 2D point list in world coordinates |
|
neighborhoodRadius |
FLOAT |
[1+] |
Input radius or radius list in world coordinates. If points is a single value neighborhoodRadius must also be a single value. |
referenceSurface |
? |
Reference plane, defines the zero level in world coordinates. Default is the plane z=0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
min |
FLOAT |
[?*] |
Minimal value, or vector of values with one entry for each region. |
max |
FLOAT |
[?*] |
Maximal value, or vector of values with one entry for each region. |
average |
FLOAT |
[?*] |
Average value, or vector of values with one entry for each region. |
standardDeviation |
FLOAT |
[?*] |
Standard deviation, or vector of standard deviations with one entry for each region. |
Sample
min, max, average, standardDeviation = Image.getLocalStatistics(image, points, neighborhoodRadius, referenceSurface)getLocalStd()
Short description
Get the standard deviation of the pixel values within a circular neighborhood of a point. By default, a reference plane z=0 is used. Another reference plane may be provided, giving the mean difference from that plane. When using multiple points, point neighborhoods which are empty or have no valid data are reported as having standard deviation value NaN. Image world coordinate system handling: Image world coordinate system values are used. Missing data handling: Missing data pixels are not included.
Keywords
average, statistics, mean
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
points |
[1+] |
Input 2D point or 2D point list in world coordinates |
|
neighborhoodRadius |
FLOAT |
[1+] |
Input radius or radius list in world coordinates. If points is a single value neighborhoodRadius must also be a single value. |
referenceSurface |
? |
Reference plane, defines the zero level in world coordinates. Default is the plane z=0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
standardDeviation |
FLOAT |
[?*] |
Standard deviation, or vector of standard deviations with one entry for each point. |
Sample
standardDeviation = Image.getLocalStd(image, points, neighborhoodRadius, referenceSurface)getLogMagnitude()
| This API is experimental |
Short description
Calculates the magnitude of the combined real and imaginary input images. The magnitude is transformed to a logarithmic scale. Image world coordinate system handling: The output images get the same x,y,z-origin and x,y,z-pixelsize as the input image. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageRe |
1 |
An image with the real valued part returned from a discrete fourier transform. |
|
imageIm |
1 |
An image with the imaginary valued part returned from a discrete fourier transform. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageMag |
? |
Output image with the combined logarithmic magnitude of the input images. |
Sample
imageMag = Image.getLogMagnitude(imageRe, imageIm)getMagnitude()
| This API is experimental |
Short description
Calculates the magnitude of the combined real and imaginary input images. Image world coordinate system handling: The output images get the same x,y,z-origin and x,y,z-pixelsize as the input image. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageRe |
1 |
An image with the real valued part returned from a discrete fourier transform. |
|
imageIm |
1 |
An image with the imaginary valued part returned from a discrete fourier transform. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageMag |
? |
Output image with the combined magnitude of the input images. |
Sample
imageMag = Image.getMagnitude(imageRe, imageIm)getMax()
Short description
Returns the maximum pixel value in an image. The position of the first maximum value pixel and its uniqueness is also returned. Optionally, a pixel region may be provided. For RGB images, each output will consist of three values corresponding to the result in the R, G and B channel respectively. If a reference surface is used the maximum signed distance to the plane is calculated. Image world coordinate system handling: The output value is specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are ignored.
Keywords
rank, statistics, maximum
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
region |
CONST_OBJECT |
[?*] |
Optional region(s) in which to find the min and max, default is the entire image. For RGB images, it is not possible to use more than one region. |
referenceSurface |
? |
Reference surface. If a plane is specified the maximum signed distance to the plane is calculated. If a polynomial surface is used the Z-axis aligned maximum signed distance is calculated. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
maxValue |
FLOAT |
[?*] |
The maximum pixel value(s) in world coordinates (millimeters). |
position |
[?*] |
The position(s) of the first maximum value pixel in the image scan order, in world coordinates (millimeters). |
|
unique |
BOOL |
[?*] |
Boolean(s) indicating if there is only one pixel with the maximal value. |
Sample
maxValue = Image.getMax(image)getMean()
Short description
Get the mean pixel value. If a region is provided, the mean is calculated within that region. By default, a reference plane z=0 is used. Another reference surface may be provided, giving the mean difference from that surface. Several regions in a list may be used, in which case one mean value is calculated for each region. When using multiple regions, regions which are empty or have no valid data are reported as having mean value nan. Image world coordinate system handling: The output mean value is specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are not included.
Keywords
average, statistics, mean
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
region |
CONST_OBJECT |
[?*] |
Input region or regions, defines the image region in which to calculate the mean, default is the entire image. If several regions are provided, a list of mean values is returned. |
referenceSurface |
? |
Reference surface. If a plane is specified the signed distances to the plane are used to calculate the mean. If a polynomial surface is used the Z-axis aligned signed distance are used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
mean |
FLOAT |
[?*] |
Mean value or list of mean values. Nil on error |
Sample
mean = Image.getMean(image, region, referenceSurface)getMedian()
Short description
Get the median value of the pixels within the region, a special case of Image.getPercentiles. The default method to calculate the median is partial sorting, alternatively a histogram variant can be used. The histogram variant is approximative when using fewer bins than intensity levels. A reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0. A vector of regions can be provided, the median is then calculated within each region. If a median value can’t be calculated a NaN value is returned..
Keywords
percentile, statistics
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
region |
CONST_OBJECT |
[?*] |
Input region or regions, defines the image region in which to calculate the median, default is the entire image. If several regions are provided, a list of median values is returned. |
referenceSurface |
? |
Zero-reference plane for pixel world coordinate values. Optional, default is the plane z=0. |
|
orthogonalToSurface |
BOOL |
? |
Indicates if the distance shall be measured as the orthogonal distance from the reference plane. Default is false, measuring the distance along the z-axis of the image. |
binCount |
INT |
? |
Set the number of bins to use in the histogram for calculating the value, more bins provides a more accurate result. Default is zero. If set to zero, a histogram is not used, but a partial sort is used instead. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
median |
FLOAT |
[?*] |
The approximate median(s). |
Sample
median = Image.getMedian(image, region, referenceSurface, orthogonalToSurface, binCount)getMin()
Short description
Returns the minimum pixel value in an image. The position of the first minimum value pixel and its uniqueness is also returned. Optionally, a pixel region may be provided. For RGB images, each output will consist of three values corresponding to the result in the R, G and B channel respectively. If a reference surface is used the minimum signed distance to the plane is calculated. Image world coordinate system handling: The output value is specified in image world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are ignored.
Keywords
rank, statistics, minimum
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
region |
CONST_OBJECT |
[?*] |
Optional region(s) in which to find the min and max, default is the entire image. For RGB images, it is not possible to use more than one region. |
referenceSurface |
? |
Reference surface. If a plane is specified the minimum signed distance to the plane is calculated. If a polynomial surface is used the Z-axis aligned minimum signed distance is calculated. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
minValue |
FLOAT |
[?*] |
The minimum pixel value(s) in world coordinates (millimeters). |
position |
[?*] |
The position(s) of the first minimum value pixel in the image scan order, in world coordinates (millimeters). |
|
unique |
BOOL |
[?*] |
Boolean(s) indicating if there is only one pixel with the minimal value. |
Sample
minValue = Image.getMin(image)getMinMax()
Short description
Returns the minimum and maximum pixel value in an image. The positions of the first minimum and maximum value pixels and their uniqueness is also returned. Optionally, a pixel region may be provided. For RGB images, each output will consist of three values corresponding to the result in the R, G and B channel respectively. If a reference surface is used the minimum and maximum signed distances to the plane are calculated. Image world coordinate system handling: The output value is specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are ignored.
Keywords
maximum, rank, statistics, minimum
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
region |
CONST_OBJECT |
[?*] |
Optional region in which to find the min and max, default is the entire image. For RGB images, it is not possible to use more than one region. |
referenceSurface |
? |
Reference surface. If a plane is specified the minimum and maximum signed distances to the plane are calculated. If a polynomial surface is used the Z-axis aligned minimum and maximum signed distances are calculated. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
minValue |
FLOAT |
[?*] |
The minimum pixel value(s) in world coordinates (millimeters). |
maxValue |
FLOAT |
[?*] |
The maximum pixel value(s) in world coordinates (millimeters). |
minPosition |
[?*] |
The position(s) of the first minimum value pixel in the image scan order, in world coordinates (millimeters). |
|
maxPosition |
[?*] |
The position(s) of the first maximum value pixel in the image scan order, in world coordinates (millimeters). |
|
minUnique |
BOOL |
[?*] |
Boolean(s) indicating if there is only one pixel with the minimal value. |
maxUnique |
BOOL |
[?*] |
Boolean(s) indicating if there is only one pixel with the maximal value. |
Sample
minValue, maxValue, minPosition, maxPosition, minUnique, maxUnique = Image.getMinMax(image)getMissingDataFlag()
Short description
Gets the missing data setting in the image. 0 means no missing data handling, 1 means that the value 0 is treated as missing data.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
missingDataFlag |
INT |
1 |
Returns the missing data setting. |
Sample (auto-generated)
missingDataFlag = Image.getMissingDataFlag(image)getMissingDataImage()
Short description
Creates a binary image indicating the missing data pixels in the source image. Image world coordinate system handling: The output binary image gets the same x,y-origin and x,y-pixelsize as the input image, but the z-origin is set to 0 and the z-pixelsize to 1. Missing data handling: The output image has no missing data flag set as it is a binary image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
missingValue |
INT |
? |
The value to assign result pixels for missing data in the source image. Default = 1 |
dataValue |
INT |
? |
The value to assign result pixels for data in the source image. Default = 2 |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
The resulting binary image, always of uint8 pixel type |
Sample
result = Image.getMissingDataImage(image)getMissingDataRegion()
Short description
Creates a PixelRegion object of all missing data pixels in the source image.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
? |
The region containing all missing data pixels. |
Sample
region = Image.getMissingDataRegion(image)getOrigin()
Short description
Retrieves the origin of the image world coordinate in the image. The origin corresponds to the world coordinate of the top-left image pixel.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
origin |
1 |
Returns the origin as a point in 3D. |
Sample (auto-generated)
origin = Image.getOrigin(image)getOriginZ()
Short description
Retrieves the z-origin of the image world coordinate in the image.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
originZ |
FLOAT |
1 |
The z-origin of the image. |
Sample (auto-generated)
originZ = Image.getOriginZ(image)getPercentile()
Short description
Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. The default method to calculate the percentiles is partial sorting, alternatively a histogram variant can be used. The histogram variant is approximative when using fewer bins than intensity levels. A reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. This function estimates one percentile for each region, see also getPercentiles to calculate several percentiles for one region.
Keywords
statistics
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
percentileLevel |
FLOAT |
1 |
Percentile level in the range (0..1) |
region |
CONST_OBJECT |
[?*] |
Input region or regions, defines the image region in which to calculate the percentile, default is the entire image. If several regions are provided, a list of values is returned. |
referenceSurface |
? |
Zero-reference plane for pixel world coordinate values. Optional, default is the plane z=0. |
|
orthogonalToSurface |
BOOL |
? |
Indicates if the distance shall be measured as the orthogonal distance from the reference plane. Default is false, measuring the distance along the z-axis of the image. |
binCount |
INT |
? |
Set the number of bins to use in the histogram for calculating the value, more bins provides a more accurate result. Default is zero. If set to zero, a histogram is not used, but a partial sort is used instead. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
values |
FLOAT |
* |
Output values, one for each region. |
Sample
values = Image.getPercentile(image, percentileLevel, regions, referenceSurface, orthogonalToSurface, binCount)getPercentiles()
Short description
Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. The default method to calculate the percentiles is partial sorting, alternatively a histogram variant can be used. The histogram variant is approximative when using fewer bins than intensity levels. A reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0. This function operates on one region, see also getPercentile to obtain one quantile each from many regions.
Keywords
statistics
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
percentileLevels |
FLOAT |
+ |
Percentile levels in the range (0..1) |
region |
CONST_OBJECT |
? |
Input region, default is the entire image. |
referenceSurface |
? |
Zero-reference plane for pixel world coordinate values. Optional, default is the plane z=0. |
|
orthogonalToSurface |
BOOL |
? |
Indicates if the distance shall be measured as the orthogonal distance from the reference plane. Default is false, measuring the distance along the z-axis of the image. |
binCount |
INT |
? |
Set the number of bins to use in the histogram for calculating the value, more bins provides a more accurate result. Default is zero. If set to zero, a histogram is not used, but a partial sort is used instead. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
values |
FLOAT |
* |
Output values, one for each quantile level. |
Sample
values = Image.getPercentiles(image, percentileLevels, region, referenceSurface, orthogonalToSurface, binCount)getPixel()
Short description
Returns the pixel value of an image at position (x,y) in pixel coordinates. For monochrome image types this is a single float value, for RGB24 a vector of three float values in the order red, green, blue.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to get the pixel from. |
|
x |
INT |
[1+] |
The x pixel coordinate or list of x coordinates. |
y |
INT |
[1+] |
The y pixel coordinate or list of y coordinates. |
pixelValueType |
ENUM |
? |
How the pixel value is returned. It can be returned in raw (default) or world coordinates. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
value |
FLOAT |
[?*] |
The raw/world pixel value, or a list of RGB values, or nil for invalid coordinates. If a list of x and y coordinates is provided the output will be a list of pixel values, and for a color image the list is in the format [R values, G values, B values]. |
Sample (auto-generated)
value = Image.getPixel(image, x, y, pixelValueType)getPixelSize()
Short description
Retrieves the pixel size of the image world coordinate system.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
sizeX |
FLOAT |
1 |
Returns the size of a pixel in the X dimension in world coordinate units. |
sizeY |
FLOAT |
1 |
Returns the size of a pixel in the Y dimension in world coordinate units. |
sizeZ |
FLOAT |
1 |
Returns the size of a pixel in the Z dimension in world coordinate units. |
Sample (auto-generated)
sizeX, sizeY, sizeZ = Image.getPixelSize(image)getPixelSizeZ()
Short description
Retrieves the pixel size in the z-dimension of the image world coordinate system.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
sizeZ |
FLOAT |
1 |
Returns the size of a pixel in the Z dimension in world coordinate units. |
Sample (auto-generated)
sizeZ = Image.getPixelSizeZ(image)getRoughness()
Short description
Return roughness statistics for the provided image. This measurement consists of the mean, standard deviation, skewness and kurtosis statistics (i.e. the four first moments of the distribution). The roughness is calculated from the pixel values in the region, using the image world coordinate system. The skewness is a measure of the asymmetry of the distribution, and the kurtosis is a measure of the "tailedness" of the distribution. To get the excess kurtosis, subtract 3 from the returned kurtosis value. Missing data handling: Missing data pixels are omitted from the statistics and are treated like they didn’t exist.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. |
|
region |
CONST_OBJECT |
[?*] |
Optional input region or list of regions. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
mean |
FLOAT |
[?*] |
Mean in world units. |
stddev |
FLOAT |
[?*] |
Standard deviation in world units. |
skewness |
FLOAT |
[?*] |
Skewness in world units. |
kurtosis |
FLOAT |
[?*] |
Kurtosis in world units. |
Sample
mean, stddev, skewness, kurtosis = Image.getRoughness(image)getSize()
Short description
Returns the width and height of an image.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to get the size of. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
width |
INT |
1 |
Width of the image in pixels. |
height |
INT |
1 |
Height of the image in pixels. |
Sample (auto-generated)
width, height = Image.getSize(image)getStatistics()
Short description
Get pixel value statistics. If a region is provided, the statistics is calculated within that region. Image world coordinate system values are used and pixels with missing data are excluded. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided, basing the statistics on deviations from that surface. If the statistics can not be calculated, nil is returned. A vector of regions can be provided, in which case four vectors of statistics are returned, one entry for each input region. Any invalid input region in the vector will have the corresponding output entries set to zero.
Keywords
average, max, mean, statistics, min
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
region |
CONST_OBJECT |
[?*] |
Input region or regions, defines the image region in which to calculate the statistics, default is the entire image. If several regions are provided, lists of statistics values are returned. |
referenceSurface |
? |
Reference plane, defines the zero level in world coordinates. Default is the plane z=0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
min |
FLOAT |
[?*] |
Minimal value, or vector of values with one entry for each region. |
max |
FLOAT |
[?*] |
Maximal value, or vector of values with one entry for each region. |
average |
FLOAT |
[?*] |
Average value, or vector of values with one entry for each region. |
standardDeviation |
FLOAT |
[?*] |
Standard deviation, or vector of standard deviations with one entry for each region. |
Sample
min = Image.getStatistics(image, region, referenceSurface)getSum()
Short description
Returns the sum of the pixel values in an image. Image world coordinate system handling: The sum is in world coordinates, i.e., the origin and pixel size in the z-dimension are considered should the image represent a height map, distance or range image. Missing data handling: Missing data pixels are not included.
Keywords
statistics
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
region |
CONST_OBJECT |
[?*] |
Optional region in which to find the sum, default is the entire image. |
referenceSurface |
? |
Reference surface. If a plane is specified the signed distances to the plane are calculated and accumulated. If a polynomial surface is used the Z-axis aligned signed distance is calculated. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageSum |
FLOAT |
? |
The sum of all pixels expressed in world coordinates (millimeters) |
pixelCount |
INT |
? |
The number of pixels used to calculate the sum. |
Sample
imageSum = Image.getSum(image)getType()
Short description
Returns the pixel type of the image.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pixelType |
ENUM |
1 |
The pixel type (e.g.: UINT8, INT16, FLOAT64, RGB24). Please note, most image types are single channel (monochrome) but for example RGB24 has 3 color channels. |
Sample (auto-generated)
pixelType = Image.getType(image)getValidDataRegion()
Short description
Creates a PixelRegion object of all non-missing data pixels in the source image.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
? |
A PixelRegion containing all valid data pixels. |
Sample
local region = Image.getValidDataRegion(image)getWidth()
Short description
Returns the width of an image.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to get the width of. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
width |
INT |
1 |
Width of the image in pixels. |
Sample (auto-generated)
width = Image.getWidth(image)getWorldZ()
Short description
Returns the z-values at given 2D (x,y)-points, interpreting the image as a range image. Linear interpolation is used for positions between the pixel grid positions. For points outside the image the z-origin value is return corresponding to raw pixel value 0. Coordinate system handling: The image world coordinate system is used in this operation, i.e., the input 2D points are interpreted using the pixelsizes and origin in the (x,y)-dimensions and the output z value is also in world coordinates. Missing data handling: Missing data is respected so that missing data pixels are ignored in the interpolation calculation.
Keywords
getHeight
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
points |
[1+] |
The 2D point to sample at, or a list of 2D points, in world coordinates. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
valuesZ |
FLOAT |
[?*] |
Z value or values in world coordinates, or nil if unsuccessful. |
Sample
local valuesZ = Image.getWorldZ(image, points)growRegion()
Short description
Starting from the seed regions, the regions are expanded to fill the pixel areas whose world pixel values in the image lies between the lower and upper threshold in world coordinates. Pixels with missing data are not grown into. Pixels included in the seed region will always be included in the output region, independent of the corresponding pixel value and missing status. Image world coordinate system handling: The thresholds are interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 or a z-pixelsize different than 1. Missing data handling: Pixels with missing data are not included in the grown region, unless covered by the seed region.
Keywords
seeded, segmentation, floodfill
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image indicating where the region should grow. |
|
seedRegion |
CONST_OBJECT |
1 |
The region to grow. |
minThreshold |
FLOAT |
? |
Minimum value to allow growth. Optional, default is the smallest representable value. |
maxThreshold |
FLOAT |
? |
Maximum value to allow growth. Optional, default is the largest representable value. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
grownRegion |
? |
Result region or nil if operation failed. |
Sample
grownRegion = Image.growRegion(image, seedRegion, minThreshold, maxThreshold)harris()
| This API is experimental |
Short description
Applies the Harris corner detector to an image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8 and float32. |
|
kernelSizePix |
INT |
? |
Optional size of the kernel, must be positive, odd and not larger than 31. Default value is 3. |
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
harrisResponse |
? |
Harris operator response. |
Sample
harrisResponse = Image.harris(image, kernelSizePix)houghTransformCircle()
Short description
Finds circle candidates with a given radius in an edge image where any non-zero pixel is considered an edge. The output is an accumulator image binned over circle centers in world coordinates. The world coordinates of the output accumulator directly matches circle centers, i.e. the world coordinates of a maxima in the accumulator image corresponds directly to the input image circle center in world coordinates. Use Image.houghTransformExtremaToCircles to create circles from accumulator image maxima (as a pixel region), or extract maxima as points and use Shape.createCircle(points, radius) directly. Image world coordinate system handling: Input image world coordinates are used. The radius is in world coordinates. The accumulator world coordinates directly relate maxima to circle centers. Pixel values in the input image are interpreted in raw pixel values. Missing data handling: Missing data are interpreted as not edges.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
edgeImage |
1 |
Input image. Supported image types are uint8 and uint16. Non-zero pixels are counted as edges. |
|
radius |
FLOAT |
1 |
The radius of circles to search for, in world coordinates. |
resolutionX |
INT |
? |
The number of bins to use for the x-position of the circles, also the width of the output image, default 200. |
resolutionY |
INT |
? |
The number of bins to use for the y-position of the circles, also the height of the output image, default 200. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
houghAccumulator |
? |
Circle candidate center accumulator image. |
Sample
houghAccumulator = Image.houghTransformCircle(edgeImage, radius, resolutionX, resolutionY)houghTransformExtremaToCircles()
Short description
Converts pixels extracted from an accumulator image obtained from houghTransformCircle to geometrical circles. The accumulator image is required to get the world coordinate system and accumulator values. Results are sorted in descending order by accumulator value. Image world coordinate system handling: Pixel region of extremas should be related to the accumulator image. Circles are returned in world coordinates. Missing data handling: Not applicable, there is no missing data in the input accumulator image.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
accumulatorImage |
1 |
Accumulator image as returned from houghTransformCircle. |
|
extremalRegion |
CONST_OBJECT |
1 |
Pixel region with extremal points extracted from the accumulator image, will be recalculated to the corresponding circles. |
radius |
FLOAT |
1 |
Radius of the circles to create. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
circles |
* |
Circles as shapes, or nil on error. |
|
accumulatorValues |
FLOAT |
* |
Accumulator image value corresponding to each circle. |
Sample
circles, accumulatorValues = Image.houghTransformExtremaToCircles(accumulatorImage, extremalRegion, radius)houghTransformExtremaToLines()
Short description
Converts pixels extracted from an accumulator image obtained from houghTransformLine to geometrical lines. Both the accumulator and edge images are required to get the world coordinate system. Since horizontal lines end up just where the accumulator image wraps around, the accumulator is usually extended with a few extra rows. These may result in duplicate line detections (the direction differ by pi, with opposite sign of the distance to the image center). By default, such duplicate lines are removed but this feature can be turned off. The accumulator value corresponding to each line candidate is returned. Results are sorted in descending order by accumulator value. Image world coordinate system handling: Pixel region of extremas should be related to the accumulator image. Lines are returned in world coordinates of the original input image. Missing data handling: Not applicable, there is no missing data in the input accumulator image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
accumulatorImage |
1 |
Accumulator image as returned from houghTransformLines. |
|
extremalRegion |
CONST_OBJECT |
1 |
Pixel region with extremal points extracted from the accumulator image, will be recalculated to the corresponding lines. |
edgeImage |
1 |
Input image as sent to houghTransformLine, used for coordinate reference. |
|
removeDuplicates |
BOOL |
? |
Flag indicating if duplicate lines should be removed, default is true. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
lines |
* |
Lines as shapes, or nil on error. |
|
accumulatorValues |
FLOAT |
* |
Accumulator image value corresponding to each line. |
Sample
lines = Image.houghTransformExtremaToLines(accumulatorImage, extremalRegion, edgeImage, removeDuplicates)houghTransformLine()
Short description
Finds line candidates in an edge image where any non-zero pixel is considered an edge. The output is an accumulator image binned over line candidate direction and signed distance from the center of the input image. E.g. a line candidate with direction pi/2 and distance -5 is a vertical line located five world coordinate units to the left of the center point of the input image. Line candidates are on the form x*sin(theta) + y*cos(theta) = d, where x and y are input image positions relative to the center of the input image, d is the signed distance from the center of the input image and theta is the line direction. All are expressed in world coordinates. d is binned over distanceBins bins which also is the width of the output image. Theta is binned over directionBins bins. The range of theta is from zero to pi, d is from minus to plus half the diagonal of the input image. Since the direction parameter is circular in nature, a maxima at the upper and lower accumulator image border (theta is zero or pi) with opposite signs of d correspond to the same line. Since maxima extraction routines tend to skip maxima close to image borders, a few extra rows are added to the bottom of the accumulator image, corresponding to the first rows of accumulators. The number of extra rows is set by the overlapBins parameters, recommended to be set to the maxima extraction filter size. The accumulator image height is thus directionBins + overlapBins. The search space can be limited by setting the directionCenter and directionRange parameters. The direction search range is centered around the direction center. If set, the rows of the accumulator image are distributed over the specified direction range and no overlap bins are added. The first row of the accumulator image corresponds to directionCenter - directionRange/2. The canny function can be used to generate an edge image suitable as input. The threshold or findLocalExtrema functions can be used to find extrema in the accumulator image. Use houghTransformExtremaToLines to transform extrema from the accumulator image into Shape lines. Image world coordinate system handling: Input image world coordinates are used. All output values are with respect to the center of the input image. The output image world coordinates are set to directly get d and theta values. Raw pixel values of the input image are used. Missing data handling: Missing data are interpreted as not edges.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
edgeImage |
1 |
Input image. Supported image types are uint8 and uint16. Non-zero pixels are counted as edges. |
|
distanceBins |
INT |
? |
The number of bins to use for the distance to the line from the edge image center, the width of the output image, default 200. |
directionBins |
INT |
? |
The number of bins to use for the direction of the line, the height of the output image, default 360. |
overlapBins |
INT |
? |
The number of extra rows to add at the bottom of the accumulator image, overlapping with the first rows. Recommended value is the size of the maxima filter to be used, default is 5. |
directionCenter |
FLOAT |
? |
The central direction when searching for lines with directions within a limited range in radians. Horizontal lines have direction zero, vertical lines have direction pi/2. Default is to search the full range. |
directionRange |
FLOAT |
? |
The range of directions for a limited range search, in radians (between zero and pi) and centered around the specified central direction. Default is nil, searching for lines with any direction. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
houghAccumulator |
? |
Line candidate accumulator image. |
Sample
houghAccumulator = Image.houghTransformLine(edgeImage, distanceBins, directionBins, overlapBins)inpaint()
Short description
Replaces the image content in a specified region with the content around the region. This is done in an iterative manner and increasing the radius increases the speed of the algorithm, at the cost of quality of the result. Image world coordinate system handling: The world coordinate system of the input image is not used. The output will have the same coordinate system as the input image. Missing data handling: Operation is performed in raw pixel values. If there are missing data along the borders of the region it will be used for inpainting.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image in which to perform inpainting. |
|
region |
CONST_OBJECT |
1 |
The region to be replaced. |
radius |
FLOAT |
? |
Pixel radius used by inpainting algorithm. Default is 3.0. |
method |
ENUM |
? |
Inpainting method. Default is NAVIER_STOKES. |
Sample
local result = Image.inpaint(image, region)intensityFilter()
Short description
All pixel values outside the min/max limits are set to the reset value.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
distanceImage |
1 |
The distance image to be converted. |
|
intensityImage |
1 |
The intensity image to get the values to convert the distance image. |
|
minThres |
INT |
1 |
The minimal value of the intensity filter. |
maxThres |
INT |
1 |
The maximum value of the intensity filter. |
resetThres |
INT |
? |
The reset value of the intensity filter. Default is 0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
convertedImage |
? |
Returns the converted image or nil. |
Sample
local convertedImage = Image.intensityFilter(distanceImage, intensityImage, 100, 5000)invert()
Short description
Inverts the pixel values in the image, so that dark becomes bright and vice versa. The operation imOutput = getMax(imInput) - imInput. To do an inversion in the sense 1/x use the pow-function. Image world coordinate system handling: The output image keeps the coordinate system of the input image. The z-component of the output image origin is set to zero, this makes the inversion correct both for world pixel values and raw pixel values. Missing data handling: A missing data pixel in the input image results in a missing data pixel in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
brightness, contrast, inverse
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
maxValue |
FLOAT |
? |
Optional value to subtract the image from, in world units. The default behavior is to find and use the maximum value in the input image. |
Sample
result = Image.invert(image)invertInplace()
Short description
Inplace version of the Image.invert function that modifies the input image. See base function for full documentation.
Keywords
brightness, contrast, inverse
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
|
maxValue |
FLOAT |
? |
Optional value to invert around. The default behavior is to find and use the maximum value in the input image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.invertInplace(image)isEqual()
Short description
Checks if two images are equal, both in terms of size, type and pixel content. This function disregards the image world coordinate information and looks only at raw pixel values.
Keywords
compare, similar, check
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. |
|
image2 |
1 |
The second source image. |
|
tolerance |
FLOAT |
? |
The difference allowed between the images in the pixel value comparison. Value is in pixel coordinates. Default is 0. |
compareMetaData |
BOOL |
? |
Select if missing data flags, origin or pixel size differences should influence the comparison. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
? |
True if the images have identical size and pixel type, and equal contents at each pixel. |
Sample
result = Image.isEqual(image1, image2)isolatedPixelFilter()
Short description
Identifies and modifies single outlier pixels in the image. Each pixel’s value is compared to the values of the direct neighbor pixels. If its value is by threshold smaller than the neighbor with minimal value or by threshold greater than the neighbor with maximal value, the value is altered. There are two possibilities for altering the value: If the value difference between the max and the min neighbor is smaller than threshold, the current pixel value is set to the median of these two neighbors' values. If the difference between the max and the min neighbor is greater than threshold, the current pixel’s value is set to 0, i.e. it is filtered out.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to be converted. |
|
threshold |
INT |
1 |
The value threshold. Reducing the value will increase the filter sensitivity. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
convertedImage |
? |
Returns the converted image or nil. |
Sample
local convertedImage = Image.isolatedPixelFilter(image, threshold)isWithinBounds()
Short description
Checks whether a pixel coordinate is within the bounds of the image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
||
x |
INT |
1 |
The x pixel coordinate of the point to be checked. |
y |
INT |
1 |
The y pixel coordinate of the point to be checked. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isInBounds |
BOOL |
1 |
Returns true if the point is within the image, false otherwise. |
Sample (auto-generated)
isInBounds = Image.isWithinBounds(image, x, y)laplace()
Short description
Applies a Laplace filter to the input image, i.e., the sum of the local second-order gradients in the x- and y-directions. Image world coordinate system handling: The Laplace filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
Keywords
convolve, derivative, gradient, edge
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, float32 and float64. |
|
kernelSizePix |
INT |
1 |
Size of the kernel, must be positive, odd and not larger than 29. |
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Pixel values outside the region are undefined. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
laplaceImage |
? |
Output image with the Laplace values. |
Sample
laplaceImage = Image.laplace(image, kernelSizePix)load()
Short description
Loads an image from the specified file path. The format is defined by the file extension: .bmp: Bitmap .png: PNG .jpg/jpeg: JPEG (not supported by all devices) .pgm: PGM (not supported by all devices) .json: JSON AppSpace format (redirects to Object.load) .msgpack: MessagePack AppSpace format (redirects to Object.load)
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filepath |
STRING |
1 |
The path and name of the file to load the image from. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
The Image object which is loaded. |
Sample
local image = Image.load("resources/image.bmp")log()
Short description
Applies the natural logarithm to the value at each pixel. The output will be an image of type FLOAT32 (or FLOAT64 in case the input is already FLOAT64). Negative and zero values have no representation and will be presented as NaN and negative infinity respectively. Image world coordinate system handling: The z-scale of the image is considered. The image metadata from the input image is copied to the output image except for the z-scale and z-origin, values are instead stored in world coordinates directly. Missing data handling: Missing data is not supported and the missing data flag must be toggled off. Input values of zero will be returned as negative infinity.
Keywords
arithmetic, cube, exp, exponent, inverse, invert, power, sqr, sqrt, square, logarithm
See also
Sample
result = Image.log(image)max()
Short description
Creates an image with the maximum pixel values of the source images. The images must be of equal size and pixel type. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.
Keywords
arithmetic, compare, maximum
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. |
|
image2 |
1 |
The second source image. |
Sample
result = Image.max(image1, image2)maxInplace()
Short description
Inplace version of the Image.max function which modifies the first input image to contain the pixelwise maximum of the input images. See base function for full documentation.
Keywords
arithmetic, compare, maximum
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. This image is overwritten with the pixelwise maximum. |
|
image2 |
1 |
The second source image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.maxInplace(image1, image2)median()
Short description
Applies median filter to the image to smooth and remove noise. Image world coordinate system handling: The median filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.
Keywords
denoise, edge preserving, filter, smooth
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, int16, float32 and rgb. |
|
kernelSizePix |
INT |
1 |
Size of the kernel, must be positive and odd. For kernel sizes larger than 5 the only supported image type is uint8. |
region |
CONST_OBJECT |
? |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false. |
preserveDetails |
BOOL |
? |
Optional flag to reduce detail loss. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
medianImage |
? |
Output image blurred by the median filter. |
Sample
medianImage = Image.median(image, kernelSizePix)min()
Short description
Creates an image with the minimum pixel values of the source images. The images must be of equal size and pixel type. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.
Keywords
arithmetic, compare, minimum
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. |
|
image2 |
1 |
The second source image. |
Sample
result = Image.min(image1, image2)minInplace()
Short description
Inplace version of the Image.min function which modifies the first input image to contain the pixelwise minimum of the input images. See base function for full documentation.
Keywords
arithmetic, compare, minimum
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. This image is overwritten with the pixelwise minimum. |
|
image2 |
1 |
The second source image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.minInplace(image1, image2)minMax()
Short description
Calculates a local min and max around each pixel. Image world coordinate system handling: The kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. The output image inherits the missing data flag of the input image.
Keywords
filter, maximum, minimum, statistics
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
|
kernelSizePix |
INT |
1 |
Size of the kernel, must be positive. |
region |
CONST_OBJECT |
? |
Optional region of interest. Enter nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
minImage |
? |
Output min image. Same type as the input image. |
|
maxImage |
? |
Output min image. Same type as the input image. |
Sample
local minImage, maxImage = Image.minMax(image, kernelSizePix)mirror()
Short description
Mirrors an image in the horizontal or vertical axis. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is mirrored. Missing data handling: All missing data values will be retained after mirroring.
Keywords
flip
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. |
|
mirrorHorizontally |
BOOL |
1 |
Set to true to mirror horizontally in the vertical axis, set to false to mirror vertically in the horizontal axis. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
mirroredImage |
? |
The mirrored image |
Sample
mirroredImage = Image.mirror(image, mirrorHorizontally)missingDataReduce()
Short description
Reduces missing data pixels in an image by using valid values in the neighborhood. Valid pixel values are unaffected. This will fill in scattered missing data values but larger patches of missing data will remain. The type of operation performed to fill a missing pixel is selected using the method parameter. Optionally, reduction of missing data can be limited to a region in the image. Valid pixel values within a neighborhood but outside the region will still be used to fill missing data. To fill a missing pixel, at least one quarter of the neighbor pixels need to have valid values. The available methods are: MAX - Sets missing pixels to the maximum valid value in the neighborhood. MIN - Sets missing pixels to the minimum valid value in the neighborhood. MEAN - Sets missing pixels to the mean of all valid values in the neighborhood. MEDIAN - Sets missing pixels to the median of all valid values in the neighborhood. EDGE - Fills missing values by edge-preserving interpolation among pixels in the 3x3 pixel neighborhood. A missing data pixel will be filled in only if there are valid values on both sides of a pixel. For all methods except EDGE, the neighborhood is nSize-by-nSize pixels. nSize must be odd and at least three. For method EDGE, nSize determines how many times the algorithm will be repeated. For EDGE, nSize must be a positive integer.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputImage |
1 |
The input image. An error is returned if the input image does not have the missing data flag set. |
|
method |
ENUM |
1 |
Method to be used for reducing missing data. |
nSize |
INT |
? |
The size of the neighborhood for most methods, the number of iterations for EDGE. Default is 3. |
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within this region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputImage |
? |
The output image, or nil if an error occurred. |
Sample
outputImage = Image.missingDataReduce(inputImage, method, nSize, region)missingDataSetAll()
Short description
Sets all missing data pixels in the entire image or within a specified region to a given value. All missing pixels are set and the missing data flag of the image is cleared. If a region is provided, only pixels within the region are considered. The missing data flag of the image is still cleared, leaving any pixels with missing data outside the region in an undetermined state. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is removed from the output image, also if the operation is only performed within a region of interest.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The input image. |
|
valueWorld |
FLOAT |
1 |
The value to set, in world coordinates considering z-origin and z-pixelsize if applicable. |
region |
CONST_OBJECT |
? |
A region of interest to operate within. Optional, default is operate on the entire image. |
Sample
result = Image.missingDataSetAll(image, value, region)missingDataSetAllInplace()
Short description
Inplace version of the Image.missingDataSetAll function that modifies the input image. See base function for full documentation.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to set missing data in. This image is overwritten with the result image. |
|
valueWorld |
FLOAT |
1 |
The value to set, in world coordinates considering z-origin and z-pixelsize if applicable. |
region |
CONST_OBJECT |
? |
A region of interest to operate within. Optional, default is operate on the entire image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.missingDataSetAllInplace(image, value, region)missingDataSetSurface()
Short description
Sets all missing data pixels to the surface value, values are clamped to the representable range of the image. All valid values are left unchanged. If a region not covering the full image is used, any missing data outside the region will be left in an undetermined state. Currently, either a plane surface represented as a Shape3D or a 2nd order polynomial extracted by the Image.SurfaceFitter is supported, other surface types may be supported in the future. For a 2nd order polynomial surface, the following representation is expected z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients. Image world coordinate system handling: The surface is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: This function replaces all missing data pixels with the surface value. The missing data flag for the output image is removed, also when this operation is performed only within a specified region of interest.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to set missing data in. |
|
surface |
CONST_AUTO |
[1+] |
The surface to clamp to, represented as a 2nd order polynomial or Shape3D. For 3D shapes currently only a plane type is supported, in future more surface types may be supported. A second order order polynomial is represented with as a vector of the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
region |
CONST_OBJECT |
? |
Optional region where the operation is to be performed, default is the full image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
clampedImage |
? |
The image without missing data. Nil if an error occurred. |
Sample
clampedImage = Image.missingDataSetSurface(image, surface, region)missingDataSetSurfaceInplace()
Short description
Inplace version of the Image.missingDataSetSurface function which sets all missing data pixels to a surface value. See base function for full documentation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to set missing data in. This image is overwritten and the missing data is set according to the surface value. |
|
surface |
CONST_AUTO |
[1+] |
The surface to clamp to, represented as a 2nd order polynomial or Shape3D. For 3D shapes currently only a plane type is supported, in future more surface types may be supported. A second order order polynomial is represented with as a vector of the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
region |
CONST_OBJECT |
? |
Optional region where the operation is to be performed, default is the full image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.missingDataSetSurfaceInplace(image, surface, region)mixColorize()
Short description
Mix two images using a predefined colormap from blue to red. One image represent the general background and the other which color to mix in. The background image can be either a single channel UINT8 image or a three channel RGB image. Generally this function can be used to visualize error values over an input image. Values below the limit of the colormap will remain the same as in the background input image. Values above the limit of the colormap will saturate towards the upper end of the colormap. To use a custom colormap see the related function Image.mixColormap. The colormap created by this function corresponds to the following stops and colors. colormap:addStop(0.0, 0, 0, 127) colormap:addStop(0.125, 0, 0, 255) colormap:addStop(0.375, 0, 255, 255) colormap:addStop(0.625, 255, 255, 0) colormap:addStop(0.875, 255, 0, 0) colormap:addStop(1.0, 127, 0, 0) Image world coordinate system handling: The image content is converted and the coordinate system preserved except for the value dimensions. The value dimension of the overlay image is used in world coordinates to find the color of the colormap. Missing data handling: Missing data values are not affected in the background image. The overlay image must be float32 and missing data may need preprocessing before conversion.
Keywords
paint, colorize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
background |
1 |
The background image to use as grayscale background. Needs to be UINT8. |
|
overlay |
1 |
The overlay image that together with the colormap creates the color in each pixel. |
|
min |
FLOAT |
1 |
Values below this level in the heatmap will be rendered the same in the result image as in the input background. |
max |
FLOAT |
1 |
Values at or above this level in the heatmap will be rendered red in the output image. |
imageWeight |
FLOAT |
? |
Tune the relative mixing between background content and overlay. Default is 0.5. |
Sample
image = Image.mixColorize(background, overlay, min, max, imageWeight)mixColormap()
Short description
Mix two images using a colormap. One image represent the general background and the other which color of the supplied colormap to mix in. The background image can be either a single channel UINT8 image or a three channel RGB image. Generally this function can be used to visualize error values over an input image. Values below the limit of the colormap will remain the same as in the background input image. Values above the limit of the colormap will saturate towards the upper end of the colormap. For a simpler interface with a predefined colormap see the related Image.mixColorize function. Image world coordinate system handling: The image content is converted and the coordinate system preserved except for the value dimensions. The value dimension of the overlay image is used in world coordinates to find the color of the colormap. Missing data handling: Missing data values are not affected in the background image. The overlay image must be float32 and missing data may need preprocessing before conversion.
Keywords
paint, colorize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
background |
1 |
The background image to use as grayscale background. Needs to be UINT8. |
|
overlay |
1 |
The overlay image that together with the colormap creates the color in each pixel. |
|
colormap |
CONST_OBJECT |
1 |
Provide the color map to use when converting the image. |
imageWeight |
FLOAT |
? |
Tune the relative mixing between background content and overlay. Default is 0.5. |
Sample
image = Image.mixColormap(background, overlay, colormap, imageWeight)morphology()
Short description
A morphological transformation applied to grayscale images. The possible transformation types are: ERODE, DILATE, OPEN, CLOSE, GRADIENT, TOPHAT and BLACKHAT. A circular structuring element/kernel is used for all types. The diameter of the kernel can be specified by diameterPix. For erosion the basic idea is just like soil erosion, it erodes away the boundaries of an object making it thinner. The dilation is the opposite transformation. The elements of the kernel contain: 0-background or 1-foreground. It is centered at each image pixel and defines the neighborhood pixels to be used. For grayscale erosion the new pixel value corresponds to the minimum value of the image pixels under the structuring element foreground. Similarly, for grayscale dilation the maximum of the neighborhood is used. The remaining transformations are: opening - erosion followed by dilation; closing - dilation followed by erosion; morphological gradient - difference between dilation and erosion; top hat - difference between input image and opening; black hat - difference between closing and input image. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The diameter of the structuring element is in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.
Keywords
binary, blackhat, close, erode, open, tophat, dilate
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageIn |
1 |
Input image. Supported image types are uint8, uint16, int8, int16, int32, float32 and float64. |
|
diameterPix |
INT |
1 |
The diameter of the circular structuring element/kernel in pixels. The value must be odd and between 3 and 51. |
transform |
1 |
The morphological transformation, possible types are: ERODE, DILATE, OPEN, CLOSE, GRADIENT, TOPHAT and BLACKHAT. |
|
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageOut |
? |
Morphology transformed image |
Sample
imageOut = Image.morphology(imageIn, diameterPix, transform, region)mosaic()
Short description
Crops an image into a vector of smaller tiles. The mosaic tiles can be specified to overlap. A valid tile must be completely within the source image, i.e., tiles that would partly extend outside the image at the right and bottom borders of the source image are not included in the output vector. The vector of tiles is sorted row wise so that all the tiles covering the uppermost part of the image come first.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
tileWidth |
INT |
1 |
The width of a tile in pixels. |
tileHeight |
INT |
1 |
The height of a tile in pixels. |
xOverlap |
INT |
? |
Optional overlap between tiles in the x-direction in pixels. Default is no overlap, i.e., 0 pixels. |
yOverlap |
INT |
? |
Optional overlap between tiles in the y-direction in pixels. Default is no overlap, i.e., 0 pixels. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageTiles |
+ |
Vector of image tiles. |
|
xTileCount |
INT |
1 |
Number of tiles in the x-direction. |
yTileCount |
INT |
1 |
Number if tiles in the y-direction. |
Sample (auto-generated)
imageTiles, xTileCount, yTileCount = Image.mosaic(image, tileWidth, tileHeight, xOverlap, yOverlap)multiply()
Short description
Multiplies two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate value. The second image is treated as a unit-less modifier and it must therefore have a standard image world coordinate system with pixel sizes all equal to 1 and origins equal to 0. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. Note that it is possible to obtain 0 as result of the multiplication and that such pixels then will be considered as missing data in subsequent processing steps.
Keywords
arithmetic, scale, times
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. |
|
image2 |
1 |
The second source image. |
Sample
result = Image.multiply(image1, image2)multiplyAddConstant()
Short description
Multiplies an image pixelwise by a constant alpha and then adds a second constant beta: alpha*Image + beta. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
arithmetic, scale, offset
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
alpha |
FLOAT |
[1+] |
The constant to multiply with. A vector with three values must be given if the input image is an RGB image. |
beta |
FLOAT |
[1+] |
The constant to add. A vector with three values must be given if the input image is an RGB image. |
Sample
result = Image.multiplyAddConstant(image, alpha, beta)multiplyAddConstantInplace()
Short description
Inplace version of Image.multiplyAddConstant function which modifies the input image. See base function for full documentation.
Keywords
arithmetic, scale, offset
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
|
alpha |
FLOAT |
[1+] |
The constant to multiply with. A vector with three values must be given if the input image is an RGB image. |
beta |
FLOAT |
[1+] |
The constant to add. A vector with three values must be given if the input image is an RGB image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.multiplyAddConstantInplace(image, alpha, beta)multiplyConstant()
Short description
Multiplies all pixels in the image with a constant value. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, multiplication of the world z-value is done, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw pixel values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
arithmetic, scale, times
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
constant |
FLOAT |
[1+] |
The constant to multiply with. A vector with three values must be given if the input image is an RGB image. |
Sample
result = Image.multiplyConstant(image, 2.0)multiplyConstantInplace()
Short description
Inplace version of Image.multiplyConstant function which modifies the input image. See base function for full documentation.
Keywords
arithmetic, scale, times
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
|
constant |
FLOAT |
[1+] |
The constant to multiply with. A vector with three values must be given if the input image is an RGB image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.multiplyConstantInplace(image, 2.0)multiplyInplace()
Short description
Inplace version of the Image.multiply function which modifies the first input image to contain the product of the input images. See base function for full documentation.
Keywords
arithmetic, scale, times
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. This image is overwritten with the product. |
|
image2 |
1 |
The second source image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.multiplyInplace(image1, image2)multiplyProfile()
Short description
Returns the image with the profile multiplied with all rows or all columns depending on the dimension argument. The dimension argument is optional and if not provided processing is done row by row. Image world coordinate system handling: The input image coordinate system is transferred to the output image. The operation is performed in the world coordinate system. The z-origin of the input image must be zero. Missing data handling: Missing data in the image will remain in the output image. Missing data in the profile will leave the corresponding image values unchanged.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
profile |
1 |
The profile. |
|
dimension |
ENUM |
? |
Optional processing dimension (row/column). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Image with profile multiplied along processing dimension. |
Sample
result = Image.multiplyProfile(image, profile, dimension)multiplyProfileInplace()
Short description
Inplace version of the Image.multiplyProfile function that modifies the input image. See base function for full documentation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. This image is overwritten with the result image. |
|
profile |
1 |
The profile. |
|
dimension |
ENUM |
? |
Optional processing dimension (row/column). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.multiplyProfileInplace(image, profile, dimension)normalize()
Short description
Scales the raw pixel values linearly so that all pixels fit into a given range (lowerBound, upperBound). Keeps the world values constant. Target bounds outside the representable range of the image type are accepted. In that case, pixel values are clamped to the representable range. Image world coordinate system handling: The world coordinate system of the output image along the value axis z is chosen such that the world pixel values remains unchanged unless clamping occurs. For integer type images, rounding to integer raw pixel values will change the world values slightly. Other meta data are copied from the input image. Missing data handling: Pixels with missing data remain marked as missing in the output. For images with the missing data flag set, raw pixel values are clamped to 1 instead of 0 to avoid introducing more pixels marked as missing.
Keywords
contrast, intensity, scale, stretch, equalize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, int8, int16, int32, float32 and float64. |
|
lowerBound |
FLOAT |
? |
Lower bound (raw pixel value). Default value is minimum value of underlying datatype. |
upperBound |
FLOAT |
? |
Upper bound (raw pixel value). Default value is maximum value of underlying datatype. |
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
normalizedImage |
? |
Normalized image |
Sample
normalizedImage = Image.normalize(image)normalizedDifference()
Short description
Computes the pixel-wise normalized difference between two images, based on the NDVI (normalized difference vegetation index). The images must be of equal size and pixel type. An optional minimum and maximum value in the range [-1, 1] can be given, to enhance the contrast for the range that is of interest. All normalized difference values outside this value range will then be clamped, and for integer images the image will be rescaled such that the kept range fills out the full image range. This function only accepts the following image types: UINT8, UINT16, UINT32, FLOAT32 and FLOAT64. Image world coordinate system handling: The pixel size and origin in the z-direction are set such that the world values in the result image will correspond to the calculated normalized difference value, in the range [-1, 1]. Pixel sizes and origins in the x- and y-dimensions are copied from the first input image, but are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.
Keywords
arithmetic, contrast, scale, stretch, normalize
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. |
|
image2 |
1 |
The second source image. |
|
minValue |
FLOAT |
? |
Optional minimum value for the normalized difference, used for clamping and (in the case of integer image types) rescaling the image. Default is -1 (no clamping). |
maxValue |
FLOAT |
? |
Optional maximum value for the normalized difference, used for clamping and (in the case of integer image types) rescaling the image. Default is 1 (no clamping). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
The normalized difference image. |
Sample
result = Image.normalizedDifference(image1, image2)pad()
Short description
Image padding, adds a border to the image. Image world coordinate system handling: The image world coordinate system is used to update the output image origin, it is calculated as follows: (Oxout, Oyout, Ozout) = (Oxin - pixelSizeX * leftPaddingPix, Oyin - pixelSizeY * topPaddingPix, Ozin), the world pixel sizes remain the same. The boundary paddings are in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not use the missing data flag. If the padding contains zeros it will be treated as missing data if the flag is on.
Keywords
replicate, extend
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageIn |
1 |
Input image. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB. |
|
topPaddingPix |
INT |
1 |
The top padding in pixels |
bottomPaddingPix |
INT |
1 |
The bottom padding in pixels |
leftPaddingPix |
INT |
1 |
The left padding in pixels |
rightPaddingPix |
INT |
1 |
The right padding in pixels |
borderType |
ENUM |
1 |
The border type to use for the padding, currently CONSTANT, REPLICATE, REFLECT and WRAP are available. If the border type is not CONSTANT the padding value is not used. |
intensity |
FLOAT |
[?*] |
The padding intensity. In case the image type is RGB then an array of 3 elements (one per channel) must be provided. If the border type is not CONSTANT this value does not need to be specified. |
Sample
imageOut = Image.pad(imageIn, topPaddingPix, bottomPaddingPix, leftPaddingPix, rightPaddingPix, borderType, intensity)pow()
Short description
Applies an exponent to the value at each pixel. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel data type respectively. Image world coordinate system handling: The z-scale of the image is considered, but the operation is not implemented for images with z-origin different from 0.0. The image metadata from the input image is copied to the output image. Missing data handling: In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
arithmetic, cube, exp, exponent, inverse, invert, sqr, sqrt, square, power
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. |
|
exponent |
FLOAT |
[1+] |
The exponent. Should be a vector (r,g,b) for RGB24 images. |
Sample
result = Image.pow(image, exponent)powInplace()
Short description
Inplace version of the Image.pow function which modifies the input image. See base function for full documentation.
Keywords
arithmetic, cube, exp, exponent, inverse, invert, sqr, sqrt, square, power
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
|
exponent |
FLOAT |
[1+] |
The exponent. Should be a vector (r,g,b) for RGB24 images. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
A reference to the result image. |
Sample
Image.powInplace(image, exponent)proposeColorToGrayWeights()
Short description
Calculates conversion weights that can be used to convert an RGB image into a gray value image. The weights are selected to optimally maintain image contrast.
Keywords
RGB, gray
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageRGB |
1 |
RGB image (8-bit). |
|
region |
CONST_OBJECT |
? |
Optional region. If set, the conversion weights are calculated with the image values inside the, otherwise all the image values are used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
redWeight |
FLOAT |
? |
The weight that adjusts the contribution of the Red channel. |
greenWeight |
FLOAT |
? |
The weight that adjusts the contribution of the Green channel. |
blueWeight |
FLOAT |
? |
The weight that adjusts the contribution of the Blue channel. |
Sample
redWeight, greenWeight, blueWeight = Image.proposeColorToGrayWeights(imageRGB, region)refineLocalExtrema()
Short description
Estimates the sub pixel positions of a found extrema guided by an image. This is done by use of a local polynomial in the neighborhood of the point position. The input extremaRegion is assumed to be a pixelregion with multiple disjoint maxima, as returned from the Image.findLocalExtrema function. The output is subpixel precision points according to the input image coordinate system. If the pixel region extrema seed does not correspond to an image extrema (within the local neighborhood) the resulting position may be imperfect. Image world coordinate system handling: The placement of the returned points is placed in the coordinate system of the guiding image. Missing data handling: This function does not handle missing data. Remove missing data before calling this function.
Keywords
maxima, min, minima, subpixel, max
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The input image. |
|
extremaRegion |
CONST_OBJECT |
1 |
PixelRegion with local extrema points. |
extremaType |
ENUM |
1 |
Which type of extrema to look for. MIN or MAX. |
neighborhoodSize |
INT |
? |
The neighborhood size, width and height in pixels. Must be odd and >= 3. Default is 3. |
discardBoundaryPoints |
BOOL |
? |
Points too close to the border to be accurately refined can be discarded or unchanged. Default is true. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
extremaPoints |
* |
The subpixel positions of the points. |
Sample
local extremaPoints = Image.refineLocalExtrema(image, extremaRegion, "MAX")removeDynamicChanges()
Short description
Removes pixels which changed compared to the reference Image. All changes above the threshold are set to the reset value (default: 0).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to be filtered. |
|
referenceImage |
1 |
The image used as reference. |
|
threshold |
INT |
1 |
The threshold value. Defines the change between the images to mark pixels as invalid. |
resetValue |
INT |
? |
The reset value used for invalid pixels. Default is 0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filteredImage |
? |
Returns the filtered image or nil. |
Sample
local filteredImage = Image.removeDynamicChanges(image, referenceImage, threshold)renderPlane()
Short description
Renders a plane to an image, clamping values to the representable range of the image. The output image is of the same type as the input image. Image world coordinate system handling: The surface is rendered in the world space defined by the reference image, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the reference image is copied to the output image. Missing data handling: The missing data flag of the reference image is copied to the output image. If the flag is set, raw pixel values are clamped to 1 instead of 0 to avoid generating pixels with missing data.
Keywords
draw
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The reference image defining the output image size, type and coordinate system. |
|
plane |
1 |
The plane to render, should be a plane shape. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
renderedImage |
? |
The image with the rendered plane. Nil if an error occurred. |
Sample
renderedImage = Image.renderPlane(image, plane)renderPlaneInplace()
Short description
Inplace version of the Image.renderPlane function which modifies the input image by adding the value of a given plane. See base function for full documentation.
Keywords
draw
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Reference input image. This image is overwritten with the result image. |
|
plane |
1 |
The plane to render, must be a Shape3D plane. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.renderPlaneInplace(image, plane)renderPolynomial()
Short description
Renders a 2nd order polynomial into an image, clamping values to the representable range of the image. The output image is of the same type as the input image. The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients. Image world coordinate system handling: The surface is rendered in the world space defined by the reference image, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the reference image is copied to the output image. Missing data handling: The missing data flag of the reference image is copied to the output image. If the flag is set, raw pixel values are clamped to 1 instead of 0 to avoid generating pixels with missing data.
Keywords
draw
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The reference image defining the output image size, type and coordinate system. |
|
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
offsetZ |
FLOAT |
? |
Optional offset to avoid clamping. The world unit results are added with this offset before being placed in the output. Image z-origin is adjusted to maintain the correct absolute coordinates. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
renderedImage |
? |
The image with the rendered polynomial. Nil if an error occurred. |
Sample
renderedImage = Image.renderPolynomial(image, polynomial)renderPolynomialInplace()
Short description
Inplace version of the Image.renderPolynomial function which modifies the input image by adding the value of a given polynomial. See base function for full documentation.
Keywords
draw
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Reference input image. This image is overwritten with the result image. |
|
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
offsetZ |
FLOAT |
? |
Optional offset to avoid clamping. The world unit results are added with this offset before being placed in the output. Image z-origin is adjusted to maintain the correct absolute coordinates. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.renderPolynomialInplace(image, polynomial)renderText()
Short description
Renders text into an image by modifying the pixel values. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The font parameters and text position are in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not use the missing data flag.
Keywords
characters, letters, draw
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the text into. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB. |
|
text |
STRING |
1 |
The characters that cannot be rendered using the specified font are replaced by question marks. |
positionWorld |
1 |
The position of the text inside the image, in world coordinates. The text is aligned to the bottom-left corner. |
|
fontSizePix |
INT |
1 |
The font size in pixels. |
fontThicknessPix |
INT |
1 |
The font line thickness radius in pixels. To calculate the overall thickness the following equation can be used: thickness=(fontThicknessPix*2+1). |
value |
FLOAT |
[1+] |
The text (intensity/color) value. In case the image type is RGB then an array of 3 elements (one per channel) must be provided. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
? |
Image with rendered text |
Sample
image = Image.renderText(image, text, positionWorld, fontSizePix, fontThicknessPix, value)renderTextInplace()
Short description
Inplace version of the Image.renderText function that modifies the input image. See base function for full documentation.
Keywords
characters, letters, draw
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to render the text into. This image is overwritten with the rendered text. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB. |
|
text |
STRING |
1 |
The characters that cannot be rendered using the specified font are replaced by question marks. |
positionWorld |
1 |
The position of the text inside the image, in world coordinates. The text is aligned to the bottom-left corner. |
|
fontSizePix |
INT |
1 |
The font size in pixels. |
fontThicknessPix |
INT |
1 |
The font line thickness radius in pixels. To calculate the overall thickness the following equation can be used: thickness=(fontThicknessPix*2+1). |
value |
FLOAT |
[1+] |
The text (intensity/color) value. In case the image type is RGB then an array of 3 elements (one per channel) must be provided. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.renderTextInplace(image, text, positionWorld, fontSizePix, fontThicknessPix, value)replace()
Short description
Replaces the image content in a specified region with the content of another image. The images must have the same pixel type. Image world coordinate system handling: The world coordinate systems of the input images are not used. The output will have the same coordinate system as the first input image. Missing data handling: Raw pixel values are copied as they are. If there are missing data within the region in the replacing image, the source image pixels will be replaced by missing data.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
sourceImage |
1 |
Base image onto which the other image is painted. |
|
replacingImage |
1 |
The image containing the information to replace with. |
|
region |
CONST_OBJECT |
1 |
The region to replace. |
Sample
local result = Image.replace(sourceImage, replacingImage, region)replaceInplace()
Short description
Inplace version of the Image.replace function which modifies the first input image by replacing pixel values with pixel values from another image. See base function for full documentation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
sourceImage |
1 |
Base image onto which the other image is painted. |
|
replacingImage |
1 |
The image containing the information to replace with. |
|
region |
CONST_OBJECT |
1 |
The region to replace. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
local result = Image.replaceInplace(sourceImage, replacingImage, region)resize()
Short description
Resizes an image to a given size in pixels. Different interpolation methods can be used. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
Keywords
decimate, downsample, resample, subsample, transform, upsample, scale
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image |
|
width |
INT |
1 |
The width of the result |
height |
INT |
1 |
The height of the result. |
method |
ENUM |
? |
The resampling method. Default is LINEAR. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resizedImage |
? |
Image with new size. |
Sample
resizedImage = Image.resize(image, 300, 400, "LINEAR")resizeScale()
Short description
Resizes an image by a scale factor. Different interpolation methods can be used. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
Keywords
decimate, downsample, resample, subsample, transform, upsample, scale
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image |
|
fx |
FLOAT |
1 |
Scaling factor along the x-axis. |
fy |
FLOAT |
? |
Scaling factor along the y-axis. Optional, if omitted the same as the x-scale is used. |
method |
ENUM |
? |
The resampling method. Default is LINEAR. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resizedImage |
? |
Image with new size. |
Sample
resizedImage = Image.resizeScale(image, 1.5, 1.5, "LINEAR")resizeScaleGaussian()
| This API is experimental |
Short description
Resizes an image by a scale factor using gaussian sampling. This method is usually slower than normal Image.resizeScale. Image world coordinate system handling: The coordinate system of the output image will be adjusted in relation to the input to take into account pixel size changes. Missing data handling: Currently there is no missing data handling.
Keywords
decimate, downsample, resample, subsample, transform, upsample, scale
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image |
|
fx |
FLOAT |
1 |
Scaling factor along the x-axis. |
fy |
FLOAT |
? |
Scaling factor along the y-axis. Optional, if omitted the same as the x-scale is used. |
sigma |
FLOAT |
? |
Increase to produce a smoother result at the expense of longer processing time. Default is 0.6. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resizedImage |
? |
Image with new size. |
Sample
resizedImage = Image.resizeScaleGaussian(image, 0.8, 0.8, 0.6)rotate()
Short description
Rotates an image around the center of the image. Optionally a different origin of rotation can be specified. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image |
|
rotationRad |
FLOAT |
1 |
Rotation in radians. As the image has a left-handed coordinate system, a positive rotation is in a counter clockwise direction. |
origin |
? |
Optional origin of rotation if other than center of image. Represented as a 2D Point type. |
|
method |
ENUM |
? |
The resampling method. |
grid |
ENUM |
? |
The pixel grid to use for the output, default is SAME, the same as the input image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
rotatedImage |
? |
The rotated image. |
Sample
rotatedImage = Image.rotate(image, rotationRad)rotate90()
Short description
Rotates an image +90, -90 or 180 degrees. A positive rotation is in the clockwise direction. The pixels are rearranged and no interpolation takes place, making the operation faster than a general rotation. Image world coordinate system handling: For plus and minus 90 degree rotations, the x- and y-pixel sizes are swapped so that the width and height are also swapped. The image origin is copied from the input image. Missing data handling: Missing data is rotated in the same way as the input image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image |
|
rotationSteps |
INT |
1 |
The number of 90-degree steps to rotate the image in, e.g. -1, 1 or 2. Other integers are allowed, representing the same rotations. A positive rotation is in a clockwise direction. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
rotatedImage |
? |
The rotated image. |
Sample
rotatedImage = Image.rotate90(image, rotationSteps)roughness()
Short description
Calculates a local roughness metrics around each pixel. Also returns local average and standard deviation (the same as from Image.stdDev). The skewness is a measure of the asymmetry of the distribution, and the kurtosis is a measure of the "tailedness" of the distribution. To get the excess kurtosis, subtract 3 from the returned kurtosis value. Image world coordinate system handling: The kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. The output image inherits the missing data flag of the input image.
Keywords
convolve, filter, kurtosis, skewness, smoothness, variance, statistics
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
|
kernelSizePix |
INT |
1 |
Size of the kernel, must be positive. |
region |
CONST_OBJECT |
? |
Optional region of interest. Enter nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when processing images containing missing data. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
meanImage |
? |
Output mean image. Same type as input image. |
|
stdDevImage |
? |
Output standard deviation image. Of type float32 unless input is float64, then float64 is returned. |
|
skewnessImage |
? |
Output skewness image. Of type float32 unless input is float64, then float64 is returned. |
|
kurtosisImage |
? |
Output kurtosis image. Of type float32 unless input is float64, then float64 is returned. |
Sample
local meanImage, stdDevImage, skewnessImage, kurtosisImage = Image.roughness(image, kernelSizePix)save()
Short description
Saves an image to the specified file path. Overwrites the file if it already exists. Supported pixel types are: UINT8, UINT16, INT8, INT16, INT32, FLOAT32 and FLOAT64. The format is defined by the file extension: .bmp: Bitmap, no data compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are not saved. .pgm: Portable gray map, no data compression. (Optional compression parameter can be used to set the bit depth in the pgm header. Only smaller values are allowed. E.g. 8 bit image → Valid compression parameter: [0 … 255]). Image origin, pixel size and missing data flag are not saved. .png: PNG (not supported by all devices), lossless data compression. (Compression level can be controlled by compression parameter. Allowed values are "0" to "9". Default is "6".) Image origin, pixel size and missing data flag are not saved. For pixel types INT8, INT16, INT32, FLOAT32 and FLOAT64 the values are clamped to 0-255. .jpg: JPEG (not supported by all devices), lossy data compression. Not supported on all devices. (Quality can be controlled by compression parameter. Allowed values are "0" to "100". Default is "95") Image origin, pixel size and missing data flag are not saved. .json: JSON AppSpace format (redirects to Object.save), no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved. .msgpack: MessagePack AppSpace format (redirects to Object.save), no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to save. |
|
filepath |
STRING |
1 |
The path and name of the file to write the image to. |
compression |
STRING |
? |
Optional parameters controlling compression ratio for certain file formats. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true on success. |
Sample
Image.save(image, "private/image.bmp")setAll()
Short description
Sets all raw pixel values in an image to the specified value. The value can be a vector (r, g, b) for RGB24 images. Pixels with missing data are also set. Setting all pixels to zero on an image with the global missing data flag set, all pixels will be marked as missing.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
value |
FLOAT |
[1+] |
The raw pixel value to set. Can be a vector (r, g, b) for RGB24 images. |
Sample (auto-generated)
Image.setAll(image, value)setColumn()
Short description
Fills in a column of an image with the value(s) provided. Values are given in world coordinates (e.g. millimeters). Note that this function operates inplace. If a scalar value is provided, all rows from startRow to the image height will be filled with the value. If the provided value(s) is a vector of length N, N rows will be filled with these values starting at row startRow. Coordinate system handling: The image world coordinate system is only considered along the value range. Values are clamped to fit the pixel value range of the target image. Missing data handling: A missing data image may be used as the target image. Values to be set are clamped to the valid range of the target image, that is, the value to be set is clamped such that it is always marked as a valid value. Temporarily disable the missing data flag to allow setting values that will be regarded as missing (raw pixel value zero).
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The target image. All pixel types except RGB are supported. |
|
values |
FLOAT |
[1+] |
The values to be set, in world coordinates. |
column |
INT |
[1+] |
Index of column(s) to fill, zero-based. |
startRow |
INT |
? |
The first row index to fill, zero-based. If no index is given 0 will be used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if values could be set. |
Sample
local success = Image.setColumn(image, values, column, startRow)setColumnProfile()
Short description
Fills in a column of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image column starting at row startRow. The number of values set are equal to the length of the profile. Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels. Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The target image. All pixel types except RGB are supported. |
|
profile |
[1+] |
The source profile. |
|
column |
INT |
[1+] |
Index of column(s) to fill, zero-based. |
startRow |
INT |
? |
The first row index to fill, zero-based. If no index is given 0 will be used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if values could be set. |
Sample
local success = Image.setColumnProfile(image, profile, column, startRow)setMissingDataFlag()
Short description
Sets the missing data setting in the image. 0 means no missing data handling, 1 means that the value 0 is treated as missing data.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
||
missingDataFlag |
INT |
1 |
0 means no missing data handling, 1 means that the value 0 is treated as missing data. |
Sample (auto-generated)
Image.setMissingDataFlag(image, missingDataFlag)setOrigin()
Short description
Sets the origin of the image world coordinate system in the image. The origin corresponds to the image world coordinate of the top-left pixel. If a 2D point is provided, the origin is unchanged in the z-direction.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
||
origin |
1 |
A 3D point describing the world coordinate of the top-left image pixel. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successfully set the origin. |
Sample (auto-generated)
success = Image.setOrigin(image, origin)setOriginZ()
Short description
Sets the z-origin of the image world coordinate system in the image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Image object to update. |
|
originZ |
FLOAT |
1 |
The new z-origin. |
Sample (auto-generated)
Image.setOriginZ(image, originZ)setPixel()
Short description
Set the pixel value or a vector of pixel values in an image at position(s) (x,y) to the given pixel value. For monochrome image types this is a single float value, for RGB24 a vector of three float values in the order red, green, blue.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to set the pixels to |
|
x |
INT |
[1+] |
The x coordinate, or a vector of x coordinates, of the pixel(s) to set. |
y |
INT |
[1+] |
The y coordinate, or a vector of y coordinates, of the pixel(s) to set. |
value |
FLOAT |
[1+] |
The pixel value, or a vector of RGB values, to set. |
pixelValueType |
ENUM |
? |
How the pixel value is set. It can be set in raw (default) or world coordinates. |
Sample
Image.setPixel(image, 5, 6, 127)
Image.setPixel(imageRGB, {5, 5}, {6, 7}, {0, 127, 255})setPixelSize()
Short description
Sets the pixel size in world coordinates. If the size in the Z direction is omitted, the Z size is unchanged.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
||
sizeX |
FLOAT |
1 |
The size of a pixel in the X dimension in world coordinate units. |
sizeY |
FLOAT |
1 |
The size of a pixel in the Y dimension in world coordinate units. |
sizeZ |
FLOAT |
? |
The size of a pixel in the Z dimension in world coordinate units (optional). |
Sample (auto-generated)
Image.setPixelSize(image, sizeX, sizeY, sizeZ)setPixelSizeZ()
Short description
Sets the pixel size in the z-dimension in world coordinates, e.g., the number of millimeters each pixel value integer increment corresponds to.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
||
sizeZ |
FLOAT |
1 |
The size/scale along the z-dimension. |
Sample (auto-generated)
Image.setPixelSizeZ(image, sizeZ)setRow()
Short description
Fills in a row of an image with the value(s) provided. Values are given in world coordinates (e.g. millimeters). Note that this function operates inplace. If a scalar value is provided, all columns from startColumn to the image width will be filled with the value. If the provided value(s) is a vector of length N, N columns will be filled with these values starting at column startColumn. Coordinate system handling: The image world coordinate system is only considered along the value range. Values are clamped to fit the pixel value range of the target image. Missing data handling: A missing data image may be used as the target image. Values to be set are clamped to the valid range of the target image, that is, the value to be set is clamped such that it is always marked as a valid value. Temporarily disable the missing data flag to allow setting values that will be regarded as missing (raw pixel value zero).
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The target image. All pixel types except RGB are supported. |
|
values |
FLOAT |
[1+] |
The values to be set, in world coordinates. |
row |
INT |
[1+] |
Index of row(s) to fill, zero-based. |
startColumn |
INT |
? |
The first column index to fill, zero-based. If no index is given 0 will be used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if all values could be set. |
Sample
local success = Image.setRow(image, values, row, startColumn)setRowProfile()
Short description
Fills in a row of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image row starting at column startColumn. The number of values set are equal to the length of the profile. Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels. Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The target image. All pixel types except RGB are supported. |
|
profile |
[1+] |
The source profile. |
|
row |
INT |
[1+] |
Index of row(s) to fill, zero-based. |
startColumn |
INT |
? |
The first column index to fill, zero-based. If no index is given 0 will be used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if values could be set. |
Sample
local success = Image.setRowProfile(image, profile, row, startColumn)sobel()
Short description
Applies the standard 3x3 Sobel filter operator to find gradients and edges in the x- and y-directions. Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
Keywords
convolve, derivative, gradient, edge
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
|
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Pixel values outside the region are undefined. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
gx |
? |
Output image with gradient x. |
|
gy |
? |
Output image with gradient y. |
Sample
gx, gy = Image.sobel(image)sobelMagnitude()
Short description
Calculates the magnitude of the standard 3x3 Sobel operator gradient responses dx and dy to find edges in the input image. Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
Keywords
convolve, derivative, gradient, edge
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, uint32, int8, int16, int32, float32 and float64. |
|
region |
CONST_OBJECT |
? |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
metric |
ENUM |
? |
Select if the faster abs(dx)+abs(dy) or the more precise sqrt(dx2+dy2) should be used. Default is 'ABS'. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageMag |
? |
Output image with gradient magnitude. |
Sample
imageMag = Image.sobelMagnitude(image)splitRGB()
Short description
Splits an RGB image into the individual R, G, B color components. The input RGB image must be of 8-bit RGB type.
Keywords
color
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageRGB |
1 |
RGB image (8-bit) to convert. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageR |
? |
Red component as image. |
|
imageG |
? |
Green component as image. |
|
imageB |
? |
Blue component as image. |
Sample
imageR, imageG, imageB = Image.splitRGB(imageRGB)stdDev()
Short description
Calculates a local standard deviation around each pixel. Also returns the local average (the same as from Image.blur). Image world coordinate system handling: The kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.
Keywords
box, boxcar, convolve, denoise, filter, smooth, statistics
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
|
kernelSizePix |
INT |
1 |
Size of the kernel, must be positive. |
region |
CONST_OBJECT |
? |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when processing images containing missing data. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
stdDevImage |
? |
Output standard deviation image. Of type float32 unless input is float64, then float64 is returned. |
|
meanImage |
? |
Output mean image. Same type as input image. |
Sample
stdDevImage, meanImage = Image.stdDev(image, kernelSizePix)subtract()
Short description
Subtracts two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. For unsigned integer types it can be useful to first apply Image.adjustOriginZ() to image1 to avoid clamping the results to 0. For images A, B subtracting B from A would cause clamping when values in B are larger than those in A by such a large amount that the difference exceeds the Z-origin of A. By adjusting the origin of A to a smaller value this can be remedied. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.
Keywords
arithmetic, difference, minus
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. |
|
image2 |
1 |
The second source image. |
Sample
result = Image.subtract(image1, image2)subtractInplace()
Short description
Inplace version of the Image.subtract function which modifies the first input image to contain the difference of the input images. See base function for full documentation.
Keywords
arithmetic, difference, minus
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image1 |
1 |
The first source image. This image is overwritten with the difference. |
|
image2 |
1 |
The second source image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.subtractInplace(image1, image2)subtractPlane()
Short description
Subtracts a plane from an image. For every pixel, the corresponding plane z-value is subtracted. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. By setting autoAdjustOriginZ true for unsigned integer data, the origin of the result image will be adjusted to avoid clamping at zero. Using automatic origin adjustment on a partial region of the image will not compensate the pixel values outside the region for the new origin, such pixels will appear with an offset in global coordinates. Image world coordinate system handling: The plane is interpreted in world space and subtracted from the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
gradient, ramp
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
plane |
1 |
The plane to subtract, must be a Shape3D plane. |
|
region |
CONST_OBJECT |
? |
Region of the image where the plane should be subtracted, default is the full image. An empty region or nil are interpreted as the full image. |
autoAdjustOriginZ |
BOOL |
? |
Flag indicating if the origin of the output image should be adjusted to avoid clamping at zero. Default is false, using the same origin as the input image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resultImage |
? |
The image with the subtracted plane. Nil if an error occurred. |
Sample
resultImage = Image.subtractPlane(image, plane, region, autoAdjustOriginZ)subtractPlaneInplace()
Short description
Inplace version of the Image.subtractPlane function which modifies the input image by subtracting the value of a given plane. See base function for full documentation.
Keywords
gradient, ramp
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
|
plane |
1 |
The plane to subtract, must be a Shape3D plane. |
|
region |
CONST_OBJECT |
? |
Region of the image where the plane should be subtracted, default is the full image. An empty region or nil are interpreted as the full image. |
autoAdjustOriginZ |
BOOL |
? |
Flag indicating if the origin of the output image should be adjusted to avoid clamping at zero. Default is false, using the same origin as the input image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.subtractPlaneInplace(image, plane, region, autoAdjustOriginZ)subtractPolynomial()
Short description
Subtracts a 2nd order polynomial from an image. For every pixel, the corresponding polynomial z-value is subtracted. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. By setting offsetZ to a value other than zero, the origin of the result image can be adjusted to avoid clamping. Note that the functions Image.thresholdPolynomial and Image.binarizePolynomial exist for object segmentation. The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients. Image world coordinate system handling: The polynomial is interpreted in world space and subtracted from the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
Keywords
quadratic
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
region |
CONST_OBJECT |
? |
Region of the image where the polynomial is to be subtracted, default is the full image. An empty region or nil are interpreted as the full image. |
offsetZ |
FLOAT |
? |
Optional offset to avoid clamping. The world unit results are added with this offset before being placed in the output. Image z-origin is adjusted to maintain the correct absolute coordinates. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
resultImage |
? |
The image with the subtracted polynomial. Nil if an error occurred. |
Sample
resultImage = Image.subtractPolynomial(image, polynomial, region, offsetZ)subtractPolynomialInplace()
Short description
Inplace version of the Image.subtractPolynomial function which modifies the input image by subtracting the value of a given polynomial. See base function for full documentation.
Keywords
quadratic
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image. This image is overwritten with the result image. |
|
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
region |
CONST_OBJECT |
? |
Region of the image where the polynomial is to be subtracted, default is the full image. An empty region or nil are interpreted as the full image. |
offsetZ |
FLOAT |
? |
Optional offset to avoid clamping. The world unit results are added with this offset before being placed in the output. Image z-origin is adjusted to maintain the correct absolute coordinates. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.subtractPolynomialInplace(image, polynomial, region, offsetZ)subtractProfile()
Short description
Returns the image with the profile subtracted from all rows or all columns depending on the dimension argument. The dimension argument is optional and if not provided processing is done row by row. Image world coordinate system handling: The input image coordinate system is transferred to the output image. The input profile is subtracted in world coordinates. Missing data handling: Missing data in the input image remains missing in the output image. For missing data in the profile, the image data will be unchanged. If missing data, note that the minimum pixel value is always 1 for valid pixels.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. |
|
profile |
1 |
The profile. |
|
dimension |
ENUM |
? |
Optional processing dimension (row/column). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Image with profile subtracted along processing dimension. |
Sample
result = Image.subtractProfile(image, profile, dimension)subtractProfileInplace()
Short description
Inplace version of the Image.subtractProfile function that modifies the input image. See base function for full documentation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image. This image is overwritten with the result image. |
|
profile |
1 |
The profile. |
|
dimension |
ENUM |
? |
Optional processing dimension (row/column). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.subtractProfileInplace(image, profile, dimension)thin()
Short description
Applies a morphological thinning, also known as skeletonization, using the Guo-Hall algorithm. It is typically performed on an already binarized input image. Zeros in the input image (raw pixel value) are interpreted as background pixels. Note: The algorithm can be slow for large images with many non-zeros (large binary objects). Consider operating on regions of interest if possible. Pixels outside the region of interest may be set to any value. The output is a binary image with the skeleton indicated by pixels set to 1. Image world coordinate system handling: The image world coordinate system is not considered in this function. The output image inherits the x,y origin and x,y pixelsize. The z-origin should be set to 0 and z-pixelsize to 1 in the input image. Missing data handling: The missing data flag should be cleared in the input image and is cleared in the output image.
Keywords
morphology, skeleton
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image, expected to be binary. Supported image types are uint8 and uint16. |
|
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
Sample
skeletonImage = Image.thin(image)threshold()
Short description
Threshold the image by keeping all pixels with a value between lowerThreshold and upperThreshold (inclusive). Return the result as a PixelRegion object. Image world coordinate system handling: The input thresholds are interpreted in the image world coordinate system considering the z-origin and z-pixelsize, e.g., in millimeter scale if the image would represent a range image with z-origin different from 0 of a z-pixelsize different from 1. A conversion is done within the function to raw pixel value thresholds. Missing data handling: Missing data pixels are excluded from the output PixelRegion object.
Keywords
background, blob, foreground, region, segmentation
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. |
|
lowerThreshold |
FLOAT |
1 |
Lower threshold. Expressed in image world coordinates if applicable. |
upperThreshold |
FLOAT |
? |
Upper threshold. Optional, default is no upper threshold (only include pixels larger than the lower threshold) |
regionOfInterest |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
? |
Pixel region containing all pixels with value between the thresholds. |
Sample
region = Image.threshold(image, 1, 255) -- Gets a region containing all non-zero values of an uint8 imagethresholdColor()
Short description
Threshold a color image by keeping all pixels with a value between lowerThreshold and upperThreshold (inclusive). If the color system selected is RGB, threshold1 controls the R channel, threshold2 the G channel and threshold3 the R channel. All channels have range: [0, 255]. If the color system selected is HSV, threshold1 controls the H channel with range [0, 360] degrees, threshold2 the S channel and threshold3 the V channel with ranges [0,100]%. Return the result as a PixelRegion object. Missing data handling: Missing data is not supported.
Keywords
background, blob, foreground, region, segmentation
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
RGB input image. |
|
lowerThresholds |
FLOAT |
+ |
Lower thresholds. A vector with three thresholds (one per channel) must be provided. |
upperThresholds |
FLOAT |
+ |
Upper thresholds. A vector with three thresholds (one per channel) must be provided. |
regionOfInterest |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. |
colorSpace |
ENUM |
? |
Optional, the color space used to perform the threshold. Only RGB and HSV are supported at the moment. The default is RGB. |
invertRanges |
BOOL |
* |
Optional, allows to invert the ranges per channel. For example if the color space is RGB and invertRanges={false, false, true} the B channel range will be inverted, i.e. the threshold condition will become: [0,lowThresholdB] or [upperThresholdB, maxRangeValueB]. Default value is {false, false, false}. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
? |
Pixel region containing all pixels with value between the thresholds. |
Sample
region = Image.thresholdColor(image, {10, 30, 20}, {30, 100, 200})thresholdCompare()
Short description
Threshold an image by pixelwise comparison with a reference image. All pixels with a value greater than or equal to the corresponding reference image value are included in the output PixelRegion object. An optional margin (positive or negative) may be provided, adjusting the reference image values prior to the comparison. A larger positive margin results in fewer included pixels. The optional flag findBright may be set to false, returning the region where the image is lower/darker than the reference image. A region of interest can be provided, limiting the processing to that region. The images must be of the same pixel type and be of equal size. This function gives a PixelRegion objects as output, to get a binary image as output use binarizeCompare instead. Image world coordinate system handling: To allow for an efficient comparison, the z-pixelsizes of the input images must be equal but the z-offsets may differ. The margin parameter is interpreted in image world coordinates, e.g., as a millimeter margin if the input is a range image. Missing data handling: Missing data pixels are excluded from the output PixelRegion object.
Keywords
adaptive, background, blob, foreground, region, segmentation, binarize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image to threshold. |
|
referenceImage |
1 |
Reference image to compare the input image with. |
|
marginWorld |
FLOAT |
? |
Optional margin added to the reference image. Default value is 0. |
findBright |
BOOL |
? |
Optional flag indicating if pixels brighter/higher or darker/lower than the reference image should be included. Default is true, returning brighter pixels. |
regionOfInterest |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. The default region is the entire image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
? |
PixelRegion object containing all pixels passing the comparison operation. |
Sample
region = Image.thresholdCompare(image, referenceImage, marginWorld, findBright, regionOfInterest)thresholdEdgeStrength()
Short description
Threshold the image by keeping all edge pixels with a strength value between lowerThreshold and upperThreshold (inclusive). Return the result as a PixelRegion object. Image world coordinate system handling: The input thresholds are interpreted in the image world coordinate system considering the z-origin and z-pixelsize, e.g., in millimeter scale if the image would represent a range image with z-origin different from 0 of a z-pixelsize different from 1. A conversion is done within the function to raw pixel value thresholds. Missing data handling: Missing data pixels are excluded from the output PixelRegion object. If the current pixel is not missing data but some of its neighbors (used to calculate the edge strength) are considered to have the value of zero.
Keywords
edge, gradient, region, segmentation
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. |
|
lowerEdgeStrengthThreshold |
FLOAT |
1 |
Lower threshold. Expressed in image world coordinates if applicable. |
upperEdgeStrengthThreshold |
FLOAT |
? |
Upper threshold. Optional, default is no upper threshold (only include pixels larger than the lower threshold) |
step |
INT |
? |
Difference step in pixels (used to calculate the edge strength), must be greater than or equal to 1. The default value is 1. |
regionOfInterest |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
? |
Pixel region containing all pixels with edge strength values between the thresholds. |
Sample
region = Image.thresholdEdgeStrength(image, 1, 255)thresholdPlane()
Short description
Thresholds the image by keeping all pixels with a world value between lowerThreshold and upperThreshold relative to the provided plane (inclusive). Returns the result as a PixelRegion object. Thresholding values strictly below or above the reference plane is also supported, using relative thresholds with the same sign. Image world coordinate system handling: The plane is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. Thresholds are interpreted in the world coordinate system. Missing data handling: No pixel marked as missing is included in the output region.
Keywords
adaptive, background, blob, foreground, region, segmentation, binarize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image |
|
lowerThreshold |
FLOAT |
1 |
Lower threshold relative to plane. |
upperThreshold |
FLOAT |
1 |
Upper threshold relative to plane. |
plane |
1 |
The plane, represented as a Shape3D, to which the lower and upper thresholds are related. The shape type must be a plane. |
|
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
thresholdedRegion |
? |
Pixel region containing all pixels with value between the thresholds relative to the plane. |
Sample
thresholdedRegion = Image.thresholdPlane(image, lowerThreshold, upperThreshold, plane, region)thresholdPolynomial()
Short description
Thresholds the image by keeping all pixels with a world value between lowerThreshold and upperThreshold relative to the provided 2nd order polynomial. Returns the result as a PixelRegion object. Thresholding values strictly below or above the reference polynomial is also supported, using relative thresholds with the same sign. The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients. Image world coordinate system handling: The polynomial is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. Thresholds are interpreted in the world coordinate system, e.g., in millimeter unit. Missing data handling: No pixel marked as missing is included in the output region.
Keywords
adaptive, background, blob, foreground, region, segmentation, binarize
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image |
|
lowerThreshold |
FLOAT |
1 |
Lower threshold relative to the polynomial in image world units, i.e., the z-pixel size and origin are used so that the threshold is interpreted in millimeters in case the image is a height map/distance/range image. |
upperThreshold |
FLOAT |
1 |
Upper threshold relative to the polynomial in image world units. |
polynomial |
FLOAT |
+ |
The polynomial to add represented with the 6 coefficients Ac, Ax, Ay, Axx, Axy, Ayy. |
region |
CONST_OBJECT |
? |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
thresholdedRegion |
? |
Pixel region containing all pixels with value between the thresholds relative to the polynomial. |
Sample
thresholdedRegion = Image.thresholdPolynomial(image, lowerThreshold, upperThreshold, polynomial, region)toGray()
Short description
Converts an RGB image into a gray value image.
Keywords
RGB, gray
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageRGB |
1 |
RGB image (8-bit) to convert. |
|
redWeight |
FLOAT |
? |
The weight that adjusts the contribution of the Red channel. |
greenWeight |
FLOAT |
? |
The weight that adjusts the contribution of the Green channel. |
blueWeight |
FLOAT |
? |
The weight that adjusts the contribution of the Blue channel. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageGray |
? |
Gray value image of uint8 pixel type. |
Sample
imageGray = Image.toGray(imageRGB, redWeight, greenWeight, blueWeight)toHSV()
Short description
Converts an RGB image into individual HSV color space components. The Hue-component is usually represented as an angle in the interval [0,360], but to fit in a uint8 image the value is divided by 2 to be in the interval [0,180].
Keywords
HSL, hue, RGB, saturation, color
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageRGB |
1 |
RGB image (8-bit) to convert. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageH |
? |
Hue image, uint8 pixel type and in range [0,180] |
|
imageS |
? |
Saturation image, uint8 pixel type and in range [0,255] |
|
imageV |
? |
Value image, uint8 pixel type and in range [0,255] |
Sample
imageH, imageS, imageV = Image.toHSV(imageRGB)toLab()
Short description
Converts an RGB image into individual Lab color space components.
Keywords
RGB, color
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageRGB |
1 |
RGB image (8-bit) to convert. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageL |
? |
Lightness image, uint8 pixel type and in range [0,255] |
|
imageA |
? |
'a' color component image, uint8 pixel type and in range [1,255] |
|
imageB |
? |
'b' color component image, uint8 pixel type and in range [1,255] |
Sample
imageL, imageA, imageB = Image.toLab(imageRGB)toMatrix()
Short description
Creates a matrix from a monochrome image. Each entry in the matrix corresponds to the pixel value scaled by the image world Z coordinates. Missing data is set to NaN in the matrix.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputImage |
1 |
The input image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matrix |
? |
The matrix with the image content. |
Sample (auto-generated)
matrix = Image.toMatrix(inputImage)toMesh()
Short description
Creates a mesh from an image. The image values are interpreted in world units and are used to create one vertex from each pixel. The intensity input is optional and can be used to set the intensity of the mesh. The mesh intensities are represented as values between 0 and 1. To use a UINT8 image as source set the pixel size in z to 1/255. The color input is also optional and must be an image of RGB type. It can be used alone or together with the intensity input. The final mesh color is a mix of the intensity and color data such that the final color is intensity*color. Image world coordinate system handling: The image world coordinate system is used to create the mesh, i.e. the (x, y, z)-pixel sizes and origins are used to create the (x, y, z)-vertices of the mesh. Missing data handling: For images with missing data the missing values will be represented as mesh coordinates with the z value set to nan.
Keywords
triangle mesh, polygon mesh
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The source image with range/depth information. |
|
calcNormals |
BOOL |
? |
Select if normals should be estimated from the image. Default is false. |
intensity |
? |
Optional image that will be used for intensity at each point. The values are interpreted in world coordinates. Default is 1.0 for all points. |
|
color |
? |
Optional image that will be used for color at each point. Default is white (255,255,255). |
|
close |
BOOL |
? |
Select if the mesh should be closed by a thin sheet just below the image content (minimum height). Default is false. |
thickness |
FLOAT |
? |
The thickness of the bottom when the mesh is closed. Must be positive. Default is 5. |
Sample
local mesh = Image.toMesh(image, true, intensity, color)toPixelCoordinate()
Short description
Converts an image world coordinate to a pixel coordinate.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
||
worldCoordinate |
1 |
The world coordinate point. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pixelCoordinate |
1 |
Returns the pixel coordinate. |
Sample (auto-generated)
pixelCoordinate = Image.toPixelCoordinate(image, worldCoordinate)toPixelRegion()
Short description
Segments the image by creating pixel regions for several value ranges within a bounded interval. Each inner interval, or bin, corresponds to a range decided by the outer bounds and the selection of number of bins. If a certain value range is empty the corresponding pixel region will be empty. Each interval can be considered a label in the case of segmentation or a level curve in the case of a height image. The start of the first interval is at minVal and end of the last interval is at maxVal. Selecting minVal=1 and maxVal=3 and using binCount=2 the following bin ranges are used [1, 2[, [2, 3[. That is, the upper bound is non-inclusive. Image world coordinate system handling: The value ranges are interpreted in world coordinates. Missing data handling: Missing data pixels are never returned in any interval. To include them toggle the missing data flag of the image.
Keywords
labels, segmentation
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The labeled image. |
|
minVal |
FLOAT |
1 |
Minimum label value to consider. |
maxVal |
FLOAT |
1 |
Maximum label value to consider. |
binCount |
INT |
1 |
The number of bins. |
region |
CONST_OBJECT |
? |
Optional region of interest. This can save a lot of computation time, if the region is small. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pixelRegionList |
* |
The pixelRegion list or nil if operation failed. |
Sample
pixelRegionList = Image.toPixelRegion(image, 1, 10, 10)toPixelZ()
Short description
Converts a z world coordinate value to a raw pixel value using the image world coordinate system supplied by the input reference image. The mapping pixelValue = (worldZCoordinate - originZ)/pixelSizeZ is made.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
refImage |
1 |
Image carrying the image world coordinate system. No other information from the image is used. |
|
worldZCoordinate |
FLOAT |
[1+] |
World z coordinate(s), e.g., millimeters. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pixelValue |
FLOAT |
[1+] |
Raw pixel value(s). |
Sample (auto-generated)
pixelValue = Image.toPixelZ(refImage, worldZCoordinate)toPointCloud()
Short description
Creates a pointcloud from image(s). Typically one heightmap input image is used in which the pixel pitch is constant in each dimension. The alternative use cases are to supply separate images for either x and z or for x, y and z coordinates. In total there are three ways this can be used: 1. Image.toPointCloud(range, true/false, intensity, region) 2. Image.toPointCloud({X, Z}, true/false, intensity, region) 3. Image.toPointCloud({X, Y, Z}, true/false, intensity, region) In case 1 the pixel sizes and origin of the range image is used to create the X and Y coordinates. In case 2 the pixel sizes and origin of of Z is used to create the Y coordinates in the output. In case 3 all positions are uniquely determined by the input images X, Y and Z. Pixel sizes and origin in the input images are unused. The intensity and region inputs are optional and can be used to set the intensity of the output pointcloud and to remove points respectively. Image world coordinate system handling: in general the image world coordinate system is used to create the pointcloud, i.e. the (x, y, z)-pixel sizes and origins are used to create the (x, y, z)-components of the pointcloud. For details see the longer text above. Missing data handling: For images with missing data it is possible to select to keep or remove the missing points. If missing points are kept they are marked as such in the pointcloud and will be black in intensity. If they are removed the grid structure of the image is lost and the point cloud will be considered an unordered point cloud.
Keywords
extrude
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
[1+] |
The source image(s) with range/depth information. Either one range image or 3 coordinate images (X, Y and Z). |
|
removeMissing |
BOOL |
? |
Select if points that are missing data should be removed or not. For images without missing data this has no effect. Default is false. |
intensity |
? |
Optional uint8 image that will be used for intensity information for each point. The pixel values are divided by 255 to create a number in the range [0,1] for the pointcloud intensity. |
|
region |
CONST_OBJECT |
? |
Optional PixelRegion. If supplied, only points within the region are converted. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pointcloud |
OBJECT |
? |
The resulting pointcloud. |
Sample
local pointcloud = Image.toPointCloud(image, removeMissing, intensity, region)toRGB()
Short description
Creates an RGB image from three grayscale images. The input images must be of uint8 type.
Keywords
color
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageR |
1 |
Gray value image of uint8 type. |
|
imageG |
1 |
Gray value image of uint8 type. |
|
imageB |
1 |
Gray value image of uint8 type. |
|
colorSpace |
ENUM |
1 |
The color space the input images represent. |
Sample
imageRGB = Image.toRGB(imageR, imageG, imageB, colorSpace)toSquarePixels()
Short description
Resizes an image to have square pixels, i.e., to have equal pixelsizes in the x and y dimensions. Having square pixels is sometimes required for further processing. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, will be copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
Keywords
resample, scale, transform, anisotropic
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image |
|
upsample |
BOOL |
? |
Select if to upsample one axis or downsample the other. Default is false. |
method |
ENUM |
? |
The resampling method. Default is LINEAR. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
squarePixelImage |
? |
Image with square pixels. |
Sample
squarePixelImage = Image.toSquarePixels(image)toString()
Short description
Gets a user-friendly string description of the image, containing all properties but no actual pixel values.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to describe. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
str |
STRING |
1 |
User-friendly description of the image. |
Sample (auto-generated)
str = Image.toString(image)toType()
Short description
Converts an image to a new image of specified pixel type. The raw pixel values are casted and there may be underflow/overflow effects when casting to a type of lower capacity. For example, the value 256 in a uint16 image will overflow to 0 if converted to a uint8 type. To avoid such effects, clamp the input pixel values to the min and max values of the target pixel type. When converting from a monochrome image to RGB, all channels are set to the same value. Use toRGB to convert three monochrome images into a color image or splitRGB to split a color image into three monochrome images.
Keywords
conversion, RGB, gray
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image to be converted. |
|
type |
ENUM |
1 |
The pixel type, e.g., UINT8, INT16, FLOAT64, RGB24). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
convertedImage |
? |
Returns the image of specified type or nil. |
Sample
local convertedImage = Image.toType(image, "UINT8")toTypeFit()
Short description
Converts a gray value image into another gray value image of a different type. The input image values are rescaled to fit the target type. For integer images without missing data the min and max values provided are mapped to the limits of the data type. World values outside of these limits in the input image are clamped to the min and max of the data type. For integer images with missing data the clamping option allows to either discard values that are out of range or to clamp them to the limits in the same way as for non-missing data images. Set clamping to false to discard values. For float images the min and max value provided will be mapped to 0 and 1. The clamping option selects if values outside the provided interval should clamp or be allowed to extend beyond the range 0 and 1. Image world coordinate system handling: The boundaries are provided in world coordinates of the input image. The output image is updated with an adjusted world coordinate system that as closely as possible maintain the absolute world values of the input in the result. Missing data handling: For missing data images missing data is preserved. Note that for a missing data type input only unsigned integer output types are allowed. If clamping is set to false values outside the selected range are set to missing.
Keywords
conversion, plotting, scaling, visualization, gray
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image to convert. |
|
targetType |
ENUM |
1 |
The target pixel type. |
minValue |
FLOAT |
? |
The lowest value in world units in the source image to keep in the result. Default is the smallest representable value of the target type or zero for float targets. |
maxValue |
FLOAT |
? |
The highest value in world units in the source image to keep in the result. Default is the largest representable value of the target type or one for float targets. |
clamp |
BOOL |
? |
Decide how to handle values that are out of range for missing data images. Default is true. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Converted image. Nil on failure. |
Sample
imageGray = Image.toTypeFit(image, "UINT8")toVector()
Short description
Creates a vector from a monochrome image. If the vectors of each channel of a color image are needed please first split the channels using Image.splitRGB. Each entry in the vector corresponds to the raw pixel value. Missing data is set to 0. Please note, this function should be used with care for large images, because it can exhaust the memory of the device.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputImage |
1 |
The input image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
vector |
FLOAT |
* |
The vector with the raw image content. |
Sample (auto-generated)
vector = Image.toVector(inputImage)toWorldCoordinate()
Short description
Converts a pixel coordinate to an image world coordinate.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The image |
|
pixelCoordinate |
[1+] |
The pixel coordinate point. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
worldCoordinate |
[1+] |
Returns the world coordinate. |
Sample (auto-generated)
worldCoordinate = Image.toWorldCoordinate(image, pixelCoordinate)toWorldZ()
Short description
Converts a pixel raw value to a z world coordinate value using the image world coordinate system supplied by the input reference image. The mapping worldZCoordinate = pixelValue*pixelSizeZ + originZ is made.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Image carrying the image world coordinate system. No other information from the image is used. |
|
pixelValue |
FLOAT |
[1+] |
Raw pixel value(s). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
worldZCoordinate |
FLOAT |
[1+] |
World z coordinate(s), e.g., millimeters. |
Sample (auto-generated)
worldZCoordinate = Image.toWorldZ(image, pixelValue)transform()
Short description
Applies a linear geometric transform to an image. The result image uses the same pixel grid as the input image, if the SAME output grid is selected. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
Keywords
linear, rotate, scale, shear, shift, warp
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. |
|
transform |
1 |
A linear transform defined by a Transform object. |
|
method |
ENUM |
? |
Interpolation method to use. Default is NEAREST. |
grid |
ENUM |
? |
The pixel grid to use for the output, default is SAME, the same as the input image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
transformedImage |
? |
Transformed image. |
Sample
transformedImage = Image.transform(image, transform, method)transformInto()
Short description
Applies a 2D linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. The pixel grid and coordinate system of the destination image is used for transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes (except Z if an height map) of the output image - The world origin of the output image All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image. Image world coordinate system handling: If the image or destination image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is kept in the destination image and the transformed image is painted onto this coordinate system. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image. The missing data flags of the input and destination images must match.
Keywords
linear, rotate, scale, shear, shift, warp
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
sourceImage |
1 |
Source image. |
|
transform |
1 |
A linear transform defined by a Transform object. |
|
destinationImage |
1 |
Destination image, the output will be placed into this image. The image size, pixels sizes and world origin from this image are used. |
|
method |
ENUM |
? |
The resampling method. Default is NEAREST. |
clearTarget |
BOOL |
? |
Select if the destination image should be reset to zero before transforming the source image into it. Default is true. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
transformedImage |
? |
A reference to the input destination image. Nil on failure. |
Sample
transformedImage = Image.transformInto(sourceImage, transform, destinationImage, method)transformInto3D()
Short description
Applies a 3D linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. Compared to the transformInto function, this function adds the possibility for 3D tilts. The function is typically used for heightmap image data. The pixel grid and coordinate system of the destination image are used for the transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes of the output image - The world origin of the output image All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image. Image world coordinate system handling: If the image or reference image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the reference image and the transformed image is repainted onto this coordinate system. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
Keywords
linear, rotate, scale, shear, shift, warp
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
sourceImage |
1 |
Source image. |
|
transform |
1 |
A linear affine 3D transform defined by a Transform object. |
|
destinationImage |
1 |
Destination image, the output will be placed into this image. The image size, pixels sizes and world origin from this image are used. |
|
method |
ENUM |
? |
The resampling method. Default is NEAREST. |
splatX |
INT |
? |
The influence distance of a source point in the target image x direction. Default is 3. |
splatY |
INT |
? |
The influence distance of a source point in the target image y direction. Defaults to splatX if unset. |
clearTarget |
BOOL |
? |
Select if the destination image should be reset to missing data before transforming the source image into it. Default is true. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
transformedImage |
? |
A reference to the input destination image. Nil on failure. |
Sample
transformedImage = Image.transformInto3D(sourceImage, transform, destinationImage, method)variance()
Short description
Calculates a the variance around each pixel. Also returns the local average (the same as from Image.blur). Image world coordinate system handling: The kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.
Keywords
box, boxcar, convolve, denoise, filter, smooth, statistics
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
|
kernelSizePix |
INT |
1 |
Size of the kernel, must be positive. |
region |
CONST_OBJECT |
? |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
fillMissingData |
BOOL |
? |
Optional flag to also fill in missing data pixels when processing images containing missing data. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
varianceImage |
? |
Output variance image. Of type float32 unless input is float64, then float64 is returned. |
|
meanImage |
? |
Output mean image. Same type as input image. |
Sample
varianceImage, meanImage = Image.variance(image, kernelSizePix)warpFromSector()
Short description
Warps the inner area from a sector shape to a rectilinear Cartesian grid. Image world coordinate system handling: The sector and source of warp is interpreted in world coordinates. The output image is sampled uniformly in an angular-radial grid and pixel size is set to match the source image as close as possible along the outer radius. Optionally, the output resolution can be manually set. The output image origin is at (0,0). The z-axis size and origin is transferred to the output image. Missing data handling: Missing data is supported for unsigned integer type images and nearest neighbor interpolation.
Keywords
rectify, unwarp, unwrap, wrap
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Input image. |
|
sector |
1 |
A sector shape defining the area in the source image to warp from. |
|
interpolation |
ENUM |
? |
Interpolation method to use. LINEAR and NEAREST are available, default is LINEAR for images without missing data, and NEAREST for images with missing data. |
outputWidth |
INT |
? |
Optional width of the output image, in pixels. Default is to approximately keep the resolution of the input image along the outer circle. |
outputHeight |
INT |
? |
Optional height of the output image, in pixels. Default is to approximately keep the resolution of the input image along a radial line. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
warpedImage |
? |
The warped image, or nil on failure. |
Sample
warpedImage = Image.warpFromSector(image, sector, interpolation, outputWidth, outputHeight)warpToSector()
Short description
Warps a rectangular grid image into a sector shape onto an image. Image size and world coordinate settings for the output image are taken from the reference image. Image type and missing data settings from the source image are used. Pixels outside the sector is set to zero in pixel value. This is the inverse operation of Image.warpFromSector. Image world coordinate system handling: The sector and destination of the warp is interpreted in world coordinates. The x/y pixel size and origin of the source image is disregarded, the source image is shaped to fill the target sector. The z-values are matched to the target image, i.e. world values are transferred. Missing data handling: Missing data is supported for unsigned integer type images and nearest neighbor interpolation. The output image uses the missing data setting of the source image, disregarding the setting of the reference image.
Keywords
rectify, unwarp, unwrap, warp, wrap
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
targetReferenceImage |
1 |
Reference image to define the output. |
|
sourceImage |
1 |
Input image to be warped. |
|
sector |
1 |
A sector shape defining the area in the target image to warp to. |
|
interpolation |
ENUM |
? |
Interpolation method to use. LINEAR and NEAREST are available, default is LINEAR for images without missing data, and NEAREST for images with missing data. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
warpedImage |
? |
The image with the source image warped into it, or nil on failure. |
Sample
warpedImage = Image.warpToSector(targetReferenceImage, sourceImage, sector, interpolation)warpToSectorInplace()
Short description
Warps a rectangular grid image into a sector shape onto the target image, the inverse operation of Image.warpFromSector. Image world coordinate system handling: The sector and destination of the warp is interpreted in world coordinates. The x/y pixel size and origin of the source image is disregarded, the source image is shaped to fill the target sector. The z-values are matched to the target image, i.e. world values are transferred. Missing data handling: Missing data is supported for unsigned integer type images and nearest neighbor interpolation. The output image uses and preserves the missing data setting of the target image.
Keywords
rectify, unwarp, unwrap, warp, wrap
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
targetImage |
1 |
Target image. The sector contents is overwritten. |
|
sourceImage |
1 |
Input image. |
|
sector |
1 |
A sector shape defining the area in the target image to warp to. |
|
interpolation |
ENUM |
? |
Interpolation method to use. LINEAR and NEAREST are available, default is LINEAR for images without missing data, and NEAREST for images with missing data. |
Sample
Image.warpToSectorInplace(targetImage, sourceImage, sector, interpolation)watershedSeeded()
| This API is experimental |
Short description
Performs a seeded watershed transform for object segmentation. Return the result either as an image or a vector of pixel regions.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageBinary |
1 |
Binary image of uint8 type |
|
markers |
AUTO |
[1+] |
Either an image (int32) with seeds or a vector of seed pixel regions. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
segmented |
AUTO |
[?*] |
Either an image with markers (in this case the original marker values are preserved) or a vector of pixel regions representing the markers. |
Sample
segmented = Image.watershedSeeded(imageBinary, markers)Image.AI
Image.BackgroundModel
Short description
Functions for pixelwise modeling the background values and normal variations in an image. A pixelwise statistical model of the background, e.g., average and standard deviation variations in each pixel, is estimated based on a series of training images. Live images can then be compared to the model to find outliers, typically caused by new foreground objects that were not present in the background training images. The following two models are supported: - Average model: The background model consists of the pixelwise average over all added training images. - Gaussian model: The background model consists of the pixelwise average and variance over all added training images. After creation of a BackgroundModel object, the model is built up incrementally by repeatedly adding background images to it using the BackgroundModel.add() function. To compare a new image with the built up model the BackgroundModel.compare() function is used. To use the BackgroundModel for anomaly detection purposes, it is important that the images are pre-aligned so that the object-of-interest is in the same position in all images. This can for example be achieved using the EdgeMatcher or PointMatcher algorithms. All pixel types (uint8, uint16, float32, etc) except color RGB are supported. Image world coordinate system handling: The pixel variations are modeled in world coordinates using the z-pixelsize and z-origin. This is mainly relevant for range/heightmap/depthmap images. Missing data handling: All models automatically handle missing data: Missing data pixels are not used to update the model and will not show up as foreground after a call to Image.BackgroundModel.compare.
Keywords
anomaly, average, background, detection, gaussian, mean, mixture, mu, my, presence, segmentation, separation, sigma, standard deviation, subtraction, surveillance, variance, foreground
See also
Overview
Functions
add()
Short description
Add an image to the model to teach it the background of the scene, the chosen model will be incrementally updated with the data in the supplied image. The model is built by repeatedly adding images, the more images added the more accurate the model becomes. All images added must have the same size. If lineMode has been set to true, only the image width needs to be the same but the heights of the background images can vary. If a region input is provided and a region was set by Image.BackgroundModel.setRegionOfInterest the intersection of these regions is used to update the model. If Image.BackgroundModel.setRegionOfInterest was never used the input region is used as is. All pixel types (uint8, uint16, float32, etc.) except color RGB are supported.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The background model to use. |
|
image |
1 |
Background sample image. |
|
region |
CONST_OBJECT |
? |
An optional region in which to update the model. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the image could be added. |
Sample
local success = Image.BackgroundModel.add(bgm, image)compare()
Short description
Compare a new image to the current background model to classify pixels as background or foreground. It is possible to get either ALL, BRIGHTER or DARKER pixels relative to the model. The comparison is based on the deviation d between the image pixel value I and the model average value M for the same pixel: d = I - M The Average model uses a parameter averageThreshold and the following conditions for classifying pixels as background or foreground: ALL: Foreground if |d| greater than averageThreshold BRIGHTER: Foreground if d greater than averageThreshold DARKER: Foreground if d lesser than -averageThreshold The Gaussian and Median models additionally applies the model standard deviation value S for the comparison. Specifically it puts a threshold on the normalized deviation d/S, i.e., the number of standard deviations the observed pixel value I is from the model average M: ALL: Foreground if |d/S| greater than normalizedThreshold BRIGHTER: Foreground if d/S greater than normalizedThreshold DARKER: Foreground if d/S lesser than -normalizedThreshold Note that for a pixel to be classified as foreground by in the Gaussian model, both the check on d and d/S must be true. Using both checks captures cases when the standard deviation S has been estimated to a very low value, which can artificially make d/S very big. Including the direct threshold on the difference d only can suppress such cases from being classified as foreground. When tuning the parameters, it can be beneficial to set averageThreshold to 0 which functionally disables this check. The normalizedThreshold can then first be tuned, typically to a value around 2.0-4.0. If needed the averageThreshold can then be raised if necessary to regularize the classification result. If a region input is provided and a region was set by Image.BackgroundModel.setRegionOfInterest the intersection of these regions is used. If Image.BackgroundModel.setRegionOfInterest was never used the input region is used as is.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The background model to use. |
|
image |
1 |
The image to compare the model to. |
|
direction |
? |
Select the comparison direction to detect foreground (ALL, DARKER, BRIGHTER). Default is ALL. |
|
averageThreshold |
FLOAT |
? |
Required deviation from the to background average for a pixel to be classified as foreground, see main function description. Default is 0.0. |
normalizedThreshold |
FLOAT |
? |
Required deviation in terms of number of standard deviations for a pixel to be classified as foreground, see main function description. A higher value gives a less sensitive background model. Default is 2.5. |
region |
CONST_OBJECT |
? |
An optional PixelRegion region in which to evaluate the model. |
includeModelMissing |
BOOL |
? |
Select if pixels over an invalid model point should be included in the foregroundRegion. Default is true. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
foregroundRegion |
? |
A pixel region containing foreground pixels. |
Sample
local foregroundRegion = Image.BackgroundModel.compare(bgm, image, "ALL", roi)createAverage()
Short description
Construct an empty background model of Average type. This model is based on calculating the average value in every pixel: average = (images[1] + images[2] + …) / #images Optionally there is a lineMode parameter to calculate the average over the entire columns in the training images, creating a 1-dimensional model. This mode is suited for line-scanning camera devices. The Average model will never forget added images and should be built up using training images with representative of background only.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
lineMode |
BOOL |
? |
Select if input images are from a line scan camera or standard area sensor. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The created background model. |
Sample
bgm = Image.BackgroundModel.createAverage()createGaussian()
Short description
Construct an empty background model of Gaussian type. This model is based on calculating the average value and variance in every pixel average = (images[1] + images[2] + …) / #images var = ((images[1] - average)^2 + (images[2] - average)^2 + …) / (#images - 1) Optionally there is a lineMode parameter to calculate the average and variance over the entire columns in the training images, creating a 1-dimensional model. This mode is suited for line-scanning camera devices. The Average model will never forget added images and should be built up using training images with representative of background only.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
lineMode |
BOOL |
? |
Select if input images are from a line scan camera or standard area sensor. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The created background model. |
Sample
bgm = Image.BackgroundModel.createGaussian()createRunningGaussian()
Short description
Construct an empty background model of RunningGaussian type. This model is calculating a running average and a running variance in each pixel average1 = images[1] var1 = initialSigma, or local estimate in a 3x3 region around each pixel in images[1] averageN = (1 - learningRate) * averageN-1 + learningRate * image[N] varianceN = (1 - learningRate) * varianceN-1 + learningRate * (image[N] - averageN)^2 The RunningGaussian model is updated incrementally and should generally be allowed to adopt to changing conditions by calling Image.BackgroundModel.add() continuously. Optionally there is a lineMode parameter to calculate the average and variance over the entire columns in the training images, creating a 1-dimensional model. This mode is suited for line-scanning camera devices. For missing data input the model points are reset using the last added image if they have not been observed for more than 1/learningRate images and are now observed again.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
lineMode |
BOOL |
? |
Select if input images are from a line scan camera or standard area sensor. Default is false. |
learningRate |
FLOAT |
? |
Selects how fast the model is updated and old images forgotten. Setting the learning rate to 0.1 will make a weighted update of the current model and a new image, using 90% of the current model and 10% with new values from the the image. Default is 0.01. |
memory |
INT |
? |
The number of observations as value can be missing data before being reinitialized. Default is 1/learningRate. |
initialSigma |
FLOAT |
? |
The initial standard deviation expected in the image. If set to a negative value a small neighborhood in the first image is used to estimate the standard deviation. Default is to use a local estimate around each pixel. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The created background model. |
Sample
bgm = Image.BackgroundModel.createRunningGaussian(0.01)createRunningMedian()
Short description
Construct an empty background model of RunningMedian type. This model approximates the median value of each pixel. The approximate median is initialized to the first added image. For each new image and pixel, the approximate median is stepped up or down with the learningRate parameter step size. Thus the model value for each pixel will stabilize around a value where there are equally many updates above and below the model value. Depending on the order of which data arrives, the median estimate may vary a few step sizes up and down. The step size should be chosen small enough such that the estimate does not drift too far. At the same time, a larger step size allows the model to adapt faster to changes. The step size can be changed, such that a large step size can be used in the beginning, and a smaller when the model is close to converging. An estimate of the variance is kept for use as a threshold, the second order moment centered around the median model value to be more specific. The variance update rate is set by the varianceLearningRate parameter. See Image.BackgroundModel.createRunningGaussian(). The RunningMedian model is updated incrementally and should generally be allowed to adopt to changing conditions by calling Image.BackgroundModel.add() continuously. Optionally there is a lineMode parameter to calculate the approximate median and variance over the entire columns in the training images, creating a 1-dimensional model. This mode is suited for line-scanning camera devices. For missing data input the model points are reset using the last added image if they have not been observed for more than a given number of images and are now observed again. This is set by the history parameter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
lineMode |
BOOL |
? |
Select if input images are from a line scan camera or standard area sensor. Default is false. |
learningRate |
FLOAT |
? |
Selects the update step size, i.e. the absolute value of the change in the approximate median for each observed image. Default is 1.0. |
varianceLearningRate |
FLOAT |
? |
Selects how fast the variance estimate is updated and old images forgotten. Setting the variance learning rate to 0.01 will make a weighted update of the current model and a new image, using 99% of the current model and 1% with new values from the the image. Default is 0.01. |
memory |
INT |
? |
The number of observations as value can be missing data before being reinitialized. Default is 1/varianceLearningRate. |
initialSigma |
FLOAT |
? |
The initial standard deviation expected in the image. Default is to set it to the learningRate. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The created background model. |
Sample
bgm = Image.BackgroundModel.createRunningMedian(lineMode, learningRate, varianceLearningRate, memory, initialSigma)getImageCount()
Short description
Returns the total number of images accumulated in the background model when operating in area mode. When lineMode is set to true in the model creation the count is instead the number of accumulated lines.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
CONST_OBJECT |
1 |
An background model object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
count |
INT |
1 |
The number of added images. |
Sample
local count = Image.BackgroundModel.getImageCount(bgm)getModelImages()
Short description
Return a list of model images produced within the BackgroundModel object. For the Average model the returned image contains the per-pixel average of the added training images. The Gaussian model additionally returns an image of the per-pixel variance. The final image is a pixelwise observation count. For RunningGaussian this is the remaining memory per pixel. For other methods it’s simply the number of observations recorded. If the lineMode parameter has been set the returned images have a height of 1.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The background model instance. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
images |
[?*] |
The background model represented as float32 images. If unavailable nil is returned. |
Sample
local images = Image.BackgroundModel.getModelImages(bgm)isEmpty()
Short description
Checks if a background model is empty or initialized by some data.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
CONST_OBJECT |
1 |
An background model object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isEmpty |
BOOL |
1 |
True if the model is empty. |
Sample
local isEmpty = Image.BackgroundModel.isEmpty(bgm)reset()
Short description
Clear a model. This can be useful to change the image resolution or to restart the accumulators in a model. If a region was set using setRegionOfInterest() this is also reset and must be set again.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The background model to reset. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the model could be reset. |
Sample
local success = Image.BackgroundModel.reset(bgm)setLearningRate()
Short description
Update the learning rate of a RunningGaussian model or the update step size for a RunningMedian model. This affects how quickly a model pixel will be updated to match new data. For a gaussian model, setting the learning rate to 0.01 will make a weighted update of the current model and a new image, using 99% of the current model and 1% with new values from the the image. The default learning rate for a RunningGaussian model is 0.01 and the default step size for a RunningMedian model is 1.0.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The background model to update the learning rate for. |
|
learningRate |
FLOAT |
1 |
The new learning rate to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the rate could be set. |
Sample
Image.BackgroundModel.setLearningRate(bgm, learningRate)setMemoryLength()
Short description
Update the memory of a RunningGaussian or RunningMedian model. This affects how quickly a model pixel will be considered old. Setting the memory to 10 will make a point that is not touched in 10 calls to add() marked as old. An old point is reset to the first valid pixel in an add() call and thus does not propagate old knowledge that is likely to be outdated. An old point is treated specially in compare() calls and can be configured to either never or always be treated as foreground using the CompareDirection enum.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The background model to update the memory for. |
|
memory |
INT |
1 |
The number of observations as value can be missing before being reinitialized. Defaults to 1/learningRate if zero or negative. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the memory could be set. |
Sample
Image.BackgroundModel.setMemoryLength(bgm, memory)setRegionOfInterest()
Short description
Optional function to configure a pre-defined region in the input images in which the model is built. Unless set with this function, a model is made for the entire image. This can be used to improve performance in cases where only a part of the image needs to be modeled. For pixels outside the region of interest the model will remain uninitialized. The add() and compare() functions also allow a region input per image. An intersection with the region set in this function will then be used.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
1 |
The background model to update the region for. |
|
region |
CONST_OBJECT |
? |
The region in which to compute and evaluate the model. Unless set a model is estimated for all pixels in the entire image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the region could be set. |
Sample
Image.BackgroundModel.setRegionOfInterest(bgm, roi)toString()
Short description
Get a textual description of the background model instance.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bgm |
CONST_OBJECT |
1 |
An background model object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
str |
STRING |
1 |
A string representation of the model. |
Sample
local str = Image.BackgroundModel.toString(bgm)Image.Calibration
Short description
Functionality for performing camera calibration on 2D images.
Keywords
alignment, correction, distortion, lens correction, perspective correction, pose estimation, rectification, undistortion
See also
Overview
Image.Calibration.Camera
Short description
Image.Calibration.Camera can be used to estimate intrinsic and lens distortion parameters of a single camera. The full checkerboard pattern does not have to be visible in the calibration image for the algorithm to work. It is recommended to provide multiple images with varying pattern orientation to get an accurate calibration. The estimation of the intrinsic and extrinsic parameters can be adapted to different requirements. Therefore the Image.Calibration.Camera handle has multiple methods to enable or disable different camera model parameters. If you are only interested in extracting checkerboard corners, you can use the "findCornerPoints" method. The result object of Image.Calibration.Camera is the Image.Calibration.CameraModel with the intrinsic parameter defined as K = [fx s cx, 0 fy cy, 0 0 1]
Overview
Functions
addImage()
Short description
Add an image to the calibration image evaluation. The method returns true if the image is a valid. An image can be valid but too similar to previously added images. If this occurs this is indicated by the imgSelected output. The method is overloaded for the two different calibration patterns. The "optional" arguments are only needed for the CHECKERBOARD_PLUS_CODE calibration pattern.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
image |
1 |
Gray scale image of the calibration target. |
|
codeContent |
BINARY |
* |
Optional: List of code contents. |
codeRegion |
* |
Optional: List of code ROIs, each represented as a 4-point polyline shape. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imgValid |
BOOL |
1 |
Returns true if valid points found. |
featurePoints2D |
+ |
2D checkerboard corners in image plane for the result visualization. |
|
featurePoints3D |
+ |
Corresponding 3D world coordinates of the checkerboard corners. |
|
imgSelected |
BOOL |
1 |
If the returned value is true the input image will contribute to the calibration. |
Sample
Image.Calibration.Camera.addImage(handle, image, codeContent, codeRegion)calculate()
| This API is deprecated |
Short description
Calculate the intrinsic sensor parameters from the set of images containing the calibration target collected under different perspectives. Deprecated, please use Image.Calibration.Camera.estimate instead.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if a valid solution for the calibration was found. |
cameraModel |
OBJECT |
? |
Calibration result parameter. |
calibConfidence |
FLOAT |
? |
Calibration result confidence value. Range: [100 - 90] percent is very good; [90 - 70] percent is OK; [70 - 50] accuracy is not that high; [50 - 0] re-calibration is suggested |
reprojectionError |
FLOAT |
? |
The square root of the average squared distance between detected 2D feature points and projected 3D feature points using the estimated camera calibration parameters. |
residuals |
OBJECT |
* |
The calibration residuals for each calibration point. For each image you receive a vector of vectors of 2D points. |
Sample
local success, cameraModel = Image.Calibration.Camera.calculate(handle)create()
Short description
Create a handle for the calibration
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The calibration object handle. |
Sample
handle = Image.Calibration.Camera.create()estimate()
Short description
Estimate the intrinsic sensor parameters from the set of images containing the calibration target collected under different perspectives.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
? |
Calibration result parameter. |
error |
FLOAT |
? |
The square root of the average squared distance between detected 2D feature points and projected 3D feature points using the estimated camera calibration parameters. |
Sample
local cameraModel, error = Image.Calibration.Camera.estimate(handle)evaluate()
Short description
Evaluate the calibration, either an in the Camera class existing cameraModel or an inserted cameraModel. The values in the images residualImageX and residualImageY is the mean residual for the corners found in the different image regions. The values in the image sampleHistogram is the number of corners found in the different image regions.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
cameraModel |
OBJECT |
? |
Calibration result parameter. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
? |
Returns true if a valid solution for the evaluation was found. |
reprojectionError |
FLOAT |
? |
The square root of the average squared distance between detected 2D feature points and projected 3D feature points using the estimated camera calibration parameters. |
residualImageX |
? |
Mean x residual in image regions. |
|
residualImageY |
? |
Mean y residual in image regions. |
|
sampleHistogram |
? |
Histogram of x,y corner positions. |
|
residuals |
OBJECT |
* |
The calibration residuals for each calibration point. |
featurePoints2D |
* |
2D checkerboard corners in image plane for the result visualization. |
Sample
local success, reprojectionError, residualImageX, residualImageY, sampleHistogram, residuals, featurePoints2D = Image.Calibration.Camera.evaluate(handle, cameraModel)evaluateOnImage()
Short description
Evaluate the calibration using an image of the calibration target.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
image |
1 |
Gray scale or RGB image of the calibration target. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if a valid solution for the evaluation was found. |
reprojectionError |
FLOAT |
? |
The square root of the average squared distance between detected 2D feature points and projected 3D feature points using the estimated camera calibration parameters. |
residuals |
OBJECT |
* |
The calibration residuals for each calibration point. |
featurePoints2D |
* |
2D checkerboard corners in image plane for the result visualization. |
Sample
local success, reprojectionError, residuals, featurePoints2D = Image.Calibration.Camera.evaluateOnImage(handle, image)findCornerPoints()
Short description
Computes the calibration target feature points without adding the result to the camera calibration data set.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
image |
1 |
Gray scale or RGB image of the calibration target. |
|
codeContent |
BINARY |
* |
Optional: List of code contents. |
codeRegion |
* |
Optional: List of code ROIs, each represented as a 4-point polyline shape. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imgValid |
BOOL |
1 |
Returns true if valid points found. |
featurePoints2D |
+ |
2D checkerboard corners in image plane for the result visualization. |
|
featurePoints3D |
+ |
Corresponding 3D world coordinates of the checkerboard corners. |
Sample
local imgValid, featurePoints2D, featurePoints3D = Image.Calibration.Camera.findCornerPoints(handle, image)getCornerPoints()
Short description
Returns the vector of corner points for the n-th image or for all images if index is left empty.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
index |
INT |
? |
Image index. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
featurePoints2D |
+ |
2D checkerboard corners in image plane for the result visualization. |
|
featurePoints3D |
+ |
Corresponding 3D world coordinates of the checkerboard corners. |
Sample
local featurePoints2D, featurePoints3D = Image.Calibration.Camera.getCornerPoints(handle, index)getDataCompleteness()
Short description
Returns data completeness estimates. These are useful for visualizing the state of the calibration prior to calling calibrate.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
area |
FLOAT |
+ |
Estimate of relative image area covered by the board. 1.0 means the complete image. |
tiltX |
FLOAT |
+ |
Estimates of the amount of tilt of the board along the X direction. One for each collected image. |
tiltY |
FLOAT |
+ |
Estimates of the amount of tilt of the board along the Y direction. One for each collected image. |
distance |
FLOAT |
+ |
Distance to the board estimates. One for each collected image. |
sampleHistogram |
1 |
Histogram of x,y corner positions. |
Sample
local area, tiltX, tiltY, distance, sampleHistogram = Image.Calibration.Camera.getDataCompleteness(handle)getResiduals()
Short description
Returns the vector of residuals the n-th image or the residuals for all images if index is left empty.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
index |
INT |
? |
Image index. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
residuals |
+ |
The residuals of 3D points reprojected into the image. |
Sample
local residuals = Image.Calibration.Camera.getResiduals(handle, index)setCheckerSquareSideLength()
Short description
Set checkerboard square size in mm. Must be positive.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
sideLength |
FLOAT |
[1+] |
Checkerboard corner side length in mm. If your target is not accurate enough and your checkerboard elements are not quadratic, you can enter the side length dimensions for x, y and z. The algorithm will correct the world corner values. Keep in mind you also have to specify the 'checkerboardDimensions' for the CHECKERBOARD type. Otherwise the algorithm cannot determine which side length belongs to which dimension. |
checkerboardDimensions |
INT |
* |
Optional and only for CHECKERBOARD : Number of checkerboard corners in x and y direction. |
Sample
Image.Calibration.Camera.setCheckerSquareSideLength(handle, size)setDistortionCoefficientsEnabled()
Short description
Enable the estimation of radial and tangential distortion [k1, k2, p1, p2, k3]. No distortion is estimated if the parameters are not set.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
k1 |
BOOL |
? |
Enable or disable 2nd order radial lens distortion coefficient. |
k2 |
BOOL |
? |
Enable or disable 4th order radial lens distortion coefficient. |
p1 |
BOOL |
? |
Enable or disable 1st order tangential lens distortion coefficient. |
p2 |
BOOL |
? |
Enable or disable 2nd order tangential lens distortion coefficient. |
k3 |
BOOL |
? |
Enable or disable 6th order radial lens distortion coefficient. |
Sample
Image.Calibration.Camera.setDistortionCoefficientsEnabled(handle, true, true, false, false, false)setDistortionCoefficientValues()
Short description
Set the lens distortion start values for the non-linear optimization.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
k1 |
FLOAT |
1 |
Set initial value for estimating 2nd order radial lens distortion coefficient. |
k2 |
FLOAT |
1 |
Set initial value for estimating 4th order radial lens distortion coefficient. |
p1 |
FLOAT |
? |
Set initial value for estimating 1st order tangential lens distortion coefficient. |
p2 |
FLOAT |
? |
Set initial value for estimating 2nd order tangential lens distortion coefficient. |
k3 |
FLOAT |
? |
Set initial value for estimating 6th order radial lens distortion coefficient. |
Sample
Image.Calibration.Camera.setDistortionCoefficientValues(handle, k1, k2, p1, p2, k3)setDownsampleFactor()
Short description
Set the minimum number of octaves to downsample the calibration images in the corner detection stage. Large number gives higher speed but requires larger chess squares.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
downsamplefactor |
INT |
? |
Set the number of octaves to downsample the input images. |
Sample
Image.Calibration.Camera.setDownsampleFactor(handle, downsamplefactor)setSkewEnabled()
Short description
Enable the skew estimation of the intrinsic camera matrix K. By default, the skew parameter estimation is deactivated.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
s |
BOOL |
1 |
Enable intrinsic camera matrix skew parameter estimation. |
Sample
Image.Calibration.Camera.setSkewEnabled(handle, false)setSkipUntilStable()
| This API is experimental |
Short description
Enable skipping of all images until two consecutive images that are similar enough are found.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
skipUntilStable |
BOOL |
1 |
Enable Skipping of images. |
threshold |
FLOAT |
? |
High threshold means that a higher degree of similarity is required. |
Sample
Image.Calibration.Camera.setSkipUntilStable(handle, false, sensitivity)setUniquenessThreshold()
Short description
Enable automatic image selection and set the acceptance threshold. Only unique images are stored, that is, images that have not previously been observed in terms of orientation and distance. A lower threshold results in more accepted images. The threshold relates to three different properties of the input image. The distance between camera and calibration board and the tilt of the calibration board in the horizontal and vertical direction respectively. All measurements are relative and not real world units. Real world units are not accessible until after calibration has been completed. To allow additions of calibration boards closer together than default select a threshold value under 1.0, to instead be more selective select a value above 1.0. Distance With the threshold set to 1.0, the images must be at least 15% apart in distance to be accepted. For example, if one accepted image is taken at distance 1.0 m, the next must be at least 1.15 m away to be accepted. The minimum distance change required to take a new image is the (current distance)*(0.15 * threshold). Tilt (same for X and Y) With the threshold set to 1.0, the distance variation between corners in the checkerboard along X/Y must be 10% greater or lower than any previously observed image. For example, if one accepted image has no tilt (same distance between all corners on the board), the distance must change from e.g. 1.0 m to 1.1 m when moving along X/Y on the board.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance to use. |
enable |
BOOL |
1 |
True to enable automatic image selection, false to use all input images. Default is true. |
threshold |
FLOAT |
? |
Set the threshold. Default is 1.0. |
Sample
Image.Calibration.Camera.setUniquenessThreshold(handle, enable, threshold)Image.Calibration.CameraModel
Short description
Calibration result object of single camera. These objects can be stored to and loaded from file. The results of the camera calibration satisfy the camera transformation equation from world to the image coordinate system: xp = KD([R|t] * X) K = [fx s cx, 0 fy cy, 0 0 1] D = Brown–Conrady lens model: k1, k2, p1, p2, k3 R = [r11 r12 r13, r21 r22 r23, r31 r32 r33] t = [tx ty tz]^T
Overview
Functions
create()
Short description
Create a instance for the calibration result handling
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The calibration result object instance. |
Sample (auto-generated)
cameraModel = Image.Calibration.CameraModel.create()crop()
Short description
Function used to calculate a new camera model for a cropped version of a calibrated image. That is, if Image.crop has been applied to an image, this function can be used to find a camera model that fits the new image.
Keywords
reduce, shrink, cut
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the camera calibration. |
x |
INT |
1 |
The x pixel position of the first pixel. |
y |
INT |
1 |
The y pixel position of the first pixel. |
width |
INT |
1 |
The amount of pixels in the horizontal direction. |
height |
INT |
1 |
The amount of pixels in the vertical direction. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The camera model adjusted to a cropped image. |
Sample
croppedModel = Image.Calibration.CameraModel.crop(cameraModel, x, y, width, height)evaluate()
| This API is experimental |
Short description
Evaluates a calibration model on a set of 2D and 3D correspondences. These can typically be obtained from the available calibration routines. The error and density is evaluated by binning over a 15 by 15 grid. The error is the average error within each bin resampled to the sensor size. This gives and idea of how homogeneous the error is over the sensor area. The density value is the amount of points close to each sensor point. E.g. for a 2048x2048 image a value of 10 means that we have approximately 10 points within a region of 136x136 pixels.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the camera calibration. |
sensorPoints |
+ |
Point positions on the sensor. Each point must have a corresponding point in worldPoints. |
|
worldPoints |
+ |
Point positions in external world coordinates. Each point must have a corresponding point in sensorPoints. |
|
colorCoded |
BOOL |
? |
Set to true if a pseudo color RGB image is desired. Default is false. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
errorImage |
1 |
Color coded error image. |
|
densityImage |
1 |
Intensity coded density image. |
|
minError |
FLOAT |
1 |
Minimum absolute error. Note, this is not the min of the densityImage, but the smallest reprojection error. |
maxError |
FLOAT |
1 |
Maximum absolute error. Note, this is not the max of the densityImage, but the largest reprojection error. |
Sample
errorImage, densityImage = Image.Calibration.CameraModel.evaluate(cameraModel, sensorPoints, worldPoints)getCalibrationImageSize()
Short description
Get the image size for which the calibration is valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
imageWidth |
INT |
1 |
The image width for which the calibration is valid. |
imageHeight |
INT |
1 |
The image height for which the calibration is valid. |
Sample (auto-generated)
imageWidth, imageHeight = Image.Calibration.CameraModel.getCalibrationImageSize(cameraModel)getCameraID()
Short description
Get the unique camera identifier.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraID |
STRING |
1 |
The unique camera identifier. |
Sample (auto-generated)
cameraID = Image.Calibration.CameraModel.getCameraID(cameraModel)getEulerAngles()
Short description
Get the Euler angle representation (yaw, pitch, roll) of the transform into camera coordinates (in degree).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
yaw |
FLOAT |
1 |
The rotation around x-axis in degree. |
pitch |
FLOAT |
1 |
The rotation around y-axis in degree. |
roll |
FLOAT |
1 |
The rotation around z-axis in degree. |
Sample (auto-generated)
yaw, pitch, roll = Image.Calibration.CameraModel.getEulerAngles(cameraModel)getFocalDistance()
Short description
Get the camera model focus setting parameter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
focalDistance |
FLOAT |
1 |
Distance from the camera to the plane of best image sharpness. |
unit |
STRING |
1 |
Focal distance unit. Default is mm. |
Sample (auto-generated)
focalDistance, unit = Image.Calibration.CameraModel.getFocalDistance(cameraModel)getFrustum()
Short description
Calculates camera frustum in a given plane. If a plane is not supplied the overlap will be calculated in the calibration plane pose was calculated, or at unit distance from the camera if uncalibrated.
Keywords
fov, field of view
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the camera calibration. |
plane |
? |
The world plane in which to calculate the frustum. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
center |
? |
The camera center in world coordinates. |
|
topLeft |
? |
||
topRight |
? |
||
bottomRight |
? |
||
bottomLeft |
? |
Sample
center, topLeft, topRight, bottomRight, bottomLeft = Image.Calibration.CameraModel.getFrustum(cameraModel)getFrustumOverlap()
Short description
Calculates the camera frustum projection onto a world plane for two or more cameras and returns the overlapping region in each camera image.
Keywords
fov, field of view
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
+ |
Camera model objects (at least 2). |
plane |
? |
The world plane in which to calculate the overlap. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
regions |
* |
A list of PixelRegions with the view overlap projected into each view. |
|
corners |
* |
The world corners of the overlapping region. |
Sample
regions, corners = Image.Calibration.CameraModel.getFrustumOverlap(cameraModel)getIntrinsicK()
Short description
Get the intrinsic camera matrix.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
intrinsic |
1 |
A 3x3 matrix with the intrinsic camera parameters: K = [fx s cx, 0 fy cy, 0 0 1] |
Sample (auto-generated)
intrinsic = Image.Calibration.CameraModel.getIntrinsicK(cameraModel)getPosition()
Short description
Returns the position of the camera center as a 3D Point. If no extrinsic calibration is available the position will be in origin (0, 0, 0).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
center |
1 |
Camera center world position as a 3D point. |
Sample (auto-generated)
center = Image.Calibration.CameraModel.getPosition(cameraModel)getProjectionMatrix()
Short description
Get the 3x4 projection matrix P = K[R|t]. Transformation xp = K*(R*Xw + T), with xp = [u/z, v/z, z/z] = [x,y,1] in homogeneous coordinates and Xw = [X,Y,Z] in 3D world coordinates.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
projectionMatrix |
1 |
A 3x4 projection matrix P = K[R |
Sample (auto-generated)
projectionMatrix = Image.Calibration.CameraModel.getProjectionMatrix(cameraModel)getRodriguesVector()
Short description
Get the Rodrigues representation of the transform into camera coordinates.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
rodrigues |
1 |
Rigid transformation in form of a Rodrigues vector. |
Sample
local rodrigues = Image.Calibration.CameraModel.getRodriguesVector(cameraModel)getRotation()
| This API is experimental |
Short description
Returns the rotation of the camera relative the calibrated world. If no extrinsic calibration is available the returned Matrix will be the identity matrix.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
rotation |
1 |
The camera rotation as a 3x3 Matrix. |
Sample (auto-generated)
rotation = Image.Calibration.CameraModel.getRotation(cameraModel)getSensorToWorldDistortion()
Short description
Get the lens distortion coefficients [k1, k2, p1, p2, k3].
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
k1 |
FLOAT |
1 |
Second order radial lens distortion coefficient. |
k2 |
FLOAT |
1 |
Fourth order radial lens distortion coefficient. |
p1 |
FLOAT |
1 |
First tangential lens distortion coefficient. |
p2 |
FLOAT |
1 |
Second tangential lens distortion coefficient. |
k3 |
FLOAT |
1 |
Sixth order radial lens distortion coefficient. |
Sample (auto-generated)
k1, k2, p1, p2, k3 = Image.Calibration.CameraModel.getSensorToWorldDistortion(cameraModel)getTransform()
Short description
Returns the pose of the camera as Transform object.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
transform |
1 |
Rigid transformation from world to camera coordinates [R,t]. |
Sample (auto-generated)
transform = Image.Calibration.CameraModel.getTransform(cameraModel)getVisualization()
| This API is experimental |
Short description
Calculates camera frustum in a given plane and returns line segments for viewing. If a plane is not supplied the overlap will be calculated in the calibration plane pose was calculated, or at unit distance from the camera if uncalibrated.
Keywords
fov, field of view
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the camera calibration. |
plane |
? |
The world plane in which to calculate the frustum. |
Sample
lines = Image.Calibration.CameraModel.getVisualization(cameraModel, plane)getWorldToSensorDistortion()
Short description
Get the lens distortion coefficients [k1, k2, p1, p2, k3].
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
k1 |
FLOAT |
1 |
Second order radial lens distortion coefficient. |
k2 |
FLOAT |
1 |
Fourth order radial lens distortion coefficient. |
p1 |
FLOAT |
1 |
First tangential lens distortion coefficient. |
p2 |
FLOAT |
1 |
Second tangential lens distortion coefficient. |
k3 |
FLOAT |
1 |
Sixth order radial lens distortion coefficient. |
Sample (auto-generated)
k1, k2, p1, p2, k3 = Image.Calibration.CameraModel.getWorldToSensorDistortion(cameraModel)getXMLVersionTag()
Short description
Get the version tag of the XML file.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
versionTag |
STRING |
1 |
The version tag of the XML. |
Sample (auto-generated)
versionTag = Image.Calibration.CameraModel.getXMLVersionTag(cameraModel)load()
| This API is deprecated |
Short description
Load calibration result object from a file. This function is deprecated, please use Object.save/load instead.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fileName |
STRING |
1 |
Filename, including path and file extension. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
? |
The calibration result object or nil |
Sample
local cameraModel = Image.Calibration.CameraModel.load("private/CalibrationResult.xml)loadDF()
| This API is experimental |
Short description
Load old style camera models.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
path |
STRING |
1 |
The path the the calibration file. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
model |
OBJECT |
? |
The converted camera model. |
Sample
model = Image.Calibration.CameraModel.loadDF(path)mapPoints()
Short description
Transform points between the three coordinate systems related to a camera model. See the CoordinateSystem enum for details.
Keywords
apply camera model, transform
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
points |
[1+] |
A single or a list of points to be transformed. |
|
sourceSystem |
ENUM |
1 |
Specifies the coordinate system in which the input point is defined. |
targetSystem |
ENUM |
1 |
Specifies the coordinate system to transform the points into. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pointsOut |
[?*] |
Transformed points (single point or array). |
Sample
local pointsOut = Image.Calibration.CameraModel.mapPoints(cameraModel, pointsIn, "CAMERA_PIXEL", "EXTERNAL_WORLD")resize()
Short description
Function used to calculate a new camera model for a resized version of a calibrated image. That is, if Image.resize has been applied to an image, this function can be used to find a camera model that fits the new image.
Keywords
enlarge, morph, shrink, rescale
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the camera calibration. |
width |
INT |
1 |
The width of the target. |
height |
INT |
1 |
The height of the target. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The camera model adjusted to a resized image. |
Sample
resizedModel = Image.Calibration.CameraModel.resize(cameraModel, width, height)resizeScale()
Short description
Function used to calculate a new camera model for a resized version of a calibrated image. That is, if Image.resizeScale has been applied to an image, this function can be used to find a camera model that fits the new image.
Keywords
enlarge, morph, shrink, rescale
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the camera calibration. |
scaleX |
FLOAT |
1 |
The scale factor to apply in the horizontal direction. |
scaleY |
FLOAT |
? |
The scale factor to apply in the vertical direction. If left out scaleX will be used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The camera model adjusted to a resized image. |
Sample
resizedModel = Image.Calibration.CameraModel.resizeScale(cameraModel, scale)save()
| This API is deprecated |
Short description
Save calibration result object to a file. This function is deprecated, please use Object.save/load instead.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The instance to use. |
fileName |
STRING |
1 |
Filename, including path and file extension. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if the file is written correctly. |
Sample
local success = Image.Calibration.CameraModel.save(cameraModel, "private/CalibrationResult.xml")setCalibrationImageSize()
Short description
Set the image size for which the calibration is valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The instance to use. |
imageWidth |
INT |
1 |
The image width for which the calibration is valid. |
imageHeight |
INT |
1 |
The image height for which the calibration is valid. |
Sample (auto-generated)
Image.Calibration.CameraModel.setCalibrationImageSize(cameraModel, imageWidth, imageHeight)setCameraID()
Short description
Set the unique camera identifier.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The instance to use. |
cameraID |
STRING |
1 |
The unique camera identifier. |
Sample (auto-generated)
Image.Calibration.CameraModel.setCameraID(cameraModel, cameraID)setFocalDistance()
Short description
Set the camera model focus setting parameter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The instance to use. |
focalDistance |
FLOAT |
1 |
Distance from the camera to the plane of best image sharpness. |
unit |
STRING |
1 |
Focal distance unit. Default is mm. |
Sample (auto-generated)
Image.Calibration.CameraModel.setFocalDistance(cameraModel, focalDistance, unit)setIntrinsicK()
Short description
Set the intrinsic camera matrix.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The instance to use. |
intrinsic |
1 |
A 3x3 matrix with the intrinsic camera parameters: K = [fx s cx, 0 fy cy, 0 0 1] |
Sample (auto-generated)
Image.Calibration.CameraModel.setIntrinsicK(cameraModel, intrinsic)setProjectionMatrix()
Short description
Set the 3x4 projection matrix P = K[R|t].
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The instance to use. |
projectionMatrix |
1 |
A 3x4 projection matrix P = K[R |
Sample (auto-generated)
Image.Calibration.CameraModel.setProjectionMatrix(cameraModel, projectionMatrix)setSensorToWorldDistortion()
Short description
Set the lens distortion coefficients [k1, k2, p1, p2, k3].
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The instance to use. |
k1 |
FLOAT |
? |
Set second order radial lens distortion coefficient. |
k2 |
FLOAT |
? |
Set fourth order radial lens distortion coefficient. |
p1 |
FLOAT |
? |
Set first tangential lens distortion coefficient. |
p2 |
FLOAT |
? |
Set second tangential lens distortion coefficient. |
k3 |
FLOAT |
? |
Set sixth order radial lens distortion coefficient. |
Sample (auto-generated)
Image.Calibration.CameraModel.setSensorToWorldDistortion(cameraModel, k1, k2, p1, p2, k3)setTransform()
Short description
Set the pose transformation of the camera as Transform object.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The instance to use. |
transform |
1 |
Rigid transformation describing the transformation from world to camera coordinates [R,t]. |
Sample (auto-generated)
Image.Calibration.CameraModel.setTransform(cameraModel, transform)setWorldToSensorDistortion()
Short description
Set the lens distortion coefficients [k1, k2, p1, p2, k3].
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
The instance to use. |
k1 |
FLOAT |
? |
Set second order radial lens distortion coefficient. |
k2 |
FLOAT |
? |
Set fourth order radial lens distortion coefficient. |
p1 |
FLOAT |
? |
Set first tangential lens distortion coefficient. |
p2 |
FLOAT |
? |
Set second tangential lens distortion coefficient. |
k3 |
FLOAT |
? |
Set sixth order radial lens distortion coefficient. |
Sample (auto-generated)
Image.Calibration.CameraModel.setWorldToSensorDistortion(cameraModel, k1, k2, p1, p2, k3)toString()
Short description
Gets a short string description of the camera model.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
The camera model object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
str |
STRING |
1 |
Description of the camera model. |
Sample (auto-generated)
str = Image.Calibration.CameraModel.toString(cameraModel)transform()
Short description
Calculate a camera model object with the pose transformed in accordance with the provided transform object. The transformation is applied from the left such that the camera pose transform C becomes C' = transform*C.
Keywords
align, modify pose
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
CONST_OBJECT |
1 |
Camera model object containing the camera calibration. |
transform |
1 |
The transform object describing how to move the camera. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
updatedModel |
OBJECT |
? |
The resulting camera placed at the new location. On failure nil is returned. |
Sample
updatedModel = Image.Calibration.CameraModel.transform(cameraModel, transform)translate()
Short description
Calculate camera model objects with poses translated one or more distance(s) along the input direction vector. The variable "distance" can be a scalar or a vector and the output will have the same dimension.
Keywords
align, modify pose, move
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the camera calibration. |
directionVector |
FLOAT |
+ |
The direction of the motion represented as a vector (x, y, z). |
distance |
FLOAT |
[1+] |
Exposure distance along the direction vector (can be a scalar or a vector of distances). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModelPoses |
OBJECT |
[1+] |
Camera model(s) corresponding to the position(s) along the direction vector. Will have the same size as the input distance. |
Sample
cameraModelPoses = Image.Calibration.CameraModel.translate(cameraModel, directionVector, distance)Image.Calibration.Correction
Short description
Correction of image distortions based on a calibrated camera model. Supports correction of lens distortion and perspective distortion from small tilt angles and image rotations.
Keywords
distortion, lens, perspective, rectification, rectify, untilt, unwarp, undistort
See also
Overview
Functions
apply()
Short description
Apply the image correction to an input image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
corr |
HANDLE |
1 |
The correction object to use. |
inputImage |
1 |
Input image |
Sample
outputImage = corr:apply(inputImage)create()
Short description
Create an image correction object.
See also
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
corr |
HANDLE |
1 |
Sample
corr = Image.Calibration.Correction.create()getValidRegion()
Short description
Get a pixel region corresponding to the valid part of the corrected image. The valid part of the output image contains pixel values from the input image, and the invalid part is just set to zero.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
corr |
HANDLE |
1 |
The correction object to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
validRegion |
? |
Valid region of the output. |
Sample
validRegion = corr:getValidRegion()getVirtualCamera()
Short description
Get a camera model representing the virtual camera producing the corrected image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
corr |
HANDLE |
1 |
The correction object to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
camera |
OBJECT |
? |
Virtual camera of the correction procedure. |
Sample
camera = corr:getVirtualCamera()mapPoints()
Short description
Map points between the four coordinate systems related to the correction process. See the CoordinateSystem enum for details.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
corr |
HANDLE |
1 |
The correction object to use. |
pointsIn |
[1+] |
Points to transform (single point or array). |
|
sourceSystem |
ENUM |
1 |
Specifies the coordinate system in which the input point is defined. |
targetSystem |
ENUM |
1 |
Specifies the coordinate system to transform the points into. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pointsOut |
[1+] |
Transformed points (single point or array). |
Sample
pointsOut = corr:mapPoints(pointsIn, sourceSystem, targetSystem)setAlignMode()
Short description
Setup the correction to map specific world ground plane rectangle to an image. This gives precise control of the pixel size and world origin of the output image.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
corr |
HANDLE |
1 |
The correction object to setup. |
cameraModel |
OBJECT |
1 |
A model of a calibrated camera, as returned from the Image.Calibration functions. |
worldRect |
1 |
World rectangle describing the world region to cover. |
|
pixelSize |
FLOAT |
? |
Desired pixel size (mm/pixel) of the output image. If omitted, a similar pixel size as in the input image center will be used. |
interpolation |
ENUM |
? |
Interpolation method to use. Default is LINEAR. |
Sample
corr:setAlignMode(cameraModel, worldRect, pixelSize, interpolation)setUndistortMode()
Short description
Setup the correction to compensate for lens distortion only. The other parts of the camera model are ignored.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
corr |
HANDLE |
1 |
The correction object to setup. |
cameraModel |
CONST_OBJECT |
1 |
A model of a calibrated camera, as returned from the Image.Calibration functions. |
cropMode |
ENUM |
? |
Crop mode, determines how to crop the output. Default is FULL. |
interpolation |
ENUM |
? |
Interpolation method to use. Default is LINEAR. |
Sample
corr:setUndistortMode(cameraModel, cropMode, interpolation)setUntiltMode()
Short description
Setup the correction to compensate for lens distortion and perspective distortions caused by a tilt angle between the world ground plane and the camera. Any in-plane rotation between the camera and world is left unaltered.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
corr |
HANDLE |
1 |
The correction object to setup. |
cameraModel |
CONST_OBJECT |
1 |
A model of a calibrated camera, as returned from the Image.Calibration functions. |
cropMode |
ENUM |
? |
Crop mode, determines how to crop the output. Default is FULL. |
interpolation |
ENUM |
? |
Interpolation method to use. Default is LINEAR. |
targetWidth |
INT |
? |
Output image width. Default is same size as the input. |
targetHeight |
INT |
? |
Output image height. Default is same size as the input. |
Sample
corr:setUntiltMode(cameraModel, cropMode, interpolation)Image.Calibration.Pattern
Short description
Different pattern generators and detectors for calibration targets. Currently supports the three types PLAIN, THREE_DOT and COORDINATE_CODE. PLAIN is recommended for intrinsic camera calibration which can be performed using Image.Calibration.Camera. THREE_DOT and COORDINATE_CODE are recommended for pose calibration with the corresponding function under Image.Calibration.Pose. THREE_DOT has the advantage of being simple, while having the limitation that all cameras must see the same three dots to find the origin of the world coordinate system. COORDINATE_CODE patterns allows cameras to observe completely distinct pieces of the calibration target, while still producing a calibration in the same world coordinate system.
Functions
detectCheckerboard()
Short description
Finds a checkerboard in an image and returns the image points together with their sorted grid positions. This can be used to create custom calibration routines or to build other things based on checkerboards.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
The input image in which to find a checkerboard. |
|
patternType |
ENUM |
1 |
The pattern type to look for when deciding the origin. |
downsamplefactor |
INT |
? |
A value larger of equal to 0. A higher value gives faster runtime but possibly less detections. Default is 0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
* |
Image points that correspond to checkerboard corners. |
|
indices |
* |
The world grid coordinates corresponding to points. |
Sample
Image.Calibration.Pattern.detectCheckerboard(image, "COORDINATE_CODE")getCheckerboardDPI()
Short description
Generates a checkerboard pattern based on sizes in millimeters. The generation takes limits on the output image in mm, the desired square size and a DPI resolution. The square size is internally adjusted to fit to the closest integer position. Therefore the actual size of each square after print is not exactly the selected value. The actual size is returned as the first output. Note that the DPI needs to be set before print as the image does not carry the DPI setting. Alternatively it’s possible to print with the appropriate scale. For example most printers assume 72 DPI and if the pattern was generated using 300 DPI the scale can be set to 0.24 (72/300). For details on the different patterns see the enum description.
Keywords
``
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
maxWidth |
FLOAT |
1 |
The maximum width of the image in mm at given resolution. |
maxHeight |
FLOAT |
1 |
The maximum height of the image in mm at given resolution. |
squareSide |
FLOAT |
1 |
Specify how many mm it is desired to have along each side of a square in the generated image. |
type |
ENUM |
1 |
Select the type of pattern to generate. |
dpi |
INT |
? |
Specify the desired dots per inch, i.e. the resolution when printing. Default is 300 dpi. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
actualSquareSide |
FLOAT |
? |
The actual size of a square after print if printing at the set resolution. |
generatedPattern |
? |
The generated pattern image. |
Sample
Image.Calibration.Pattern.getCheckerboardDPI(297, 210, 15, "COORDINATE_CODE")getCheckerboardPixel()
Short description
Generates a checkerboard pattern based on given values in pixels and number of squares. For details on the different patterns see the enum description.
Keywords
``
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
horizontalSquares |
INT |
1 |
The number of horizontal squares in the pattern. At least 2, for THREE_DOT at least 5. |
verticalSquares |
INT |
1 |
The number of vertical squares in the pattern. At least 2. |
squareSide |
INT |
1 |
Specify how many pixels to have along each side of a square in the generated image. Cannot be less than 24. |
type |
ENUM |
1 |
Select the type of pattern to generate. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
generatedPattern |
? |
Returns the generated pattern as an image. |
Sample
Image.Calibration.Pattern.getCheckerboardPixel(10, 12, 100, "COORDINATE_CODE")Image.Calibration.Pose
Short description
Image.Calibration.Pose can be used to estimate the pose (the extrinsic parameters) of one or multiple cameras. Different calibration targets are supported, for example a simple checkerboard with squared corners for single camera calibration and a checkerboard combined with 2D codes for use in multi-camera systems.
Overview
Functions
estimate()
Short description
Calculate the sensor pose (extrinsic parameters) from a reference image of the calibration target. If successful, the results of the pose are added to the "cameraModel" input object. This method uses a simple checkerboard with squared corners. The full checkerboard pattern does not have to be visible in the calibration image for the algorithm to work.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
A gray scale image of the calibration target. |
|
cameraModel |
CONST_OBJECT |
1 |
A CameraModel containing calibration results from a previous intrinsic calibration. |
sideLength |
FLOAT |
[1+] |
Checkerboard corner side length in mm. If your target is not accurate enough and your checkerboard elements are not quadratic, you can enter the side length dimensions for x and y. The algorithm will correct the world corner values. Keep in mind you also have to specify the 'checkerboardDimensions' for the CHECKERBOARD type. Otherwise the algorithm cannot determine which side length belongs to which dimension. |
checkerboardDimensions |
INT |
* |
Optional and only for CHECKERBOARD : Number of checkerboard corners in x and y direction. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
If successful, a new calibration model containing a valid pose is returned, otherwise nil. |
reprojectionError |
FLOAT |
1 |
Sum of squared distances between the detected 2D feature points and the projected 3D feature points using the estimated camera calibration parameter. |
featurePoints2D |
* |
2D checkerboard corners in image plane for the result visualization. |
|
featurePoints3D |
* |
Corresponding 3D world coordinates of the checkerboard corners. |
|
residuals |
* |
The calibration residuals for each calibration point consisting in a vector of vectors of 2D points. |
Sample
local cameraModel = Image.Calibration.Pose.estimate(image, cameraModel, sideLength)estimateCodeExternal()
| This API is deprecated |
Short description
Deprecated, please use Image.Calibration.Pose.estimateMatrixCode instead. Calculate the absolute sensor pose (extrinsic parameters) from a reference image of the calibration target. If successful, a new "cameraModel" object including the pose is returned. This method uses a checkerboard combined with 2D codes. The code contents and regions are supplied by Image.CodeReader. From one placement of the calibration target it is possible to estimate the extrinsic poses of a multi-camera system.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
A gray scale image of the calibration target. |
|
cameraModel |
OBJECT |
1 |
A CameraModel containing calibration results from a previous intrinsic calibration. |
codeContent |
BINARY |
+ |
Optional: List of code contents. |
codeRegion |
+ |
Optional: List of code ROIs, each represented as a 4-point polyline shape. |
|
sideLength |
FLOAT |
[?*] |
Checkerboard corner side length in mm. May if your target is not accurate enough and your checkerboard elements are not quadratic you can enter the checker side length dimensions for x,y and z. The algorithm will correct the world corner values. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
If successful, a new calibration model containing a valid pose is returned, otherwise nil. |
reprojectionError |
FLOAT |
1 |
Sum of squared distances between the detected 2D feature points and the projected 3D feature points using the estimated camera calibration parameter. |
featurePoints2D |
* |
2D checkerboard corners in image plane for the result visualization. |
|
featurePoints3D |
* |
Corresponding 3D world coordinates of the checkerboard corners. |
|
residuals |
* |
The calibration residuals for each calibration point consisting in a vector of vectors of 2D points. |
Sample
local cameraModel = Image.Calibration.Pose.estimateCodeExternal(image, cameraModel, codeContent, codeRegion)estimateCoordinateCode()
Short description
Performs the estimation of the camera pose based on a checkerboard with coordinate codes in some squares. The pattern can be generated using Image.Calibration.Pattern.getCheckerboardDPI or getCheckerboardPixel with the type enum set to "COORDINATE_CODE". In order for alignment to work well each camera should see at least two coordinate codes. Which codes each camera sees, does not matter. The coordinate system produced is right orthogonal with the Z-axis point up from the calibration target. At least 20 corners on the calibration target must be seen for the calibration to succeed.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the intrinsic calibration parameters of the camera. |
image |
1 |
Image that will be used for the calibration. |
|
squareSize |
FLOAT |
+ |
The length of the sides of the checkerboard squares. If two values are supplied they should be in X, Y order. |
thickness |
FLOAT |
? |
Set this parameter to offset the base plane to compensate for a calibration plate with some thickness. |
regionOfInterest |
? |
If the image is cluttered, a Shape rectangle containing the calibration pattern in the image can be supplied. This makes the algorithm more robust to noise. The rectangle should be axis aligned. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModelPose |
OBJECT |
? |
If successful a new calibration model containing a valid pose is returned, otherwise nil. |
reprojectionError |
FLOAT |
? |
Mean of Euclidean distances between the detected 2D feature points and the projected 3D feature points using the estimated camera calibration parameters. |
points2D |
* |
2D checkerboard corners in image plane for result visualization. |
|
points3D |
* |
Corresponding 3D world coordinates of the checkerboard corners. |
|
residuals |
* |
The calibration residuals for each calibration point consisting of a vector of 2D points. |
Sample
cameraModelPose = Image.Calibration.Pose.estimateCoordinateCode(cameraModel, image, {10.0})estimateFromPoints()
Short description
Performs the estimation of the camera pose based on a set of 2D and 3D points. The 2D points should be as observed in the image and before any undistortion has been applied. The corresponding 3D points should be the known, or desired, locations of these 2D points in the world. Note that this function is very flexible and can support most use cases. It’s even possible to align several cameras to the same world coordinate system, but it’s recommended to instead consider Image.Calibration.Pose.estimateThreeDot or Image.Calibration.Pose.estimateCoordinateCode. The coordinate system produced depends on the order and orientation of the input points. At least 4 point pairs are needed for calibration to succeed.
Keywords
calibration, camera model, pnp solver, camera pose estimation
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the intrinsic calibration parameters of the camera. |
sensorPoints |
+ |
Point positions on the sensor. Each point must have a corresponding point in worldPoints. |
|
worldPoints |
+ |
Point positions in external world coordinates. Each point must have a corresponding point in sensorPoints. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModelPose |
OBJECT |
? |
If successful a new calibration model containing a valid pose is returned, otherwise nil. |
reprojectionError |
FLOAT |
? |
Mean of Euclidean distances between the detected 2D feature points and the projected 3D feature points using the estimated camera calibration parameters. |
residuals |
* |
The calibration residuals for each calibration point consisting of a vector of 2D points. |
Sample
cameraModelPose = Image.Calibration.Pose.estimateFromPoints(cameraModel, sensorPoints, worldPoints)estimateMatrixCode()
Short description
Calculate the absolute sensor pose (extrinsic parameters) from a reference image of the calibration target. If successful, a new "cameraModel" object including the pose is returned. This method uses a checkerboard combined with 2D codes. The code contents and regions are supplied by Image.CodeReader. From one placement of the calibration target it is possible to estimate the extrinsic poses of a multi-camera system.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
A gray scale image of the calibration target. |
|
cameraModel |
OBJECT |
1 |
A CameraModel containing calibration results from a previous intrinsic calibration. |
codeContent |
BINARY |
+ |
List of code contents. |
codeRegion |
+ |
List of code ROIs, each represented as a 4-point polyline shape. |
|
sideLength |
FLOAT |
[?*] |
Checkerboard corner side length in mm. May if your target is not accurate enough and your checkerboard elements are not quadratic you can enter the checker side length dimensions for x,y and z. The algorithm will correct the world corner values. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
If successful, a new calibration model containing a valid pose is returned, otherwise nil. |
reprojectionError |
FLOAT |
1 |
Sum of squared distances between the detected 2D feature points and the projected 3D feature points using the estimated camera calibration parameter. |
featurePoints2D |
* |
2D checkerboard corners in image plane for the result visualization. |
|
featurePoints3D |
* |
Corresponding 3D world coordinates of the checkerboard corners. |
|
residuals |
* |
The calibration residuals for each calibration point consisting in a vector of vectors of 2D points. |
Sample
local cameraModel = Image.Calibration.Pose.estimateMatrixCode(image, cameraModel, codeContent, codeRegion)estimateOneShot()
Short description
Performs a calibration of a camera based on a planar world assumption. This means that for measurements outside of the calibrated plane accuracy cannot be guaranteed to be accurate. The advantage of this model is that only one image is required to get a reasonable image to world transformation. The coordinate system produced is right orthogonal with the Z-axis point up from the calibration target. At least 20 corners on the calibration target must be seen for the calibration to succeed.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Image that will be used for the calibration. |
|
squareSize |
FLOAT |
+ |
The length of the sides of the checkerboard squares. If two values are supplied they should be in X, Y order. |
type |
ENUM |
? |
Select the type of pattern to look for. If left out PLAIN will be used. |
estimateLensModel |
BOOL |
? |
Select if a lens model should be estimated. Default is true. |
lockLensCenter |
BOOL |
? |
Select if the lens center should be forced to the center of the screen. Locking the lens center is more robust than allowing it to move. Default is true. |
regionOfInterest |
? |
If the image is cluttered, a Shape rectangle containing the calibration pattern in the image can be supplied. This makes the algorithm more robust to noise. The rectangle should be axis aligned. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraPose |
OBJECT |
? |
If successful a new calibration model containing a valid pose is returned, otherwise nil. |
reprojectionError |
FLOAT |
? |
Mean of Euclidean distances between the detected 2D feature points and the projected 3D feature points using the estimated camera calibration parameter. |
featurePoints2D |
* |
2D checkerboard corners in image plane for result visualization. |
|
featurePoints3D |
* |
Corresponding 3D world coordinates of the checkerboard corners. |
|
residuals |
* |
The calibration residuals for each calibration point consisting of a vector of 2D points. |
Sample
Image.Calibration.Pose.estimateOneShot(image, {10.0}, "COORDINATE_CODE")estimatePlain()
Short description
Performs the estimation of the camera pose based on a plain (empty) checkerboard pattern that can be generated using Image.Calibration.Pattern.getCheckerboardDPI or getCheckerboardPixel with the type enum set to "PLAIN". Note that the pose given by a calibration using a plain target can be used to correct for perspective, but not to align several cameras to the same world coordinate system. This is because two cameras observing the same calibration target typically will get different world coordinate system origins. The coordinate system produced is right orthogonal with the Z-axis point up from the calibration target. At least 20 corners on the calibration target must be seen for the calibration to succeed.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the intrinsic calibration parameters of the camera. |
image |
1 |
Image that will be used for the calibration. |
|
squareSize |
FLOAT |
+ |
The length of the sides of the checkerboard squares. If two values are supplied they should be in X, Y order. |
thickness |
FLOAT |
? |
Set this parameter to offset the base plane to compensate for a calibration plate with some thickness. |
regionOfInterest |
? |
If the image is cluttered, a Shape rectangle containing the calibration pattern in the image can be supplied. This makes the algorithm more robust to noise. The rectangle should be axis aligned. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModelPose |
OBJECT |
? |
If successful a new calibration model containing a valid pose is returned, otherwise nil. |
reprojectionError |
FLOAT |
? |
Mean of Euclidean distances between the detected 2D feature points and the projected 3D feature points using the estimated camera calibration parameters. |
points2D |
* |
2D checkerboard corners in image plane for result visualization. |
|
points3D |
* |
Corresponding 3D world coordinates of the checkerboard corners. |
|
residuals |
* |
The calibration residuals for each calibration point consisting of a vector of 2D points. |
Sample
cameraModelPose = Image.Calibration.Pose.estimatePlain(cameraModel, image, {10.0})estimateThreeDot()
Short description
Performs the estimation of the camera pose based on a checkerboard containing three dots, which can be generated using Image.Calibration.Pattern.getCheckerboardDPI or getCheckerboardPixel with the type enum set to "THREE_DOT". In order for alignment of several cameras to work all cameras must observe the same three dots. It’s not supported to use one calibration target with several origin markers. The coordinate system produced is right orthogonal with the Z-axis point up from the calibration target. At least 20 corners on the calibration target must be seen for the calibration to succeed.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Camera model object containing the intrinsic calibration parameters of the camera. |
image |
1 |
Image that will be used for the calibration. |
|
squareSize |
FLOAT |
+ |
The length of the sides of the checkerboard squares. If two values are supplied they should be in X, Y order. |
thickness |
FLOAT |
? |
Set this parameter to offset the base plane to compensate for a calibration plate with some thickness. |
regionOfInterest |
? |
If the image is cluttered, a Shape rectangle containing the calibration pattern in the image can be supplied. This makes the algorithm more robust to noise. The rectangle should be axis aligned. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModelPose |
OBJECT |
? |
If successful a new calibration model containing a valid pose is returned, otherwise nil. |
reprojectionError |
FLOAT |
? |
Mean of Euclidean distances between the detected 2D feature points and the projected 3D feature points using the estimated camera calibration parameters. |
points2D |
* |
2D checkerboard corners in image plane for result visualization. |
|
points3D |
* |
Corresponding 3D world coordinates of the checkerboard corners. |
|
residuals |
* |
The calibration residuals for each calibration point consisting of a vector of 2D points. |
Sample
cameraModelPose = Image.Calibration.Pose.estimateThreeDot(cameraModel, image, {10.0})Image.CircularBuffer
| This API is experimental |
Short description
A buffer object to store rows of images in a circular mode.
Overview
Functions
appendImage()
Short description
Appends the given image to the given CircularBuffer beginning with the given write position.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
buffer |
OBJECT |
1 |
An object that contains image data in a circular buffer. |
image |
1 |
An Image object. |
|
row |
INT |
1 |
row, where the image should be appended to within the buffer |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
row |
INT |
1 |
resulting row after appending the given image |
Sample (auto-generated)
row = Image.CircularBuffer.appendImage(buffer, image, row)copyToImage()
Short description
Copies a rectangular part of the gray value circular buffer to an image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
buffer |
OBJECT |
1 |
An object that contains image data in a circular buffer. |
fromRow |
INT |
1 |
Top border |
toRow |
INT |
1 |
Bottom border |
fromColumn |
INT |
? |
Left border |
toColumn |
INT |
? |
Right border |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
1 |
Image defined by the given borders.. |
Sample (auto-generated)
image = Image.CircularBuffer.copyToImage(buffer, fromRow, toRow, fromColumn, toColumn)create()
Short description
Creates a CircularBuffer object.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
type |
ENUM |
1 |
Type of buffer |
numRows |
INT |
1 |
Number of rows the buffer should have |
numColumns |
INT |
1 |
Number of columns the buffer should have |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
buffer |
OBJECT |
1 |
An object that contains image data in a circular buffer. |
Sample (auto-generated)
buffer = Image.CircularBuffer.create(type, numRows, numColumns)getPixel()
Short description
Returns the pixel value of the gray image buffer at position x/y.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
buffer |
OBJECT |
1 |
An object that contains image data in a circular buffer. |
row |
INT |
1 |
The row number of the pixel |
column |
INT |
1 |
The column number of the pixel |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
value |
FLOAT |
? |
Pixel value of the specified image pixel |
Sample (auto-generated)
value = Image.CircularBuffer.getPixel(buffer, row, column)Image.Descriptor
| This API is experimental |
Short description
Image descriptors. Descriptors describe the content of an image in a more compact way. Reduction can be performed in different ways depending on what image content to preserve.
Image.Descriptor.OrientationHistogram
| This API is experimental |
Short description
Calculates gradient orientation histograms for input images. Two separate modes are supported. The base histogram of gradients or HOG descriptor with a tunable number of orientation bins and a version of the robustified Pedro Felzenszwalb histogram of gradients with 18 orientations. For the base version each feature represent a particular orientation and the number directly correspond to the orientation input. For the specialized version the first 18 features are so called contrast sensitive hog features. The second 9 are contrast insensitive hog features and the final 1 or 4 are texture features.
Overview
Functions
calculateFeatures()
| This API is experimental |
Short description
Perform OrientationHistogram descriptor calculation with one cell covering the whole image. In total the size of the output will be binCount x rotations. For the Pedro Felzenszwalb descriptor the size is always binCount x 28.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hog |
1 |
The object to use |
|
image |
1 |
The image to compute features for. |
|
orientations |
INT |
? |
The number of orientations to use in the returned histogram. |
region |
CONST_OBJECT |
? |
Optional region of interest. Default is to use the whole image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if computations succeeded. |
Sample
hogmatrix = Image.Descriptor.OrientationHistogram.calculateFeaturesInRegion(hog, image, 18)calculateFeaturesInBlocks()
| This API is experimental |
Short description
Perform OrientationHistogram descriptor calculation with the input image split into square blocks. For the Pedro Felzenszwalb descriptor the output will always be (width-2) x (height-2) x 31 number of features, where the width and height are properties of the input image. For the general case the feature size is … TODO
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hog |
1 |
The object to use |
|
image |
1 |
The image to compute features for. |
|
blockSize |
INT |
1 |
Select the size of each computation block. |
orientations |
INT |
? |
The number of orientations to use in the returned histogram. Default is 18. |
outerBlockFactor |
INT |
? |
Toggle to calculate each block multiple times with intensity normalized over a larger outer block. Set to 2 to get an outer block of twice the size as blockSize. Default is 1. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if computations succeeded. |
Sample
Image.Descriptor.OrientationHistogram.calculateFeaturesInBlocks(hog, image, binCount, cellSize)create()
| This API is experimental |
Short description
Creates a new OrientationHistogram (Histogram of Gradients) handle. Use the fhog parameter to use the specialized Pedro Felzenszwalb descriptor.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fhog |
BOOL |
? |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hog |
1 |
The new OrientationHistogram object. |
Sample
hog = Image.Descriptor.OrientationHistogram.create()getFeatureImage()
| This API is experimental |
Short description
Returns the descriptor as an image that consisting in several sub-images. This is convenient for visualization of feature content.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hog |
CONST_OBJECT |
1 |
The object to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
features |
? |
An image containing feature data. |
Sample
hogimage = Image.Descriptor.OrientationHistogram.getFeatureImage(hog)getFeatureMatrix()
| This API is experimental |
Short description
Returns the descriptor as a matrix with each column representing a feature and each row representing a patch in the input image. For calculateFeatures a single row Matrix is returned.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
hog |
CONST_OBJECT |
1 |
The object to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
features |
? |
A matrix containing feature data. |
Sample
hogimage = Image.Descriptor.OrientationHistogram.getFeatureMatrix(hog)Image.Fixture
Short description
Helper object for transformation of geometrical primitives between different views of the same object. This object is typically used in a locate-inspect concept, where a teach image is used to define a set of measurement tasks. These measurement tasks will then be executed on a set of live images, where the object to measure may be translated, rotated and/or scaled differently than in the teach image. Typically, the following steps are included in locate-inspect applications: - Teach a matching algorithm (EdgeMatcher, PointMatcher, PatternMatcher) from a teach image. Use the teach pose returned from the teach procedure as reference pose for the fixture. - Define a set of points or shapes in the teach image, related to various measurement tasks. Append these to the fixture using the append functions. - For each live image, find the object using a match call of the selected matching algorithm. Transform the fixture to this new object pose using Fixture.transform. - Get the transformed points or shapes using the get functions, now relating to the found pose of the object in the live image. Saving and loading a fixture: A Image.Fixture instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.
Keywords
local, object, reference, coordinate system
Overview
Functions
appendAngle()
Short description
Append an angle to the fixture.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the angle, used when retrieving the angle later on. |
angle |
FLOAT |
1 |
Angle to append. |
Sample
Image.Fixture.appendAngle(fixture, "angle1", 3.1415/2)appendPoint()
Short description
Append a point to the fixture.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the point, used when retrieving the point later on. |
point |
1 |
Point to append. |
Sample
Image.Fixture.appendPoint(fixture, "point1", point)appendPose()
Short description
Append a pose transform to the fixture. Typically, the appended pose defines the pose of an object part. For example, the pose returned from the PatternVerifier teach method can be appended to a fixture. After calling Fixture.transform() to transform the fixture to a live image, Fixture.getPose() will give the pose of the part in the live image. The output from getPose can then be used in a call to PatternVerifier.verify() to verify the part in the live image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the pose, used when retrieving the pose later on. |
pose |
1 |
Pose to append, defined in image world coordinates. |
Sample
Image.Fixture.appendPose(fixture, "pose1", pose)appendShape()
Short description
Append a shape or composite shape to the fixture.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the shape, used when retrieving the shape later on. |
shape |
1 |
Shape or composite shape to append. |
Sample
Image.Fixture.appendShape(fixture, "shape1", shape)create()
Short description
Create a new fixture.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
The new fixture. |
Sample
fixture = Image.Fixture.create()getAngle()
Short description
Get an angle from the fixture, transformed according to the current fixture transform.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the angle to retrieve. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
angle |
FLOAT |
? |
The retrieved angle. |
Sample
angle = Image.Fixture.getAngle(fixture, "angle1")getAsPixelRegion()
Short description
Get a shape or composite shape region from the fixture, transformed directly to a pixel region for use as algorithm input. Since the returned object is not a shape, more general transformations are supported by this function compared to getShape().
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the shape or composite shape to retrieve. |
referenceImage |
1 |
Reference image, use to determine the pixel-world mapping. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
? |
The transformed shape, converted to a pixel region. |
Sample
region = Image.Fixture.getAsPixelRegion(fixture, "shape1", referenceImage)getPoint()
Short description
Get a point from the fixture, transformed according to the current fixture transform.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the point to retrieve. |
Sample
point = Image.Fixture.getPoint(fixture, "point1")getPose()
Short description
Get a pose from the fixture, transformed according to the current fixture transform. Typically, this is used to get the pose of an object part. For example, the pose returned from getPose can be used as input to the PatternVerifier match function. See appendPose for more information.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the pose to retrieve. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pose |
? |
The retrieved pose. |
Sample
pose = Image.Fixture.getPose(fixture, "pose1")getShape()
Short description
Get a shape or composite shape from the fixture, transformed according to the current fixture transform. Nil is returned if the shape can not be transformed accordingly.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the object to retrieve. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
shape |
AUTO |
? |
The retrieved shape or composite shape. |
Sample
shape = Image.Fixture.getShape(fixture, "shape1")setReferencePose()
Short description
Set the reference pose of this fixture. This defines the object pose that all geometrical items will be related to. Typically, the teachPose output from the teach function of a matching tool (for example Image.Matching.EdgeMatcher.teach()) is used as input to this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
referencePose |
1 |
Pose transform of the object that all appended geometrical items will be related to. |
Sample
Image.Fixture.setReferencePose(fixture, referencePose)toString()
Short description
Get a user-friendly string description of the fixture.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
description |
STRING |
? |
User-friendly description of the fixture. |
Sample
local description = Image.Fixture.toString(fixture)transform()
Short description
Transform the fixture to a new pose. This will affect the pose of all geometrical items retrieved using the get functions. Typically, the pose transform output from the match function of a matching tool (for example Image.Matching.EdgeMatcher.match()) is often used as input to this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
poseTransform |
1 |
Pose transform of the new fixture pose. |
Sample
Image.Fixture.transform(fixture, poseTransform)Image.Fixture3D
Short description
Helper object for transformation of 3D geometrical primitives (Shapes, Points, regions). This object is typically used in a locate-inspect concept together with the EdgeMatcher3D, where a teach image is used to define a set of measurement tasks. These measurement tasks will then be executed on a set of live images, where the object to measure may be translated, rotated and/or scaled differently than in the teach image. The shadow region of a shape on the z=0 plane can be obtained directly using getAsPixelRegion. This function also allows more general transforms compared to the getShape function. E.g. using getPose on a circle will only allow up to similarity transforms, while getAsPixelRegion allows homography transforms. Typically, the following steps are included in locate-inspect applications: - Teach a 3D matching algorithm such as EdgeMatcher3D using a teach image. Use the teach pose returned from the teach procedure as reference pose for the fixture. - Define a set of points or shapes in the teach image, related to various measurement tasks. Append these to the fixture using the append functions. - For each live image, find the object using a match call of the selected matching algorithm. Transform the fixture to this new object pose using Fixture3D.transform(). - Get the transformed points or shapes using the get functions, now relating to the found pose of the object in the live image. Saving and loading a fixture: A Image.Fixture3D instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.
Keywords
local, object, reference, coordinate system
Overview
Functions
appendPoint()
Short description
Appends a 3D point to the fixture.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the point, used when retrieving the point later on. |
point |
1 |
3D point to append. |
Sample
Image.Fixture3D.appendPoint(fixture, "point1", point)appendPose()
Short description
Appends a pose transform (Transform 3D object) to the fixture. Typically, the appended pose defines the pose of an object part, for example, the pose returned from teaching 3D matchers for sub-components. After calling Fixture3D.transform() to transform the fixture to a live image, Fixture3D.getPose() will give the pose of the part in the live image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the pose, used when retrieving the pose later on. |
pose |
1 |
Transform pose (3D Transform) to append, defined in image world coordinates. |
Sample
Image.Fixture3D.appendPose(fixture, "pose1", pose)appendShape()
Short description
Appends a Shape3D object to the fixture.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the shape, used when retrieving the shape later on. |
shape |
1 |
Shape3D object to append. |
Sample
Image.Fixture3D.appendShape(fixture, "shape1", shape)create()
Short description
Creates a new 3D fixture.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
The new fixture. |
Sample
fixture = Image.Fixture3D.create()getAsPixelRegion()
Short description
Gets a 3D shape from the fixture represented as a pixel region plus height boundaries (zMin, zMax). The pixel region is the convex hull of the shape projected onto the plane z = 0. More general transforms are allowed when using getAsPixelRegion, even transforms that changes the type of shape.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the shape to retrieve. |
referenceImage |
1 |
Reference image, used to supply the image world coordinate system. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
? |
The transformed shape, converted to a pixel region. |
|
zMin |
FLOAT |
? |
The lowest z-value encountered in the shape after transformation but before projection. |
zMax |
FLOAT |
? |
The highest z-value encountered in the shape after transformation but before projection. |
Sample
region = Image.Fixture3D.getAsPixelRegion(fixture, "shape1", referenceImage)getPoint()
Short description
Gets a point from the fixture, transformed according to the current fixture transform.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the point to retrieve. |
Sample
point = Image.Fixture3D.getPoint(fixture, "point1")getPose()
Short description
Gets a pose from the fixture, transformed according to the current fixture transform. Typically, this is used to get the pose of an object part.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the pose to retrieve. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pose |
? |
The retrieved pose transform (Transform 3D). |
Sample
pose = Image.Fixture3D.getPose(fixture, "pose1")getShape()
Short description
Gets a shape from the fixture, transformed according to the current fixture transform.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
name |
STRING |
1 |
Name of the shape to retrieve. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
shape |
? |
The retrieved 3D shape. |
Sample
shape = Image.Fixture3D.getShape(fixture, "shape1")setReferencePose()
Short description
Sets the reference pose of this fixture. This defines the object pose that all geometrical items will be related to. Typically, the teachPose output from the teach function of a matching tool, e.g., EdgeMatcher3D, is used as input to this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
referencePose |
1 |
Pose transform (Transform3D) of the object that all appended geometrical items will be related to. |
Sample
Image.Fixture3D.setReferencePose(fixture, referencePose)toString()
Short description
Gets a user-friendly string description of the fixture.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
description |
STRING |
1 |
User-friendly description of the fixture. |
Sample
local description = Image.Fixture3D.toString(fixture)transform()
Short description
Transforms the fixture to a new pose. This will affect the pose of all geometrical items retrieved using the get functions. Typically, the pose transform output from the match function of a matching tool is often used as input to this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
fixture |
HANDLE |
1 |
Fixture object. |
poseTransform |
1 |
Pose transform (Transform 3D object) of the new fixture pose. |
Sample
Image.Fixture3D.transform(fixture, poseTransform)Image.Format
Short description
Image file formats/encodings.
Overview
Image.Format.BMP
Short description
BMP encoding functionality
See also
Functions
create()
Short description
Creates a new instance of the BMP encoder.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the instance. |
Sample (auto-generated)
handle = Image.Format.BMP.create()decode()
Short description
Create an Image object from a binary buffer containing a BMP encoded image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the BMP instance |
bmpBuffer |
BINARY |
? |
Binary buffer containing the BMP encoded image |
Sample (auto-generated)
image = Image.Format.BMP.decode(handle, bmpBuffer)encode()
Short description
Create a binary buffer with the BMP encoded image data. Supported image types: UINT8, RGB24
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
imageIn |
1 |
image to encode |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
bmpBuffer |
BINARY |
? |
binary buffer containing the BMP encoded image or nil |
Sample (auto-generated)
bmpBuffer = Image.Format.BMP.encode(handle, imageIn)Image.Format.JPEG
Short description
JPEG encoding functionality
See also
Overview
Functions
create()
Short description
Creates a new instance of the JPEG encoder.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
? |
Handle to the new instance if available. Can be nil if unavailable. |
Sample (auto-generated)
handle = Image.Format.JPEG.create()decode()
Short description
Create an Image object from a binary buffer containing a JPEG encoded image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
jpegBuffer |
BINARY |
? |
Binary buffer containing the JPEG encoded image |
Sample (auto-generated)
image = Image.Format.JPEG.decode(handle, jpegBuffer)encode()
Short description
Create a binary buffer with the JPEG encoded image data.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
imageIn |
1 |
Image to encode |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
jpegBuffer |
BINARY |
? |
Binary buffer containing the JPEG encoded image or nil |
Sample (auto-generated)
jpegBuffer = Image.Format.JPEG.encode(handle, imageIn)setQuality()
Short description
Configure the JPEG encoding quality, a lower value results in higher compression. Which quality level can be set depends on whether the calculation is done on the CPU or on the co-processing FPGA (see device specification if a co-processing FPGA is available or not).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
quality |
INT |
1 |
Quality level, CPU → Initial: 80, Min: 0, Max: 100, FPGA → Initial: 50, Min: 20, Max: 80 |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful, false otherwise |
Sample (auto-generated)
success = Image.Format.JPEG.setQuality(handle, quality)Image.Format.PNG
Short description
PNG encoding functionality
See also
Overview
Functions
create()
Short description
Creates a new instance of the PNG encoder.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the instance. |
Sample (auto-generated)
handle = Image.Format.PNG.create()decode()
Short description
Create an Image object from a binary buffer containing a PNG encoded image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
pngBuffer |
BINARY |
? |
Binary buffer containing the PNG encoded image |
Sample
local image = Image.Format.PNG.decode(handle, pngBuffer)encode()
Short description
Create a binary buffer with the PNG encoded image data. Supported image types: UINT8, UINT16, RGB24
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
imageIn |
1 |
image to encode |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pngBuffer |
BINARY |
? |
binary buffer containing the PNG encoded image or nil |
Sample
local pngBuffer = Image.Format.PNG.encode(handle, image)setCompression()
Short description
Configure the PNG encoding compression (0-9), a higher value results in higher compression and higher run time.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle |
compression |
INT |
1 |
Ranges from 0 (no compression) to 9 (high compression). Default: 6. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successful, false otherwise |
Sample (auto-generated)
success = Image.Format.PNG.setCompression(handle, compression)Image.Format.SSR
| This API is experimental |
Short description
SSR encoding functionality
Functions
create()
Short description
Creates a new instance of the SSR encoder.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the instance. |
Sample (auto-generated)
handle = Image.Format.SSR.create()encode()
Short description
Create a binary buffer with the SSR encoded image data.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle to the instance |
imageIn |
1 |
image to encode |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ssrBuffer |
BINARY |
? |
binary buffer containing the SSR encoded image or nil |
Sample (auto-generated)
ssrBuffer = Image.Format.SSR.encode(handle, imageIn)Image.Matching
Short description
Functions for matching and locating objects and patterns in images based on different object models, including edge-based models, interest point models and pixel pattern models.
Image.Matching.EdgeMatcher
Short description
Object matching of objects which are well defined by clean edges/contours in a 2D image. An alternative to the EdgeMatcher is the PointMatcher for objects whose appearance is rather described by a texture pattern. Teach an object model from a reference image and call match to find the location of the same object in a new image. The EdgeMatcher searches for translation, rotation and scale (range 80% - 120%) of objects. Results are given as pose transforms which describe how the object model is transformed to matched positions in the new image. Each match gets a score between 0.0 and 1.0 where 1.0 means a perfect match. The EdgeMatcher is often used together with the Image.Fixture object that facilitates local coordinate transforms based on the result of the EdgeMatcher. The most important parameters for the EdgeMatcher are the following: - Edge threshold: Make sure to select an edge strength threshold that includes the edges of the reference object but excludes clutter edges in the background. Use the getModelContours() function to graphically verify the object model obtained. - Background clutter: If the images contain patterns and structures other than the object of interest, use the HIGH setting in setBackgroundClutter() which is the default. If the object is on a clean background one can gain speed by setting the background clutter flag to MEDIUM or LOW. There is an interaction with the background clutter setting and the downsample factor parameter below though: It can be possible to run with higher downsample factors using the HIGH background clutter and thus gain higher speed compared to running a MEDIUM background clutter and a lower downsample factor. - Downsample factor: The EdgeMatcher works internally on downsampled images for computational performance reasons. The downsample factor is the most important parameter for the speed versus robustness trade-off. An initial choice of downsample factor could be one that generates a downsampled image of size about 200 x 200. For example, if images of size 1024 x 1024 are used, one could start experimenting with a downsample factor of 5. The downsample factor has an effect on the robustness of the algorithm (finding the correct match) but not on the position accuracy. - Rotation range: The rotation range parameter should be selected to be as narrow as possible both for computational reasons and for robustness reasons. If it is known that the target object only can appear within a certain rotation interval relative to the teach pose, make sure to reduce the rotation range search parameter. - Scale range: As with the rotation range parameter, set the scale range as narrowly as possible for computational and performance reasons. Set a narrow scale range to allow for slight size variations due to noise or minor perspective changes. By default, scale search is disabled. Pixel types: The EdgeMatcher accepts uint8 and uint16 pixel type images. Hardware acceleration: Some devices have FPGA-support for the EdgeMatcher. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. If there is FPGA support it is set as default, but note that the FPGA is not able to support all configurations, mainly there is a lower restriction on the downsample factor for memory limitation reasons. There is typically only one instance of the FPGA calculation unit in a device. If many EdgeMatcher instances are created running in parallel, all using the FPGA acceleration, they may try to access the FPGA resource at the same time. The behavior is then that a match call will wait until the FPGA resource is available again. Coarse mode: In cases where coarse positioning is sufficient, faster matching may be obtained by skipping fine search. See setPerformFineSearch(). Image world coordinate system handling: The image (x,y)-pixelsize and origin are considered within the EdgeMatcher, all calculations are made in the image world coordinate system. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: The EdgeMatcher does not accept missing data images, turn off the missing data flag to use it anyway or use the EdgeMatcher3D. Object model: An object representation of the contours in the teach reference image is generated in a teach call. The center of the model, and also the rotation center, is the center of the teach region. Saving and loading a configuration: A trained EdgeMatcher instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.
Keywords
contour, find, matching, object, pattern, shape, locator
See also
Overview
Functions
create()
Short description
Creates a new edge matcher for object localization in 2D intensity images.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The new EdgeMatcher instance. |
Sample
locator = Image.Matching.EdgeMatcher.create()getCoarseEdgeProbeCounts()
| This API is experimental |
Short description
Gets the number of positive and negative coarse edge probes found during last teach. Intended for unit tests.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
positiveCount |
INT |
1 |
The number of positive edge probes. |
negativeCount |
INT |
1 |
The number of negative edge probes. |
Sample
positiveCount, negativeCount = Image.Matching.EdgeMatcher.getCoarseEdgeProbeCounts(matcher)getDownsampleFactorLimits()
Short description
A support function which outputs the minimum and maximum values of the downsample factor. In particular when FPGA acceleration is utilized there are memory limitations setting a minimal value for the downsample factor. However, if the tiling is used (see setTileCount() and getNeededTileCount() ), this is not a hard limit anymore, but will give a performance drop. The maximum downsample factor is derived from the smallest allowed downsampled image size to look for matches in.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
image |
1 |
An image with the size that the EdgeMatcher will work on |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
minDsf |
FLOAT |
1 |
Minimum allowed downsample factor. |
maxDsf |
FLOAT |
1 |
Maximum allowed downsample factor. |
Sample
minDsf, maxDsf = Image.Matching.EdgeMatcher.getDownsampleFactorLimits(matcher, image)getEdgePoints()
| This API is deprecated |
Short description
Deprecated: This function has been renamed to getModelPoints to align with the PointMatcher API. The functions give the same output. Get sample edges of the object represented as a vector of 2D Points. This function is intended for graphical feedback using representative points on edges of the reference object. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. Can only be called after a successful teach.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
* |
Edge points in internal model coordinates. |
Sample
points = Image.Matching.EdgeMatcher.getEdgePoints(matcher)getModelContours()
Short description
Get object model contours for visualization purposes. Results are returned as polyline shape objects.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
polylines |
* |
Edge lines in internal model coordinates. |
Sample
polylines = Image.Matching.EdgeMatcher.getModelContours(matcher)getModelPoints()
Short description
Get the object model as a vector of 2D Points of located edges. This function is intended for graphical feedback using representative points on edges of the reference object. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. Can only be called after a successful teach. Note: As it may be inefficient to overlay a lot of points in images, it is recommended to use the getModelContours function instead for graphical feedback.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
maxCount |
INT |
? |
Optional parameter to specify the maximum number of control points along the polylines to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
* |
Edge points in internal model coordinates. |
Sample
points = Image.Matching.EdgeMatcher.getModelPoints(matcher, 1000)getNeededTileCount()
Short description
Get the needed number of tiles the match image must be split into during match. A successful teach must be done before calling this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
image |
1 |
An image with the size that the EdgeMatcher will work on |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
neededTileCount |
INT |
1 |
Needed number of tiles. |
tilingPossible |
BOOL |
1 |
True if tiling is possible. |
Sample
neededTileCount, tilingPossible = Image.Matching.EdgeMatcher.getNeededTileCount(matcher, image)getPerformFineSearch()
Short description
Get the setting that indicates if a fine search should be performed.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
performFineSearch |
BOOL |
1 |
The value of the setting indicating if a fine search is performed. |
Sample
performFineSearch = Image.Matching.EdgeMatcher.getPerformFineSearch(matcher)getRotationStep()
| This API is experimental |
Short description
Gets rotation step for coarse search.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
rotationStep |
INT |
1 |
Rotation step used in coarse search. Default is 1. |
Sample
rotationStep = Image.Matching.EdgeMatcher.getRotationStep(matcher)getTeachPose()
Short description
Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
teachPose |
? |
2D pose transform transforming the object model to its position in the teach image, or nil if unsuccessful. |
Sample
teachPose = Image.Matching.EdgeMatcher.getTeachPose(matcher)getTileCount()
Short description
Get the desired and actual number of tiles the match image is split into during a match.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
tileCount |
INT |
1 |
Desired number of tiles. 0 means automatic selection. 1 means not tiling. |
actualTileCount |
INT |
1 |
Number of tiles the match image was split into. Same as tileCount if tileCount != 0. |
Sample
tileCount, actualTileCount = Image.Matching.EdgeMatcher.getTileCount(matcher)match()
Short description
Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to the match in the live image. For the EdgeMatcher, the output posed transforms are of 2D Transform type. They can be used with the Fixture object to transform other 2D objects and regions. The match scores are based on how well edge information in the image matches the object model. The status code indicates what happened during the call and may be set to any of the values below. Status code zero means no error and no warning. Negative status codes are used for warnings, where results are returned but may not be as expected. * -132: Search region was partially or entirely outside the image. * -131: Search region was empty. * 0: Matching was successful (although no objects may have been found, there was no error). * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 210: Timeout, matching was aborted. Check the set time limit. * 220: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 230: Region error, something was wrong with the search region. * 240: Unteached matcher, the matcher is not successfully teached. * 260: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use |
liveImage |
1 |
The live image or image pyramid to find the object in. |
|
searchRegion |
CONST_AUTO |
? |
Optional search region in the live image, either a pixel region or a closed 2D shape such as a rectangle. Edges are only detected within this region and it should cover the entire object to be found. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
poseTransforms |
* |
Pose transforms defining the location of each detected object. |
|
matchScores |
FLOAT |
* |
A score between 0.0 and 1.0 for each detected object (high score means good match). |
status |
INT |
? |
A status code indicating what happened during the call. |
Sample
transforms, scores, status = Image.Matching.EdgeMatcher.match(matcher, liveImage, searchRegion)setBackgroundClutter()
Short description
A setting that indicates to what level the live images supplied to the match function are expected to contain non-object edges. Keep this parameter at HIGH (default) if the image contains a lot of other edges, structures, noise, clutter in areas not belonging to the object of interest. Examples of such structures are barcodes and text which generate a lot of edge responses. For clean scenes this parameter can be set to MEDIUM or LOW to gain speed. Note however that it may be possible to work with higher downsample factors if this parameter is set to HIGH. Setting this parameter will invalidate any previous teach call.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
backgroundClutterLevel |
AUTO |
1 |
Set to the expected background clutter level, LOW, MEDIUM or HIGH. Default is HIGH. In a previous version of this function this input was a bool where 'true' maps to the MEDIUM enum and 'false' to the LOW enum. |
Sample
Image.Matching.EdgeMatcher.setBackgroundClutter(matcher, backgroundClutterLevel)setDownsampleFactor()
Short description
Sets downsampling factor in the x- and y-dimensions of the image. If the original image has size (M,N), the downsampled image has size (M/d, N/d) where d is the downsampling factor. Setting this parameter will invalidate any previous teach call. More downsampling will increase the speed but eventually will reduce the matching robustness. Especially, for small object or thin contours the downsampling cannot be set too low as the details will become washed out in the downsampled image. However, some downsampling can also be beneficial for the matching as noise and irrelevant edges are removed. Therefore, a good downsampling is usually somewhere between 2.0 and 10.0. Setting a high downsampling does not have an impact on the final matching position accuracy as matches are fine-tuned on finer image resolutions. For FPGA acceleration there is lower limit on the downsampling factor due to memory limitations. This limit is different for various devices but is usually around 5.0 to 6.0. Use the getDownsampleFactorLimits to find out the lower and upper limits on the downsample factor.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
downsampleFactor |
FLOAT |
1 |
A factor larger than or equal to 1.0. The default value is 8.0. |
Sample
Image.Matching.EdgeMatcher.setDownsampleFactor(matcher, 6.0)setEdgeThreshold()
Short description
Sets the edge threshold, i.e., minimal edge strength. The edge strength is calculated as using a local image gradient filter so that smooth edges may generate weak edge responses. The default value is 50. For lower contrast edges one must reduce this value and for very sharp and high-contrast edges it should be raised. Check with the getModelContours() function the edges that are obtained.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
threshold |
FLOAT |
1 |
Edge threshold. The default value is 50. |
Sample
Image.Matching.EdgeMatcher.setEdgeThreshold(matcher, 20)setFineSearchIterations()
Short description
Sets the fine search number of iterations. A lower value will increase the speed but might reduce the matching robustness.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
fineSearchIterations |
INT |
1 |
The number of fine search iterations, it must be a positive integer number. The default value is 1. |
Sample
Image.Matching.EdgeMatcher.setFineSearchIterations(matcher, 2)setMaxMatches()
Short description
Sets the maximum number of objects to find in a match call. Note that the actual number found can be smaller than this number. Increasing the number of matches to consider is also a way to control the number of match candidates considered within the algorithm. Thus, in cluttered scenes it may be possible to increase robustness to increase this parameter even if one knows that there is only one object present at the end. This parameter can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
matchCount |
INT |
1 |
An integer larger than or equal to 1 specifying the maximum number of objects to find. Maximum number is 100. The default value is 1. |
Sample
Image.Matching.EdgeMatcher.setMaxMatches(matcher, 3)setMinSeparation()
Short description
Sets the minimum separation between the centers of object matches. The unit is in image world units (typically millimeters) taking the image pixel size into account. For 2D images the pixel size is by default 1.0, in which case the value equals the separation in pixels. This parameter only has effect if the number of matches to find is larger than 1. This parameter can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
minSeparation |
FLOAT |
1 |
The minimum separation between the centers of two objects in image world units. The default value is 50. |
Sample
Image.Matching.EdgeMatcher.setMinSeparation(matcher, 100)setPerformFineSearch()
Short description
Set if the fine search should be performed. The default is true. Disabling the fine search may reduce the runtime of the matcher in cases where accurate positioning is not required. In order to obtain fast matching, the downsampling factor should be set as high as possible while turning off scale and rotation search.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
performFineSearch |
BOOL |
1 |
Set to true to perform a coarse followed by a fine search. If set to false only a coarse search is performed. |
Sample
Image.Matching.EdgeMatcher.setPerformFineSearch(matcher, performFineSearch)setProcessingUnit()
Short description
Sets processing unit for the calculations. Some devices support FPGA acceleration of the EdgeMatcher. If this is the case the FPGA acceleration is set by default when the EdgeMatcher object is created. This parameter can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
processingUnit |
1 |
Which type of processing unit to use. If there is FPGA support in the device it will be used as default, otherwise CPU. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if processing unit choice was successfully set. False if the processing unit or configuration is not supported. |
Sample
Image.Matching.EdgeMatcher.setProcessingUnit(matcher, "FPGA")setRotationRange()
Short description
Sets rotation interval to search in relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. If prior orientation information is known, the prior rotation can be set to allow a more narrow search range. The final search range is then up to plus/minus the search range parameter starting from the prior rotation. These parameters can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
rotationRad |
FLOAT |
1 |
Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI (180 degrees), i.e., full rotation. |
priorRotationRad |
FLOAT |
? |
Optional prior orientation in radians. If specified, the orientation search range is centered around this orientation. Default is zero (i.e. same orientation as teach object). |
Sample
Image.Matching.EdgeMatcher.setRotationRange(matcher, rotationRad, priorRotationRad)setScaleRange()
Short description
Sets scale interval to search relative to the teach size. The end points are represented as scale factors. setScaleRange(0.8, 1.2) searches for objects appearing down to 20% smaller or larger than the teach object. Default is not to search in scale, i.e, scale range parameters [1.0, 1.0]. An optional prior scale can be set, this affects both the minimum and maximum scale (both limits are multiplied with the prior scale). The prior scale moves the entire scale search range and does not affect matching time. The prior scale accepts a larger range of values than the min and max scale parameters. If the object to find has a fixed non-unit scale relative to the teach object, or if prior information on the scale of the object is available, use the prior scale. The default value is 1.0. By setting both minScale and maxScale to 1.0, scale search is disabled but the prior scale parameter still has effect. A scale range of [1.0, 1.0] completely disables scale search, however, if there are small size variations due to noise, a small scale search range, e.g. [0.98, 1.02] lets the matcher adapt to small size variations without the time penalty of a large search range. These parameters can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
minScale |
FLOAT |
1 |
The smallest scale factor to search for. Lower limit is 0.8. Default value is 1.0. |
maxScale |
FLOAT |
1 |
The largest scale factor to search for. Upper limit is 1.2. Default value is 1.0. |
priorScale |
FLOAT |
? |
Optional prior scale factor. Set to the expected scale of the object to find, relative to the size of the teach object. E.g. 1.25 if the object to find is 25% larger than the teach object. Min: 0.1. Max: 10 |
Sample
Image.Matching.EdgeMatcher.setScaleRange(matcher, minScale, maxScale, priorScale)setTileCount()
Short description
Set into how many tile images the match image should be split into. This can decrease the minimum downsampling factor and/or the maximum image size, when FPGA processing is used. 0 gives automatic selection, using the minimum number of image tiles required to support the selected downsampling factor. 1 disables tiling.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
tileCount |
INT |
1 |
Number of tile images to split into. 0 gives automatic selection. 1 disables tiling. Default: 0. |
Sample
Image.Matching.EdgeMatcher.setTileCount(matcher, tileCount)setTimeout()
Short description
Abort the match call if the match time exceeds a user-defined number of seconds. The main purpose is to protect against excessively long execution times, the granularity does not allow exact abortion at the given timeout parameter. This parameter can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
timeoutSeconds |
FLOAT |
1 |
Time in seconds after which the algorithm should abort. The default value is 5 seconds. |
Sample
Image.Matching.EdgeMatcher.setTimeout(matcher, 2.0)teach()
Short description
Teaches an object model from edges in an image. It is important to set the edge strength threshold properly for this to work. Graphical feedback from the teach process is obtained through the getModelContours function. The status code indicates what happened during the call and may be set to any of the following values: * 0: Teaching was successful. * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 110: Timeout, teaching was aborted. Check the set time limit. * 120: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 130: Region error, something was wrong with the teach region. * 160: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy. * 170: Model edge error, too few model edges were found. Check the edge threshold, the input image and that the teach region covers the object of interest.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use |
teachImage |
1 |
The teach image or image pyramid. |
|
teachRegion |
CONST_AUTO |
1 |
A pixel region or a closed 2D shape defining the area where to extract edges, this should include the object to be located. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
teachPoseTransform |
? |
Pose transform of the object model, or nil if unsuccessful. |
|
status |
INT |
? |
A status code indicating what happened during the call. |
Sample
teachPoseTransform, status = Image.Matching.EdgeMatcher.teach(matcher, teachImage, teachRegion)toString()
Short description
Returns a human readable description of the matcher, including parameters.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
description |
STRING |
? |
A description of the matcher object, or nil on failure. |
Sample
description = Image.Matching.EdgeMatcher.toString(matcher)Image.Matching.EdgeMatcher3D
Short description
The EdgeMatcher3D is an extension of the EdgeMatcher for object matching in range images and heightmaps. See the EdgeMatcher documentation for information on the basic usage. The documentation below focuses on the extensions and differences to the EdgeMatcher. The most important additional parameters and difference for the EdgeMatcher3D are the following: - The EdgeMatcher3D searches for height and tilt (rotation around the x- and y-axes) of objects. The function setFindTiltHeight() enables and disables these additional parameters in the search. Tilt and height estimation is turned on by default. Turn these off for increased speed and robustness if the objects of interest always have the same tilt or height. - As range images generally contain missing data pixels, there is a mandatory "reference height" parameter that is set using the setReferenceHeight(). The EdgeMatcher3D uses this parameter to replace missing data pixels internally. - The output of the EdgeMatcher3D are 3D pose transforms. These can be used together with the Fixture3D object for locate-inspect applications. - Teach and search regions have additional zMin and zMax parameters to specify limits along the z-dimension. Pixel types: The EdgeMatcher3D accepts uint16 pixel type images. Hardware acceleration: Some devices have FPGA-support for the EdgeMatcher3D. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. If there is FPGA support it is set as default, but note that the FPGA is not able to support all configurations, mainly there is a lower restriction on the downsample factor for memory limitation reasons. There is typically only one instance of the FPGA calculation unit in a device. If many EdgeMatcher3D instances are created running in parallel, all using the FPGA acceleration, they may try to access the FPGA resource at the same time. The behavior is then that a match call will wait until the FPGA resource is available again. Image world coordinate system handling: All parameters (thresholds, zMin, zMax, reference height) use the z-origin and z-pixelsize. That is, the parameters are interpreted in world units, typically in millimeters. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: Both images with and without missing data flag are accepted. If the input image has missing data, the reference height parameter must be set to handle missing data internally. Object model: An object representation of the contours in the teach reference image is generated in a teach call. The center of the model, and also the rotation center, is the center of the teach region. The center in the z-dimension is (zMin + zMax)/2. Saving and loading a configuration: The configuration of a trained EdgeMatcher handle instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.
Overview
Functions
create()
Short description
Creates a new edge matcher for 3D object localization in range images.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The new instance. |
Sample
locator = Image.Matching.EdgeMatcher3D.create()getCoarseEdgeProbeCounts()
| This API is experimental |
Short description
Gets the number of positive and negative coarse edge probes found during last teach. Intended for unit tests.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
positiveCount |
INT |
1 |
The number of positive edge probes. |
negativeCount |
INT |
1 |
The number of negative edge probes. |
Sample
positiveCount, negativeCount = Image.Matching.EdgeMatcher3D.getCoarseEdgeProbeCounts(matcher)getDownsampleFactorLimits()
Short description
A support function which outputs the minimum and maximum values of the downsample factor. In particular when FPGA acceleration is utilized there are memory limitations setting a minimal value for the downsample factor. The maximum downsample factor is derived from the smallest allowed downsampled image size to look for matches in.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
image |
1 |
An image with the size that the EdgeMatcher3D will work on. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
minDsf |
FLOAT |
1 |
Minimum allowed downsample factor. |
maxDsf |
FLOAT |
1 |
Maximum allowed downsample factor. |
Sample
minDsf, maxDsf = Image.Matching.EdgeMatcher3D.getDownsampleFactorLimits(matcher, image)getFineSearchDiagnosticFloat()
| This API is experimental |
Short description
Gets diagnostic floating point data from the fine search part of the match operation. The data is only available if diagnostic info is enabled using 'enableDiagnosticInfo' before the match operation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
type |
1 |
Type of value to return. |
|
match |
INT |
? |
Match index. Default is first match (0). |
pyramidLevel |
INT |
? |
Pyramid level index. Default is most detailed level (0). |
iteration |
INT |
? |
Iteration index. First iteration has index 0. Default is last iteration. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
value |
FLOAT |
? |
Single floating point number, or nil if the requested value was not found. |
Sample
value = Image.Matching.EdgeMatcher3D.getFineSearchDiagnosticFloat(matcher, valueType, match, pyramidLevel, iteration)getFineSearchDiagnosticInteger()
| This API is experimental |
Short description
Gets diagnostic integer data from the fine search part of the match operation. The data is only available if diagnostic info is enabled using 'enableDiagnosticInfo' before the match operation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
type |
1 |
Type of value to return. |
|
match |
INT |
? |
Match index. Default is first match (0). |
pyramidLevel |
INT |
? |
Pyramid level index. Default is most detailed level (0). |
iteration |
INT |
? |
Iteration index. First iteration has index 0. Default is last iteration. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
value |
INT |
? |
Single integer number, or nil if the requested value was not found. |
Sample
value = Image.Matching.EdgeMatcher3D.getFineSearchDiagnosticInteger(matcher, valueType, match, pyramidLevel, iteration)getFineSearchDiagnosticPoints()
| This API is experimental |
Short description
Gets diagnostic points data from the fine search part of the match operation. The data is only available if diagnostic info is enabled using 'enableDiagnosticInfo' before the match operation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
type |
1 |
Type of points to return. |
|
match |
INT |
? |
Match index. Default is first match (0). |
pyramidLevel |
INT |
? |
Pyramid level index. Default is most detailed level (0). |
iteration |
INT |
? |
Iteration index. First iteration has index 0. Default is last iteration. |
maxCount |
INT |
? |
Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
* |
Debug points in world coordinates. |
Sample
points = Image.Matching.EdgeMatcher3D.getFineSearchDiagnosticPoints(matcher, pointsType, match, pyramidLevel, iteration, maxCount)getFineSearchDiagnosticPose()
| This API is experimental |
Short description
Gets diagnostic pose data from the fine search part of the match operation. The data is only available if diagnostic info is enabled using 'enableDiagnosticInfo' before the match operation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
type |
1 |
Type of pose to return. |
|
match |
INT |
? |
Match index. Default is first match (0). |
pyramidLevel |
INT |
? |
Pyramid level index. Default is most detailed level (0). |
iteration |
INT |
? |
Iteration index. First iteration has index 0. Default is last iteration. |
Sample
pose = Image.Matching.EdgeMatcher3D.getFineSearchDiagnosticPose(matcher, poseType, match, pyramidLevel, iteration)getModelContours()
Short description
Gets object model contours for visualization purposes. Results are returned as polyline Shape3D objects.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
polylines |
* |
Edge lines in internal model coordinates. |
Sample
polylines = Image.Matching.EdgeMatcher3D.getModelContours(matcher)getModelPlanePoints()
Short description
Gets object model points for visualization purposes. This function returns center points of planar patches.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
maxCount |
INT |
? |
Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
planarPoints |
* |
Vector of 3D planar points in internal model coordinates. |
Sample
planarPoints = Image.Matching.EdgeMatcher3D.getModelPlanePoints(matcher)getModelPoints()
Short description
Gets object model points for visualization purposes. This function returns points along the edges of object. See also getModelContours.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
maxCount |
INT |
? |
Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
* |
Edge points in internal model coordinates. |
Sample
points = Image.Matching.EdgeMatcher3D.getModelPoints(matcher)getNeededTileCount()
Short description
Get the needed number of tiles the match image must be split into during match. A successful teach must be done before calling this function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
image |
1 |
An image with the size that the EdgeMatcher will work on |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
neededTileCount |
INT |
1 |
Needed number of tiles. |
tilingPossible |
BOOL |
1 |
True if tiling is possible. |
Sample
neededTileCount, tilingPossible = Image.Matching.EdgeMatcher3D.getNeededTileCount(matcher, image)getPerformFineSearch()
Short description
Get the setting that indicates if a fine search should be performed.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
performFineSearch |
BOOL |
1 |
The value of the setting indicating if a fine search is performed. |
Sample
performFineSearch = Image.Matching.EdgeMatcher3D.getPerformFineSearch(matcher)getReferenceHeight()
Short description
Gets the reference height for missing data handling. This value is used to replace missing data pixels within the algorithm. Image world coordinate system handling: The reference height is interpreted in the image world coordinate system, typically in millimeters, considering the z-origin and z-pixelsize of the image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
referenceHeight |
FLOAT |
? |
The reference height in image world units, typically millimeters. |
Sample
referenceHeight = Image.Matching.EdgeMatcher3D.getReferenceHeight(matcher)getRotationStep()
| This API is experimental |
Short description
Gets rotation step for coarse search.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
rotationStep |
INT |
1 |
Rotation step used in coarse search. Default is 1. |
Sample
rotationStep = Image.Matching.EdgeMatcher3D.getRotationStep(matcher)getTeachDiagnosticFloat()
| This API is experimental |
Short description
Gets diagnostic floating point data from the teach operation. The data is only available if diagnostic info is enabled using 'enableDiagnosticInfo' before the teach operation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
type |
1 |
Type of value to return. |
|
pyramidLevel |
INT |
? |
Pyramid level index. Default is most detailed level (0). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
value |
FLOAT |
? |
Single floating point number, or nil if the requested value was not found. |
Sample
value = Image.Matching.EdgeMatcher3D.getTeachDiagnosticFloat(matcher, valueType, pyramidLevel)getTeachDiagnosticInteger()
| This API is experimental |
Short description
Gets diagnostic integer data from the teach operation. The data is only available if diagnostic info is enabled using 'enableDiagnosticInfo' before the teach operation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
type |
1 |
Type of value to return. |
|
pyramidLevel |
INT |
? |
Pyramid level index. Default is most detailed level (0). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
value |
INT |
? |
Single integer number, or nil if the requested value was not found. |
Sample
value = Image.Matching.EdgeMatcher3D.getTeachDiagnosticInteger(matcher, valueType, pyramidLevel)getTeachDiagnosticPoints()
| This API is experimental |
Short description
Gets diagnostic points data from the teach operation. The data is only available if diagnostic info is enabled using 'enableDiagnosticInfo' before the teach operation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
type |
1 |
Type of points to return. |
|
pyramidLevel |
INT |
? |
Pyramid level index. Default is most detailed level (0). |
maxCount |
INT |
? |
Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
* |
Debug points in world coordinates. |
Sample
points = Image.Matching.EdgeMatcher3D.getTeachDiagnosticPoints(matcher, pointsType, pyramidLevel, maxCount)getTeachDiagnosticPose()
| This API is experimental |
Short description
Gets diagnostic pose data from the teach operation. The data is only available if diagnostic info is enabled using 'enableDiagnosticInfo' before the teach operation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
type |
1 |
Type of pose to return. |
|
pyramidLevel |
INT |
? |
Pyramid level index. Default is most detailed level (0). |
Sample
pose = Image.Matching.EdgeMatcher3D.getTeachDiagnosticPose(matcher, poseType, pyramidLevel)getTeachPose()
Short description
Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
teachPose |
? |
Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful. |
Sample
teachPose = Image.Matching.EdgeMatcher3D.getTeachPose(matcher)getTileCount()
Short description
Get the desired and actual number of tiles the match image is split into during a match.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
tileCount |
INT |
1 |
Desired number of tiles. 0 means automatic selection. 1 means not tiling. |
actualTileCount |
INT |
1 |
Number of tiles the match image was split into. Same as tileCount if tileCount != 0. |
Sample
tileCount, actualTileCount = Image.Matching.EdgeMatcher3D.getTileCount(matcher)match()
Short description
Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to the match in the live image. For the EdgeMatcher3D, the output pose transforms are of 3D Transform type. They can be used with the Fixture3D object to transform other 3D objects and regions. The match scores are based on how well edge information in the image matches the object model. Currently, only (x,y) locations of edges are included in the score calculation, meaning that a mismatch in z-dimension can still give a high score. Image world coordinate system handling: The two parameters zMin and zMax specify the range interval of the teach region. The parameters are interpreted in image world units, typically millimeters, taking the z-origin and z-pixelsize of the input image into account. The status code indicates what happened during the call and may be set to any of the values below. Status code zero means no error and no warning. Negative status codes are used for warnings, where results are returned but may not be as expected. * -132: Search region was partially or entirely outside the image. * -131: Search region was empty. * 0: Matching was successful (although no objects may have been found, there was no error). * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 210: Timeout, matching was aborted. Check the set time limit. * 220: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 230: Region error, something was wrong with the search region. * 240: Unteached matcher, the matcher is not successfully teached. * 250: Reference plane error, something was wrong with the reference height for missing data. * 260: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use |
liveImage |
1 |
The live image or image pyramid to find the object in. |
|
searchRegion |
CONST_AUTO |
? |
Optional search region in the live image, either a pixel region or a closed 2D shape such as a rectangle. Edges are only detected within this region and it should cover the entire object to be found. |
zMin |
FLOAT |
? |
Optional minimum value for z heights in world units (millimeters). Only edges above this level are included as features for the matching. If not set, a large negative number is used as default. |
zMax |
FLOAT |
? |
Optional maximum value for z heights in world units (millimeters). Only edges below this level are included as features for the matching. If not set, a large positive number is used as default. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
poseTransforms |
* |
Pose transforms defining the location of each detected object. |
|
matchScores |
FLOAT |
* |
A score between 0.0 and 1.0 for each detected object (high score means good match). |
status |
INT |
? |
A status code indicating what happened during the call. |
Sample
transforms, scores = Image.Matching.EdgeMatcher3D.match(matcher, liveImage)proposeReferenceHeight()
Short description
Tries to estimate a reference height using valid pixels outside the teach region. Use this function carefully as it can give inaccurate results, for example if the teach region covers only the object partially.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use |
teachImage |
1 |
The teach image. |
|
teachRegion |
CONST_AUTO |
1 |
A pixel region or a closed 2D shape defining which area to consider as containing object edges. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
referenceHeight |
FLOAT |
? |
An estimated reference height in image world units, typically millimeters. Returns nil if height estimation fails. |
Sample
referenceHeight = Image.Matching.EdgeMatcher3D.proposeReferenceHeight(matcher, teachImage, teachRegion)setBackgroundClutter()
Short description
A setting that indicates to what level the live images supplied to the match function are expected to contain non-object edges, e.g., noise and other clutter structures. The default setting is "MEDIUM". For very cluttered scenes it is possible to use a "HIGH" setting. Setting this parameter will invalidate any previous teach call.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
backgroundClutterLevel |
AUTO |
1 |
Set to the expected background clutter level, LOW, MEDIUM or HIGH. Default is MEDIUM. |
Sample
Image.Matching.EdgeMatcher3D.setBackgroundClutter(matcher, backgroundClutterLevel)setDownsampleFactor()
Short description
Sets downsample factor in the x- and y-dimensions of the image. If the original image has size (M,N), the downsampled image has size (M/d, N/d) where d is the downsample factor. Setting this parameter will invalidate any previous teach call. More downsampling will increase the speed but eventually will reduce the matching robustness. Especially, for small object or thin contours the downsampling cannot be set too low as the details will become washed out in the downsampled image. However, some downsampling can also be beneficial for the matching as noise and irrelevant edges are removed. Therefore, a good downsampling is usually somewhere between 2.0 and 10.0. Setting a high downsampling does not have an impact on the final matching position accuracy as matches are fine-tuned on finer image resolutions.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
downsampleFactor |
FLOAT |
1 |
A factor larger than or equal to 1.0. The default value is 8.0. |
Sample
Image.Matching.EdgeMatcher3D.setDownsampleFactor(matcher, downsampleFactor)setEdgeThreshold()
Short description
Sets the edge threshold, i.e., minimal edge strength. The edge strength is calculated as using a local image gradient filter so that smooth edges may generate weak edge responses. The default value is 10. Check with the getModelPoints() or the getModelContours() function the edges that are obtained. Image world coordinate system handling: The edge threshold is interpreted in the image world coordinate system, i.e., typically in millimeters. The threshold is converted internally to a raw pixel value threshold using the z-origin and z-pixelsize of the image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
threshold |
FLOAT |
1 |
Edge threshold interpreted in the image world coordinate system. The default value is 10 for EdgeMatcher3D. |
Sample
Image.Matching.EdgeMatcher3D.setEdgeThreshold(matcher, threshold)setFindTiltHeight()
Short description
Flags to find the tilt and/or height of objects relative to the teach pose. Depending on the application, one may for example know that the tilt and or height is always the same as for the teach object. If so, turn off the estimation of these parameters for increased speed and robustness. If tilt-search is on, height-search is turned on automatically. Setting this parameter will invalidate any previous teach call. The maximum tilt angle the algorithm can find is about 10 - 15 degrees relative to the teach pose, for higher tilts the algorithm may not match robustly.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
findTilt |
BOOL |
1 |
Set to true to find tilt of matched objects. Default is true. |
findHeight |
BOOL |
1 |
Set to true to find height of matched objects. Default is true. |
Sample
Image.Matching.EdgeMatcher3D.setFindTiltHeight(matcher, findTilt, findHeight)setFineSearchIterations()
Short description
Sets the fine search number of iterations. A lower value will increase the speed but might reduce the matching robustness.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
fineSearchIterations |
INT |
1 |
The number of fine search iterations, it must be a positive integer number. The default value is 1. |
Sample
Image.Matching.EdgeMatcher3D.setFineSearchIterations(matcher, 2)setMaxMatches()
Short description
Sets the maximum number of objects to find in a match call. Note that the actual number found can be smaller than this number. This parameter can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
matchCount |
INT |
1 |
An integer larger than or equal to 1 specifying the maximum number of objects to find. Maximum number is 100. The default value is 1. |
Sample
Image.Matching.EdgeMatcher3D.setMaxMatches(matcher, matchCount)setMinSeparation()
Short description
Sets the minimum separation in the (x,y)-dimension between the centers of object matches. This parameter only has effect if the number of matches to find is larger than 1. This parameter can be updated in a teached matcher without re-teaching. Image world coordinate system handling: The unit is in image world units (typically millimeters) taking the image (x,y)-pixelsizes into account.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
minSeparation |
FLOAT |
1 |
The minimum separation between the centers of two objects in image world units. The default value is 50. |
Sample
Image.Matching.EdgeMatcher3D.setMinSeparation(matcher, minSeparation)setPerformFineSearch()
Short description
Set if the fine search should be performed. The default is true. Disabling the fine search may reduce the runtime of the matcher in cases where accurate positioning is not required. In order to obtain fast matching, the downsampling factor should be set as high as possible while turning off scale and rotation search.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
performFineSearch |
BOOL |
1 |
Set to true to perform a coarse followed by a fine search. If set to false only a coarse search is performed. |
Sample
Image.Matching.EdgeMatcher3D.setPerformFineSearch(matcher, performFineSearch)setProcessingUnit()
Short description
Sets processing unit for the calculations. Some devices support FPGA acceleration of the EdgeMatcher3D. If this is the case the FPGA acceleration is set by default when the EdgeMatcher3D object is created. This parameter can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
processingUnit |
1 |
Which type of processing unit to use. If there is FPGA support in the device it will be used as default, otherwise CPU. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
? |
True if processing unit choice was successfully set. False if the chosen processing unit is not supported. |
Sample
Image.Matching.EdgeMatcher3D.setProcessingUnit(matcher, "FPGA")setReferenceHeight()
Short description
Sets a reference height for missing data handling. This value is used to replace missing data pixels within the algorithm. Use the height of the floor, belt or any other application-dependent height. Setting this parameter is mandatory if the input images have the missing data flag on. If missing data has been removed before calling the EdgeMatcher3D, this parameter has no effect. This parameter can be updated in a teached matcher without re-teaching. A suggested reference height can be obtained using the proposeReferenceHeight()-function. Image world coordinate system handling: The reference height is interpreted in the image world coordinate system, typically in millimeters, considering the z-origin and z-pixelsize of the image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The matcher instance to use. |
referenceHeight |
FLOAT |
1 |
Reference height specified in world units, e.g., millimeters. |
Sample
Image.Matching.EdgeMatcher3D.setReferenceHeight(matcher, referenceHeight)setRotationRange()
Short description
Sets rotation interval around the z-axis to search in relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. This parameter can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
rotationRad |
FLOAT |
1 |
Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI. |
Sample
Image.Matching.EdgeMatcher3D.setRotationRange(matcher, rotationRad)setTileCount()
Short description
Set into how many tile images the match image should be split into. This can decrease the minimum downsampling factor and/or the maximum image size, when FPGA processing is used. 0 gives automatic selection, using the minimum number of image tiles required to support the selected downsampling factor. 1 disables tiling.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
tileCount |
INT |
1 |
Number of tile images to split into. 0 gives automatic selection. 1 disables tiling. Default: 0. |
Sample
Image.Matching.EdgeMatcher3D.setTileCount(matcher, tileCount)setTimeout()
Short description
Abort the match call if the match time exceeds a user-defined number of seconds. The main purpose is to protect against excessively long execution times, the granularity does not allow exact abortion at the given timeout parameter. This parameter can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
timeoutSeconds |
FLOAT |
1 |
Time in seconds after which the algorithm should abort. The default value is 5 seconds. |
Sample
Image.Matching.EdgeMatcher3D.setTimeout(matcher, timeoutSeconds)teach()
Short description
Teaches an object model from edges in an image. It is important to set the edge strength threshold properly for this to work. Graphical feedback from the teach process is obtained through the getModelPoints() or getModelContours() functions. The teach procedure extracts both edge information and planar patches within the teach region. The latter are used to estimate tilt and height parameters in match. Image world coordinate system handling: The two parameters zMin and zMax specify the range interval of the teach region. The parameters are interpreted in image world units, typically millimeters, taking the z-origin and z-pixelsize of the input image into account. The status code indicates what happened during the call and may be set to any of the following values: * 0: Teaching was successful. * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 110: Timeout, teaching was aborted. Check the set time limit. * 120: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 130: Region error, something was wrong with the teach region. * 150: Reference plane error, something was wrong with the reference height for missing data. * 160: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy. * 170: Model edge error, too few model edges were found. Check the edge threshold, the input image and that the teach region covers the object of interest. * 180: Model plane error, too few planar probes were found. See status code 170.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use |
teachImage |
1 |
The teach image or image pyramid. |
|
teachRegion |
CONST_AUTO |
1 |
A pixel region or a closed 2D shape defining where to extract edges, this should include the object to be located. |
zMin |
FLOAT |
? |
Optional minimum value for z heights in world units (millimeters). Only edges and planar points above this level are included in the model. If not set, a large negative number is used as default. |
zMax |
FLOAT |
? |
Optional maximum value for z heights in world units (millimeters). Only edges and planar points below this level are included in the model. If not set, a large positive number is used as default. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
teachPoseTransform |
? |
Pose transform of the object model, or nil if unsuccessful. |
|
status |
INT |
? |
A status code indicating what happened during the call. |
Sample
teachPoseTransform, status = Image.Matching.EdgeMatcher3D.teach(matcher, teachImage, teachRegion, zMin, zMax)toString()
Short description
Returns a human readable description of the matcher, including parameters.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
description |
STRING |
1 |
A description of the matcher object. |
Sample
description = Image.Matching.EdgeMatcher3D.toString(matcher)Image.Matching.PatternMatcher
Short description
Finds an object in an image based on its pixel pattern. Teach the object from a reference image and call match to find the location of the same object in a live image. The PatternMatcher primarily searches for translated and rotated objects. Search in scale can be activated. Results are given in pose transforms which describe how the object model is transformed to matched positions in the live image. Each match gets a score between 0.0 and 1.0 where 1.0 means a perfect match. The PatternMatcher is often used together with the Fixture object that facilitates local coordinate transforms based on the result of the PatternMatcher. The most important parameters for the PatternMatcher are the following: - Downsample factor: The PatternMatcher works internally on downsampled images for computational performance reasons. The downsample factor is the most important parameter for the speed versus robustness trade-off. A initial choice of downsample factor could be one that generates a downsampled image of size about 150 x 150. That is, if images of size 1024 x 1024 are used, one could start experimenting with a downsample factor of around 7. A warning will be issued during teach if the downsample factor makes the object model too small. - Rotation range: The rotation range parameter should be selected to be as narrow as possible both for computational reasons and for robustness reasons. If it is known that the target object only can appear within a certain rotation interval, make sure to reduce the rotation range search parameter.
Keywords
correlation, matching, pixel, template, locator
Overview
Functions
create()
Short description
Creates a new pattern matcher for 2D object localization.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The new instance. |
Sample
locator = Image.Matching.PatternMatcher.create()getDownsampleFactor()
Short description
Gets the current downsample parameter setting.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
downsampleFactor |
FLOAT |
? |
The current downsample factor. |
Sample
downsampleFactor = Image.Matching.PatternMatcher.getDownsampleFactor(locator)getMaxMatches()
Short description
Gets the current maximum number of objects to find.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matchCount |
INT |
? |
The current maximum number of objects to find. |
Sample
matchCount = Image.Matching.PatternMatcher.getMaxMatches(locator)getMinSeparation()
Short description
Gets the current minimum separation between centers of object matches.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
minSeparation |
FLOAT |
? |
The minimum separation between the centers of two objects in image world units. |
Sample
minSeparation = Image.Matching.PatternMatcher.getMinSeparation(locator)getModelBoundingBox()
Short description
Get a bounding box of the teach object centered on the image world origin. It can be transformed directly by the pose transformations obtained from match to visualize matching results.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
modelBox |
? |
A rectangle Shape representing the bounding box of the teach region, or nil if unsuccessful. |
Sample
modelBox = Image.Matching.PatternMatcher.getModelBoundingBox(locator)getRotationRange()
Short description
Gets the current rotation range parameter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
rotationRad |
FLOAT |
? |
The current rotation range. |
Sample
rotationRad = Image.Matching.PatternMatcher.getRotationRange(locator)getTeachPose()
Short description
Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
teachPose |
? |
Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful. |
Sample
teachPose = Image.Matching.PatternMatcher.getTeachPose(matcher)getTimeout()
Short description
Gets the selected timeout for matching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
timeoutSeconds |
FLOAT |
? |
Time in seconds after which the algorithm will abort. |
Sample
timeoutSeconds = Image.Matching.PatternMatcher.getTimeout(locator)match()
Short description
Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to matched positions in the live image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The matcher instance to use. |
liveImage |
1 |
The live image to find the object in. |
|
searchRegion |
? |
Optional search region in the live image, must be a rectangle. Only the part of the image within the search region is considered by the matcher, it should cover the entire object to be found. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
poseTransforms |
* |
Pose transforms defining the location of each detected object. |
|
matchScores |
FLOAT |
* |
A score between 0.0 and 1.0 for each detected object (high score means good match). |
Sample
transforms, scores = Image.Matching.PatternMatcher.match(locator, liveImage, searchRegion)setDownsampleFactor()
Short description
Sets the downsample factor. Increasing this value will reduce computation time, but also reduce accuracy.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
downsampleFactor |
FLOAT |
1 |
A factor larger than or equal to 1.0. The default value is 16. |
Sample
Image.Matching.PatternMatcher.setDownsampleFactor(locator, 10.0)setEdgeSensitivity()
Short description
Sets sensitivity to edge pixel intensity values used when matching. Sharp edges generate large errors for noisy edge positions, setting a low sensitivity (default) reduces errors due to small edge position variations among objects and typically increases the performance of the matcher.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
edgeSensitivity |
ENUM |
1 |
Sensitivity to edge pixels (e.g.: LOW, HIGH). |
Sample
Image.Matching.PatternMatcher.setEdgeSensitivity(locator, edgeSensitivity)setMaxMatches()
Short description
Sets the maximum number of objects to find in a match call. The actual number of matches found can be smaller than this number. This parameter can be changed without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
matchCount |
INT |
1 |
An integer larger or equal than 1 specifying the maximum number of object to find. |
Sample
Image.Matching.PatternMatcher.setMaxMatches(locator, 3)setMinSeparation()
Short description
Sets the minimum separation between the centers of object matches. The unit is in image world units (typically millimeters) taking the image pixel size into account. For 2D images the pixel size is by default 1.0, in which case the value equals the separation in pixels. This parameter can be changed without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
minSeparation |
FLOAT |
1 |
The minimum separation between the centers of two objects in image world units. The default value is 50. |
Sample
Image.Matching.PatternMatcher.setMinSeparation(locator, 50)setRotationRange()
Short description
Sets the rotation interval to search in, relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
rotationRad |
FLOAT |
1 |
Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI/16. |
Sample
Image.Matching.PatternMatcher.setRotationRange(locator, 3.1415/16)setScaleSearch()
Short description
Activates searching for objects of different scales, from minimalSize to maximalSize. By default, no scale search is active, corresponding to setScaleSearch(1.0, 1.0).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use |
minimalScale |
FLOAT |
1 |
Size of objects relative to teach object, 0.5 searches for objects down to half the size of the teach object. |
maximalScale |
FLOAT |
1 |
Size of objects relative to teach object, 2.0 searches for objects up to double the size of the teach object. |
Sample
Image.Matching.PatternMatcher.setScaleSearch(locator, minimalScale, maximalScale)setTimeout()
Short description
Abort the match call if the match time exceeds a user-defined number of seconds. The default value is 5 seconds. This parameter can be changed without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
timeoutSeconds |
FLOAT |
1 |
Time in seconds after which the algorithm should abort. |
Sample
Image.Matching.PatternMatcher.setTimeout(locator, 10.0)teach()
Short description
Teaches an object model from an image. It is important to set a reasonable downsample factor and the desired rotational range beforehand.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
teachImage |
1 |
The teach image. |
|
teachRegion |
CONST_AUTO |
1 |
A pixel region or closed 2D shape defining which area to consider as containing the object. The locator pattern is extracted from this region. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
teachPoseTransform |
? |
Pose transform of the object model, or nil if unsuccessful. |
Sample
teachPose = Image.Matching.PatternMatcher.teach(locator, teachImage, teachRegion)toString()
Short description
Returns a human readable description of the matcher, including parameters.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The matcher instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
description |
STRING |
? |
A description of the matcher object, or nil on failure. |
Sample
description = Image.Matching.PatternMatcher.toString(handle)Image.Matching.PatternVerifier
Short description
Verifies a pixel value pattern. Create a new instance using the create function, set parameters using the set functions, teach the correct pattern from a reference image and call verify to find the similarity to the taught pattern. The PatternVerifier can tolerate some errors in the given translation, rotation and scale of the pattern to verify, however for large uncertainties, use a matcher object to find the pattern first. By default all tolerances are set to zero. Results are given as similarity scores as well as an image indicating where the differences are. A refined pose is returned.
Keywords
checking, comparison, pixel, verification, correlation
See also
Overview
Functions
create()
Short description
Creates a new pattern verifier for pixel value pattern verification.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The new instance. |
Sample
verifier = Image.Matching.PatternVerifier.create()generateOverlay()
Short description
Generates an overlay PixelRegion by thresholding a difference image. The overlay is transformed to match the latest live image and refined pose.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
differenceImage |
1 |
Difference image to threshold. |
|
threshold |
FLOAT |
1 |
Threshold for difference image, all pixels with values above the threshold will be included in the pixel region. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
overlay |
? |
Overlay pixel region, or nil if unsuccessful. |
Sample
overlay = Image.Matching.PatternVerifier.generateOverlay(verifier, differenceImage, threshold)getModelBoundingBox()
Short description
Get a bounding box of the teach object centered on the image world origin. It can be transformed directly by the pose transformations sent to and obtained from verify to visualize the working area of the verifier.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
modelBox |
? |
A rectangle Shape representing the bounding box of the teach region, or nil if unsuccessful. |
Sample
modelBox = Image.Matching.PatternVerifier.getModelBoundingBox(verifier)setEdgeSensitivity()
Short description
Sets the sensitivity to edge pixel intensity values used when verifying. Sharp edges generate large errors for noisy edge positions, setting a low sensitivity (default) reduces errors due to small edge position variations among objects.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
edgeSensitivity |
ENUM |
1 |
Sensitivity to edge pixels (e.g.: HIGH, LOW). |
Sample
Image.Matching.PatternVerifier.setEdgeSensitivity(verifier, edgeSensitivity)setPositionTolerance()
Short description
Sets how much the position of the pattern may deviate from the pose given to the verify function. Narrowing the translational search range speeds up the verification considerably. The range is given as a distance in world units, allowing the pattern to be translated up to plus/minus the distance along both dimensions.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
translation |
FLOAT |
1 |
Allowed distance in world units. The default tolerance is zero. |
Sample
Image.Matching.PatternVerifier.setPositionTolerance(verifier, 2.0)setRotationTolerance()
Short description
Sets how much the rotation of the pattern may deviate from the pose given to the verify function. Narrowing the rotation search range speeds up the verification considerably. The range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
rotationRad |
FLOAT |
1 |
Angle in radian units, the maximum deviation from the given object orientation to search for. The default tolerance is zero. |
Sample
Image.Matching.PatternVerifier.setRotationTolerance(verifier, 3.1415/16)setScaleTolerance()
Short description
Sets how much the scale of the pattern may deviate from the pose given to the verify function. Narrowing the scale search range speeds up the verification considerably. The range is given as the minimum and maximum size of the pattern, relative to the transformation supplied to the verify function. The default is no scale change tolerance, i.e., setScaleTolerance(1.0, 1.0).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
minimumScale |
FLOAT |
1 |
Minimum relative scale to accept, e.g. setting to 0.9 allows pattern sizes down to 90%. |
maximumScale |
FLOAT |
1 |
Maximum relative scale to accept, e.g. setting to 1.1 allows pattern sizes up to 110%. |
Sample
Image.Matching.PatternVerifier.setScaleTolerance(verifier, 0.9, 1.1)setTimeout()
Short description
Abort the verify call if the verify time exceeds a user-defined number of seconds. The default value is 5 seconds.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
timeoutSeconds |
FLOAT |
1 |
Time in seconds after which the algorithm should abort. |
Sample
Image.Matching.PatternVerifier.setTimeout(verifier, 2.0)teach()
Short description
Teaches a pattern from an image. The returned pose is usually appended to a Fixture related to the main inspected object.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
teachImage |
1 |
The teach image. |
|
teachRegion |
CONST_OBJECT |
1 |
A pixel region defining which area to consider as containing the pattern. The pattern in this area is used for verification. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
teachPoseTransform |
? |
Pose transform of the pattern, or nil if unsuccessful. |
Sample
teachPose = Image.Matching.PatternVerifier.teach(verifier, teachImage, teachRegion)toString()
Short description
Returns a human readable description of the pattern verifier, including parameters.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
description |
STRING |
? |
A description of the verifier, or nil on failure. |
Sample
description = Image.Matching.PatternVerifier.toString(verifier)verify()
Short description
Verifies a pattern by comparing to the teach pattern. A teach call must be made first. Some errors in the pose can be tolerated by setting the respective tolerance values.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
verifier |
HANDLE |
1 |
The instance to use. |
liveImage |
1 |
The live image to verify the pattern in. |
|
pose |
1 |
The pose of the pattern to be verified, usually obtained from a Fixture. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
score |
FLOAT |
? |
A score between 0.0 and 1.0, or nil if unsuccessful. High score means the pattern is similar to the teach pattern. |
differenceImage |
? |
The difference image, indicating where the patterns differ, or nil if unsuccessful. Pixel values close to zero indicate areas where the patterns match. The default image contains the absolute pixel value differences between the live image and the transformed teach pattern. The difference image is sampled in an object-centered coordinate system with the origin in the center of the image, and cropped to the bounding box of the teach pattern. Any indications in the difference image should be transformed using the refinedPose to obtain the corresponding position in the live image. |
|
refinedPose |
? |
The refined pose of the pattern, or nil if unsuccessful. If all tolerances are set to zero, this will be equal to the given pose. |
Sample
score, differenceImage, refinedPose = Image.Matching.PatternVerifier.verify(verifier, liveImage, pose)Image.Matching.PointMatcher
Short description
Finds an object in an image based on feature points. Salient points are found on the reference object and similar points are searched for in the live images. Teach the object from a reference image and call match to find the location of the same object in a live image. The strength of the PointMatcher relative the EdgeMatcher is for objects whose appearance can be described in terms of textured pattern rather than clear edges or contours. The PointMatcher can also easily find large scale or perspective changes which the EdgeMatcher cannot. The outputs from the PointMatcher are a so-called pose transform and a match score. The pose transform is a Transform object which transforms the model points extracted in the teach step to the matched location in the live image. The PointMatcher is often used together with the Fixture object that facilitates local coordinate transforms based on the pose transform. The match score is a number between 0.0 and 1.0 indicating the fraction of model points that have a match in the input image. The most important parameters for the PointMatcher are the following: - Pose type: This parameter tells the PointMatcher which type of appearance change to look for in the match process, e.g., does the object of interest change size relative to the teach object, does the camera position change leading to a perspective change of the imaged object, etc.? Restrict the pose type as much as possible for a more robust matching. By default, the pose type is restricted and must explicitly be set to allow more general pose transforms. See the documentation of the setPoseType-function for more information. - Pose variability: If the object of interest is imaged from very different angles or distances, leading to large perspective or scale changes, set the pose variability to HIGH for more robustness. Otherwise, set the pose variability to LOW for a higher matching speed. Use the setPoseVariability-function to set the pose variability. - Point count: The target number of salient points to extract. Fewer points will make the matching faster, but with too few points the matching will fail. Use setPointCount() to reduce the number of points. - Downsample factor: Tells the PointMatcher to work on a downsampled version of the input image. This can increase speed and in some cases even robustness if the original image is of high-resolution. Setting the downsample factor too high reduces the robustness though as the feature points in the ensuing low resolution image are not distinct enough. - Rotation range: The rotation range narrows the expected rotations relative to the teach pose. This parameter does not affect matching speed but increases robustness as false matches can be rejected. Set this range as narrow as possible but still wide enough to let valid matches through. - Scale range: The scale range narrows the expected scale change to the teach pose. This parameter does not affect matching speed but increases robustness as false matches can be rejected. Set this range as narrow as possible but still wide enough to let valid matches through. Restrictions: - Only uint8 images are accepted. - The PointMatcher can currently only find 1 object instance per image. Image world coordinate system handling: The image (x,y)-pixelsize and origin are considered, all calculations are made in the image world coordinate system. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: The PointMatcher does not accept missing data images, remove missing data first before usage.
Keywords
descriptor, feature point, interest point, keypoint, landmark, matching, object, perspective, locator
Overview
Functions
create()
Short description
Creates a new point matcher for 2D object localization.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The new instance. |
Sample
locator = Image.Matching.PointMatcher.create()getDetectedPoints()
Short description
Fetches two lists with salient points that were detected in the live image during the last match call. Points are returned in world coordinates and are intended to be plotted directly on the live image for graphical feedback. The first list contains all detected points while the second list only contains those points that were matched and found to be geometrically consistent with the corresponding model point under the found pose transformation.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
detectedPointsWorld |
+ |
Detected salient points during the last call to match, may be empty. |
|
matchedPointsWorld |
+ |
Matched points in the last live image, in world coordinates. The matched points are a subset of the detected salient points. |
Sample
detectedPointsWorld, matchedPointsWorld = Image.Matching.PointMatcher.getDetectedPoints(locator)getDetectedPointsInfo()
| This API is experimental |
Short description
Returns deeper information on the points detected in the last live image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
diameter |
FLOAT |
+ |
Diameters of all detected points in last live image. |
angle |
FLOAT |
+ |
Angle of all detected points in last live image. |
score |
FLOAT |
+ |
Scores of all detected points in last live image. |
octave |
INT |
+ |
Octave on which each point was detected. |
Sample
diameter, angle, score, octave = Image.Matching.PointMatcher.getDetectedPointsInfo(locator)getModelPoints()
Short description
Gets the list of salient points detected during the last teach call as a vector of 2D Points. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. A maximum number of points to return may be specified. The default is to return all points. This function is intended for graphical feedback. Note: to control the number of points detected in the image and used when matching, use the setPointCount function.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
maxCount |
INT |
? |
Optional parameter to specify the maximum number of points to return. Default is to return all points. Note that one can obtain fewer points than the value specified here. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
+ |
Salient model points in internal model coordinates, may be empty. |
Sample
points = Image.Matching.PointMatcher.getModelPoints(locator, maxCount)getTeachPose()
Short description
Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
teachPose |
? |
Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful. |
Sample
teachPose = Image.Matching.PointMatcher.getTeachPose(matcher)match()
Short description
Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms with one or zero entries, or nil. An empty vector indicates that no object was found while nil indicates that the matcher encountered an error. The transform describes how the object model is transformed to matched positions in the live image. The optional search region indicates where salient points will be extracted and should include the entire area where the object may appear. By default, the entire image is used. Use getDetectedPoints after match to visualize detected salient points in the live image and salient points matched to the model.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The matcher instance to use. |
liveImage |
1 |
The live image to find the object in. |
|
searchRegion |
? |
Optional search region in the live image, must be a rectangle. Feature points are only extracted within this region, it should cover the entire object to be found. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
poseTransforms |
* |
Pose transform defining the location of any detected object. Note that this is a vector with at most one element/transform for future compatibility when adding multiple matches. |
|
matchScores |
FLOAT |
* |
A score between 0.0 and 1.0 for any detected object (high score means good match). Note that this is a vector with at most one element/score for future compatibility when adding multiple matches. |
inlierRMS |
FLOAT |
* |
The root mean squared error among inlier points in world coordinates (lower is better). Note that this is a vector with at most one element/value for future compatibility when adding multiple matches. |
Sample
poseTransforms, matchScores, inlierRMS = Image.Matching.PointMatcher.match(locator, liveImage, searchRegion)setDownsampleFactor()
Short description
Sets the factor in the x- and y-dimensions for the internal downsampling of the image. Increasing this value will reduce the time required for detecting salient points. A larger downsampling factor may improve results in cases where the image structure is smooth or slightly out of focus. A higher downsampling factor reduces the accuracy of the estimated pose.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. Default is 2.0. |
downsampleFactor |
FLOAT |
1 |
A factor larger than or equal to 1.0. |
Sample
Image.Matching.PointMatcher.setDownsampleFactor(matcher, downsampleFactor)setIterations()
Short description
Sets the maximum number of iterations in the geometrical robust fitting step. Decreasing this parameter makes the geometrical matching faster, however using too small values, good matches may be missed. When a match with high probability of being the correct one is found, fewer iterations may be used. The number of iterations set here is also used to control the probability threshold, where a higher number of iterations corresponds to requiring a higher probability of a correct match before stopping the iteration in advance.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
iterations |
INT |
1 |
Number of iterations, must be larger than one, the default is 5000. |
Sample
Image.Matching.PointMatcher.setIterations(locator, iterations)setOutlierMargin()
Short description
Set the outlier margin in world units, must be greater than zero. The point matcher searches for the transform that is supported by the highest number of salient points. This setting determines how far a transformed model point can be from the corresponding live image point before it is considered an outlier and not supporting the current transform hypothesis. Decreasing this parameter will require the salient points of the template and live images to be geometrically more coherent. A too small value will remove almost all point match candidates, which will reduce object match accuracy significantly.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
margin |
FLOAT |
1 |
Outlier margin in world units, the default is 5.0. |
Sample
Image.Matching.PointMatcher.setOutlierMargin(locator, margin)setPointCount()
Short description
Sets the desired number of salient points to detect in an image. The final number of points may be larger or smaller. The desired number of points is related to the full image. For a part of an image, the number of found points is lower in general.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
desiredPointCount |
INT |
1 |
A larger number generates more keypoints, default 1000. |
Sample
Image.Matching.PointMatcher.setPointCount(locator, desiredPointCount)setPoseType()
Short description
The pose type puts a limit on the generality of pose transforms returned by the match function. In the following list, the first option is the most restrictive and every new type contains all previously listed types as special cases. "RIGID" - Searches for objects whose image appears translated and rotated. The scale range is ignored in this mode. Set rotation range to zero for pure translations. "SIMILARITY" - Searches for objects whose image appears translated, rotated and uniformly scaled. This is the default option. Set rotation range to zero for translation and scaling only. "AFFINE" - Searches for objects whose image appears translated, rotated, non-uniformly scaled and skewed. "HOMOGRAPHY" - This is the most general transform, it allows e.g. out-of-plane rotation for flat objects.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
poseTransformType |
1 |
The type of pose transformation to allow when searching for matching objects. |
Sample
Image.Matching.PointMatcher.setPoseType(locator, poseTransformType)setPoseVariability()
Short description
Set to the expected variability in pose of the objects in the live image. Setting a higher variability will use more robust salient point detectors and descriptors but those will be slower in most cases. In general, try the lowest setting first and change to higher settings if required. "HIGH" - The default value, more robust but also slower in general. "LOW" - Faster in general and should be fine for any rotation, scale changes up to at least 30% and small perspective effects. When using this mode, the image size in pixels must be the same for all images.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
variability |
ENUM |
1 |
The expected pose variability of objects in the live image. |
Sample
Image.Matching.PointMatcher.setPoseVariability(locator, variability)setRotationRange()
Short description
Sets rotation interval to search within, in relation to the teach orientation. The search range is given as a positive angle in radians. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. For the point matcher, the search time is not affected by the rotation range. A too narrow range will remove all tentative matches. If prior orientation information is known, the prior rotation can be set to allow a more narrow search range. The final search range is then up to plus/minus the search range parameter starting from the prior rotation. These parameters can be updated in a teached matcher without re-teaching. When pose type is set to RIGID or SIMILARITY, setting the rotation range to zero will force the matcher to look for pure translations, or translation and scaling only.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
rotationRad |
FLOAT |
1 |
Angle in radians, the maximum deviation from the original object orientation to search for. The default value is PI. Input is silently clamped to the range from 0 to PI. |
priorRotationRad |
FLOAT |
? |
Optional prior orientation in radians. If specified, the orientation search range is centered around this orientation. Default is zero (i.e. same orientation as teach object). |
Sample
Image.Matching.PointMatcher.setRotationRange(matcher, rotationRad)setScaleRange()
Short description
Sets scale interval where objects are expected to appear. Tentative objects with a scale outside the scale range are discarded. Default range is from 0.5 to 2.0, searching for object from half to twice the size of the teach object. For transform types without a specific scale (affine and homogeneous), an approximate apparent scale is used. The scale range is ignored when the matcher is in rigid mode. For the point matcher, the search time is not affected by the scale range. A too narrow range will remove all tentative matches. An optional prior scale can be set, this affects both the minimum and maximum scale (both limits are multiplied with the prior scale). The prior scale accepts a larger range of values than the min and max scale parameters. If the object to find has a fixed non-unit scale relative to the teach object, or if prior information on the scale of the object is available, use the prior scale. The default value is 1.0. By setting both minScale and maxScale to 1.0, scale search is disabled but the prior scale parameter still has effect. These parameters can be updated in a teached matcher without re-teaching.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
matcher |
HANDLE |
1 |
The instance to use. |
minScale |
FLOAT |
1 |
The smallest scale factor to allowed. |
maxScale |
FLOAT |
1 |
The largest scale factor to allowed. |
priorScale |
FLOAT |
? |
Optional prior scale factor. Set to the expected scale of the object to find, relative to the size of the teach object. E.g. 1.25 if the object to find is 25% larger than the teach object. |
Sample
Image.Matching.PointMatcher.setScaleRange(matcher, minScale, maxScale)setTimeout()
Short description
Abort the match call if the match time exceeds a user-defined number of seconds. The default value is 5 seconds.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
timeoutSeconds |
FLOAT |
1 |
Time in seconds after which the algorithm should abort. |
Sample
Image.Matching.PointMatcher.setTimeout(locator, timeoutSeconds)teach()
Short description
Teaches an object model from an image. Use getModelPoints after teach to visualize the detected salient points on the teach object.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
teachImage |
1 |
The teach image. |
|
teachRegion |
CONST_AUTO |
1 |
A pixel region or closed 2D shape defining which area to consider as containing the object. Feature points are extracted from this region. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
teachPoseTransform |
? |
Pose transform of the object model, or nil if unsuccessful. |
Sample
teachPose = Image.Matching.PointMatcher.teach(locator, teachImage, teachRegion)toString()
Short description
Get a user-friendly string description of the matcher. The parameters are the internal parameters of the matcher, call teach for parameter changes to take effect and appear in the description string.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
locator |
HANDLE |
1 |
The instance to use. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
description |
STRING |
? |
User-friendly description of the matcher. |
Sample
description = Image.Matching.PointMatcher.toString(locator)Image.MultiStereo
Short description
Object for creating 3D point clouds using one or more stereo pairs.
Keywords
active stereo, disparity, epipolar, laser, structured light, triangulation, reconstruction
See also
Image.MultiStereo.BlockMatching
Short description
Block matching stereo object. The block matching multi stereo method is used to generate point clouds from one (regular stereo) or more stereo pairs. It can use a random dot laser that projects laser dots into the scene (recommended, but not necessary if the scene has enough structure). A dense 3D reconstruction can be obtained; all image pixels are tested for a possible match. It is only supported horizontal or vertical stereo, i.e. the cameras must be displaced mainly in the horizontal or vertical directions. A region of interest box must be specified and the objects to be reconstructed should be inside it (only 3D points inside the box will be generated). Due to the dense nature of the method it is typically necessary to reduce the images resolution before using it. For stereo matching, a pixelwise cost (based on the pixels of the blocks) and a smoothness constraint are used. They are combined and expressed as an energy function that is optimized (semiglobal optimization) to find the best match. Both the pixelwise cost and the smoothness constrains require data from the blocks to compute their values, in addition the smoothness constraint also requires smoothness parameters to control its behavior. After the optimization the best matches are selected and triangulated to obtain the 3D points.
Keywords
active stereo, disparity, epipolar, laser, reconstruction, semiglobal, structured light, triangulation, sparse
See also
Overview
Functions
addCameraPair()
Short description
Using two input camera models containing both intrinsic and extrinsic parameters this function calculates the look up tables for fast rectification and new rectified camera models. The output is a stereo pair id. To retrieve the newly calculated camera models the function getCameraModels can be used. Returns nil if the camera models are incompatible.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
The MultiStereo instance to use. |
|
firstCameraModel |
OBJECT |
1 |
Input camera model object containing the camera calibration of the first camera. |
secondCameraModel |
OBJECT |
1 |
Input camera model object containing the camera calibration of the second camera. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pairID |
INT |
? |
The corresponding id for the stereo pair. Returns nil if the camera models are incompatible. |
Sample
local pairID = Image.MultiStereo.BlockMatching.addCameraPair(ms, firstCameraModel, secondCameraModel)calculate()
Short description
Calculates the point cloud. The stereo camera models (addCameraPair), images (setImagePair) and roi (setRoiBox) must be set before using this function or else the method will return nil
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
The MultiStereo instance to use. |
|
pointcloudIntensity |
ENUM |
? |
How to attribute the intensity of the point cloud points. |
pairID |
INT |
? |
The stereo pair id. If omitted the point clouds of all stereo pairs are calculated. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pointCloud |
OBJECT |
? |
The estimated point cloud. |
Sample
local pointCloud = Image.MultiStereo.BlockMatching.calculate(ms, pointcloudIntensity, pairID)create()
Short description
Creates a new instance of a multistereo block matching object.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
The new instance. |
Sample
local ms = Image.MultiStereo.BlockMatching.create()getCameraModels()
Short description
Retrieves the rectified camera models corresponding to the camera pair with id 'pairID'. Returns nil if the pairID is not valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
The MultiStereo instance to use. |
|
pairID |
INT |
1 |
The id for the stereo pair. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
firstCameraModelRectified |
OBJECT |
? |
Rectified camera model object corresponding to the firstCameraModel (see addCameraPair). |
secondCameraModelRectified |
OBJECT |
? |
Rectified camera model object corresponding to the secondCameraModel (see addCameraPair). |
Sample
local firstCameraModelRectified, secondCameraModelRectified = Image.MultiStereo.BlockMatching.getCameraModels(ms, pairID)getRectifiedImages()
Short description
Retrieves the rectified images corresponding to the camera pair with id 'pairID'. These are typically used for visual inspection that the rectification was correct. Returns nil if the pairID is not valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
The MultiStereo instance to use. |
|
pairID |
INT |
1 |
The stereo pair id. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
firstImageRectified |
? |
Rectified image corresponding to the firstImage (see setImagePair). |
|
secondImageRectified |
? |
Rectified image corresponding to the secondImage (see setImagePair). |
Sample
local firstImageRectified, secondImageRectified = Image.MultiStereo.BlockMatching.getRectifiedImages(ms, pairID)getRelativeTransform()
Short description
Get the relative transformation of the stereo pair cameras. Refer to the corresponding set function for more details. Returns nil if the pairID is not valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
The MultiStereo instance to use. |
|
pairID |
INT |
1 |
The stereo pair id. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
camerasRelativeTransform |
? |
The relative transformation applied to the camera pair. By default the relative transformation matrix is the identity matrix. |
Sample
local camerasRelativeTransform = Image.MultiStereo.BlockMatching.getRelativeTransform(ms, pairID)proposeRoiBox()
Short description
Returns a suggestion for a region of interest bounding box. The box will be axis aligned and placed in the world zero plane. The returned box might need tuning to get optimal results. Typically the stereo cameras should be placed at least 50 cm from the calibration pattern plane, looking towards the pattern. If the cameras are not oriented towards the same objects or the distance to the ground plane is less than 30 cm it will not be possible to propose a box in this case nil will be returned.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ms |
1 |
The MultiStereo instance to use. |
|
pairID |
INT |
? |
Optional pair id. If omitted pair 0 will be used. |
height |
FLOAT |
? |
Optional box height. If omitted a box from the base plane to 30 cm from the lowest camera will be created. |
padding |
FLOAT |
? |
Optional box padding. This will make the box slightly wider and longer, control height with the height parameter. |
Sample
local roiBox = Image.MultiStereo.BlockMatching.proposeRoiBox(ms)setImagePair()
Short description
Updates the input images corresponding to the camera pair with id 'pairID'. It also stereo rectifies the input images using the look up tables computed using the function addCameraPair. To retrieve the rectified images of a specific stereo pair the function getRectifiedImages can be used. Returns false if the stereo images are incompatible and if they are incompatible with the camera models.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
The MultiStereo instance to use. |
|
firstImage |
1 |
Input image corresponding to the first image of the stereo pair |
|
secondImage |
1 |
Input image corresponding to the second image of the stereo pair. |
|
pairID |
INT |
1 |
The stereo pair id. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successful. |
Sample
local success = Image.MultiStereo.BlockMatching.setImagePair(ms, firstImage, secondImage, pairID)setRelativeTransform()
Short description
A relative transformation is concatenated to the camera poses of a stereo pair (2 cameras). In matrix format the transformation is: newCameraWorldMatrix = originalCameraWorldMatrix * cameraRelativeTransformMatrix. One example application that can benefit from using a relative transformation is when the cameras are rigidly attached to a robot. The robot can provide the relative transformation between the original and the current pose and this value can be used as the cameraRelativeTransform parameter without the need to recalibrate the stereo pair. Please note: for the changes to take effect this function must be called after the addCameraPair function or else the new pairs will have the default values. Returns false if the pairID is not valid or the transformation is not rigid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
The MultiStereo instance to use. |
|
camerasRelativeTransform |
1 |
The relative transformation applied to the camera pair. By default the relative transformation matrix is the identity matrix. |
|
pairID |
INT |
? |
The stereo pair id. If omitted the same relative transformation will be used by all stereo pairs. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successful. |
Sample
local success = Image.MultiStereo.BlockMatching.setRelativeTransform(ms, camerasRelativeTransform, pairID)setRoiBox()
Short description
Set the region of interest (a 3D box shape). The reconstructed objects should be contained in the box. It is mandatory that the roi box is specified. The roi is used for two purposes, first: to compute the minimum and maximum disparities that will be used by the stereo matching methods and second: so that only 3D points inside the roi are computed. The roi specification has a great impact on the speed and accuracy of the 3D reconstruction, for example if the roi is larger than it should be the disparity range will increase and with it the stereo matching ambiguity (more possible matches). The roi is specified in the world coordinate system. It is not allowed that the camera positions are inside the roi, in this case the method will return false. It will also return false if the cameras are not oriented towards the roi, i.e. the cameras frustum do not overlap the roi. If the box transformation is the identity, it will be aligned with the world coordinate system axis (obtained using the calibration pattern) and centered at the origin. Typically, a translation in the z direction is applied in order for the roi box base plane to be slightly below the ground plane. The proposed approach to set the roi for a pallet is: first measure the width, length and height of the pallet, slightly larger values should be used to create the roi box object. Rotate the roi (e.g. a rotation around the z axis) to align its axes with the pallet axes and finally translate for the final adjustment. The last rotation and translation are specified using a transform object. Alternatively, you can use the proposeRoiBox method to obtain an initial roi box. In the case that two roi boxes are needed two Multistereo objects must be created. For the corresponding two point clouds to be aligned, the extrinsic calibration must be performed equally for both Multistereo instances, i.e. using the same calibration pattern with a fixed position.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
The MultiStereo instance to use. |
|
roiBox |
1 |
The 3D roi box. The box is a 3D shape object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successful. |
Sample
success = Image.MultiStereo.BlockMatching.setRoiBox(ms, roiBox)Image.MultiStereo.RandomDot
Short description
Random dot stereo object. The random dot multi stereo method is used to generate point clouds from one (regular stereo) or more stereo pairs. It uses a random dot laser that projects laser dots into the scene. Only the 3D points at the centers of the laser dots are reconstructed. It is only supported horizontal or vertical stereo, i.e. the cameras must be displaced mainly in the horizontal or vertical directions. A region of interest box must be specified and the objects to be reconstructed should be inside it (only 3D points inside the box will be generated). For stereo matching, epipolar constraints are used i.e. for horizontal stereo corresponding points in the rectified images must have the same rows and for vertical stereo the same columns. If a poor calibration was performed, the epipolar tolerance (the pixel distance from the epipolar line) needs to be increased in order to obtain a complete 3D scene reconstruction. The tolerance increase will impact the quality of the reconstruction (the matching ambiguity is higher) and how fast the results can be computed (more possible matches to be tested). The centers of the dots are calculated in the rectified images, resulting in a subpixel vector of 2D points. This operation might have some localization error, for this reason the effective epipolar tolerance is the specified epipolar tolerance plus the laser dot radius. For the possible matches that pass the initial epipolar constraint another geometrical constraint is applied and an initial matching score is calculated. This constraint relies on the neighboring points (10 closest neighbors) to the point currently being tested. The idea is that the angles and distances between a possible match point in the first image and its neighbors is similar to its counterpart in the second image. The matching score will be higher if more angles and distances are similar between the two images. Next, a regularization step is applied to improve the matching score and finally the best matches are selected and triangulated to obtain the 3D points.
Keywords
active stereo, disparity, epipolar, laser, reconstruction, structured light, triangulation, sparse
See also
Overview
Functions
addCameraPair()
Short description
Using two input camera models containing both intrinsic and extrinsic parameters this function calculates the look up tables for fast rectification and new rectified camera models. The output is a stereo pair id. To retrieve the newly calculated camera models the function getCameraModels can be used. Returns nil if the camera models are incompatible.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
firstCameraModel |
OBJECT |
1 |
Input camera model object containing the camera calibration of the first camera. |
secondCameraModel |
OBJECT |
1 |
Input camera model object containing the camera calibration of the second camera. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pairID |
INT |
? |
The corresponding id for the stereo pair. |
Sample
local pairID = Image.MultiStereo.RandomDot.addCameraPair(ms, firstCameraModel, secondCameraModel)calculate()
Short description
Calculates the point cloud. The stereo camera models (addCameraPair), images (setImagePair) and roi (setRoiBox) must be set before using this function or else the method will return nil.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
pointcloudIntensity |
ENUM |
? |
How to attribute the intensity of the point cloud points. |
pairID |
INT |
? |
The stereo pair id. If omitted the point clouds of all stereo pairs are calculated. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pointCloud |
OBJECT |
? |
The estimated point cloud. |
Sample
local pointCloud = Image.MultiStereo.RandomDot.calculate(ms, pointcloudIntensity, pairID)create()
Short description
Creates a new instance of a multistereo randomDot object.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The new instance. |
Sample
local ms = Image.MultiStereo.RandomDot.create()getCameraModels()
Short description
Retrieves the rectified camera models corresponding to the camera pair with id 'pairID'. Returns nil if the pairID is not valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
pairID |
INT |
1 |
The stereo pair id. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
firstCameraModelRectified |
OBJECT |
? |
Rectified camera model object corresponding to the firstCameraModel (see addCameraPair). |
secondCameraModelRectified |
OBJECT |
? |
Rectified camera model object corresponding to the secondCameraModelRectified (see addCameraPair). |
Sample
local firstCameraModelRectified, secondCameraModelRectified = Image.MultiStereo.RandomDot.getCameraModels(ms, pairID)getEpipolarlineTolerance()
Short description
Get the epipolar line tolerance. Refer to the corresponding set function for more details. Returns nil if the pairID is not valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
pairID |
INT |
1 |
The stereo pair id. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
epipolarlineTolerance |
INT |
? |
The epipolar line tolerance, in pixels. |
Sample
local epipolarlineTolerance = Image.MultiStereo.RandomDot.getEpipolarlineTolerance(ms, pairID)getPatternProperties()
Short description
Get the random dot laser pattern properties. Refer to the corresponding set function for more details. Returns nil if the pairID is not valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
pairID |
INT |
1 |
The stereo pair id. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
dotRadius |
INT |
? |
The laser dots radius, in pixels. |
dotDistance |
INT |
? |
The distance between the laser dots, in pixels. |
Sample
local dotRadius, dotDistance = Image.MultiStereo.RandomDot.getPatternProperties(ms, pairID)getRectifiedImages()
Short description
Retrieves the rectified images corresponding to the camera pair with id 'pairID'. These are typically used for visual inspection that the rectification was correct. Returns nil if the pairID is not valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
pairID |
INT |
1 |
The stereo pair id. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
firstImageRectified |
? |
Rectified image corresponding to the firstImage (see setImagePair). |
|
secondImageRectified |
? |
Rectified image corresponding to the secondImage (see setImagePair). |
Sample
local firstImageRectified, secondImageRectified = Image.MultiStereo.RandomDot.getRectifiedImages(ms, pairID)getRelativeTransform()
Short description
Get the relative transformation of the stereo pair cameras. Refer to the corresponding set function for more details. Returns nil if the pairID is not valid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
pairID |
INT |
1 |
The stereo pair id. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
camerasRelativeTransform |
? |
The relative transformation applied to the camera pair. By default the relative transformation matrix is the identity matrix. |
Sample
local camerasRelativeTransform = Image.MultiStereo.RandomDot.getRelativeTransform(ms, pairID)proposeRoiBox()
Short description
Returns a suggestion for a region of interest bounding box. The box will be axis aligned and placed in the world zero plane. The returned box might need tuning to get optimal results. Typically the stereo cameras should be placed at least 50 cm from the calibration pattern plane, looking towards the pattern. If the cameras are not oriented towards the same objects or the distance to the ground plane is less than 30 cm it will not be possible to propose a box in this case nil will be returned.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ms |
HANDLE |
1 |
The MultiStereo instance to use. |
pairId |
INT |
? |
Optional pair id. If omitted pair 0 will be used. |
height |
FLOAT |
? |
Optional box height. If omitted a box from the base plane to 30 cm from the lowest camera will be created. |
padding |
FLOAT |
? |
Optional box padding. This will make the box slightly wider and longer, control height with the height parameter. |
Sample
local roiBox = Image.MultiStereo.RandomDot.proposeRoiBox(ms)setEpipolarlineTolerance()
Short description
Set the epipolar line tolerance. The stereo matching algorithm uses rectified images, computed using epipolar geometry. These geometrical constraints guarantee that a possible match of a point in the first image corresponds to a line in the second image. Using rectified images with horizontal stereo the rows of the points to be matched should be the same and in vertical stereo the columns should be the same. If a poor calibration was performed, the epipolar tolerance (the pixel distance from the epipolar line) needs to be increased in order to obtain a complete 3D scene reconstruction. The tolerance increase will impact the quality of the reconstruction (the matching ambiguity is higher) and how fast the results can be computed (more possible matches to be tested). Please note: for the changes to take effect this function must be called after the addCameraPair function or else the new pairs will have the default values. Returns false if the pairID is not valid or the value is not in the correct range.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
epipolarlineTolerance |
INT |
1 |
The epipolar line tolerance, in pixels. The default value is 5 pixels. |
pairID |
INT |
? |
The stereo pair id. If omitted set the value for all pairs. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successful. |
Sample
success = Image.MultiStereo.RandomDot.setEpipolarlineTolerance(ms, epipolarlineTolerance, pairID)setImagePair()
Short description
Updates the input images corresponding to the camera pair with id 'pairID'. It also stereo rectifies the input images using the look up tables computed using the function addCameraPair. To retrieve the rectified images of a specific stereo pair the function getRectifiedImages can be used. Returns false if the stereo images are incompatible and if they are incompatible with the camera models.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
firstImage |
1 |
Input image corresponding to the first image of the stereo pair. |
|
secondImage |
1 |
Input image corresponding to the second image of the stereo pair. |
|
pairID |
INT |
1 |
The stereo pair id. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successful. |
Sample
local success = Image.MultiStereo.RandomDot.setImagePair(ms, firstImage, secondImage, pairID)setPatternProperties()
Short description
Set the random dot laser pattern properties. The pattern is composed of approximately circular laser dots that have a specific radius and are placed randomly in relation to each other with an approximate similar distance between them. With this function it is possible to specify these properties, i.e. the dots radius and distance. Their values are in pixels and can be obtained by examining the rectified images. Typically, some tuning is necessary to optimize the result. Please note: for the changes to take effect this function must be called after the addCameraPair function or else the new pairs will have the default values. Returns false if the pairID is not valid or the values are not in the correct range.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
dotRadius |
INT |
1 |
The laser dots radius, in pixels. The default value is 5 pixels. |
dotDistance |
INT |
1 |
The distance between the laser dots, in pixels. The default value is 10 pixels. |
pairID |
INT |
? |
The stereo pair id. If omitted set the values in all pairs. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successful. |
Sample
local success = Image.MultiStereo.RandomDot.setPatternProperties(ms, dotRadius, dotDistance, pairID)setRelativeTransform()
Short description
A relative transformation is concatenated to the camera poses of a stereo pair (both cameras). In matrix format the transformation is: newCameraWorldMatrix = originalCameraWorldMatrix * cameraRelativeTransformMatrix. One example application that can benefit from using a relative transformation is when the cameras are rigidly attached to a robot. The robot can provide the relative transformation between the original and the current pose and this value can be used as the cameraRelativeTransform parameter without the need to recalibrate the stereo pair. Please note: for the changes to take effect this function must be called after the addCameraPair function or else the new pairs will have the default values. Returns false if the pairID is not valid or the transformation is not rigid.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
camerasRelativeTransform |
1 |
The relative transformation applied to the camera pair. By default the relative transformation matrix is the identity matrix. |
|
pairID |
INT |
? |
The stereo pair id. If omitted the same relative transformation will be used by all stereo pairs. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successful. |
Sample
success = Image.MultiStereo.RandomDot.setRelativeTransform(ms, camerasRelativeTransform, pairID)setRoiBox()
Short description
Set the region of interest (a 3D box shape). The reconstructed objects should be contained in the box. It is mandatory that the roi box is specified. The roi is used for two purposes, first: to compute the minimum and maximum disparities that will be used by the stereo matching methods and second: so that only 3D points inside the roi are computed. The roi specification has a great impact on the speed and accuracy of the 3D reconstruction, for example if the roi is larger than it should be the disparity range will increase and with it the stereo matching ambiguity (more possible matches). The roi is specified in the world coordinate system. It is not allowed that the camera positions are inside the roi, in this case the method will return false. It will also return false if the cameras are not oriented towards the roi, i.e. the cameras frustum do not overlap the roi. If the box transformation is the identity, it will be aligned with the world coordinate system axis (obtained using the calibration pattern) and centered at the origin. Typically, a translation in the z direction is applied in order for the roi box base plane to be slightly below the ground plane. The proposed approach to set the roi for a pallet is: first measure the width, length and height of the pallet, slightly larger values should be used to create the roi box object. Rotate the roi (e.g. a rotation around the z axis) to align its axes with the pallet axes and finally translate for the final adjustment. The last rotation and translation are specified using a transform object. Alternatively, you can use the proposeRoiBox method to obtain an initial roi box. In the case that two roi boxes are needed two Multistereo objects must be created. For the corresponding two point clouds to be aligned, the extrinsic calibration must be performed equally for both Multistereo instances, i.e. using the same calibration pattern with a fixed position.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The MultiStereo instance to use. |
roiBox |
1 |
The 3D roi box. The box is a 3D shape object. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if successful. The box is a 3D shape object. |
Sample
local success = Image.MultiStereo.RandomDot.setRoiBox(ms, roiBox)Image.NormalEstimation
Short description
Functions for converting height maps to images with representations of the normal direction.
Keywords
conversion, derivative, direction, shape, normals
Overview
Functions
apply()
Short description
Converts an input image to a new representation. The output type and mode should be set before calling this function. Missing data handling: The conversion functions automatically handle missing data. Different degrees of missing data infill will occur depending on settings. World coordinate system handling: The input image world coordinates are respected. The output image copies the X and Y coordinate system of the input image, but always have origin zero and pixel size 1 for the Z-axis Z. The raw values along the Z axis are normalized with respect to the configured input range (see setRangeX/Y/Z) and is between 0 and 1 for float, or 0 and 255 for UINT8/RGB24 output types.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
OBJECT |
1 |
The normal estimation object. |
image |
1 |
The image to convert. |
|
outputRef |
? |
Pre-allocated image that can be re-used. Will be faster for large images. Must be of the right type, will be re-allocated if not. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
output |
? |
The converted image of type UINT8, FLOAT32 or RGB24. Nil on failure. |
Sample (auto-generated)
output = Image.NormalEstimation.apply(ne, image, outputRef)create()
Short description
Creates a new normal estimation object.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
HANDLE |
1 |
The new instance. |
Sample (auto-generated)
ne = Image.NormalEstimation.create()setCentralDifference()
Short description
Use central difference to estimate the tilt of the surface in each point. This mode only supports implicit missing data reduction. If the central difference kernel has support it will give a direction estimate even if the underlying point was missing, this behavior cannot be configured. In general, the tilt of the surface will be less precise than the other options and is only recommended in cases where speed is most important, or the central difference is the best way to estimate the surface.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
OBJECT |
1 |
The normal estimation object. |
dx |
INT |
? |
The step length of the central difference in pixels. Default is 1. |
dy |
INT |
? |
The step length of the central difference in pixels in the vertical direction. If unset dx is used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if mode was successfully selected |
Sample (auto-generated)
success = Image.NormalEstimation.setCentralDifference(ne, dx, dy)setGaussian()
Short description
Use a Gaussian derivative kernel to estimate the tilt of surfaces in each point. Can be configured to reduce missing data by a smoothing operation orthogonal to the derivative direction. The sigma should be given relative to the pixel grid and not in world coordinates. Selecting a sigma will generate a kernel such that the tails of the Gaussian are low at the edges.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
OBJECT |
1 |
The normal estimation object. |
smoothOrthogonal |
BOOL |
1 |
Decide if a smoothing kernel should be applied orthogonal to the derivative direction. This has a filling effect on missing data. |
sigmaX |
FLOAT |
? |
The standard deviation of the Gaussian kernel in pixel coordinates. Default is 1.2. |
sigmaY |
FLOAT |
? |
The standard deviation of the Gaussian kernel in pixel coordinates in the Y-direction. If unset sigmaX is used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if mode was successfully selected |
Sample (auto-generated)
success = Image.NormalEstimation.setGaussian(ne, smoothOrthogonal, sigmaX, sigmaY)setMissingDataValue()
Short description
Configure how to represent missing values in the converted images. Default is set them as if all vectors had equal length. For FLOAT32 this means a value of 1/sqrt(3), converted to UINT8 the value becomes 127.5 + 127.5 * 1/sqrt(3) = 201. Provide the value normalized to the range -1 to 1, where -1 corresponds to the lowest representable value for the output type and 1 the highest.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
OBJECT |
1 |
The normal estimation object. |
missingValue |
FLOAT |
? |
The value used for missing pixels. Default is 1/sqrt(3). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the value was successfully set. |
Sample (auto-generated)
success = Image.NormalEstimation.setMissingDataValue(ne, missingValue)setOutputType()
Short description
Configure what output to compute. There are mainly two output types; X, Y, Z normal values represented as an RGB image or only the Z component represented either as a FLOAT32 or UINT8 image. The UINT8 values are converted from the normalized vector representation to the range 0-255 by rescaling and clamping. The following operation: Vu = max(0, min(Vf*127.5 + 127.5, 255)), is applied. I.e. for an RGB output the result is (R, G, B) = (Nx * 127.5 + 127.5, Ny * 127.5 + 127.5, Nz * 127.5 + 127.5).
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
OBJECT |
1 |
The normal estimation object. |
mode |
1 |
The output to get. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if mode was successfully selected. |
Sample (auto-generated)
success = Image.NormalEstimation.setOutputType(ne, mode)setRangeX()
Short description
Select how to use the available data range of the X component (red) for the quantized output type RGB24. The default range is -1 to 1, meaning that a normal with coefficient -1 corresponds to 0 and 1 to 255. If the range is set to 0 to 1, the normal with coefficient 0 corresponds to 0 and 1 to 255, meaning that negative normal coefficients are clamped to zero.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
OBJECT |
1 |
The normal estimation object. |
min |
FLOAT |
? |
The lowest value to represent, equal to 0 in the output. Defaults to -1 if unset. |
max |
FLOAT |
? |
The highest value to represent, equal to 255 in the output. Defaults to 1 if unset. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the range was successfully set. |
Sample (auto-generated)
success = Image.NormalEstimation.setRangeX(ne, min, max)setRangeY()
Short description
Select how to use the available data range of the Y component (green) for the quantized output type RGB24. The default range is -1 to 1, meaning that a normal with coefficient -1 corresponds to 0 and 1 to 255. If the range is set to 0 to 1, the normal with coefficient 0 corresponds to 0 and 1 to 255, meaning that negative normal coefficients are clamped to zero.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
OBJECT |
1 |
The normal estimation object. |
min |
FLOAT |
? |
The lowest value to represent, equal to 0 in the output. Defaults to -1 if unset. |
max |
FLOAT |
? |
The highest value to represent, equal to 255 in the output. Defaults to 1 if unset. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the range was successfully set. |
Sample (auto-generated)
success = Image.NormalEstimation.setRangeY(ne, min, max)setRangeZ()
Short description
Select how to use the available data range of the quantized output types, UINT8 and RGB24. The default range is -1 to 1, meaning that a normal with coefficient -1 corresponds to 0 and 1 to 255. If the range is set to 0 to 1, the normal with coefficient 0 corresponds to 0 and 1 to 255, meaning that negative normal coefficients are clamped to zero.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
OBJECT |
1 |
The normal estimation object. |
min |
FLOAT |
? |
The lowest value to represent, equal to 0 in the output. Defaults to -1 if unset. |
max |
FLOAT |
? |
The highest value to represent, equal to 255 in the output. Defaults to 1 if unset. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the range was successfully set. |
Sample (auto-generated)
success = Image.NormalEstimation.setRangeZ(ne, min, max)setScharr()
Short description
Use a Scharr filter to estimate the tilt of surfaces in each point. Can be configured to reduce missing data by a smoothing operation orthogonal to the derivative direction.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
ne |
OBJECT |
1 |
The normal estimation object. |
smoothOrthogonal |
BOOL |
1 |
Decide if a smoothing kernel should be applied orthogonal to the derivative direction. This has a filling effect on missing data. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if mode was successfully selected |
Sample (auto-generated)
success = Image.NormalEstimation.setScharr(ne, smoothOrthogonal)Image.PixelRegion
Short description
A PixelRegion represents a collection of pixels in an image. A common use-case is to represent regions or masks in an image and the underlying representation is therefore run-length coded in form of a list of connected row-segments. This makes the representation computationally efficient to work with. The pixels in a PixelRegion need not be connected though, but can consist of isolated pixels or a set of connected regions. It is assumed that a PixelRegion is used together with an Image object in which it defines the collection of pixels. The PixelRegion therefore knows only about pixel coordinates and is not aware of the Image object’s world coordinate system. For measurements inside the given PixelRegion or for transformations of the PixelRegion requiring the Image world coordinate system, the reference Image object must also be supplied as parameter to the corresponding functions. The PixelRegion can be obtained as a rasterized Shape object, but there is currently no function for converting a PixelRegion to a Shape object. A PixelRegion can be generated from an Image object, for example through a threshold operation, and it is possible to render a PixelRegion back into an Image object.
Overview
Functions
clone()
Short description
Create an independent copy of a pixel region in new allocated memory. Can also be called with a vector of pixel regions.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
The source pixel region to clone. Can also be a vector of pixel regions. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
clonedRegion |
[1+] |
Copy of the input pixel region in new allocated memory. If the input is a vector the output is a vector of pixel regions. |
Sample (auto-generated)
clonedRegion = Image.PixelRegion.clone(region)contains()
Short description
Return true if the region(s) contains the given point. If more than one region is provided true is returned if the point is inside any of the regions. If more than one point is provided an array is returned with one value for each input point.
Keywords
included, inside
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region(s) |
point |
[1+] |
Input point(s) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
BOOL |
[1+] |
True if the point is within the region(s), otherwise false |
Sample
result = Image.PixelRegion.contains(region, point)countBorderPixels()
Short description
Return the number of border pixels of the region. A border pixel is located within the region and with neighboring pixels outside the region. 4-connectivity is used for the neighbor relation.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pixelCount |
INT |
[1+] |
Computed number of border pixels (single value or list) |
Sample
pixelCount = Image.PixelRegion.countBorderPixels(region)countHoles()
Short description
Return the number of holes in the region. To avoid including very small holes that only represent image noise, consider performing a dilate operation before calling countHoles.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
holeCount |
INT |
[1+] |
Computed number of holes (single value or list) |
Sample
holeCount = Image.PixelRegion.countHoles(region)countPixels()
Short description
Return the number of pixels within the region.
Keywords
area
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pixelCount |
INT |
[1+] |
Computed number of pixels (single value or list) |
Sample
pixelCount = Image.PixelRegion.countPixels(region)createCircle()
Short description
Create a pixel region containing all pixels within the given circle. By providing vectors of centers and radii several pixel regions can be created. All vectors must be of equal length.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
center |
[1+] |
Circle center. Can also be a vector to create several regions. |
|
radius |
FLOAT |
[1+] |
Circle radius. Can also be a vector to create several regions. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
[?*] |
The created pixel region, or vector of pixel regions for vector input. |
Sample (auto-generated)
region = Image.PixelRegion.createCircle(center, radius)createEmpty()
Short description
Create an empty region.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
1 |
The created empty pixel region. |
Sample (auto-generated)
region = Image.PixelRegion.createEmpty()createFromPoints()
Short description
Create a PixelRegion from a set of 2D or 3D points defined in image world coordinates. Any points outside the reference image bounds are ignored. For 3D points the z component is ignored. By default, each point sets one pixel in the output region. The region point size can be adjusted by the pointDiameter parameter.
Keywords
toPixelRegion
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
+ |
List of world coordinates, represented as Point objects, for each pixel in the region. |
|
referenceImage |
1 |
Reference image, defines the image world coordinate system. |
|
pointDiameter |
INT |
? |
Diameter of the points to create, in pixels. Point diameter must be odd and positive. A circular kernel is used to dilate the points. Optional, default is one. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
? |
The generated pixel region |
Sample
region = Image.PixelRegion.createFromPoints(points, referenceImage, pointDiameter)createRectangle()
Short description
Create a pixel region containing all pixels within a rectangle with upper-left corner (x0,y0) and lower-right corner (x1,y1). By providing vectors of corners several pixel regions can be created. All vectors must be of equal length.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
x0 |
INT |
[1+] |
x0 (upper-left). Can also be a vector to create several regions. |
y0 |
INT |
[1+] |
y0 (upper-left). Can also be a vector to create several regions. |
x1 |
INT |
[1+] |
x1 (lower-right). Can also be a vector to create several regions. |
y1 |
INT |
[1+] |
y1 (lower-right). Can also be a vector to create several regions. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
[?*] |
The created pixel region, or vector of pixel regions for for vector input. |
Sample (auto-generated)
region = Image.PixelRegion.createRectangle(x0, y0, x1, y1)dilate()
Short description
Dilate the input region with a disc of the given pixel diameter.
Keywords
morphology, expand
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or list of regions. |
diameter |
INT |
1 |
Disc diameter in pixels (must be odd). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
Dilated region or list of regions, or nil on error. |
Sample
outputRegion = Image.PixelRegion.dilate(region, diameter)downsample()
Short description
Downsample the pixel region(s) by an integer factor, keeping only rows and columns with coordinates equal to n*factor, where n = 0,1,2,…
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputRegion |
CONST_OBJECT |
[1+] |
Input region(s). |
factor |
INT |
1 |
Downsample factor. Must be larger than zero. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
Input region(s) downsampled by the provided factor. |
Sample
outputRegion = Image.PixelRegion.downsample(inputRegion, 2)erode()
Short description
Erode the input region with a disc of the given pixel diameter.
Keywords
morphology, shrink
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or list of regions. |
diameter |
INT |
1 |
Disc diameter in pixels (must be odd). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
Eroded region or list of regions, or nil on error. |
Sample
outputRegion = Image.PixelRegion.erode(region, diameter)fillHoles()
Short description
Fill any holes in a region.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
Output region, where any holes in the input region has been filled. |
Sample
outputRegion = Image.PixelRegion.fillHoles(region)fillRegion()
Short description
Set all pixels within the given region(s) in the target image to a specific value in world coordinates. The pixels outside the input region keep their original values. A new image with updated values is returned, and the input image is left unchanged. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. If the value parameter is outside the image value range it will be clamped to the closest valid value. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is kept in the output image, but the pixels in the fill region will be updated with non missing data.
Keywords
inpaint, flood
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
The region(s) to fill. |
value |
FLOAT |
[1+] |
World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image. |
inputImage |
1 |
Input image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputImage |
? |
Result image or nil if operation failed. |
Sample
outputImage = Image.PixelRegion.fillRegion(region, value, inputImage)fillRegionInplace()
Short description
Inplace version of the Image.PixelRegion.fillRegion function that modifies the input image. See base function for full documentation.
Keywords
inpaint, flood
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
The region(s) to fill. |
value |
FLOAT |
[1+] |
World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image. |
image |
1 |
The image. This image is overwritten with the result image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
result |
? |
Reference to the result image. |
Sample
result = Image.PixelRegion.fillRegionInplace(region, value, image)findConnected()
Short description
Find the connected components of an input pixel region, i.e., splits a PixelRegion object into a list of separated regions. Only keeps regions with a size (counted in number of pixels) within the range [minSize, maxSize].
Keywords
blob extraction, labeling, connected components
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputRegions |
CONST_OBJECT |
[1+] |
Input region(s) |
minSize |
INT |
? |
Minimum output region size |
maxSize |
INT |
? |
Maximum output region size |
maxRegionCount |
INT |
? |
Maximum number of output regions to return (default is 1000). Used to limit the memory requirements of the algorithm. |
timeoutSeconds |
FLOAT |
? |
The algorithm will abort if not finished approximately within this time limit, default is five seconds. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
regions |
* |
List of connected components represented as pixel regions, sorted by decreasing size |
Sample
regions = Image.PixelRegion.findConnected(inputRegions, 10)getArea()
Short description
Return the area of the specified region. This is equal to the number of pixels in the region times the area of each pixel as specified by the pixel sizes in the x,y-dimensions. Missing data handling: Any missing data information of the referenceImage is ignored. The area is calculated purely on the pixelRegion and scaled using the pixel scale of the image world coordinate system.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceImage |
1 |
Reference image, defining the image world coordinate system. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
area |
FLOAT |
[1+] |
Region area or areas in world units |
Sample
area = Image.PixelRegion.getArea(region, referenceImage)getBorderRegion()
Short description
Get the border pixels of the input region as a new pixel region. Border pixels are pixels within the input region bordering to pixels outside the region.
Keywords
edge, perimeter
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or list of regions |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
borderRegion |
[1+] |
Output border region or list of regions |
Sample
outputRegion = Image.PixelRegion.getBorderRegion(region)getBoundingBox()
Short description
Return an axis-aligned box of the region as a rectangle Shape in image world coordinates. To get the bounding box in pixel coordinates instead, just omit the optional referenceImage parameter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list. |
referenceImage |
? |
Reference image, defining the image world coordinate system. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
box |
[?*] |
Bounding box, represented as a rectangle Shape object, always with zero rotation (single box or list). |
Sample
box = Image.PixelRegion.getBoundingBox(region)getBoundingBoxOriented()
Short description
Returns the rectangle (not necessarily axis-aligned) of minimum area containing the object. The area is computed in world coordinates. A rectangle is defined by its center, width, height and a rotation around the center point. For an image in a left-handed coordinate system (such as a standard 2D image), a positive rotation is in a clockwise direction. The angular search range is unlimited by default and for unlimited search, the found box is oriented such that the width is larger or equal to the height and such that the orientation angle in the range (0..PI). A limited search can be specified by providing the center angle (rotationAngleRad) and the tolerance (rotationToleranceRad) of the desired range. By only setting the center angle (rotationAngleRad) and not the tolerance (rotationToleranceRad), a bounding box with a fixed rotation is obtained. This is useful when the orientation of the rectangle is known beforehand. For limited search the orientation angle is returned in the range (-PI..PI). The orientation can be obtained from other functions to find bounding boxes where the orientation is based on a different measure. E.g. Image.PixelRegion.getPrincipalAxes returns the orientation of the major axis of the region.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceImage |
1 |
Reference image, used to define the image world coordinate system |
|
accuracyRad |
FLOAT |
? |
Deprecated: After optimization this function always return the best accuracy of the rotation without penalty to the speed. |
rotationAngleRad |
FLOAT |
? |
The rotation angle in radians, if set specifies the center of the range of possible rotations. For an image in a left-handed coordinate system (such as a standard 2D image), a positive rotation is in a clockwise direction. |
rotationToleranceRad |
FLOAT |
? |
An angle that specifies the maximum rotation angle deviation, in radians. Along with the rotation angle, they specify a range of possible rotations. The default tolerance is zero. The value is limited to the interval (0..PI/2) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
rectangle |
[?*] |
The computed oriented bounding box, represented as a rectangle Shape object (single object or list) |
Sample
rectangle = Image.PixelRegion.getBoundingBoxOriented(region, referenceImage)getCenterOfGravity()
Short description
Return the center of gravity of the region in image world coordinates. Missing data handling: Any missing data information of the referenceImage is ignored. The center of gravity is calculated purely on the pixelRegion compensated for image scale and origin.
Keywords
cog
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceImage |
1 |
Reference image, defining the image world coordinate system |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
point |
[?*] |
Center of gravity represented as a 2D Point object (single point or list of points) |
Sample
point = Image.PixelRegion.getCenterOfGravity(region, referenceImage)getCircularity()
Short description
Returns a circularity measure that is 1.0 for ideal circles and smaller for other shapes. The measure is robust to high-frequency noise like jagged edges along the circle perimeter, so even noisy circles get a measure close to 1.0. The measure is significantly lower if the overall appearance is rather an ellipse, square or other non-circular shape.
Keywords
roundness
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceImage |
? |
Reference image, defining the image world coordinate system. If not supplied the image origin (0, 0, 0) and pixel size (1, 1, 1) will be used. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
circularity |
FLOAT |
[1+] |
The computed circularity measure (single value or list) |
Sample
circularity = Image.PixelRegion.getCircularity(region)getCompactness()
Short description
Returns the compactness measure of the region (4 * PI * Area / Perimeter^2). This is close to 1.0 for circles and smaller for less compact regions.
Keywords
roundness
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceImage |
1 |
Reference image, used to define the image world coordinate system |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
compactness |
FLOAT |
[1+] |
The computed compactness measure (single value or list) |
Sample
compactness = Image.PixelRegion.getCompactness(region, referenceImage)getConvexHull()
Short description
Get the convex hull of the input pixel region.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
sourceRegion |
CONST_OBJECT |
[1+] |
Input region or list of regions |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[1+] |
Target region or list of regions, convex hull of the input |
Sample
outputRegion = Image.PixelRegion.getConvexHull(sourceRegion)getConvexity()
Short description
Returns the convexity measure of the region (region area divided by area of convex hull). This is 1.0 for convex regions and smaller the more non-convex the region is
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
convexity |
FLOAT |
[1+] |
The computed convexity measure (single value or list) |
Sample
convexity = Image.PixelRegion.getConvexity(region)getDifference()
Short description
Get the set difference of the input regions. Returns a new region containing all pixels present in the first region but not in the second. If two regions are give, the function returns the difference of the two regions. If one list and one region is given, the function returns a list of regions containing the differences of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise difference of the regions in the lists. The lists must be the same length.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region1 |
CONST_OBJECT |
[1+] |
First input region, or list of regions |
region2 |
CONST_OBJECT |
[1+] |
Second input region, or list of regions |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
Resulting region or list of regions |
Sample
outputRegion = Image.PixelRegion.getDifference(region1, region2)getElongation()
Short description
Get the elongation of the region, defined as the ratio between the principal axes lengths. This measure is also often called eccentricity. The value is 1.0 for circles larger than 1.0 for regions that are elongated in one direction.
Keywords
eccentricity
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceImage |
1 |
Reference image, used to define the image world coordinate system |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
elongation |
FLOAT |
[1+] |
Computed elongation measure (single value or list) |
Sample
elongation = Image.PixelRegion.getElongation(region, referenceImage)getHistogram()
Short description
Get a histogram of the image values within the specified region. If the image supports missing data, pixels marked as missing are not included in the histogram. If a pixel-world mapping is specified, the histogram is computed using world coordinates. If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. Optionally, a reference surface in world coordinates may be provided, in which case the histogram is based on deviations from the reference surface. The default surface is the plane z=0. See also Image.getHistogram.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
1 |
Region specifying which parts of the image to include in the histogram |
image |
1 |
Input image, specifying values to use in the histogram |
|
binCount |
INT |
? |
Number of bins. Uses 32 bins as default. |
minValue |
FLOAT |
? |
Minimum of the value range to cover. Uses an automatic range if omitted. |
maxValue |
FLOAT |
? |
Maximum of the value range to cover. Uses an automatic range if omitted. |
referenceSurface |
? |
Zero-reference surface for the histogram. Optional, default is the plane z=0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
histogram |
FLOAT |
* |
Histogram, represented as a vector of floats |
binCenters |
FLOAT |
* |
The center of each histogram bin in the input value range |
Sample
histogram, centers = Image.PixelRegion.getHistogram(region, image, 64)getIntersection()
Short description
Get the set intersection of two regions. If two regions are give, the function returns the set intersection of the two regions. If one list and one region is given, the function returns a list of regions containing the intersections of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise intersection of the regions in the lists. The lists must be the same length.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region1 |
CONST_OBJECT |
[1+] |
First input region, or list of regions |
region2 |
CONST_OBJECT |
[1+] |
Second input region, or list of regions, subtracted from region1 |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
Resulting region or list of regions |
Sample
outputRegion = Image.PixelRegion.getIntersection(region1, region2)getMedian()
Short description
Get the median value of the pixels within the region, a special case of Image.PixelRegion.getPercentiles. The default method to calculate the median is partial sorting, alternatively a histogram variant can be used. The histogram variant is approximative when using fewer bins than intensity levels. A reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0.
Keywords
percentile, statistics
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
referenceSurface |
? |
Zero-reference 3D surface plane for pixel world coordinate values. Optional, default is the plane z=0. |
|
orthogonalToSurface |
BOOL |
? |
Indicates if the distance shall be measured as the orthogonal distance from the reference plane. Default is false, measuring the distance along the z-axis of the image. |
binCount |
INT |
? |
Set the number of bins to use in the histogram for calculating the value, more bins provides a more accurate result. Default is zero. If set to zero, a histogram is not used, but a partial sort is used instead. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
median |
FLOAT |
[?*] |
The approximate median. |
Sample
median = Image.PixelRegion.getMedian(region, image, referenceSurface, orthogonalToSurface, binCount)getPercentiles()
Short description
Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. The default method to calculate the percentiles is partial sorting, alternatively a histogram variant can be used. The histogram variant is approximative when using fewer bins than intensity levels. A reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0.
Keywords
statistics
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
1 |
Input region |
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
percentileLevels |
FLOAT |
+ |
Percentile levels in the range (0..1) |
referenceSurface |
? |
Zero-reference 3D surface plane for pixel world coordinate values. Optional, default is the plane z=0. |
|
orthogonalToSurface |
BOOL |
? |
Indicates if the distance shall be measured as the orthogonal distance from the reference plane. Default is false, measuring the distance along the z-axis of the image. |
binCount |
INT |
? |
Set the number of bins to use in the histogram for calculating the value, more bins provides a more accurate result. Default is zero. If set to zero, a histogram is not used, but a partial sort is used instead. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
values |
FLOAT |
* |
Output values |
Sample
values = Image.PixelRegion.getPercentiles(region, image, percentileLevels, referenceSurface, orthogonalToSurface, binCount)getPerimeterLength()
Short description
Get the region perimeter length in world units. The length is computed as the sum of distances between individual pixels. Note that this means that the reported perimeters are different than the analytical perimeter for mathematical objects like circles and rectangles.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceImage |
1 |
Reference image, used to define the image world coordinate system. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
perimeterLength |
FLOAT |
[1+] |
Computed perimeter length in world units (single value or list) |
Sample
perimeterLength = Image.PixelRegion.getPerimeterLength(region, referenceImage)getPrincipalAxes()
Short description
Get principal axes of the region (orientation and length of major/minor axes, derived from region moments). To calculate the axes the second moment (variance) is used in the form of the covariance matrix. The eigen vectors and values extracted from this matrix are used to calculate the orientation and length of the axes. The orientation is calculated by: atan(largestEigenVectorY / largestEigenVectorX). The length of the axes are calculated by: majorAxis=4*sqrt(eigenValueMax), minorAxis=4*sqrt(eigenValueMin), please note that sqrt(eigenValue) corresponds to the standard deviation.
Keywords
covariance, eccentricity, elongation, major, moment, PCA, minor
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or list of input regions |
referenceImage |
1 |
Reference image, defines the image world coordinate system. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
angleRad |
FLOAT |
[1+] |
Rotation angle(s) of the major axis in radians. |
majorAxisWorld |
FLOAT |
[1+] |
Length(s) of the major axis in world units |
minorAxisWorld |
FLOAT |
[1+] |
Length(s) of the minor axis in world units |
Sample
angleRad, majorAxisWorld, minorAxisWorld = Image.PixelRegion.getPrincipalAxes(region, referenceImage)getRoughness()
Short description
Return roughness statistics for the specified region. This measurement consists of the mean, standard deviation, skewness and kurtosis statistics (i.e. the four first moments of the distribution). The roughness is calculated from the pixel values in the region, using the image world coordinate system. The skewness is a measure of the asymmetry of the distribution, and the kurtosis is a measure of the "tailedness" of the distribution. To get the excess kurtosis, subtract 3 from the returned kurtosis value. Missing data handling: Missing data pixels are omitted from the statistics and are treated like they didn’t exist.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceImage |
1 |
Reference image. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
mean |
FLOAT |
[?*] |
Region mean in world units. |
stddev |
FLOAT |
[?*] |
Region standard deviation in world units. |
skewness |
FLOAT |
[?*] |
Region skewness in world units. |
kurtosis |
FLOAT |
[?*] |
Region kurtosis in world units. |
Sample
mean, stddev, skewness, kurtosis = Image.PixelRegion.getRoughness(region, referenceImage)getStatistics()
Short description
Get pixel value statistics for pixels belonging to a pixel region. Image world coordinate system values are used and pixels with missing data are excluded. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided, basing the statistics on deviations from that surface. If the statistics can not be calculated, nil is returned. A vector of regions can be provided, in which case four vectors of statistics are returned, one entry for each input region. Any invalid input region in the vector will have the corresponding output entries set to zero.
Keywords
average, max, maximum, min, minimum, standard deviation, std, mean
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region, defines the region of image in which to gather statistics, or several regions where statistics are calculated individually for each region. |
image |
1 |
Input image, defines the image from which to get pixel value input. |
|
referenceSurface |
? |
Reference surface, defines the zero level in world coordinates. Default is the plane z=0. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
min |
FLOAT |
[?*] |
Minimal value, or vector of values with one entry for each region. |
max |
FLOAT |
[?*] |
Maximal value, or vector of values with one entry for each region. |
average |
FLOAT |
[?*] |
Average value, or vector of values with one entry for each region. |
standardDeviation |
FLOAT |
[?*] |
Standard deviation, or vector of standard deviations with one entry for each region. |
Sample
min, max, average, standardDeviation = Image.PixelRegion.getStatistics(region, image, referenceSurface)getTextureOrientation()
| This API is experimental |
Short description
Calculates the structure orientation in radians within a PixelRegion on an image. The structure direction is calculated within a first quadrant of the unit circle. Eg. angles between 0 and pi/2. The angle is given in pixels, not in world coordinates. This has an effect on images with anisotropic pixels.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
1 |
The region of the image to use. |
to |
OBJECT |
1 |
The texture orientation object. |
image |
1 |
The image to calculate the orientation for. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
angle |
FLOAT |
? |
The structure direction for the selected region. Nil on failure. |
Sample
local angle = Image.PixelRegion.getTextureOrientation(region, to, image)getUnion()
Short description
Get the set union of two or more regions. If two regions are give, the function returns the set union of the two regions. If one list of regions is given, the function returns the set union of all regions in the list. If one list and one region is given, the function returns a list of regions containing the unions of each region in the list and the single region. If two lists are given, the function returns a vector of regions containing the pair-wise unions of the regions in the lists. The lists must be the same length.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region1 |
CONST_OBJECT |
[1+] |
First input region or list of regions |
region2 |
CONST_OBJECT |
[?*] |
Second input region or list of regions |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
Resulting region or list of regions |
Sample
outputRegion = Image.PixelRegion.getUnion(region1, region2)getVolume()
Short description
Get the volume between a height map and a reference surface within the region or regions. Image world coordinate system values are used. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided. The user can configure how to compute the total volume and how to handle negative values (values below the reference surface). The default is to only count the positive volume (ABOVE), meaning that values below the reference surface are considered missing data. See the VolumeDirection enum for other options. Pixels with missing data are disregarded (counted as a zero-volume-contribution). For other ways of handling missing data, such as filling using nearby data, call the appropriate Image.missingData-function before calling getVolume.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list. |
heightMap |
1 |
Input image that can be interpreted as a height map using the origin and pixelSize properties. |
|
referenceSurface |
? |
Reference surface, defines the zero level in world coordinates. Default is the plane z=0. |
|
direction |
ENUM |
? |
Select how to compute volume. Default is ABOVE, counting the positive volume. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
volume |
FLOAT |
[?*] |
The volume contained below the height map within the input region (single value or list), or nil in case of failure. |
Sample
volume = Image.PixelRegion.getVolume(region, heightMap)intersectImage()
Short description
Get the part of a pixel region within a reference image.
Keywords
complement, difference
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or list of regions. |
referenceImage |
1 |
Reference image, defines the area for cropping the region. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
The part of region or list of regions within referenceImage, or nil on error. |
Sample
outputRegion = Image.PixelRegion.intersectImage(region, referenceImage)invert()
Short description
Get the complement within a reference image, returns a pixel region(s) containing all reference image pixels not in the input region(s).
Keywords
complement
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region(s). |
referenceImage |
1 |
Reference image, defines the area for inverting the region(s). |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
The complement(s) to region(s) within referenceImage, or nil on error. |
Sample
outputRegion = Image.PixelRegion.invert(region, referenceImage)isEmpty()
Short description
Check if the region contains zero pixels. If a vector of pixel regions is provided the output is a vector of the same length.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input pixel region. Can also be a vector of pixel regions. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
isEmpty |
BOOL |
[1+] |
True if the region is empty. Can also be a vector of booleans. |
Sample (auto-generated)
isEmpty = Image.PixelRegion.isEmpty(region)resize()
Short description
Transform the region using two reference images. Can be used to adapt a region after an image resize.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputRegion |
CONST_OBJECT |
[1+] |
Input region, or a list of regions |
inputReferenceImage |
1 |
Reference image for the source size. |
|
resizedReferenceImage |
1 |
Reference image for the target size. |
|
interpolation |
ENUM |
? |
Interpolation method to use. Default is LINEAR. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[1+] |
The transformed pixel region or region list |
Sample
outputRegion = Image.PixelRegion.resize(inputRegion, inputReferenceImage, resizedReferenceImage)resizeScale()
Short description
Transform the region in a way compatible to Image.resizeScale. Can be used to adapt a region after an image resize.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputRegion |
CONST_OBJECT |
[1+] |
Input region, or a list of regions |
scaleX |
FLOAT |
1 |
The scaling factor to apply in the horizontal direction. |
scaleY |
FLOAT |
? |
The scaling factor to apply in the vertical direction. Defaults to scaleX. |
interpolation |
ENUM |
? |
Interpolation method to use. Default is LINEAR. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[1+] |
The transformed pixel region or region list |
Sample
outputRegion = Image.PixelRegion.resizeScale(inputRegion, scaleX, scaleY)thin()
Short description
Creates a skeleton region out of the input region.
Keywords
morphology, skeleton
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or list of regions. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[?*] |
Skeleton region |
Sample
outputRegion = Image.PixelRegion.thin(region)toImage()
Short description
Convert the region to an image, using a specified value for pixels within the region. The value is in world coordinates and is clamped to the representable range of the image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
1 |
Input region |
referenceImage |
1 |
Reference image, defines the size, pixel type and image world coordinate system of the output image. |
|
valueWorld |
FLOAT |
? |
World coordinate value to use within the region, default is 255 |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputImage |
? |
Image containing the region |
Sample
outputImage = Image.PixelRegion.toImage(region, referenceImage, valueWorld)toPoints2D()
Short description
Get a vector of the pixels contained in the region represented as 2D Point objects. Pixel coordinates are converted to image world coordinates using the reference image. Any parts of the input region that is outside the reference image bounds is ignored.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
1 |
The region to process |
referenceImage |
1 |
Reference image, defines the image world coordinate system |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
* |
Vector of 2D Point objects, expressed in image world coordinates, for each pixel contained within the region. |
Sample
points = Image.PixelRegion.toPoints2D(region, referenceImage)toPoints3D()
Short description
Get a vector of the pixels contained in the region represented as 3D Point objects, including a z value from the reference image. Any parts of the input region that is outside the image bounds or contains missing data is ignored.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
1 |
The region to process |
referenceImage |
1 |
Input image, defines the pixel-world mapping and is used to get z values (pixel values converted using the z-part of the pixel-world mapping) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
points |
* |
Vector of 3D Point objects, expressed in image world coordinates, for each pixel contained within the region. |
Sample
points = Image.PixelRegion.toPoints3D(region, referenceImage)toString()
Short description
Get a brief string description of the pixel region. This is equal to the text shown in the debugger to describe the region. Can also be called with a vector of pixel regions.
Keywords
description, help, print
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pixelRegion |
CONST_OBJECT |
[1+] |
Input pixel region. Can also be a vector of pixel regions. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
str |
STRING |
[1+] |
Description of the region. If the input is a vector the output is a vector of strings. |
Sample (auto-generated)
str = Image.PixelRegion.toString(pixelRegion)touchesImageBorder()
Short description
Returns true if a pixel region touches the border of provided image
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceImage |
1 |
Input image, used only to define the image size |
|
leftBorder |
BOOL |
? |
By default is true, tests if the region touches the left border. Set to false if the test should not be performed. |
rightBorder |
BOOL |
? |
By default is true, tests if the region touches the right border. Set to false if the test should not be performed. |
topBorder |
BOOL |
? |
By default is true, tests if the region touches the top border. Set to false if the test should not be performed. |
bottomBorder |
BOOL |
? |
By default is true, tests if the region touches the bottom border. Set to false if the test should not be performed. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
touches |
BOOL |
[1+] |
True if region touches image borders (single value or list) |
Sample
touches = Image.PixelRegion.touchesImageBorder(region, referenceImage)touchesRegionBorder()
Short description
Returns true if a pixel region touches the border of provided reference region
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
[1+] |
Input region or region list |
referenceRegion |
CONST_OBJECT |
1 |
Reference region, defines the region border |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
touches |
BOOL |
[1+] |
True if region touches reference region borders (single value or list) |
Sample
touches = Image.PixelRegion.touchesRegionBorder(region, referenceRegion)toVector()
Short description
Returns vectors of the Y coordinate and X coordinate start and end, corresponding to the pixel region run length encoded segments.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
region |
CONST_OBJECT |
1 |
The region to process |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
segmentsY |
INT |
+ |
Vector of the Y coordinates of a pixel region run length encoded segments. |
segmentsXStart |
INT |
+ |
Vector of the X coordinates initial position of a pixel region run length encoded segments. |
segmentsXStop |
INT |
+ |
Vector of the X coordinates end position of a pixel region run length encoded segments. |
Sample
segmentsY, segmentsXStart, segmentsXStop= Image.PixelRegion.toVector(region)transform()
Short description
Transform the region using a general 2D Transform object, expressed in image world coordinates.
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
inputRegion |
CONST_OBJECT |
[1+] |
Input region, or a list of regions |
transform |
1 |
Transform to apply, expressed in world coordinates |
|
sourceReferenceImage |
1 |
The source reference image. |
|
destinationReferenceImage |
? |
The destination reference image, the output pixel region will be transformed from the source reference image into the destination reference image. If not specified, the destination image is equal to the source. |
|
interpolation |
ENUM |
? |
Interpolation method to use. Default is LINEAR. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
outputRegion |
[1+] |
The transformed pixel region or region list. Only the pixelRegion part that is contained inside the source reference image is considered for the transformation. The transformed pixelRegion is also cropped by the destination image limits. |
Sample
outputRegion = Image.PixelRegion.transform(region, transform, sourceReferenceImage, destinationReferenceImage)Image.PixelRegion.Filter
Short description
Filter for pixel regions. Offers convenient filtering and sorting based on all features from Image.PixelRegion. The description of each filter contains a reference to the corresponding function.
Keywords
blobs, extraction, sorting, features
See also
Functions
apply()
Short description
Apply the filter to a region list. Return the filtered and sorted regions. The actual regions are copied by reference, so changing a region in the input list makes the same region change also in the output list and vice versa. Note that lists in Lua are 1-indexed and matrices are 0-indexed, so the features corresponding to filteredRegions[i] is at row i-1 in the featureValues matrix. If no blobs are found, the function returns an empty filteredRegions list and no featureValues matrix.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filter |
HANDLE |
1 |
Filter to apply |
inputRegions |
CONST_OBJECT |
+ |
Input regions |
inputImage |
1 |
Input image, used for pixel-world mapping and for pixel values if value statistics features are used (median, average, etc.) |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filteredRegions |
* |
Filtered and sorted output regions |
|
featureValues |
? |
Matrix of computed feature values. Each row corresponds to an output region and each column to a computed feature. The columns are in the same order as the features are mentioned in calls to setRange and setCondition before applying the filter. |
Sample
filteredRegions, featureValues = Image.PixelRegion.Filter.apply(filter, inputRegions, inputImage)create()
Short description
Create a new PixelRegion filter
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filter |
HANDLE |
1 |
The new filter |
Sample
filter = Image.PixelRegion.Filter.create()setCondition()
Short description
Set a new equality/inequality condition to the filter. Only regions with feature value within the given range will be included in the filter output.
Keywords
inequal, equal
See also
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filter |
HANDLE |
1 |
Input filter to modify |
featureType |
ENUM |
1 |
The feature type that the filter applies to. Must be an integer feature type. |
exactValue |
INT |
1 |
Exact value to compare to |
equality |
BOOL |
? |
Set to true for equality comparison and false for inequality. Default is equality. |
Sample
Image.PixelRegion.Filter.setCondition(filter, "HOLESCOUNT", 0)setRange()
Short description
Set a new range constraint to the filter. Only regions with feature value within the given range will be included in the filter output.
Keywords
interval
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filter |
HANDLE |
1 |
Input filter to modify |
featureType |
ENUM |
1 |
The feature type that the filter applies to |
minValue |
FLOAT |
1 |
Minimum allowed value (inclusive) |
maxValue |
FLOAT |
1 |
Maximum allowed value (inclusive) |
withinRange |
BOOL |
? |
Set to true to setup a within-range check and false for an outside-range check. Default is within-range. |
Sample
Image.PixelRegion.Filter.setRange(filter, "CONVEXITY", 0.0, 0.8)sortBy()
Short description
Defines which feature the output list shall be sorted by
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filter |
HANDLE |
1 |
Input filter to modify |
featureType |
ENUM |
1 |
The feature type to sort by |
ascending |
BOOL |
? |
Set to true to sort in ascending order (default), false for descending |
Sample
Image.PixelRegion.Filter.sortBy(filter, "CENTROIDX")toString()
Short description
Get a user-friendly string description of the filter
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
filter |
HANDLE |
1 |
Input filter |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
description |
STRING |
1 |
User-friendly description of the filter |
Sample
print("The filter is: " .. Image.PixelRegion.Filter.toString(filter))Image.PointCloudConversion
Short description
Image to point cloud converter API for special conversion cases. Choose the appropriate converter for your camera. See also the Image.toPointCloud function for conversion of already rectified images.
See also
Image.PointCloudConversion.PlanarDistance
Short description
Image to point cloud converter for 'PlanarDistance' cameras e.g. Visionary-S "V3S142". This converter needs a Z-map as input. Be aware that for the Visionary-T Mini the Z-map that can be selected as part of the X-Y-Z-map tuple is not meant to be used with this method. In this case use PointCloud.fromComponents instead.
Functions
create()
Short description
Creates a new instance of an image to point cloud converter for 'PlanarDistance' cameras.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance. |
Sample (auto-generated)
handle = Image.PointCloudConversion.PlanarDistance.create()setCameraModel()
Short description
Sets the camera model for the image to point cloud conversion.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance |
|
cameraModel |
OBJECT |
1 |
Camera model to set |
Sample (auto-generated)
Image.PointCloudConversion.PlanarDistance.setCameraModel(handle, cameraModel)setHeightmapBoundingBox()
Short description
Set bounding box and pixel sizes to define world coordinate bounds of the projected heightmap
Keywords
convert, heightmap, parallel projection, project, rectify, splat
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance |
|
box |
1 |
An axis-aligned box. All data within this box is used for creating the image. The coordinate system origin of the resulting image is defined by the box. |
|
pixelSizeX |
FLOAT |
1 |
The size of a pixel in the X dimension in world coordinate units, in the output heightmap |
pixelSizeY |
FLOAT |
? |
The size of a pixel in the Y dimension in world coordinate units, in the output heightmap. If unset, the same as pixelSizeX is used |
pixelSizeZ |
FLOAT |
? |
The size of a pixel in the Z dimension in world coordinate units, in the output heightmap. If unset, the optimal value based on the height of the bounding box is used |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the bounding box and pixel sizes could be set. |
Sample (auto-generated)
success = Image.PointCloudConversion.PlanarDistance.setHeightmapBoundingBox(handle, box, pixelSizeX, pixelSizeY, pixelSizeZ)toHeightmap()
Short description
Converts a distance image along with its intensity or RGB component to a heightmap via parallel projection. Invalid data in the source image will be omitted from the resulting heightmap. This function assumes that the CameraModel has been correctly set, such that the world origin is at the center of the projected surface. The world plane with z==0 is used as the bottom of the resulting heightmap, and the positive z-axis is pointed upwards. Points are projected onto the output image via splatting. By default behavior, the total splat size is based on the distance to the camera. To adjust how the splat size is affected by distance, use splatDynamicX and splatDynamicY. Default is 1.0 and correlates to an estimate based on the set CameraModel. In order to splat more at larger distances, set this value to greater than 1. To splat less, set it to lower than 1. The optimal value can be different based on the geometry of the scene. splatConstX and splatConstY adds size to the total splat size, unrelated to distance. The two parameters can be combined. In order to always use a fixed splat size, set splatDynamicX, splatDynamicY to 0, and splatConstX, splatConstY to some positive values.
Keywords
convert, heightmap, parallel projection, project, rectify, splat
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance |
|
distanceImage |
1 |
Distance image to convert to a Heightmap of UINT16 type |
|
intensityImage |
1 |
Intensity image for Heightmap conversion of UINT8, UINT16, or RGB24 type. |
|
splatDynamicX |
FLOAT |
? |
Adjust spread in the X direction by a factor. Default 1.0. |
splatDynamicY |
FLOAT |
? |
Adjust spread in the Y direction by a factor. Default same as splatDynamicX. |
splatConstX |
FLOAT |
? |
Adjust spread in the X direction by adding a constant, in millimeters. Default 0. |
splatConstY |
FLOAT |
? |
Adjust spread in the Y direction by adding a constant, in millimeters. Default same as splatConstX. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
heightmap |
? |
Output image of UINT16 type. |
|
heightmapIntensity |
? |
Intensity or RGB component of output image. Same type as input intensityImage |
Sample (auto-generated)
heightmap, heightmapIntensity = Image.PointCloudConversion.PlanarDistance.toHeightmap(handle, distanceImage, intensityImage, splatDynamicX, splatDynamicY, splatConstX, splatConstY)toPointCloud()
Short description
Converts the undistorted planar distance image with optional intensity or RGB image data to a point cloud. Invalid data (i.e. data with distance 0) in the source image will be omitted from the resulting point cloud.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance |
|
distanceImage |
1 |
Distance image to convert to a PointCloud |
|
rgbOrIntensityImage |
? |
Intensity or RGB image for PointCloud conversion |
|
pixelRegion |
? |
Pixel region which restricts the PointCloud conversion |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pointCloud |
OBJECT |
? |
Converted PointCloud with optional intensity or RGB data |
Sample (auto-generated)
pointCloud = Image.PointCloudConversion.PlanarDistance.toPointCloud(handle, distanceImage, rgbOrIntensityImage, pixelRegion)Image.PointCloudConversion.RadialDistance
Short description
Image to point cloud converter for 'RadialDistance' cameras, e.g. Visionary-T Mini "V3S145".
Functions
create()
Short description
Creates a new instance of an image to point cloud converter for 'RadialDistance' cameras.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance. |
Sample (auto-generated)
handle = Image.PointCloudConversion.RadialDistance.create()setCameraModel()
Short description
Sets the camera model for the image to point cloud conversion.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance |
|
cameraModel |
OBJECT |
1 |
Camera model to set |
Sample (auto-generated)
Image.PointCloudConversion.RadialDistance.setCameraModel(handle, cameraModel)setHeightmapBoundingBox()
Short description
Set bounding box and pixel sizes to define world coordinate bounds of the projected heightmap
Keywords
convert, heightmap, parallel projection, project, rectify, splat
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance |
|
box |
1 |
An axis-aligned box. All data within this box is used for creating the image. The coordinate system origin of the resulting image is defined by the box. |
|
pixelSizeX |
FLOAT |
1 |
The size of a pixel in the X dimension in world coordinate units, in the output heightmap |
pixelSizeY |
FLOAT |
? |
The size of a pixel in the Y dimension in world coordinate units, in the output heightmap. If unset, the same as pixelSizeX is used |
pixelSizeZ |
FLOAT |
? |
The size of a pixel in the Z dimension in world coordinate units, in the output heightmap. If unset, the optimal value based on the height of the bounding box is used |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if the bounding box and pixel sizes could be set. |
Sample (auto-generated)
success = Image.PointCloudConversion.RadialDistance.setHeightmapBoundingBox(handle, box, pixelSizeX, pixelSizeY, pixelSizeZ)toHeightmap()
Short description
Converts a distance image along with its intensity or RGB component to a heightmap via parallel projection. Invalid data in the source image will be omitted from the resulting heightmap. This function assumes that the CameraModel has been correctly set, such that the world origin is at the center of the projected surface. The world plane with z==0 is used as the bottom of the resulting heightmap, and the positive z-axis is pointed upwards. Points are projected onto the output image via splatting. By default behavior, the total splat size is based on the distance to the camera. To adjust how the splat size is affected by distance, use splatDynamicX and splatDynamicY. Default is 1.0 and correlates to an estimate based on the set CameraModel. In order to splat more at larger distances, set this value to greater than 1. To splat less, set it to lower than 1. The optimal value can be different based on the geometry of the scene. splatConstX and splatConstY adds size to the total splat size, unrelated to distance. The two parameters can be combined. In order to always use a fixed splat size, set splatDynamicX, splatDynamicY to 0, and splatConstX, splatConstY to some positive values.
Keywords
convert, heightmap, parallel projection, project, rectify, splat
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance |
|
distanceImage |
1 |
Distance image to convert to a Heightmap of UINT16 type |
|
intensityImage |
1 |
Intensity image for Heightmap conversion of UINT8, UINT16, or RGB24 type. |
|
splatDynamicX |
FLOAT |
? |
Adjust spread in the X direction by a factor. Default 1.0. |
splatDynamicY |
FLOAT |
? |
Adjust spread in the Y direction by a factor. Default same as splatDynamicX. |
splatConstX |
FLOAT |
? |
Adjust spread in the X direction by adding a constant, in millimeters. Default 0. |
splatConstY |
FLOAT |
? |
Adjust spread in the Y direction by adding a constant, in millimeters. Default same as splatConstX. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
heightmap |
? |
Output image of UINT16 type. |
|
heightmapIntensity |
? |
Intensity or RGB component of output image. Same type as input intensityImage |
Sample (auto-generated)
heightmap, heightmapIntensity = Image.PointCloudConversion.RadialDistance.toHeightmap(handle, distanceImage, intensityImage, splatDynamicX, splatDynamicY, splatConstX, splatConstY)toPointCloud()
Short description
Converts the radial distance image with optional intensity image data to a point cloud. Invalid data (i.e. data with distance 0) in the source image will be omitted from the resulting point cloud.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
1 |
Handle to the instance |
|
distanceImage |
1 |
Distance image to convert to a PointCloud |
|
intensityImage |
? |
Intensity image for PointCloud conversion |
|
pixelRegion |
? |
Pixel region which restricts the PointCloud conversion |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
pointCloud |
OBJECT |
? |
Converted PointCloud with optional intensity data |
Sample (auto-generated)
pointCloud = Image.PointCloudConversion.RadialDistance.toPointCloud(handle, distanceImage, intensityImage, pixelRegion)Image.Provider
Short description
Provides access to various image providers.
Overview
Image.Provider.Camera
Short description
Provides functionality to control and receive images from the camera of the programmable device.
Overview
Functions
create()
Short description
Creates an instance of the image provider, which provides images asynchronously. Will return nil if there already exists a handle of this CROWN.
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
? |
ImageProviderCam exists as long as this handle. |
Sample
handle = Image.Provider.Camera.create()deregister()
Short description
This function is used to deregister from any registered event of the handle.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
The instance handle to use |
eventname |
STRING |
1 |
The event to deregister from |
callback |
STRING |
1 |
The function name which was registered on the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
Sample (auto-generated)
success = Image.Provider.Camera.deregister(handle, eventname, callback)disable()
Short description
Disables the camera. It will not accept external or internal start/stop triggers if it was disabled. Disabling the camera will also stop the current image acquisition.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle returned by create |
Sample
Image.Provider.Camera.disable(handle)enable()
Short description
Enables the camera. The camera will only accept external or internal start/stop triggers after it has been enabled.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle returned by create |
Sample
Image.Provider.Camera.enable(handle)getActualConfig()
Short description
Get a configuration object with the actually used camera configuration. When setting a configuration, some values may be adapted or rounded. Using this function the actually used values can be requested.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle of the Camera provider. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Config instance containing the actualy configuration. |
Sample
local actualConfig = Image.Provider.Camera.getActualConfig(camHandle)getConfig()
Short description
Get a configuration object with the current camera configuration.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle of the Camera provider. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Config instance containing the current configuration. |
Sample
local config = Image.Provider.Camera.getConfig(camHandle)getDefaultConfig()
Short description
Get a configuration object with a default configuration suitable for this driver. Please consult the manual to find information what values are used for the default configuration.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle of the Camera provider. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Config instance containing the default configuration. |
Sample
local config = Image.Provider.Camera.getDefaultConfig(camHandle)getInitialCameraModel()
Short description
Query the (initial) camera model currently associated with this camera. This model is initially filled with the correction parameters from calibration and an identity-pose
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle of the Camera provider. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
cameraModel |
OBJECT |
1 |
Default camera model. |
Sample
local cameraModel = Image.Provider.CameraV3S2.getDefaultCameraModel(camHandle)register()
Short description
This function is used to register for any event of this provider. The event name is specified as parameter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle returned by create |
eventname |
STRING |
1 |
The event to register to |
callback |
STRING |
1 |
name of function to call upon the event |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if successfully registered. False if event does not exist. |
Sample
Image.Provider.Camera.register(handle, "OnNewImage", "HandleNewImage")setConfig()
Short description
Applies the given configuration to the camera provider. Can cause minor errors if called during active image acquisition.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Instance handle of the Camera provider. |
configHandle |
HANDLE |
1 |
Handle of config instance to apply. |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
true if new value could be set in configuration |
Sample
Image.Provider.Camera.setConfig(camHandle, configHandle)snapshot()
Short description
Starts taking one image.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle returned by create |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
Returns true if acquisition could be triggered. |
Sample
Image.Provider.Camera.snapshot(handle)start()
Short description
Triggers the camera to start taking images explicitly.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle returned by create |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
success |
BOOL |
1 |
True if call to start succeeded and image acquisition was started. |
Sample
Image.Provider.Camera.start(handle)stop()
Short description
Stops taking images explicitly.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
handle |
HANDLE |
1 |
Handle returned by create |
Sample
Image.Provider.Camera.stop(handle)Events
OnImageLost
Short description
This event is thrown every time an image could not be stored because of a full image queue.
Sample (auto-generated)
function handleOnImageLost()
-- Do something
end
Image.Provider.Camera.register(handle, "OnImageLost", "handleOnImageLost")OnNewImage
Short description
The image event which is thrown for every image.
Callback arguments
| Name | Type | Multiplicity | Description |
|---|---|---|---|
image |
[1+] |
the captured image |
|
sensorData |
OBJECT |
[1+] |
additional data belonging to the image |
Sample (auto-generated)
function handleOnNewImage(image, sensorData)
-- Do something
end
Image.Provider.Camera.register(handle, "OnNewImage", "handleOnNewImage")Image.Provider.Camera.V3SXX51Config
Short description
Provides functionality to configure a TOF Mini(V3SXX5_1) camera. Call Image.Provider.Camera.setConfig() to set this configuration.
Overview
Functions
enableDepthMask()
Short description
Enable or disable masking invalid pixels on depthmap. The masked pixels will be set to 0.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
|
enabled |
BOOL |
1 |
depth mask flag; true means enabled, false disabled. |
Sample
Image.Provider.Camera.V3SXX51Config.enableDepthMask(config, true)getAmbiguityFilter()
Short description
Gets the current configuration of the ambiguity filter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
Enable/Disable filter |
scale |
FLOAT |
1 |
ambiguity difference scaling factor |
Sample
local enabled, scale = Image.Provider.Camera.V3SXX51Config.getAmbiguityFilter(config)getBinning()
Short description
Gets the binning factors of the image sensors.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
colBinning |
INT |
1 |
number of columns to merge into one column |
rowBinning |
INT |
1 |
number of rows to merge into one row |
Sample
local colbinning, rowbinning = Image.Provider.Camera.V3SXX51Config.getBinning()getDistanceFilter()
Short description
Get the configuration of the radial distance filter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
Enable/Disable filter |
distanceMin |
INT |
1 |
minimal value in mm of distance filter |
distanceMax |
INT |
1 |
maximum value in mm of distance filter |
Sample
local distanceEn, distanceMin, distanceMax = Image.Provider.Camera.V3SXX51Config.getDistanceFilter(config)getEdgeCorrection()
Short description
Gets the current configuration of the edge correction.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
Enable/Disable filter |
lowerEdgeThreshold |
FLOAT |
1 |
Lower Edge Threshold. |
upperEdgeThreshold |
FLOAT |
1 |
Upper edge Threshold. |
Sample
local enabled, lowerEdgeThreshold, upperEdgeThreshold = Image.Provider.Camera.V3SXX51Config.getEdgeCorrection(config)getFlyingClusterFilter()
Short description
Gets the current configuration of the flying cluster Filter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
Enable/Disable filter |
threshold |
INT |
1 |
difference threshold between opened and closed map |
kernelSize |
? |
The kernel size of the Flying Cluster Filter. |
Sample
local enabled, threshold, kernelSize = Image.Provider.Camera.V3SXX51Config.getFlyingClusterFilter(config)getFramePeriod()
Short description
Gets the frame period of the imager.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
framePeriod |
INT |
1 |
frame period in [us]. The values may be rounded and/or reduced |
Sample
local period = Image.Provider.Camera.V3SXX51Config.getFramePeriod(config)getIntensityFilter()
Short description
Get the configuration of the intensity filter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
Enable/Disable filter |
intensityMin |
INT |
1 |
minimal intensity value |
intensityMax |
INT |
1 |
maximum intensity value |
Sample
local intensityEn, intensityMin, intensityMax = Image.Provider.Camera.V3SXX51Config.getIntensityFilter(config)getMaps()
Short description
Return the names of the currently selected maps.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
mapnames |
STRING |
* |
list of selected maps |
Sample
local mapnames = Image.Provider.Camera.V3SXX51Config.getMaps(config)getRemissionFilter()
Short description
Gets the Thresholds of the Remission Filter.
Parameters
| Name | Type | Multiplicity | Description |
|---|---|---|---|
config |
1 |
Configuration instance |
Return values
| Name | Type | Multiplicity | Description |
|---|---|---|---|
enabled |
BOOL |
1 |
Enable/Disable filter |
lowerThreshold |
FLOAT |
1</ |