Layers

The OneLightToolbox takes on a couple of different roles in our project architecture. For cleaner, more flexible code, we will separate these roles into multiple modules of abstraction

1. Core OLLibrary

The core function of the OneLightToolbox, is to provide an interface to the OneLight devices. While the actual interfacing is done using a MEX/C OneLightDriver toolbox, the OLT provides an object-oriented MATLAB API for OneLight devices.

1.1. Concepts

The OLLibrary "thinks" in the following concepts:

• OneLight objects:
• starts/stops:
• settings:
• primary values:
• calibrations: struct defining how to convert between primary values, settings, and starts/stops. These concepts are device and calibration specific.

2. Directions, backgrounds, modulations

A first layer of abstraction over the core library encapsulates our most common use of the OneLights.

2.1. Concepts

The first layer of abstraction "thinks" in the following concepts:

• direction: a direction of modulation, defined as three vectors in primary space: the background primary values (see below), the positive differential values, and the negative differential values. The positive and negative component of the direction are defined separately, because they can be asymmetric. The background is an inherent part of the direction, as it is used to generate the direction. Saved as a struct, with fields backgroundPrimary, differentialPositive, differentialNegative, and describe.

• background: the background of modulation: a vector in primary space, away from which the direction is defined. Save as a single numerical vector backgroundPrimary.

• contrast:

• waveforms:

• modulations:

These concepts are device and calibration specific.

3. Parameterization

While directions, backgrounds and temporal waveforms can be used regardless of how they are generated, we often generate them from parameters. An additional layer of abstraction provides functions for generating directions, backgrounds, and temporal waveforms from parameters.

3.1. Concepts

The parameterization layer of abstraction "thinks" in the following concepts:

• directions: see 2.1
• backgrounds: see 2.1
• waveforms: see 2.1
• parameters: (sets of) parameters that can be used to generate backgrounds, directions, waveforms. This are stored in structs. Parameters are device and calibration independent. This layer also provides functions to create directions/backgrounds/waveforms from these parameter structs, e.g., OLBackgroundPrimaryFromParams.

3.2. Dictionaries

Dictionaries associate names with sets of parameters, so that the same parameters can be recycled.

3.3. Caching

Directions and backgrounds generated from parameters can be cached for speed and convenience. Cachefiles store the direction/background information, the calibration, and the parameters used to generate them. Cached directions/backgrounds are retrieved by specifying a cachefilepath, the parameters, and a calibration. The OLCache system checks whether the specified cachefile contains the same parameters and calibration as specified. If yes, the cachefile is valid and not stale, and the direction/background data is retrieved. If no, the cachefile does not match or is stale, and no data is retrieved.