Getting started with the API

To setup a new project:

• Add the LynceeTec.API and LynceeTec.API.Sequence packages to your project.

• If working online (i.e., using the DHM hardware), also add the LynceeTec.API.Hardware packages to your project.

• The other required Lyncée Tec and third party packages will be referenced automatically.

• Do not forget to include a log for debugging! See tip below.

Tip

Lyncée Tec libraries use log4net for logging. In the future, we want to switch to Serilog. Therefore, we recommend that you use Serilog and our help classes to produce a Serilog log which also includes our legacy log4net log to help debug your work with the API. See How to redirect log4net log to Serilog for details on how to redirect log4net logs to Serilog Both log4net and Serilog libraries are available as a NuGet package, which are automatically installed by the main Lyncée Tec packages.

The LynceeTec.API API is the entry point for the Lyncée Tec APIs. It setups the environment for any software using the API. It is the link between the user code and the database. (Here “database” must be understood as the larger definition, meaning the database file itself, but also all the other data necessary to work offline).

This API provides all the data necessary to work offline (reconstruction from previously acquired data only), so that the Hardware API can be completely omitted in that case.

The Environment class is the entry and exit point for any program working with the Lyncée Tec APIs. See the Start(String, SecureString, String) and End functions.

This API is only necessary for "online" work, i.e., when acquiring holograms.

It provides all the functionality to initialize and work with the DHM hardware.

It can be completely omitted if working strictly offline (reconstruction from previously acquired data only).

The entry point for this API is the HardwareManager class. It instantiates and initializes the underlying hardware SDK classes and provides access to any hardware status or interaction with your software.

Each hardware type (camera, laser source, motor, stage, turret, stroboscopic tool and fluo filter wheel) has a "manager", which manages all the items (instances) of that hardware type. All managers implement the IHardwareItemManagerTHardwareItem interface and are accessed via properties of the HardwareManager class (CamerasManager, LaserSourcesManager, MotorsManager, StagesManager, TurretsManager, StrobosManager, FluoFilterWheelsManager).

The items managers of each hardware type implement the IReadOnlyDictionary interface: each hardware item instance is accessible through the dictionary with its unique identifier (UniqueId) as key.

The items managers have several status flags, available individually or grouped in the Status property. The managers’ status depends on their sub-items status

The managers are all designed to manage a list of several items, even if for the moment the SDK below only supports a single item. (This is the case for camera, stage and the stroboscopic module.)

All hardware items implement the IHardwareItem interface.

The items have several status flags, available individually or grouped in the Status property.

Caution
The API does not yet provide full status information for each hardware type. This is due to the underlying SDK which is currently being improved. To distinguish between a false and an unknown state, the status flags do not return boolean values, but a member of the ExtendedBool enum, which contains a Unknown element.

Each hardware item (instance) has a unique identifier.

Caution
For the moment, Basler cameras are the only hardware with real unique ids that can be read from the device. All other hardware instances use placeholder unique ids, such as "lambda1" or "PriorStage". The SDK will be extended in the near future to allow real unique id identification for each hardware element.

For each item (instance), an individual HardwareItemUsage can be defined:

• Real: The program will connect and interact with the physical device. Errors will occur if not physical device is connected

• DummyWithTimeDelay: The program will simulate the physical device, including the time it would take the physical device to execute the command. Any function can be called and have a more or less realistic effect so that a program can run from start to finish for debugging purposes

• Dummy: The program will simulate the physical device but not the time it would take the physical device to execute the command. (For example a Dummy motor move would be instantaneous). Any function can be called and have a more or less realistic effect so that a program can run from start to finish for debugging purposes

• External: Placeholder for hardware device managed by non-Lyncée Tec code.

• NotUsed: The instance will not be created.

Caution
Any hardware can have it's usage set to Dummy or DummyWithTimeDelay and the hardware initialization will work without error. However, the implementation of dummy classes for all hardware is still a work in progress and some functions might be missing for the moment.

The API does not create an Online or Offline DHM device based on the dongle, but an instance of the DHMDeviceHybrid class, which receives a usage for each item (grouped in the DHMHardwareItemsUsage class), allowing it to have a mix of Real and Dummy items.

