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.

The diagram below illustrates the position of the Inscoper API within the broader Inscoper software ecosystem.

flowchart TB
    CFG["Inscoper Configurator"]:::configurator
    CONF["System Configuration"]:::conf

    subgraph Clients ["Access Layer"]
        direction LR
        IIS["Inscoper Imaging Software (IIS)<br/>Interactive interface"]:::iis
        API["Inscoper API<br/>Programmatic interface"]:::api
    end

    DC["Inscoper Device Controller"]:::dc
    HW["Microscopy Hardware<br/>cameras · stages · shutters · light sources"]:::hw

    CFG -- "generates" --> CONF
    CONF -- "loaded by" --> IIS
    CONF -- "loaded by" --> API
    IIS -- "acquisition sequences" --> API
    API -- "acquisition sequences" --> DC
    DC -- "device control" --> HW
    HW -- "images & status" --> API
    API -- "images & status" --> IIS

    classDef configurator fill:#fff,stroke:#00a8cc,stroke-width:2px,color:#00a8cc,font-size:15px
    classDef conf        fill:#fff,stroke:#ccc,stroke-width:1px,color:#444,font-size:13px
    classDef iis         fill:#fff,stroke:#4ca64c,stroke-width:2px,color:#4ca64c,font-size:15px
    classDef api         fill:#fff,stroke:#00a8cc,stroke-width:3px,color:#00a8cc,font-size:15px,font-weight:bold
    classDef dc          fill:#2b3a55,stroke:#26a9c9,stroke-width:2px,color:#ffffff,font-size:15px
    classDef hw          fill:#1a2744,stroke:#e07c3a,stroke-width:2px,color:#ffffff,font-size:13px

    style Clients fill:#2A3B47,stroke:#2A3B47,rx:12,ry:12

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
    subgraph Applications
        JA[Java Application]
        PA[Python Application]
        CA[C++ Application]
    end

    SB[SWIG Bindings]
    Core[Device Controller API<br/>C++ Core Library]
    HW[Device Controller / Hardware]

    JA --> SB
    PA --> SB
    CA --> Core
    SB --> Core
    Core --> HW

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.

Installation¶

C++¶

Work in progress.

Java¶

Work in progress.

Python¶

pip install inscoper_api-*.whl