The .mtg file format

The .mtg file format was developed in the AMAP lab to be able to describe a plant in the MTG format directly in a file.

The file format is generally used when measuring a plant on the field or to write on disk the results of an architectural model such as AMAPSim or VPalm for example. This format helps exchange and archive data about plants in a standard and efficient way.

The format is described in details in the original paper from Godin et al. (1998), but our implementation in Julia is detailed in this section.

Example MTG

Let's define a very simple virtual plant composed of only two internodes and two leaves:

A simple 3D plant by rvezy on Sketchfab

The corresponding MTG file is provided with this package. Let's print it using Julia's built-in read method:

using MultiScaleTreeGraph
file = joinpath(dirname(dirname(pathof(MultiScaleTreeGraph))),"test","files","simple_plant.mtg")
println(read(file, String))
CODE:	FORM-A

CLASSES:
SYMBOL	SCALE	DECOMPOSITION	INDEXATION	DEFINITION
$ 	0	FREE	FREE	IMPLICIT
Individual	1	FREE	FREE	IMPLICIT
Axis	2	FREE	FREE	IMPLICIT # you can add comments anywhere
Internode	3	FREE	FREE	IMPLICIT
Leaf	3	FREE	FREE	IMPLICIT

DESCRIPTION:
LEFT	RIGHT	RELTYPE	MAX
Internode	Internode,Leaf	+	?
Internode	Internode,Leaf	<	?

FEATURES:
NAME	TYPE
Length	ALPHA
Width	ALPHA
XEuler	REAL
isAlive	BOOLEAN
dateDeath	DD/MM/YY

MTG:
ENTITY-CODE		Length	Width	XEuler	isAlive	dateDeath
/Scene0
^/Individual0
^/Axis0
^/Internode0		0.1	0.02	1
	+Leaf0	0.2	0.1		0	24/08/2022
^<Internode1		0.1	0.02	180.0	1
	+Leaf0	0.2	0.1		1

This is a consequent file for such a tiny plant! This is because MTG files have a header with several sections before the MTG of the plant itself, which only appears after the MTG: line.

Let's dig into the information we have here.

The MTG sections

Introduction

An MTG file is divided into five sections. These sections are defined by a keyword and a colon. The content of each section appears on a new line right after the keyword. A section can appear right after the content of the previous section, or they can be separated by blank lines. In fact, all blank lines are ignored in an MTG file.

The CODE section

The first section of an MTG file is the CODE section. It must appear first in the file as it is used to determine which version of the format specification the MTG file is following. The standard format in 2021 is the FORM-A specification. A new format is under reflexion but is not yet available.

The CLASSES section

The CLASSES section lists all symbols used in the MTG, and associates the scale of each symbol.

The data is presented as a table with five columns:

  • SYMBOL: the string used for the node symbol.
  • SCALE: the scale of the symbol, meaning all nodes with the given symbol will have this scale.
  • DECOMPOSITION: This is not used anymore
  • INDEXATION: This is not used anymore
  • DEFINITION: This is not used anymore

The first row of the table is reserved and shouldn't be updated. It is a standard to use the dollar sign as the symbol for the scene, i.e. the node with the higher scale that encompass all MTGs. This node is usually not used in an MTG because MTG files mostly describe just a single plant (or a part of), not a whole scene.

Warning

The symbol must be a character string without any numbers at the end, because the index of a node is read as the numbers at the end of a node name, so if a node symbol ends with a number, it will be parsed as an index. For example a symbol written Axis1 with index 1 will give Axis11 in the MTG, which will be parsed as Axis for the symbol and 11 for the index. Numbers are allowed inside the symbol though, e.g. Ax1s is allowed.

The DESCRIPTION section

The DESCRIPTION section is a table with four columns, and it defines a set of topological rules the MTG nodes of a same scale must follow. The rules are completely optional, but the header of the section is mandatory. In other words, the table can be empty.

The LEFT column designates the symbol of a parent node, the RIGHT column the symbol of a child node, the RELTYPE column the type of links allowed between the two, and MAX the maximum number of times these types of connexions are allowed in the MTG. The user can use a question mark to denote no maximum.

Note

The rules only apply between symbols sharing the same scale (e.g. a node with itself, or in our example, the Internode with a Leaf).

These rules are mainly used to check the integrity of an MTG that has been written by hand on the field.

Warning

This package does not implement any check on the rules yet. You can let this section empty (with the header) for your MTG if you don't plan to read it with other tools than MultiScaleTreeGraph.jl.

The FEATURES section

This section is a table with two columns that define the name of the attributes (or features) that can be attached to nodes, and the type of these attributes. This section makes sure that attributes are interpreted correctly when parsing the file.

The NAME column is used to give the name of an attribute, and the TYPE column its type. The type can be:

  • REAL for real numbers, e.g. 0.1
  • INT for integer numbers, e.g. 1
  • STRING for strings, e.g. broken
  • ALPHA for reserved keywords:
    • NbEl: NumBer of ELements, the number of children at the next scale
    • Length: the node length
    • BottomDiameter, the bottom tapering applied to the node for computing its geometry
    • TopDiameter, the tapering applied at the top
    • State, defines the state of a node. It can take the value D (Dead), A (Alive), B (Broken) , P (Pruned), G (Growing), V (Vegetative), R (Resting), C (Completed), M (Modified), or any combination of these given letters.
Warning

This package does not implement any check on the State of a node, and does not make use of the reserved keywords.

The MTG section

This section is the actual MTG. It describes the topology of the plant, and give the possibility to add attributes to them.

The MTG is encoded as a table with tabulation separated values. The header of this section defines the columns used for describing the topology and the ones used for the attributes. The first column name is reserved and must be named ENTITY-CODE. Then, a set of empty column names (i.e. just tabulations) that defines how many columns are used for the topology. Finally, the following columns are used to define the attributes of the nodes. Their names must match the ones given in The FEATURES section.

Each row of the table usually refers to a single node. The topology is and node description is given in the ENTITY-CODE columns.

In our example MTG, the first node is the scene: /Scene0. In this package, this notation is called a NodeMTG. It is made out of three different information:

  • The link to the parent node: /
  • The node Symbol: Scene
  • The node index: 0

The link to the parent can be either / (decomposition), < (following) or + (branching). you can read the Node MTG and attributes section for more details on the signification of each. In few words, a node decomposes its parent if it changes the scale of description, follows if it is continuing after its parent, or branching if it branches from its parent.

The node symbol is used to determine the scale of the node and eventually its properties.

The node index is completely free. It is mainly used to keep track of the number of following segments on an axis, or the branching order.

The second node in our example is ^/Individual0. It introduces a new character used as a prefix: ^. By default the parent of a node is defined as the last node present in the column preceding it, e.g.:

node1
node2
node3

Here node1 is the parent of node2 and node3. But if we want node2 as the parent of node3, we would have to create a new column:

node1
node2
node3

This means large MTGs would require a lot of columns for the topology encoding. This is where ^ becomes useful. It allows us to write a child in the same column as its parent, as long as the parent has only on child:

node1
node2
^node3

In the example above, node1 is the parent of node2, and node2 is the parent of node3.

Note

Because there is no explicit need to change column when nodes are decomposing or following, we usually create a new column only when a node branches to reduce the number of columns in the ENTITY-CODE.

Attributes are then declared in their respective columns defined in the header. If there is no value for an attribute, it is usually declared as an empty column

Note

MTGs entered manually on the field are usually done in a spreadsheet software such as MS Excel or Only Office / Open Office / Libre Office Calc. Here is an example spreadsheet used on the field.