Glossary
References
Devices
A device refers to a peripheral that can be either physical (hardware) or virtual. Each device is controlled by a driver and includes a sub-device responsible for its initialization (Init) and shutdown (Finish). A device may contain multiple sub-devices that perform various functions or actions. These can be either mechanical (e.g., moving a motor) or informational (e.g., retrieving values or version data). A hardware device can be connected either to the Inscoper Device Controller (DC) or directly to the PC (e.g., a USB camera).
Device Description
The device description is a structure summarizing all known information about a device. It is stored either in the firmware or within the driver, if applicable. The information includes:
| Field | Description |
|---|---|
| Driver | The type of driver used to control the device (see Driver Type). |
| Brand | The hardware manufacturer of the device. Example: Nikon for a Nikon microscope. |
| Model | The model(s) compatible with this device description. Example: Ti2 for a Nikon Ti2 microscope. Example: All models for Hamamatsu cameras that can be operated using the same driver. |
| Description | A short text describing the driver. |
| Author | The author of the device description. |
| Changelog | A manually maintained log of changes (no specific content convention). |
| Release Date | The date and time when the driver version was tagged. |
| Version | The version number of the driver. |
Detect
The Detect function scans all hardware connected to the computer that are compatible with the selected driver and retrieves their serial numbers. It allows the user to select the serial number corresponding to the device being added, ensuring the correct module is identified. This is particularly critical when multiple devices using the same driver (e.g., two Hamamatsu cameras) are present on the system. The Detect function is available only for custom drivers .
Diagnostic
The Diagnostic function performs two main tasks:
- It verifies that the device is properly connected to the device controller.
- It retrieves all sub-devices associated with the device, indicating whether each is available or unavailable.
Each sub-device can have one of three possible statuses:
| Status | Meaning |
|---|---|
| Available | The sub-device is detected and operational. |
| Unavailable | The sub-device is detected but not functional. |
| Unknown | The system cannot automatically determine the presence or absence of the sub-device. |
For custom drivers and Micro-Manager drivers, the function returns the list of device properties (equivalent to the list of available sub-devices).
For all drivers, the Diagnostic function updates parameter constraints such as minimum, maximum, and allowed values (list).
Camera
A Camera is a specialized device responsible for acquiring image data. In the Inscoper API, cameras are treated as high-level devices that manage image buffers, acquisition parameters, and triggering modes.
Trigger Device
A Trigger Device is used to provide precise control of a camera through triggering (TRIG) with the device controller. When installing a camera, two devices may be required:
- A Camera Device, which retrieves all camera functions and properties.
- A Trigger Device, which enables fine control and synchronization of the camera through hardware triggering by the DC.
If a camera is connected only via USB to the computer and not through the DC, only the camera device needs to be created, as trigger control is not handled by the Inscoper hardware in this case.
Camera Stream
A Camera Stream defines the method used to trigger image acquisition and control exposure timing. It determines whether the camera operates autonomously, responds to software commands, or synchronizes with external hardware signals.
| Stream Mode | Description |
|---|---|
| Internal | Used for Live or Snap operations (but not triggered Live). Also used for acquisitions not requiring specific hardware driving. |
| Software | The camera is triggered by a software command; exposure time is handled by the computer. |
| External Edge | The camera is triggered by an external TTL edge; exposure time is internal to the camera. Exposure cannot vary within a single sequence. |
| External Level | The camera is triggered by an external TTL level; exposure lasts as long as the trigger is asserted. Allows multiple different exposure times within one sequence. |
Start Acquisition
A function that sets the camera to image acquisition mode. Unlike "Snap," which captures a single image, this starts continuous image acquisition (Live). This is useful when a continuous stream of images is required. Note that images may not be acquired immediately, depending on the camera's trigger mode (Internal, Software, Edge, Level).
Stop Acquisition
A function that stops the current acquisition mode of the camera.
Snap
A function to capture a single image.
Camera Stream Definitions
Software Trigger
The sub-device used for image capture in software stream mode. The image capture signal is sent via software rather than an electronic signal.
Edge Trigger
The sub-device used for image capture in external edge stream mode. A short electronic signal is sent to start image capture.
Level Trigger
The sub-device used for image capture in external level stream mode. An electronic signal with a duration equal to the exposure time is sent to start image capture and control the exposure duration.
Check Ready
A sub-device that waits for the camera to signal it is ready to take the next picture. It waits for an electronic signal from the camera (often called "Trigger Ready") or uses a timer delay if the camera does not provide such a signal. This ensures the system waits until the camera is ready before sending the next trigger signal.
Is Controlled
A function used when the camera's external triggers are controlled by a device other than the Inscoper Controller (DC).
Select For IIS
Automatically selects the subset of sub-devices/functions that are useful for controlling the camera with the Inscoper software (IIS). This is available only for custom drivers.
Shutter
A motorized element in the microscope or an external component that allows the light source beam to pass through or be blocked.
Update Only When Imaging
When enabled for a shutter, the "Open" status is sent only while the camera is actively acquiring images, even if the shutter is set to "On" in the software. Otherwise, it remains closed to preserve the sample.
Device Controller
Firmware
Software operating within the Device Controller (DC) that enables the execution of sequences sent by the IIS. While the firmware offers many functionalities (providing device descriptions, restarting the box, etc.), its primary role is to execute pre-received sequences.
Drivers
External Resources
Path to the directory on the computer where Micro-Manager and custom drivers (DLL files) are stored.
Drivers Type
Custom
Custom driver
Drivers that have been integrated directly via their SDK and are controlled on the computer. This primarily applies to cameras.
µManager
Drivers for controlling devices using Micro-Manager.
Module Name
"Module Name" and "Device Name" are concepts specific to Micro-Manager.
Inscoper Box
Drivers that operate inside the Device Controller (DC).
Hardware ID
A unique identifier for a given hardware model.
Sub Devices
A sub-device is a functional component within a device that represents a controllable property, capability, or action. Sub-devices are the fundamental building blocks that allow the Inscoper system to interact with hardware at a granular level.
Core Concept:
While a device represents an entire piece of hardware (e.g., a motorized stage, a camera, or a filter wheel), a sub-device represents a specific aspect or function of that hardware. This modular approach allows complex devices to be controlled through simple, well-defined interfaces.
Categories of Sub-Devices:
1. Property Sub-Devices (State/Value Access)
Represent readable or writable properties of the hardware:
- Camera exposure time
- Stage X, Y, or Z position
- Filter wheel position
- Shutter open/closed state
- Objective turret position
- Device firmware version number
2. Action Sub-Devices (Commands/Operations)
Represent operations or commands that don't necessarily correspond to a single property:
MoveXY- Triggers coordinated movement of both X and Y axesStartAcquisition- Initiates camera image captureStopAcquisition- Halts ongoing acquisitionInitialize- Performs device initialization sequence
3. Virtual Sub-Devices (Software-Defined)
Exist purely in software without direct hardware correspondence:
- Calculated values derived from multiple hardware readings
- Software-managed state flags
- Version information and metadata
- Diagnostic status indicators
Examples:
A motorized XY stage device might contain these sub-devices:
XPosition(property) - Current X-axis position in micrometersYPosition(property) - Current Y-axis position in micrometersXResolution(property) - Step size for X-axis movementYResolution(property) - Step size for Y-axis movementMoveXY(action) - Command to execute coordinated movementVersion(virtual) - Firmware version string
A camera device might contain:
Exposure(property) - Exposure time in millisecondsBinning(property) - Pixel binning factorROI(property) - Region of interest coordinatesStartAcquisition(action) - Begin capturing imagesStopAcquisition(action) - End image captureSnap(action) - Capture a single image
Properties
Status
Indicates whether a sub-device is present or not for a device.
| Status | Meaning |
|---|---|
| Available | The sub-device is detected and operational. |
| Unavailable | The sub-device is detected but not functional. |
| Unknown | The system cannot automatically determine the presence or absence of the sub-device (e.g., after a diagnostic check failed to verify status). |
| Partially Available | Only some functions of the sub-device are available. |
Param
- Property Name: The name of a configurable parameter for a sub-device (e.g., "Exposure" for a camera's exposure time). This is valid only for external drivers (Custom and Micro-Manager). It is always FIXED for IIS, though not necessarily for API use.
- Property Value: The value assigned to a property (e.g., "200ms"). Valid only for external drivers. The default value is set when IIS starts but can be modified by the user.
- Example: To start a camera in "Fast Mode" upon IIS launch, set Property Name = "Read Mode" and Property Value = "3".
- Default: The default value of the parameter.
- Fixed: If checked, the sub-device’s value cannot be modified.
- Example: For a 3-axis controller, three sub-devices are created. The axis number (name) is marked as Fixed for each, while the position value remains editable.
- Note: There should never be two unfixed parameters in one sub-device.
- Min: The minimum allowed value. Defined by the device creator (based on the datasheet) or provided by the driver/Micro-Manager.
- Max: The maximum allowed value. Defined by the device creator (based on the datasheet) or provided by the driver/Micro-Manager.
- Step: Minimum increment for value update.
- The type of constraint can define the step; e.g. for integer constraint type, the default step is 1 (the step is induced by value type). If no step is provided by the firmware/drivers, IIS takes either step = 1 (if integer) or step = (max - min) / 1000 (for float).
- Type: (parameter type, among:), unsigned char, double, STRING
Description
Name
Name of the sub-device.
Type
Flags/tags to characterise the nature of a subdevice.
Lifecycle / System
| Type | Description |
|---|---|
| NONE | No specific category or behavior associated with this sub-device. |
| INIT | Sub-device that triggers the device initialization sequence. |
| FINISH | Sub-device that triggers the device shutdown sequence. |
| DIAG | Sub-device that executes the diagnostic (DIAG) procedure. |
| USB_CHECK | Verifies that the USB device is connected and responsive. |
Motion & Axis Control
| Type | Description |
|---|---|
| X_AXIS | Represents movement or positioning along the X axis. |
| Y_AXIS | Represents movement or positioning along the Y axis. |
| MOVE_AXIS | Generic movement command for an axis (X, Y, Z, or other). |
| FOCUS | Controls the focus mechanism (typically Z axis). |
Optical / Hardware Components
| Type | Description |
|---|---|
| SHUTTER | Controls opening and closing of a shutter. |
| OBJECTIVE | Selects or controls a physical objective lens. |
| CUBE | Controls filter cubes or optical paths. |
| FILTER_WHEEL | Selects filter positions using a rotating wheel. |
| MAGNIFICATION | Handles magnification settings (e.g., objective changer, zoom optics). |
| PROPERTY | Generic hardware property used for reading/writing vendor-specific parameters. |
Triggering & Synchronization
| Type | Description |
|---|---|
| TRIG_EDGE | Trigger based on a digital edge (rising/falling edge). |
| TRIG_LEVEL | Trigger based on a digital level (high/low). |
Camera Operations
| Type | Description |
|---|---|
| CAM_CHECK_READY | Checks whether the camera is initialized and ready for acquisition. |
| CAM_START_CONTINUOUS | Starts continuous acquisition mode (Live). |
| CAM_START | Starts a single-sequence acquisition. |
| CAM_STOP | Stops acquisition (Live or sequence). |
| CAM_SNAP | Camera snap sub-device: performs a single image capture. |
| CAM_SOFTWARE_TRIG | Software-triggered image acquisition sub-device. |
Functions (Set/Get/Check)
Functions
| Function | Description |
|---|---|
| Set | Assigns a new value to the device (e.g., moves an objective lens, opens a shutter).<br>Example: Sending 0 or 1 to a shutter sub-device to close or open it. |
| Get | Retrieves the current value from the device. |
| Check | Verifies whether a SET function completed successfully by repeatedly calling GET until the retrieved value matches the expected target.<br>Example: Waiting until a stage's X-axis position matches the requested position. |
For each function, there are:
- Input Params: Parameters sent to the function.
- Output Params: Parameters returned by the function.
Connections
A Connection defines the physical or logical communication channel used to control a device and exchange commands with it. Connections establish the link between a device and the Inscoper Device Controller (DC), enabling the system to send control signals and receive status information.
Key Concepts:
- Each device is configured with one or more connections that specify how it communicates with the DC
- Sub-device functions (SET, GET, CHECK) are executed through these defined connections
- The connection type determines the protocol, signal characteristics, and data flow direction
- Different connection types support different capabilities (digital signals, serial communication, analog values, etc.)
| Type | Signal Type | Direction | Description |
|---|---|---|---|
| TTL_IN_GEN | Digital (0-5V) | Input | Digital signal read by the Device Controller from external hardware. Used for reading trigger signals, limit switches, or sensor states. |
| TTL_OUT_GEN | Digital (0-5V) | Output | Digital signal sent by the Device Controller to external hardware. Used for triggering cameras, controlling shutters, or activating relays. |
| SERIAL | Serial Data | Bidirectional | RS232 or USB serial connection for command-based communication. Supports both sending commands and receiving responses. |
| USB_GENERIC | USB Protocol | Bidirectional | Standard USB connection requiring manufacturer-specific drivers. Used for devices with proprietary USB protocols. |
| USB_SERIAL | USB Serial | Bidirectional | USB connection emulating a serial port (Virtual COM Port). Combines USB convenience with serial protocol compatibility. |
| USB_HID | USB HID | Bidirectional | USB Human Interface Device protocol. Used for devices that present themselves as HID-class peripherals. |
| AIN | Analog | Input | Analog voltage input to the Device Controller. Used for reading sensor values, potentiometer positions, or other analog signals. |
| AOUT | Analog | Output | Analog voltage output from the Device Controller. Used for controlling variable-intensity light sources, motor speeds, or other analog-controlled devices. |
| UART | Serial Data | Bidirectional | Universal Asynchronous Receiver-Transmitter (RS232) connection. Low-level serial communication protocol. |
Usage Example:
A motorized filter wheel might use:
- SERIAL connection for sending position commands and receiving status
- TTL_IN_GEN connection for reading a home position sensor
- TTL_OUT_GEN connection for triggering movement completion signals
Inscoper Imaging Software
This tab allows you to set up Inscoper Imaging Software (IIS). You can:
- Define and modify graphical elements.
- Activate modules such as tiling options or virtual joysticks.
- Configure advanced calibrations linking sub-devices.
- Set up the graphical representation of sub-devices in IIS (e.g., relabeling objectives, adding side ports/filter cubes, representing laser power with sliders).
This section is divided into: Display, Group, Devices Update, Image Scaler, and Calibration.
Display
The Display tab allows you to add, modify, and organize the graphical representations of sub-devices in IIS.
Initialize
The Initialize button adds all available sub-devices defined in the configuration to the device display list. This allows you to modify how a function is displayed in the software. Note: Upon configuration creation, the display data list is empty and must be initialized.
Update
If new devices are added to an existing configuration, the Update button automatically adds their associated sub-devices to the device display list.
Image Scaler
A sub-device that enlarges or reduces the image size.
- Image Scaler Mult: A sub-device that enlarges the image size (e.g., lenses or objectives that produce image reduction).
- Inv: A sub-device that reduces the image size (e.g., lenses or objectives that produce image magnification).
Calibration
A model used to link two or more sub-devices.
Type
| Type | Description |
|---|---|
| Linear | sd1 = a * sd2 or sd1 = a * sd2 + b
(Linear formula). |
| Linear Delta | Same as Linear, but presented differently to expose the alpha parameter in IIS (used only for SoSPIM). |
| Bilinear | Represents a 3D plane (ax + by + c). |
| Linear Piecewise | Allows for curve approximation. |
| Constant | Applies a fixed parameter between two devices. |
| Formula | Allows entry of a custom formula. |
Interpolator
Interpolators are the sub-devices used in formulas to compute new values (the
sub-device that is not the objective). Example: In sd1 = a * sd2 + b
:
sd1is the target.sd2is the interpolator.aandbare computed during calibration.
Discriminant
A discriminant is a sub-device that, if modified, invalidates the current calibration. Each calibration is saved for a specific combination of discriminant values. Example: In a FRAP calibration, changing the objective or filter requires a new calibration.
Target
The sub-device that will be modified by the calibration. It is linked to an interpolator.
Complex Acquisition Available
Enables the "Complex Acquisition" / "Acquisition Designer" module if the customer has purchased the option. This module allows for advanced imaging workflows not possible with basic MDA. The module will not appear if the license does not include it, regardless of this checkbox.
Mosaic Manip
Activates Tiling options in IIS. The Tiling Dimension will appear in the graphical interface. A 5D license is required.
XY Move Strat Available
Adds an option to move the stage gradually during large movements. This reduces potential drift and prevents autofocus systems from losing track during motion.
Trigger Live Conditions
Associates a sub-device value with a condition, allowing other devices to be controlled during the camera’s live trigger sequence. Example: Trigger live acquisition only if the fluorescence shutter is open, or apply a condition based on the side-port position.
Reset USB at Startup
If checked, USB connections are reset each time IIS is opened.
Device Update
This tab allows you to select devices to be updated automatically. The interface will query the drivers (DC, Custom, Micro-Manager) to update the device value by calling the GET function at the interval specified in the "Delay (ms)" column.
Connections
Link your device to the Device Controller. Available connections for a selected device are highlighted in green.
USB View
- Serial/Digital/Analog
- PID/VID: Product ID and Vendor ID. Any USB device provides these values, along with Manufacturer, Product, and Serial Number. They are used to identify and distinguish USB peripherals.
Recipe
A structured set of instructions defining system operation, including action order, execution conditions, and sequence optimization. It defines how statuses are applied.
Recipe Element
A single unit within a recipe that associates a sub-device with one or more actions.
Action
Defines which sub-device function to execute or which recipe ID to set.
- Sub-device / Recipe Id: The target sub-device or group.
- Function: The operation to perform (SET, GET, CHECK).
- Default value: Relevant only for SET. Usually left empty for user input, but can be set for specific recipes (e.g., "Close shutter" = 0).
Type
- Simple: Contains only one element.
- Group: Calls a combination of recipes.
- Event: A Recipe Element that allows for sequence interruptions. It handles user events such as Pause, Stop, or Restart during a sequence.
Call ID
An identifier used in callConditions to determine if a recipe has
been executed.
Example (Motion Stages):
Recipe Set X -> callID = setX Recipe Set Y -> callID = setY Recipe
MoveAxis -> callCondition = setX || setY
Example (Shared Call ID):
Recipe Set X -> callID = axisMoved Recipe Set Y -> callID = axisMoved
Recipe MoveAxis -> callCondition = axisMoved
Recipe ID
An identifier assigned to one or more sub-devices. Historically used to group devices (e.g., all shutters), it is now mostly used for sub-devices created dynamically when IIS launches (e.g., timing devices, abstract sub-devices for scripting).
Tag
A label or identifier used to categorize and filter recipe execution based on the current system state or configuration. Tags are added to statuses and used in tag conditions to ensure that only relevant recipes are executed for the active devices or modes. Example: When using a specific camera model, its tag (e.g., "Fusion" or "Panda") is added to the status, ensuring only recipes with matching tag conditions are executed.
Condition
A graphical section grouping condition options for calling recipes.
Tag Condition
Ensures an action is executed only if a specific tag is present in the status. Example: If a sequence uses the "Fusion" camera, the tag "Fusion" is added to the status. Recipes requiring the "Panda" tag will not be executed, ensuring only the correct camera devices are used.
Call Condition
Ensures an action is executed only if a specific previous action has occurred.
Value Condition
Determines whether an action is executed based on a sub-device's value. Example: Change light source intensity only if the shutter is open. If the shutter is closed, the intensity change is skipped.
Optimization
Prevents reapplying a recipe if the sub-device value has not changed between two statuses. Example: Do not send XY coordinates again if they are identical to the previous position.
ILDA
Controls the Ilas and Starscan modules.
Mode
Describes the different illumination modes available in the system.
Illumination Mode
Adds a virtual device to select the illumination mode (e.g., FRAP, TIRF, Spinning Disk) in a multimodal system.
FRAP
- Scanrate: Controls the time between two points (galvo instructions).
- Diameter: Controls the distance between two points during a scan.
- Density Index: An index indicating the mode (FRAP, TIRF, WF, Spinning Disk) when sharing the scan rate sub-device. Must match the FRAP diameter value in the Device tab.
- Fire Preview: Enables the fire preview function (continuous scanning of an ROI).
- Active Channel Element: Indicates which channel is the FRAP channel. Must be activated for each illumination mode.
TIRF
- Angle (formerly Tirf Angle): The position of the point (or arc) on the circle traversed by the galvos.
- Diameter (formerly Interpoint Distance): Controls the distance between two points during a scan.
- Scanrate (formerly Pulse Time): Controls the time between two points.
- Density Index: (Obsolete after 9.3).
- Radius (formerly Penetration Depth): Corresponds to the laser angle at the lens outlet.
- Angle Length (formerly Tirf Mode): The length in degrees of the circle made by the galvos.
- Active Channel Element: Indicates which channel is the TIRF channel.
API
The Inscoper API (Application Programming Interface) is a comprehensive C++ library that enables external software to interact with and control the Inscoper system. It acts as a bridge between high-level applications (such as the Inscoper Configurator or third-party software) and the underlying hardware drivers.
Key Architectural Concepts:
- Bridge Pattern: The API exposes a single main entry point, the
Inscoper::Bridgeclass, which simplifies interaction by abstracting the complexity of internal subsystems. - Manager-Based: Core functionalities are handled by specialized singleton managers
(e.g.,
ConfigManagerfor settings,DeviceManagerfor hardware,SequenceManagerfor acquisition workflows). - Device Abstraction: The API provides a unified interface (
AbstractSystem) for all devices, regardless of whether they are controlled by Inscoper hardware, Micro-Manager, or custom drivers.
Core Capabilities:
- Configuration: Loading and saving system states via XML files.
- Control: Direct manipulation of device parameters (SET/GET/CHECK).
- Acquisition: Execution of complex, multi-dimensional acquisition sequences and recipes.
- Imaging: Management of image buffers, metadata, and pixel formats.
- Events: A listener system (
SequenceListener,ImageListener,ErrorListener) for real-time feedback and synchronization.
Log Level
Indicates the importance of a log message. Log levels are inclusive (e.g., enabling DEBUG also enables INFO, WARN, ERROR, FATAL).
| Log Level | Description |
|---|---|
| LOG_ALL | Enables all log levels. |
| LOG_TRACE | The most fine-grained information, used only for deep debugging (e.g., annotating algorithm steps or individual queries). |
| LOG_DEBUG | Less granular than TRACE but more detailed than INFO. Useful for diagnosing issues and troubleshooting in test environments. |
| LOG_INFO | Standard log level indicating normal application events (e.g., "Authorization successful"). Purely informative; missing these logs should not hide critical issues. |
| LOG_WARN | Indicates an unexpected situation that does not stop the application (e.g., "Parsing error, document skipped"). The process continues, but the event is noteworthy. |
| LOG_ERROR | Indicates an issue preventing specific functionalities from working (e.g., "Payment system unavailable"). The application may still run, but features are broken. |
| LOG_FATAL | Indicates a critical failure where core functionality is lost (e.g., "Database connection failed"). The application cannot perform its primary business functions. |
| LOG_OFF | Disables all logging. |