Skip to content

Inscoper NBO Library Documentation

The Inscoper NBO Library provides a comprehensive, type-safe data model for microscopy metadata, automatically generated from the NBO (4DN-BINA-OME) XSD schema. It offers a unified API across C++, Python, and Java, enabling developers to build applications that meet the rigorous traceability and reproducibility standards increasingly required by scientific publishers [1][2][3][4].

Overview

This library facilitates the adoption of the 4DN-BINA-OME specification, which extends the classic OME-XML model to provide enhanced descriptions of imaging techniques and production variability. By mapping the XSD schema directly to object-oriented classes, it bridges complex metadata specifications and practical software implementation.

flowchart LR
    subgraph Specs ["Metadata Specifications"]
        direction TB
        XSD["NBO XSD Schema<br/>(4DN-BINA-OME)"]:::spec
        MMA_IN["MicroMetaApp<br/>JSON Configuration"]:::spec
    end

    subgraph Lib ["Inscoper NBO Library"]
        direction TB
        GEN["xsd2cpp.py<br/>Code Generator"]:::gen
        CORE["C++ Core<br/>+ SWIG Interfaces"]:::core
    end

    subgraph APIs ["Language APIs"]
        direction TB
        CPP_A["C++"]:::lang
        PY_A["Python"]:::lang
        JA_A["Java"]:::lang
    end

    XML["NBO-XML"]:::out

    XSD -- "auto-generates" --> GEN
    GEN --> CORE
    MMA_IN -. "import" .-> CORE
    CORE --> CPP_A
    CORE -- "SWIG" --> PY_A
    CORE -- "SWIG" --> JA_A
    CPP_A --> XML
    PY_A --> XML
    JA_A --> XML

    classDef spec fill:#fff,stroke:#00a8cc,stroke-width:2px,color:#00a8cc,font-size:14px
    classDef gen  fill:#2b3a55,stroke:#26a9c9,stroke-width:2px,color:#ffffff,font-size:14px
    classDef core fill:#1a2744,stroke:#26a9c9,stroke-width:2px,color:#ffffff,font-size:14px
    classDef lang fill:#fff,stroke:#4ca64c,stroke-width:2px,color:#4ca64c,font-size:14px
    classDef out  fill:#fff,stroke:#e07c3a,stroke-width:2px,color:#e07c3a,font-size:14px

    style Specs fill:#2A3B47,stroke:#00a8cc,stroke-width:1px
    style Lib   fill:#2A3B47,stroke:#26a9c9,stroke-width:1px
    style APIs  fill:#2A3B47,stroke:#4ca64c,stroke-width:1px

Key Capabilities

  • Unified Data Model: Provides a consistent object model across multiple languages (C++, Python, and Java).
  • Standards Compliance: Ensures metadata adheres to modern quality control requirements.
  • MicroMetaApp Integration: Features direct import capabilities for MicroMetaApp configurations, instantly converting visual microscope setups into valid NBO Instrument objects.

The NBO Model

The NBO (4DN Nucleome BINA OME) model represents a significant evolution of the OME Data Model, developed jointly by the 4D Nucleome (4DN) Imaging Standards Working Group and the Bioimaging North America (BINA) Quality Control and Data Management Working Group.

It captures granular details regarding: * Instrument Hardware: Precise definitions of microscopes, detectors, light sources, objectives, and filters. * Acquisition Settings: Exact parameters such as exposure times, laser power, and channel configurations. * Experimental Context: Comprehensive tracking of sample preparation, reagents, and distinct experimental runs.

The library maps this XML schema directly into object-oriented classes, preserving the hierarchy and relationships defined in the XSD.

Code Generation

This library is auto-generated from the official nbo.xsd schema file using a custom generator script (xsd2cpp.py).

