Inscoper API Library Documentation¶

Overview¶

The Inscoper API provides a unified, type-safe programming interface for controlling microscopy hardware and managing image and sequence acquisition workflows. Inscoper implements it as a native C++ shared library with automatically generated bindings for Java and Python, ensuring consistent behavior and semantics across all supported languages.

The API is the programmatic counterpart to the Inscoper Imaging Software (IIS). While IIS provides an interactive graphical interface for acquisition workflows, the API exposes the same underlying capabilities for integration into custom software pipelines, automation scripts, and instrument control systems. Both rely on a hardware configuration generated by the Inscoper Configurator.

The API serves as the primary communication layer with the Inscoper Device Controller (the dedicated hardware appliance responsible for real-time device management and acquisition sequencing), abstracting low-level hardware interactions while enabling precise, reproducible control of microscopy devices for scientific and industrial imaging applications.

The API can be used in Standard Mode (unlicensed) for evaluation and basic development, or in Professional Mode (licensed) to unlock the full range of acquisition features and hardware control capabilities. See the License section for more details.

Prerequisites¶

Before using the Inscoper API, ensure the following conditions are met:

An Inscoper-certified installer has assembled and connected the microscopy hardware.
The Inscoper Configurator has been used to generate a system configuration file compatible with the target hardware setup.
The Inscoper Device Controller is connected, powered, and accessible on the network or host system.

If no hardware configuration exists, refer to the Inscoper Configurator documentation before proceeding.

Purpose¶

The Inscoper API is designed to:

Control and coordinate microscope hardware components.
Configure and execute image and multi-dimensional sequence acquisitions.
Provide a reproducible and traceable acquisition workflow.
Expose a stable, language-agnostic API for integration into diverse software environments.

Key Characteristics¶

Unified API across languages

A single C++ API exposed consistently to:
- C++
- Java (via a generated JAR)
- Python (via a generated Wheel)
Strongly typed interface

Public APIs are defined through explicit types, enums, and structured data models, reducing ambiguity and runtime errors across all language bindings.
Hardware abstraction

The API decouples application logic from hardware-specific implementations, providing a stable interface to:
- Cameras
- Illumination systems
- Motorized stages and focus devices
- Synchronization and triggering components
Deterministic acquisition control

Supports precise timing, sequencing, and synchronization, making it suitable for advanced microscopy workflows.

Architecture¶

The API centers on a C++ core library compiled as a shared library (DLL) and exposes a well-defined public interface through its headers. SWIG (Simplified Wrapper and Interface Generator) generates bindings for Java and Python, ensuring that all languages share the same underlying implementation.

graph TD
    JA[Java Application]:::app
    PA[Python Application]:::app
    CA[C++ Application]:::app
    JAPI[Java API]:::box
    PAPI[Python API]:::box
    Core[C++ API]:::core
    HW[Device Controller]:::box

    JA <--> JAPI
    PA <--> PAPI
    JAPI <-.->|"binding"| Core
    PAPI <-.->|"binding"| Core
    CA <--> Core
    Core <--> HW

    classDef app fill:#d0f0fa,stroke:#00a8cc,stroke-width:2px,color:#000,font-size:16px
    classDef box fill:#fff,stroke:#00a8cc,stroke-width:2px,color:#000,font-size:16px
    classDef core fill:#00a8cc,stroke:#00a8cc,stroke-width:2px,color:#fff,font-size:16px,font-weight:bold

    linkStyle default stroke:#00a8cc,stroke-width:2px

This design guarantees:

A single source of truth for device behavior.
Identical acquisition semantics across languages.
Long-term API stability.

Core Concepts¶

Acquisition Model¶

The API provides a structured acquisition model that enables applications to:

Define acquisition parameters.
Configure single image capture or complex acquisition sequences.
Start, monitor, and stop acquisitions.
Access acquired image data and associated metadata.

Supported acquisition patterns include, but are not limited to:

Single image acquisition.
Time-lapse sequences.
Z-stacks.
Multi-channel and multi-dimensional acquisitions.

Metadata and Traceability¶

Each acquisition carries structured metadata describing:

Hardware configuration.
Acquisition parameters.
Timing and sequencing information.

This metadata supports traceability and reproducibility, meeting the requirements of modern scientific imaging workflows and publication standards.

Language Bindings¶

C++¶

The C++ API provides direct access to all features. Use it for:

System-level integration.
Performance-critical applications.
Tight coupling with hardware control logic.

Java¶

The Java API is generated from the C++ headers and distributed as a JAR. It presents an idiomatic Java interface while preserving the structure and behavior of the underlying C++ API.

Python¶

The Python API is generated from the same C++ interface and distributed as a Wheel. It enables scripting, automation, and rapid prototyping while maintaining strong typing and consistent semantics.