Skip to content

Quickstart

This page checks the installation, then builds and exports a first NBO document in Python.

1. Check the installation

Import the module and read the version of the native library it wraps.

import inscoper_nbo

# Version of the Python package, as declared by the wheel
print(inscoper_nbo.__version__)

# Full identification string of the native NBO library
print(inscoper_nbo.NBOUtils.getVersion())

2. Know the three kinds of class

Every NBO document is assembled from three kinds of generated class. Recognizing which one you hold tells you how to set a value.

Kind Example How a value is set
Element Instrument, Objective, CMOS Through set<Attribute>() and addTo<Element>_List()
Restricted type InstrumentID_Type, Denomination_Type, PositiveFloat_Type Instantiate the type, call set(value), pass the object to the parent
Primitive attribute Objective.setMagnification(), CMOS.setPixelWidth() Directly, with a native Python value

A restricted type exists wherever the schema constrains a value: an enumeration, a pattern, or a numeric range. set() checks the value and raises InscoperNBOValidationException when it does not comply, so an invalid document cannot be built by accident.

3. Build and export an instrument

This example creates an instrument, identifies it, attaches a microscope stand, and prints the NBO-XML.

import inscoper_nbo

# Every NBO element is a plain Python object
instrument = inscoper_nbo.Instrument()

# Identifiers are restricted types: instantiate, validate through set(), then assign
instrument_id = inscoper_nbo.InstrumentID_Type()
instrument_id.set("Instrument:1")
instrument.setID(instrument_id)

name = inscoper_nbo.Denomination_Type()
name.set("Nikon Ti2 - Room 214")
instrument.setName(name)

# The stand is a child of the instrument. MicroscopeStand is abstract in the
# schema, so the concrete class states the geometry of the stand.
stand = inscoper_nbo.InvertedMicroscopeStand()

stand_id = inscoper_nbo.LSID_Type()
stand_id.set("MicroscopeStand:1")
stand.setID(stand_id)

# Plain XSD primitives are set with native Python values
stand.setManufacturer("Nikon")
stand.setModel("Eclipse Ti2-E")
stand.setCatalogNumber("Ti2-E")

stand_type = inscoper_nbo.MicroscopeType_Type()
stand_type.set("Compound")
stand.setType(stand_type)

instrument.addToMicroscopeStandGroup_List(stand)

# Serialize the whole tree as NBO-XML. Export validates the document, so an
# element that lacks a required attribute is reported here rather than accepted.
print(instrument.toXmlString())


<?xml version="1.0"?>
<Instrument ID="Instrument:1" Name="Nikon Ti2 - Room 214">
  <InvertedMicroscopeStand Manufacturer="Nikon" Model="Eclipse Ti2-E" CatalogNumber="Ti2-E" ID="MicroscopeStand:1" Type="Compound" />
</Instrument>

4. Expect required attributes

Export validates the document, and the schema requires more attributes than a first draft usually sets: five on InvertedMicroscopeStand, twelve on Objective, seven on Detector. A missing one names itself in the exception, so a successful export is also a compliance check.

InscoperNBOValidationException: Attribut CatalogNumber in ManufacturerSpec is required

Pass False as the trailing argument to toXmlString() or toXmlFile() to serialize an incomplete draft anyway. The result is then not schema-valid.

Next steps

Object Accessors covers the accessor patterns in full, Import a MicroMetaApp Configuration fills an instrument in one call, and Describe an Instrument describes a complete microscope.