VolViewer msr file specification

Concepts represented in the MSR file

An MSR file represents objects (geometry and growth) associated to a unique data file (for example a 3D stack).

The file is a succession of directives. Directives are either global (in the header) or per object (in the body). All directives are mandatory, unless stated otherwise.

General Syntax Overview

MSR files are simple text files (ASCII), whose general structure is :

   FIELDNAME = FIELDVALUE # Comment

All field names are case insensitive. Comments start with a '#' and end at the end of the line. The file should be parsed after removing the comments from the file.

When parsing, empty lines (i.e. truly empty or with only spaces and comments) must be skipped.

Except for version 0, that shouldn't be used anymore, the first line shoud be:

   MSR_VERSION = major.minor

The file should be readable in one pass. To help, each list of fields is preceded with a list count with the syntax:

   fieldnameCOUNT = count
   fieldname = value1
   fieldname = value2
   ...

Number and String values

Numbers can be either in decimal or scientific notation format:

0.001
1e-3
1E-3

are all accepted numbers.

String are represented using a character delimiter to allow for spaces, numbers etcs.. in the string and easy reading. This special character is the single quote ( ' ).

'hello this is my 1st string'

is a valid string. This however means we require special handling of the single quote character in a string. This is represented by using two single quote characters as follows:

'hello it''s my first string'

is a valid string to represent: hello it's my first string.

(NB) Note that newlines are not accepted in strings.

Field names and specifications

FILE HEADER: Global Directives

These directives define the header of the file.

File version

   MSR_VERSION = major.minor

This field has to be the first one of the file. If not present, it means the file is a legacy version 0, which is not covered by this document.

Version: ≥0.1 | Mandatory

Location of the original data

   ORIGINALDATA = TYPE SPEC

Reference to the original data.

Version: ≥0.1 | Mandatory

Supported reference types

• NONE

   ORIGINALDATA = NONE

This is when no original image is specified.

Version: ≥1.1 | Mandatory

• PATH

   ORIGINALDATA = PATH '/path/to/someimage'

The path to some data ie: an image is stored using '/' as the directory separator. The path may be absolute or relative. If relative, it is expressed relative to the position of the MSR file.

Version: ≥0.1 | Mandatory

• OMEROID

   ORIGINALDATA = OMEROID 'serveraddress:port/imageid'

Example:

   ORIGINALDATA = OMEROID 'cmpdartsvr1.cmp.uea.ac.uk:4063/456215'

Where SERVERADDRESS can be either the IP address or the host name of the server, PORT is the port used by the OMERO server and IMAGEID is the unique id within the database.

Version: ≥0.1 | Mandatory

Scale

   SCALE = sx sy sz

Size of a unit in meters. The three component correspond to the size of a unit square along the X, Y and Z axes. If not present, it is assumed be equivalent to:

   SCALE = 1 1 1

Version: ≥0.1

Time of the data

Can be either TIME or DATE.

   TIME = time

The time is expressed in hours from an unspecified reference.

   DATE = 'YYYY/MM/DD hh:mm:sec'

The time and day the image has been taken. The seconds may be a floating point value.

Version: ≥0.1 | Mandatory

Algorithm identification

String that uniquely identifies the algorithm used to generate that file, and its version.

   ALGORITHM = STRING

Example:

   ALGORITHM = 'measure_growth.py 1539'

Version: ≥0.1 | Optional

Number of objects

NB This field must be the last one of the header!

   OBJECTCOUNT = number_of_objects 

Version: ≥0.1

FILE BODY: Structured Directives

These are directives defining objects that can be labelled, used in lists, ...

Objects

   OBJECTCOUNT = count
   OBJECT = 'name'

Defines objects by their name. This element must be right after the header. Actually, OBJECTCOUNT defines when the header ends.

Version: ≥1.1 | Mandatory

Vertices

   VERTCOUNT = count
   VERT = Vx Vy Vz

Defines the list of vertices of an object, and their positions. Vx, Vy and Vz should be floating point values.

Version: ≥1.1 | Contained in OBJECT | Mandatory

Edges

   EDGECOUNT = count
   EDGE = source target

Defines the list of edges of an object. Source and target are 0-based indices in the list of vertices.

Version: ≥1.1 | Contained in OBJECT | Optional | Requires VERT

Faces

   FACECOUNT = count
   FACE = v1 v2 v3 ... vn

Defines the list of faces of an object. The vertices are specified by 0-based index in the list of vertices.

Version: ≥1.1 | Contained in OBJECT | Optional | Requires VERT

Volumes

   VOLCOUNT = count
   VOL = face1 face2 face3 ... facen

Defines the list of volumes of an object. The faces are specified by 0-based index in the list of faces.

Version: ≥1.1 | Contained in OBJECT | Optional | Requires FACE

Structured Directive Properties

This contains the elements that can be contained within a structured directive.

Render Type

   RENDERTYPE = 'type'

This defines how an object should be rendered. This is only a hint that is application-specific.

Version: ≥0.1 | Contained in OBJECT | Optional

Normals

  xxxxNORMAL = Nx Ny Nz

Normals are 3D normalized vectors and xxxx is to be replaced by the parent directive. Note that normals can only be specified after the directive count has been specified.

Example:

  FACENORMAL = 0.0 1.0 0.0

Version: ≥1.1 | Contained in VERT, EDGE, FACE | Optional

Colours

  xxxxCOLOUR = R G B

Colours are specified as an R,G,B vector with values from 0 to 255, xxxx is to be replaced by the parent directive. Note that colours can only be specified after the directive count has been specified.

Example:

  FACECOLOUR = 0 255 0

Version: ≥1.2 | Contained in VERT, EDGE, FACE, VOLUME | Optional

Morphogens

Morphogens are scalar values associated with vertices. Each morphogen has a name and each morphogen is defined for every vertex. Morphogen names are specified by a directive of the form:

   VERTMGENNAMES = name name name...

listing the names of all of the morphogens as quoted strings. The values for the morphogens are specified by directives of the form:

   VERTMGEN = amount amount amount...

The amounts are listed in the same order as their names were. There is one VERTMGEN line for each vertex.

Version: ≥1.2 | Contained in VERT | Optional | Requires: VERTCOUNT

Growth

Face Growth

This is a list of growths specifications for all faces. As the number has to be the same as the number of faces, it is not re-specified. The start of the list is given by:

   FACEGROWTHDT = dt

Where dt is the difference in time between this object and the object used as reference for this growth. Note that, if dt is negative, it means the growth represent the growth from the previous time to the current one, but expressed in the current reference frame.

Next, the growth parameters are given by:

   FACEGROWTH = kmax kmin Vx Vy Vz

Where kmax is the relative elemental growth rate of growth along the major axis, kmin the relative elemental growth rate of growth along the minor axis, and (Vx,Vy,Vz) is a unit vector defining the major axis. The minor axis can be found with the cross-product between the major axis and the normal to the face. Note that kmax is taken as the largest absolute value of the two growth rates.

Note, there might be many growth specified for a same object, but only one per dt.

Version: ≥0.1 | Optional | Requires: FACECOUNT

Edge Growth

This is a list of growths specifications for all edges. As the number has to be the same as the number of edges, it is not re-specified. The start of the list is given by:

   EDGEGROWTHDT = dt

Where dt is the difference in time between this object and the object used as reference for this growth. Note that, if dt is negative, it means the growth represent the growth from the previous time to the current one, but expressed in the current reference frame.

Next, the growth parameters are given by:

   EDGEGROWTH = k

Where k is the relative growth rate along the edge.

Note, there might be many growth specified for a same object, but only one per dt.

Version: ≥0.1 | Optional | Requires: EDGECOUNT

Labels

xxxxLABEL = n 'label1' 'label2' .... 'labeln'

This is a list of labels attached to some directive. If a directive is labelled, every element of it must be.

Labels start with the count for the number of labels followed by the label strings. The xxxx is to be replaced by the labelled directive. Note that a directive can be labelled only after the directive count has been specified.

Example:

  VERTLABEL = 2 'petiole' 'cell corner'

Empty labels are represented by:

  VERTLABEL = 0

Version: ≥1.2 | Contained in VERT, EDGE, FACE, VOLUME | Optional

Lists

Lists are a named ordered series of indices attached to some directive. Note that a list can be only after the directive count has been specified. Lists start with a xxxxLISTCOUNT field to facilitate reading followed by the xxxxLIST directive that starts with a sting name label followed by the indices making up the list. The number of indices in the list must match the xxxxLISTCOUNT.

xxxxLISTCOUNT = N
xxxxLIST = 'name' idx1 idx2 idx3 ... idxN

example:

EDGELISTCOUNT 5 
EDGELIST 'lamina outer edge' 5 6 4 8 2 

Version: ≥1.2 | Contained in VERT, EDGE, FACE, VOLUME | Optional

Examples

A Triangle

File:Simple triangle.svg

MSR_VERSION = 1.2
ORIGINALDATA = PATH '/path/to/image'
SCALE = 1 1 1
TIME = 0
OBJECTCOUNT = 1
OBJECT = 'Triangle'  
VERTCOUNT = 3
VERT = -10 0 0
VERT = 10 0 0
VERT = 0 10 0
EDGECOUNT = 3
EDGE = 0 1
EDGE = 1 2
EDGE = 2 0
FACECOUNT = 1
FACE = 0 1 2

Two Triangles as different objects

File:Twotriangles.svg

MSR_VERSION = 1.2
ORIGINALDATA = PATH '/path/to/image'
SCALE = 1 1 1
TIME = 0
OBJECTCOUNT = 2
OBJECT = 'Triangle1'  
VERTCOUNT = 3
VERT = -10 0 0
VERT = 10 0 0
VERT = 0 10 0
EDGECOUNT = 3
EDGE = 0 1
EDGE = 1 2
EDGE = 2 0
FACECOUNT = 1
FACE = 0 1 2
OBJECT = 'Triangle2'  
VERTCOUNT = 3
VERT = -10 0 10
VERT = 10 0 10
VERT = 0 10 10
EDGECOUNT = 3
EDGE = 0 1
EDGE = 1 2
EDGE = 2 0
FACECOUNT = 1
FACE = 0 1 2

Triangle with labels

File:Triangle labelled.svg

MSR_VERSION = 1.2
ORIGINALDATA = PATH '/path/to/image'
SCALE = 1 1 1
TIME = 0
OBJECTCOUNT = 1
OBJECT = 'Triangle'
VERTCOUNT = 3
VERT = -10 0 0
VERT = 10 0 0
VERT = 0 10 0
VERTLABEL = 0
VERTLABEL = 0
VERTLABEL = 1 'Tip'    
EDGECOUNT = 3
EDGE = 0 1
EDGE = 1 2
EDGE = 2 0
EDGELABEL = 1 'Base'
EDGELABEL = 0
EDGELABEL = 0   
FACECOUNT = 1
FACE = 0 1 2

A Leaf with Labels and Lists

File:LeafLabelsandList.svg

MSR_VERSION = 1.2
ORIGINALDATA = PATH '/path/to/image'
SCALE = 1 1 1
TIME = 0
OBJECTCOUNT = 1
OBJECT = 'ShapeModelLeaf'  
VERTCOUNT = 15
VERT = 54 144 0
VERT = 120 143 0
VERT = 157 164 0
VERT = 201 204 0
VERT = 254 221 0
VERT = 325 208 0
VERT = 385 171 0
VERT = 422 127 0
VERT = 374 82 0
VERT = 318 62 0
VERT = 255 36 0
VERT = 200 50 0
VERT = 154 72 0
VERT = 120 100 0
VERT = 47 97 0
VERTLABEL = 1 'Primary'
VERTLABEL = 1 'Primary'
VERTLABEL = 1 'Secondary'    
VERTLABEL = 1 'Secondary'    
VERTLABEL = 1 'Primary'    
VERTLABEL = 1 'Secondary'    
VERTLABEL = 1 'Secondary'    
VERTLABEL = 2 'Primary' 'Tip'   
VERTLABEL = 1 'Secondary'    
VERTLABEL = 1 'Secondary'    
VERTLABEL = 1 'Primary'    
VERTLABEL = 1 'Secondary'    
VERTLABEL = 1 'Secondary'    
VERTLABEL = 1 'Primary'    
VERTLABEL = 1 'Primary'
VERTLISTCOUNT = 13
VERTLIST = 'Lamina' 1 2 3 4 5 6 7 8 9 10 11 12 13
VERTLISTCOUNT = 4
VERTLIST = 'Petiole' 1 0 14 13
EDGECOUNT = 15
EDGE = 0 1
EDGE = 1 2
EDGE = 2 3
EDGE = 3 4
EDGE = 4 5
EDGE = 5 6
EDGE = 6 7
EDGE = 7 8
EDGE = 8 9
EDGE = 9 10
EDGE = 10 11
EDGE = 11 12
EDGE = 12 13
EDGE = 13 14
EDGE = 14 0