VolViewer msr file specification
Back to VolViewer Scripting in more detail
Back to VolViewer
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
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
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
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
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