General

General Usage

fluxEngine is distributed as as single Python module, and may be imported via:

import fluxEngine

Error Handling

Errors are reported via the RuntimeError exception class at the moment.

Initializing the Library

To initialize the library a license file is required. The user must read that license file into memory and supply fluxEngine with it.

The following code demonstrates how to properly initialize fluxLicense:

with open('fluxEngine.lic', 'rb') as f:
    licenseData = f.read()
handle = fluxEngine.Handle(licenseData)

Licenses tied to camera serial numbers

If a license is tied to a camera serial number, certain operations will fail unless the camera is currently connected. These operations include (but are not limited to):

  • Loading a model

  • Creating a processing context (even for offline processing)

  • Processing data with an already existing processing context

  • Loading a HSI cube from disk

For this reason, even if only offline data is to be processed, if a license file is tied to a camera serial number, the user must always first connect to that camera before performing any of these operations. The camera must stay connected while the user wants to perform any of these operations.

It is still possible to save HSI cubes to disk even if no camera is connected. This is to ensure that the camera fails unexpectedly during operation (because e.g. somebody unplugged it) to give the user a chance to save the data they curreently have in memory.

If the license is tied to a dongle or a mainboard serial, this does not apply, and these operations can be performed at any time after a handle has been created. (If a dongle is phyiscally removed after creating a handle, the same restrictions apply though.)

Setting up processing threads

fluxEngine supports parallel processing, but it has to be set up at the very beginning. This is done via the createProcessingThreads() method.

The following example code demonstrates how to perform processing with 4 threads, assuming a handle has already been created:

handle.createProcessingThreads(4)

Note

This will only create 3 (not 4!) background threads that will help with data processing. The thread that calls fluxEngine.ProcessingContext.processNext() will be considered the first thread (with index 0) that participates in parallel processing.

Note

Modern processors support Hyperthreading (Intel) or SMT (AMD) to provide more logical cores that are phyiscally available. It is generally not recommended to use more threads than are phyiscally available, as workloads such as fluxEngine will typically slow down when using more cores in a system than are physically available.

Note

When running fluxEngine with very small amounts of data, in the extreme case with cubes that have only one pixel, parallelization will not improve performance. In cases where cubes consisting of only one pixel are processed, it is recommended to not parallelize at all and skip this step.

Note

Only one fluxEngine operation may be performed per handle at the same time; executing multiple processing contexts from different threads will cause them to be run sequentially.

Since it is currently possible to only create a single handle for fluxEngine, this means only one operation can be active at the same time; though the limitation of only a single handle will be lifted in a later version of fluxEngine.