==== The OPF format (Open Plant Format) ====

This is a standard format to describe plant architecture.
10.1.2011 - JF. Barczi , S. Griffon

=== 1. Context ===

**Xplo** handles plant architecture data with **ArchiTree** data structure. **ArchiTree** is an improved Java implementation of the **MTG** formalism. It is a **Multiscale Tree Graph** ready to represents plant topology **AND** geometry attached to it.

Each graph node is a topology element and may carry any attribute(length, diameter, weight, notes ...) and geometry (mesh, transform matrix, material).

**ArchiTree** can be stored in standardized XML file with an extension **_.opf_**.

=== 2. Topology encoding ===

== 2.1. File example ==

A simple .opf file example (only topology) :  
<code>
<?xml version="1.0" encoding="UTF-8" ?>
<opf version="2.0" editable="true">
	<topology class="Individual" scale="1">
		<decomp class="Axis" scale="2">
		<Name>Trunk</Name>
			<decomp class="Internode" scale="6">
			<Length>5.0</Length>
			</decomp>
			<follow class="Internode" scale="6">
			<Length>4.0</Length>
			</follow>
			<follow class="Internode" scale="6">
			<Length>2.0</Length>
				<branch class="Axis" scale="2">
				<Length>3.0</Length>
					<decomp class="Internode" scale="6">
					</decomp>
				</branch>
			</follow>
			<follow class="Internode" scale="6">
			<Length>1.0</Length>
			</follow>
		</decomp>
	</topology>
</opf>
</code>

This file loaded in Xplo: 

//3D View (with default geometry rules reconstruction) + browser view//
!https://amap-dev.cirad.fr/attachments/624/opfTopology.jpg! !https://amap-dev.cirad.fr/attachments/623/opfTopologyBrowser.jpg!



== 2.3. OPF ==

An **OPF** contains one main node : **TOPOLOGY**. The **TOPOLOGY** node contains all the tree graph topology relations. 
Attributes for the **OPF** tag are :
> * **version** : version number (actually 2.0).
> * **editable** (optional): If true, this opf will be editable in Xplo.



== 2.4. TOPOLOGY ==

The **TOPOLOGY** node contains all the tree graph topology relations. It contains three main nodes : **DECOMP**, **FOLLOW** and **BRANCH**.
**DECOMP** tag defines decomposition link to the previous node.
**FOLLOW** tag defines succession link to the previous node.
**BRANCH** tag defines ramification link to the previous node.

Inside the **TOPOLOGY**, **DECOMP**, **FOLLOW** and **BRANCH** you can insert attribute nodes. (see 2.5. _ATTRIBUTE_ TAGS)

Attributes for the **TOPOLOGY**, **DECOMP**, **FOLLOW** and **BRANCH** tags are :
> * **class** : a class or type name for the current node.
> * **scale** (optional) : a specific decomposition level (scale) for the current node.


== 2.5. _ATTRIBUTE_ TAGS ==

**TOPOLOGY**, **DECOMP**, **FOLLOW** and **BRANCH** can have unlimited attribute tags.
Xplo known attributes (such as **LENGTH** tag in above example) are listed in **ArchiTree** documentation.
However, custom attribute can have any name and their values can be integer, float or string.


=== 3. Geometry encoding ===

== 3.1. File example ==

