Scientist's Digital Notebook - Graphical Annotations Configuration

Template configuration

Document updated for version: 1.2.18

Introduction

The Scientist's Digital Notebook is designed to be very flexible and easily adjustable to personal needs of scientist. The program reads a configuration XML file and creates all visual controls for inputting the data. The configuration file also dictates how the data will be saved in data XML files and also how it will be uploaded to the database. Graphical annotations are configured in two files: gobject_templates.tmpl and the template CIX file where the annotation is instantiated. gobject_templates.tmpl defines all the simple and complex g-objects as well as available environment schemas.

A note on g-objects, they are hierarchical graphical objects that may be graphical primitives or their collections. If the type of the object is unknown to the system it is considered a collection. In order to understand better the g-objects language I suggest reading it's documentation. Here we describe only the configuration of the Digital Notebook.

Primitive types are slightly different from defined in the g-objects language. It happened because the ways of acquiring things might be different but their representation is the same, e.g. line and polyline. Line can be acquired a bit faster since we know there are only 2 vertices. Although they both are stored as polyline into the XML file. The available primitives are: point, line, polyline, polygon, freehand line, freehand shape, circle, ellipse, square, rectangle, label. Note that line, polyline, polygon, freehand line, freehand shape produce the same XML output but are acquire differently. They are differentiated in the g-objects XML by a configuration tag.

CIX files

Each template may instantiate graphical annotations, it's done using <type formelement="graphics" />, see Templates. The value of the tag may define a graphical annotation environment by embedding XML into the value as CDATA. The document specifies the environment by: <!DOCTYPE bfi><bfi environment = "all_shapes"/>. The environment schemas are defined in the gobject_templates.tmpl

gobject_templates.tmpl

The gobject_templates.tmpl defines all the simple and complex g-objects as well as available environment schemas. The XML document consists of two parts: the complex object definitions <complex_gobjects> and environment schemas <edit_schema>.

<complex_gobjects>

Here user may append complex objects and define some default properties for graphical primitive objects embedded in them.

An example of the complex object definition follows:

    <gobject_tmpl type="mttrack" name="MTtrack" >
<gobject_tmpl type="polyline" name="track" >
<config_functional auto_page_advance="true" pages_to_skip="0" />
</gobject_tmpl>
<gobject_tmpl type="point" name="origin" >
</gobject_tmpl>
</gobject_tmpl>

This defines a complex object with the type mttrack and name MTtrack. Type is always necessary and is used to define the object. The name is not necessary but can be defined for differentiation between objects. In this case the MTrack is merely a default name that can be later changed by the user.

The object consists of two graphical primitives polyline and point. You can see that polyline has two configuration options: auto_page_advance and pages_to_skip. Available configuration for each type will be described later.

Some tricks: It is possible to define two different types with the same type but distinct names. In this case the defined name is differentiating them. It can be used for creating distinct annotation tools that will be later combined into the same statistics. e.g. Microtubule body can be drawn using line, polyline or freehand. But what interests in the end is it's length so all these three types can be combined into the same statistics: lengths of microtubule bodies.

Configuration for graphical primitives is done by: <config_functional> and <config_visual>:

<config_functional auto_page_advance="false" pages_to_skip="0" ... />

<config_visual color="#FF0000" line_width="1" ... />

<edit_schema>

Here we simply define new environments and specify what types are default for these environments:

<environment type="all_shapes" name="all_shapes">
<config_functional default_page_axis="t" />
<gobject_tmpl type="point" name="point"/>
<gobject_tmpl type="line" name="line"/>
<gobject_tmpl type="polyline" name="polyline"/>
<gobject_tmpl type="polygon" name="polygon"/>
</environment>

The environment type is used in the CIX template configuration. Note the configuration option: default_page_axis, it is used in case that multi page file does not have axis information. So that a particular template can hold it's default axis. For example motility studies usually use time and 3D localization z.