Skip to content

Inscoper LiMi Library

The Inscoper LiMi Library is a data model for microscopy metadata, generated from the XSD schema of the Light Microscopy (LiMi)-Model. The LiMi-Model, formerly the NBO (4DN-BINA-OME) model, is curated and maintained by QUAREP-LiMi through its Working Group 7 (Metadata). It builds on the tiered metadata specification published by Hammer et al. in Nature Methods 1. For current QUAREP-LiMi activities around the model, see the QUAREP-LiMi workshops at ELMI. The library exposes the same model in C++, Python, and Java, so an application can record the metadata that journals and imaging facilities increasingly require2345.

The library reads and writes NBO-XML, and imports MicroMetaApp configurations directly: a single call turns a visual description of a microscope into a valid Instrument object, in C++, Python, or Java alike. Inscoper distributes it free of charge, under the Apache License 2.0, for integration into any acquisition software, analysis pipeline, or facility tooling. See Availability and License.

flowchart LR
    classDef source  fill:#fff,stroke:#00a8cc,stroke-width:1.5px,color:#222,font-size:12px
    classDef tool    fill:#00a8cc,stroke:#00a8cc,stroke-width:2px,color:#fff,font-size:12px
    classDef core    fill:#00a8cc,stroke:#00a8cc,stroke-width:4px,color:#fff,font-size:13px,font-weight:bold
    classDef binding fill:#fff,stroke:#00a8cc,stroke-width:1.5px,color:#222,font-size:12px
    classDef doc     fill:#fff,stroke:#00a8cc,stroke-width:3px,color:#222,font-size:12px,stroke-dasharray:5 4

    XSD["nbo.xsd<br/>LiMi-Model schema"]:::source
    GEN["xsd2cpp.py"]:::tool
    CORE["C++ core<br/>Instrument · Acquisition · Sample"]:::core
    MMA["MicroMetaApp<br/>JSON configuration"]:::source
    XML["NBO-XML"]:::doc

    subgraph Bindings ["Language bindings"]
        direction TB
        PY["Python"]:::binding
        JA["Java"]:::binding
    end

    XSD -- "parsed by" --> GEN
    GEN -- "generates C++ classes · SWIG interfaces" --> CORE
    CORE -- "SWIG" --> PY
    CORE -- "SWIG" --> JA
    MMA -. "imports into an Instrument" .-> CORE
    CORE -- "reads · writes" --> XML

    linkStyle 0 stroke:#00a8cc,stroke-width:1.5px
    linkStyle 1 stroke:#00a8cc,stroke-width:2px
    linkStyle 2 stroke:#00a8cc,stroke-width:1.5px
    linkStyle 3 stroke:#00a8cc,stroke-width:1.5px
    linkStyle 4 stroke:#5b9aa0,stroke-width:1.5px,stroke-dasharray:5 4
    linkStyle 5 stroke:#00a8cc,stroke-width:2px

    style Bindings fill:#f5fafc,stroke:#cfe9f1,rx:12,ry:12

What the model records

A microscopy image does not record how it was produced: nothing in the pixel data states which instrument, which settings, or which sample it came from. The LiMi-Model extends the OME Data Model and describes an imaging experiment in three parts.

Part Records Main elements
Instrument hardware The microscope itself: stand, objectives, detectors, light sources, and filters Instrument, Objective, Detector, LightSource, Filter
Acquisition settings The parameters a given acquisition ran with: exposure times, illumination power, and channels Image, Pixels, Channel, Plane
Experimental context The sample and the experiment around it: preparation, reagents, and runs Experiment, Sample, Reagent

Two consequences follow. An acquisition resolves to hardware: a channel references the detector it was read out on, the light source and its wavelength, and the optical path, rather than a label such as Channel 2. And because the three parts are separate, a facility describes its microscope once and references that description from every acquisition. See The LiMi-Model for the tier system and for the parts of the schema the library does not enforce.

How the library is generated

xsd2cpp.py reads nbo.xsd and writes the C++ classes, then SWIG wraps them for Python and Java. Nothing is written by hand, so the code cannot drift from the schema, and the object tree in code has the same shape as the document on disk. Validation is part of the model: a restricted value is checked when it is set, and required attributes are checked on import and on export. The library validates field by field and does not run a full XML Schema validation, and it does not carry the tier annotations into the generated classes. See The LiMi-Model for what the schema contributes and what it does not, and Code Generation for the XSD-to-language mapping.

MicroMetaApp import

MicroMetaApp describes a microscope visually and saves the result as JSON. fromMicroMetaAppJsonFile() parses that file, maps every component to its LiMi-Model counterpart, and fills the Instrument.

The mapping is checked against a published dataset of real microscope configurations: for every instrument in that dataset, the test suite imports the JSON, re-exports it as XML, and requires an exact match with a manually reviewed ground-truth document, in all three languages. See Import a MicroMetaApp Configuration.

Getting started

Step Page
Download the Python wheel and install it, or integrate the C++ or Java package Installation
Build and export a first NBO-XML document Quickstart
Learn one mechanism of the model at a time Core examples
Describe an instrument or an acquisition end to end Application examples
Look up a class NBO Reference

The library is written for application developers who record metadata from acquisition software or analysis pipelines, and for imaging facility staff who describe their instruments once and reuse that description.

Planned work

This page describes the library, not the metadata any particular Inscoper product writes today. The two advance separately.

The library currently targets the full LiMi-Model, which carries more metadata than the standard OME model. Export to standard, OME-compliant XML is in progress, for compatibility with tools and viewers that do not read the LiMi-Model extensions.

Inscoper software writes OME metadata, because OME is what the ecosystem reads. Devices are progressively being qualified against LiMi-Model terms, which enriches that OME output first; LiMi-Model output follows as the model is filled.

References

  1. Hammer M, Huisman M, Rigano A, et al. Towards community-driven metadata standards for light microscopy: tiered specifications extending the OME model. Nature Methods 18, 1427-1440 (2021). doi:10.1038/s41592-021-01327-9 ↩

  2. Sarkans U, Chiu W, Collinson L, et al. REMBI: Recommended Metadata for Biological Images, enabling reuse of microscopy data in biology. Nature Methods 18, 1418-1422 (2021). doi:10.1038/s41592-021-01166-8 ↩

  3. Reporting light microscopy data in our pages. Nature Structural & Molecular Biology 32, 955 (2025). doi:10.1038/s41594-025-01605-6 ↩

  4. Light microscopy reporting for reproducibility. Nature Cell Biology 27, 877 (2025). doi:10.1038/s41556-025-01704-y ↩

  5. Reporting standards for microscopy. Nature collection. Collection ↩