An OPF file example with geometry looks like :  
<code>
<?xml version="1.0" encoding="UTF-8" ?>
<opf version="2.0" editable="true">
	<meshBDD>
		<mesh name="" shape="" id="0">
			<points>
				0.0	0.9511	0.309	0.0	0.0	1.0	1.0	0.0	1.0	1.0	0.9511	0.309	0.0	-0.9511	0.309	1.0	-0.9511	0.309	0.0	-0.5878	-0.809	1.0	-0.5878	-0.809	0.0	0.5878	-0.809	1.0	0.5878	-0.809	0.0	0.9511	0.309	1.0	0.9511	0.309	
			</points>
			<normals>
				0.0	0.9511	0.309	0.0	0.0	1.0	0.0	0.0	1.0	0.0	0.9511	0.309	0.0	-0.9511	0.309	0.0	-0.9511	0.309	-0.0	-0.5878	-0.809	-0.0	-0.5878	-0.809	0.0	0.5878	-0.809	0.0	0.5878	-0.809	0.0	0.9511	0.309	0.0	0.9511	0.309	
			</normals>
			<textureCoords>
				1.0	0.0	0.5	0.0	0.5	1.0	1.0	1.0	0.0	0.0	0.0	1.0	0.19098936	0.0	0.19098936	1.0	0.8090106	0.0	0.8090106	1.0	1.0	0.0	1.0	1.0	
			</textureCoords>
			<faces>
				<face Id="0">
					0	1	2	
				</face>
				<face Id="1">
					2	3	0	
				</face>
				<face Id="2">
					1	4	5	
				</face>
				<face Id="3">
					5	2	1	
				</face>
				<face Id="4">
					4	6	7	
				</face>
				<face Id="5">
					7	5	4	
				</face>
				<face Id="6">
					6	8	9	
				</face>
				<face Id="7">
					9	7	6	
				</face>
				<face Id="8">
					8	10	11	
				</face>
				<face Id="9">
					11	9	8	
				</face>

			</faces>
		</mesh>

	</meshBDD>
	<materialBDD>
		<material Id="1">
			<emission>0.0	0.0	0.0	0.0	</emission>
			<ambient>0.5019608	0.3019608	0.7019608	1.0	</ambient>
			<diffuse>0.5019608	0.3019608	0.7019608	1.0	</diffuse>
			<specular>0.5019608	0.3019608	0.7019608	1.0	</specular>
			<shininess>64.0	</shininess>
		</material>

	</materialBDD>
	<shapeBDD>
		<shape Id="0">
			<name> Mesh0</name>
			<meshIndex>0</meshIndex>
			<materialIndex>0</materialIndex>
		</shape>

	</shapeBDD>
	<topology class="Individual" scale="1">
	<geometry class="Mesh">
		<mat>
		-4.371139E-8	0.0	-1.0	0.0		
		0.0	1.0	0.0	0.0		
		1.0	0.0	-4.371139E-8	0.0		
		</mat>
		<dUp>1.0</dUp>
		<dDwn>1.0</dDwn>
	</geometry>
		<decomp class="Axis" scale="2">
		<Notes>Trunk</Notes>
		<geometry class="Mesh">
			<mat>
			-4.371139E-8	0.0	-1.0	0.0			
			0.0	1.0	0.0	0.0			
			1.0	0.0	-4.371139E-8	0.0			
			</mat>
			<dUp>1.0</dUp>
			<dDwn>1.0</dDwn>
		</geometry>
			<decomp class="Internode" scale="6">
			<Length>5.0</Length>
			<geometry class="Mesh">
				<shapeIndex>0</shapeIndex>
				<mat>
				-2.1855695E-7	0.0	-1.0	0.0				
				0.0	1.0	0.0	0.0				
				5.0	0.0	-4.371139E-8	0.0				
				</mat>
				<dUp>1.0</dUp>
				<dDwn>1.0</dDwn>
			</geometry>
			</decomp>
			<follow class="Internode" scale="6">
			<Length>4.0</Length>
			<geometry class="Mesh">
				<shapeIndex>0</shapeIndex>
				<mat>
				-1.7484555E-7	0.0	-1.0	-2.1855695E-7				
				0.0	1.0	0.0	0.0				
				4.0	0.0	-4.371139E-8	5.0				
				</mat>
				<dUp>1.0</dUp>
				<dDwn>1.0</dDwn>
			</geometry>
			</follow>
			<follow class="Internode" scale="6">
			<Length>2.0</Length>
			<geometry class="Mesh">
				<shapeIndex>0</shapeIndex>
				<mat>
				-8.742278E-8	0.0	-1.0	-3.934025E-7				
				0.0	1.0	0.0	0.0				
				2.0	0.0	-4.371139E-8	9.0				
				</mat>
				<dUp>1.0</dUp>
				<dDwn>1.0</dDwn>
			</geometry>
				<branch class="Axis" scale="2">
				<Length>3.0</Length>
				<geometry class="Mesh">
					<mat>
					2.5980763	0.0	-0.5	0.49999952					
					0.0	1.0	0.0	0.0					
					1.5	0.0	0.86602545	11.0					
					</mat>
					<dUp>1.0</dUp>
					<dDwn>1.0</dDwn>
				</geometry>
					<decomp class="Internode" scale="6">
					<geometry class="Mesh">
						<shapeIndex>0</shapeIndex>
						<mat>
						2.5980763	0.0	-0.5	0.49999952						
						0.0	1.0	0.0	0.0						
						1.5	0.0	0.86602545	11.0						
						</mat>
						<dUp>1.0</dUp>
						<dDwn>1.0</dDwn>
					</geometry>
					</decomp>
				</branch>
			</follow>
			<follow class="Internode" scale="6">
			<Length>1.0</Length>
			<geometry class="Mesh">
				<shapeIndex>0</shapeIndex>
				<mat>
				-4.371139E-8	0.0	-1.0	-4.808253E-7				
				0.0	1.0	0.0	0.0				
				1.0	0.0	-4.371139E-8	11.0				
				</mat>
				<dUp>1.0</dUp>
				<dDwn>1.0</dDwn>
			</geometry>
			</follow>
		</decomp>
	</topology>