How it Works

  1. Parser: The script analyzes the XSD file, identifying all complex types, simple types, and element definitions.
  2. Mapping: It maps XSD types to C++ equivalents (e.g., xsd:string \(\rightarrow\) std::string, xsd:float \(\rightarrow\) float).
  3. Generation:
    • C++ Classes: Creates header (.h) and implementation (.cpp) files for every entity in the schema.
    • SWIG Interfaces: Creates .i interface files to establish bindings for Python and Java.

This approach ensures the code remains synchronized with the schema definition.

Adaptations & Design

The library adheres to the XSD structure. Several adaptations ensure the generated C++ code is modern, robust, and intuitive to use.

1. Modern C++ Standards

The generated code utilizes modern C++ (C++17/20) features: * Standard Types: XSD primitives are mapped to standard C++ types (std::string, int, double, bool, long long). * Smart Pointers: All complex objects are managed via std::shared_ptr. Developers rarely need to manage memory manually. * Example: Inscoper::NBO::InstrumentPtr is an alias for std::shared_ptr<Inscoper::NBO::Instrument>. * Optionals: Optional XSD attributes and elements are wrapped in std::optional<>, enabling explicit checks for their existence. * Vectors: Repeated elements (maxOccurs="unbounded") are stored in std::vector<>.

2. Handling 'Choice' Elements

XSD <choice> elements, where a field can be one of several types, are implemented using std::variant. * Type Safety: The library ensures only valid types can be assigned to a choice field. * Utility Methods: Helper methods like is<Type>(), as<Type>(), and set<Type>() are generated to simplify interaction with variants, removing the need for complex visitors.

3. Serialization

The library includes built-in support for serializing and deserializing data: * XML: Full support for reading/writing OME-XML (via pugixml).

4. Code Stability & Compilation Speed

The library employs the Pimpl (Pointer to Implementation) Idiom: * Encapsulation: Private members are hidden from the public header files. * ABI Stability: Changes to the internal implementation do not affect the binary interface (ABI). * Faster Compilation: Reducing dependencies in header files speeds up the build process for consumer applications.

5. MicroMetaApp Import

The library includes a feature to initialize an Instrument directly from a MicroMetaApp configuration file.

  • Concept: MicroMetaApp (MMA) allows users to visually configure their microscope hardware. This library can read the resulting JSON configuration and automatically populate the corresponding NBO Instrument object.
  • Mechanism: The fromMicroMetaAppJsonFile() method parses the JSON, maps MMA components to NBO elements, and fills in all available metadata (detectors, objectives, etc.) in compliance with the generated schema.
  • Usage: This reduces a potentially complex manual setup to a single function call, ensuring the metadata model matches the physical instrument configuration defined in MMA.
  • Validation: This feature is rigorously unit-tested across all three languages using a dataset of real-world microscope configurations. For every microscope in the dataset, Inscoper has created a manually verified "ground truth" XML. The tests automatically import the JSON configuration, re-export it as XML, and confirm that the result matches the ground truth exactly.

Multi-Language Support

SWIG (Simplified Wrapper and Interface Generator) wraps the native C++ library for high-level languages.

Python

  • Installation: pip install inscoper_nbo (see specific version)
  • Usage: The Python bindings are idiomatic. Developers can iterate over lists, access properties as attributes, and use standard Python types.
  • Dependencies: Requires the matching C++ shared libraries to be present or packaged (wheels accommodate this).

Java

  • Usage: Java classes mirror the C++ hierarchy.
  • Memory Management: The underlying C++ memory is managed automatically, but standard Java garbage collection rules apply to the wrappers.

Installation

C++

Work in progress

Java

Work in progress

Python

pip install inscoper_nbo-*.whl

Future Work

OME Compliance / Backwards Compatibility

Currently, the library focuses on the full NBO extension model, which offers richer metadata than the standard OME model. Inscoper is actively working on a feature to export these model objects as standard, OME-compliant XML, ensuring full backwards compatibility with legacy OME tools and viewers that do not yet support the NBO extensions.