The items defined in the DHMHardwareItemsUsage instance must correspond to the definition in the Enabled Modules and Hardware Configuration. The API automatically checks for incoherency at init.

In the case of an incoherence, the database definitions have precedence:

• If the item is defined in the Enabled Modules or Hardware Configuration and no usage is found for it, an exception is thrown

• If the item has a usage, but there is no corresponding definition in the Enabled Modules or Hardware Configuration, it will be ignored and the instance will not be created.

There are several help classes and constructors which allow to populate the DHMHardwareItemsUsage, either based on the Enabled Modules and Hardware Configuration or via a .json configuration file

The Sequence API is used for everything related to holograms manipulation: acquisition, reconstruction and recording.

Please refere to the documentation in the LynceeTec.API.Sequence namespace. In particular to the diagrams in BaseSequenceManager and it's derived types: LiveAcquirer, ContinuousSequenceRecorder, TriggeredSequenceRecorder and SequenceLoader

The following section shows how to use the API in your code. Please refer to the API examples for more details.

Caution
For the moment, the Lyncée Tec APIs mostly return the non-specific Exception. In future releases, exceptions will be differentiated for better handling by user code.

using LynceeTec.Eucalyptus;
using LynceeTec.DHM;

//Starts the Lyncée Tec API environment and caches a reference to the config manager
//(caching is useful for the initialization of the Hardware API, but not necessary)
IConfigManager configManager = LynceeTec.API.Environment.Start(userName, userPassword, databasePath);

//Check if working Online or Offline. In Offline mode, Hardware API can be omitted completely
if(LynceeTec.API.Environment.IsDongleOffline)
{
    #region If using hardware (working online, doing acquisition)

    //Automatically initializing the DHM's hardware items defined in the database to the same usage for all
    //(usage can be defined individually for each item, but this function is useful for quick tests)
    DHMHardwareItemsUsage dhmHwItemsUsage = new DHMHardwareItemsUsage(configManager, HardwareItemUsage.Dummy);

    //You can also define a different usage for each type of hardware item, for example Real for cameras and laser sources, and Dummy for all others:
    //DHMHardwareItemsUsage dhmHwItemsUsage = new DHMHardwareItemsUsage(configManager, HardwareItemUsage.Real, HardwareItemUsage.Real,
    //    HardwareItemUsage.Dummy, HardwareItemUsage.Dummy, HardwareItemUsage.Dummy, HardwareItemUsage.Dummy, HardwareItemUsage.Dummy);

    //Uncomment the line below for another useful option: the use of a .json configuration file defining the usage of each hardware item
    //The file must reflect the hardware definitions in enabled modules
    //DHMHardwareItemsUsage dhmHwItemsUsage = DHMHardwareItemsUsage.CreateInstanceFromConfigurationFile("DHMHardwareItemsUsage.json");

    //You can generate a "starting version" of the .json file for your DHMHardwareItemsUsages by using the "create from database constructor"
    //as above, and then save the result with the line below. You can then edit it manually
    //dhmHwItemsUsage.SaveToConfigurationFile("DHMHardwareItemsUsage.json");

    //This function can take time to execute when real hardware is connected. In a real application, executing it
    //in a separate thread is recommended
    LynceeTec.API.Hardware.HardwareManager.Init(configManager, dhmHwItemsUsage);

    #endregion
}

//Cleanly ends the Lyncée Tec API session and disposes of resources

if (LynceeTec.API.Hardware.HardwareManager.IsInitialized)
    LynceeTec.API.Hardware.HardwareManager.Close();

if (LynceeTec.API.Environment.IsStarted)
    LynceeTec.API.Environment.End();

Lyncée Tec provides sample programs to show how to use the API. All the API examples use the new reconstruction, as implemented in the InterfaceProcessiongV2 package.

Caution
The InterfaceProcessingV2 package, which implements the new reconstruction, is still in development and must be considered a beta. Its result does NOT always correspond to results obtained with Koala, because the underlying computation is different.

• APISimpleExampleOffline: basic usage of the API, showing the streamlined initialization for offline use only (using previously recorded holograms).

• APISimpleExample: basic usage of the API, both online (with a connected DHM) and offline (using previously recorded holograms).

• APISequenceExample: WPF example showing how to use the Sequence API for acquisition, management and reconstruction of hologram sequences.

Reference