</opf>
</code>


This file loaded in Xplo:

**3D View**

https://amap-dev.cirad.fr/attachments/625/opfGeometry.jpg

== 3.2. MESHBDD ==

The **MESHBDD** node contains all the mesh collection used in the plant geometry.
A mesh is reprensted by a *MESH* node.

== 3.3. MESH ==

It contains four main nodes : **POINTS**, **NORMALS**, **TEXTURECOORDS** and **FACES**
Attributes for the **MESH** tag :
> * **name** : a string to identify mesh.
> * **id** : an integer to identify mesh.

== 3.4. POINTS ==

The **POINTS** node contains all the xyz mesh point coordinates. 
Coordinates are written in raw :
<pre>
xp1 yp1 zp1 xp2 yp2 zp2 xp3 yp3 zp3 ....
</pre>

== 3.5. NORMALS ==

The **NORMALS** node contains all the xyz mesh normal coordinates (linked to each point mesh => must be described in the same order than points). 
Coordinates are written in raw :
<pre>
xn1 yn1 zn1 xn2 yn2 zn2 xn3 yn3 zn3 ....
</pre>


== 3.6. TEXTURECOORDS ==

The **TEXTURECOORDS** node contains all the uv mesh texture coordinates (linked to each point mesh => must be described in the same order than points). 
Coordinates are written in raw :
<pre>
u1 v1 u2 v2 u3 v3 ....
</pre>


== 3.7. FACES ==

The **FACES** node contains all the mesh faces.
A **FACE** node references all the points to build a face. The point reference is an index into the point list (described by **POINTS**).
Point index are written in raw : (here a face composed by 4 points)
<pre>
i1 i2 i3 i4
</pre>

== 3.8. MATERIALBDD ==

The **MATERIALBDD** node contains all the material collection used by the meshes.
A material is reprensted by a **MATERIAL** node.

== 3.9. MATERIAL ==

The **MATERIAL** node contains four main nodes : **EMISSION**, **AMBIENT**, **DIFFUSE**, **SPECULAR** and **SHININESS**.
**EMISSION**, **AMBIENT**, **DIFFUSE** and **SPECULAR** color are written in raw (float value between 0.0 and 1.0):
<pre>
r g b a
</pre>
**SHININESS** is a single float value.

Attributes for the **MATERIAL** tag :
> * **id** : an integer to identify material

== 3.10. SHAPEBDD ==

The **SHAPEBDD** node contains a list of shape. A shape is referencing a mesh and a material.
A **SHAPE** node has one attribute (id : an integer to identify the shape) and is componed by 3 nodes : **NAME**, **MESHINDEX** and **MATERIALINDEX**. 
**MESHINDEX** and **MATERIALINDEX** node refers respectively to the **MESH** id and the **MATERIAL** id.

== 3.11. GEOMETRY ==

The **GEOMETRY** node is **always** linked to a topology element (like an **attribute tag**). 

A geometry contains at least a **MAT** node. This is a 4x4 transformation matrix written in raw :
<pre>
x1 y1 z1 t1
x2 y2 z2 t2
x3 y3 z3 t3
x4 y4 z4 t4
</pre>

Attributes for the **GEOMETRY** tag :
> * **class** : a string to define the type of geometry (mesh, bezier, spline...).


If geometry class is _Mesh_, then **Mesh** can be componed by : 
**shapeIndex** : the shape index (defined in **shapeBDD**).
**dDwn** : the bottom diameter of the mesh
**dUp** : the top diameter of the mesh