====== The Open Plant Scene (ops) format ======
**12.3.2015-fc** Ops files may now contain polylines and polygons (optional)\\
**26.2.2015-fc** The ops files now accept opf, gwa, but also .lig, .obj (friendly types, quick outline rendering) and any other files + an optional Terrain line \\
**17.2.2014-fc** The ops files contain .opf AND/OR .gwa files \\
**24.1.2011-sg,fc** The ops contains ONLY references to opf files \\
**21.1.2011-sg,fc** opfs -> About ops, generalization to (i) other files than opf ; (ii) scenarios and projects saving (scene is static OR along time) \\
**4.1.2011-sg,jd,fc** This is an attempt to define a standard format for a scene containing plants (originaly opf files) \\
===== A need for a scene standard format =====
Xplo works at the individual plant level on **ArchiTrees** (in memory) and generates **opf files** as a standard. These files contain the plant topology AND geometry. Each node of the plant may carry any attributes.
AMAPstudio also proposes tools to generate **Geometry With Attributes** (gwa), i.e. objects the user can add in a vegetal scenes. These objects are merely geometries, they are managed in ArchiTrees and can be given attributes the same way than the plants.
Simeo works on vegetal scenes. It can be used to build scenes interactively and tends to handle the opf files from Xplo as a standard. This document proposes a standard format for a scene made of .opf and .gwa files, to set their locations and possible rotations.
__EDIT February 2015__ The Simeo editor (aka Edito) is now able to handle any types of files. The AMAPstudio .opf and .gwa are the most complete ones (topology + geometry) and are preferred. A degraded support for __.lig__ (former AMAP format) and __.obj__ (standard wavefront geometry file) has been added: these friendly files are incomplete (no topology). They can be added in the scene, they are rendered as outlines and can be exported in ops files (with location and rotations). Other files (any other file extension) are managed the same way, but are represented by a blue pin in the scene, they are also exported in .ops files.
The format is extended to temporal scenarios (scenes at several dates) and projects (several scenarios). The ops file format is a standard exchange format between Xplo and Simeo. It may also become a standard for communication with other tools.
===== The ops scene format =====
The ops scene format is a file with an extension **.ops**. The main format is as follows (see also optional parts in this document).
# Part 1: one line per element (.opf or .gwa file) in the scene
# Note: scale is always 1
sceneId elementId elementFileName x y z scale inclinationAzimut inclinationAngle elementTwist
# Part 2 (optional), chaining: only if scenario or project, one line per sceneId in part1
motherId sceneId date
* the directory containing this scene file is called **the ops directory**
* lines beginning with a # are **comments** (ignored at reading time)
* all angles are in **degrees** and **counterclockwise**
* columns are separated by **tabs**
==== Terrain (optional) ====
A line can be added before **Part 1** to set the terrain properties. This line is optional.
Format for a flat terrain:
# T xOrigin yOrigin zOrigin xSize ySize flat
T 0 0 0 105 105 flat
Format for a Terrain with a simple slope (slope azimut is a trigonometric angle: same 0, counterclockwise, but in degrees:
# T xOrigin yOrigin zOrigin xSize ySize slope[slopeAzimut(ccw,deg);slopeElevation(deg)]
T 0 0 0 105 105 slope[45;12]
Format for a Terrain with a height map file (.png file; path relative to the ops directory):
# T xOrigin yOrigin zOrigin xSize ySize heightMap[zMin;zMax;heightMapPngFileName]
T 0 0 0 105 105 heightMap[60;96;opf/Prades_Mnt.png]
==== Part 1 ====
* **sceneId** (int): a unique identifier for the scene in the file. If the file contains one single scene (all plant lines with same sceneId and no chaining lines), the sceneId is the date of the scene
* **elementId** (int): a unique identifier for the element in the scene (.opf or .gwa)
* **elementFileName** (String): the name of the file containing the plant (.opf) OR the geometry with attributes (.gwa). This name is a path **relative to the ops directory**. The file may be directly in the ops directory (e.g. elementFileName: eucalyptus.opf) or in a subdirectory (e.g. elementFileName: plants/eucalyptus.opf)
* **x, y, z** (double): coordinates of the elements in the scene (meters fc-17.2.2014)
* **inclinationAzimut, inclinationAngle** (double, degrees): to incline the element: (1) consider the azimut around the vertical axis (ccw, 0 on the x+ axis) and (2) incline the vertical axis in the azimut plane
* **elementTwist** (double, degrees): after the inclination, rotate the element of this angle around its vertical axis (aka trunk or main axis)
NOTE for opf files: inclinationAzimut, inclinationAngle and elementTwist are applied only on the opf geometry. The attributes of the opf are not changed (sg, fc, 20.1.2011)
* it is part of the standard that **additional columns may be added after these standard columns** for specific purposes, they will be ignored by the standard tools
{{ :soft:simeo:private:scene_opfs_rotations.jpg?direct&400 |}}
The plant rotations
==== Part 2 (optional) ====
This part concerns the chaining of the scenes. These lines may be omitted in the following cases:
* if the file contains only one scene (one single sceneId)
* if the file contains only a simple scenarios, the chaining records will be rebuilt automatically by the OPSLoader. The sceneIds will be considered as dates and sorted in natural ordering.
For more complex projects with many scenarios, this simple format makes it possible to save the project to an ops.
* **motherId** (int): the id of the previous scene, convention: -1 for first scene (no father)
* **sceneId** (int): the id of the scene
* **date** (int): the date of this scene
==== Lines (optional) ====
If lines (i.e. polylines or polygons) are found in the original scene, they are exported in the ops file.
Format: the line records contain 3 columns separated by tabs.
* col1: the id of the scene containing the line (1 if the ops is for a single scene)
* col2: P for Polygon (will be closed) or L for Polyline (will stay opened). An optional color can be added by appending a ':' followed by R, G and B values in [0,255] separated by commas, e.g. P:128,128,56
* col3: a list of x,y values, e.g. x0,y0,x1,y1,x2,y2
The z value of each point is 0 if there is no terrain record. Else, the z value is given by the terrain (slope, height map).
Example:
# [Optional] Lines
# r,g,b color is optional, BLACK if missing
# Lines starting with a L are opened polylines
# Lines starting with a P are closed polygons
#sceneId P/L[:r,g,b] x,y,x,y...
1 P:128,128,128 77.092,14.943,88.986,39.912,62.019,42.689,52.728,22.446
1 L:0,0,0 41.937,29.868,59.675,29.425,78.003,30.36,97.257,38.218,103.637,44.779
{{:soft:simeo:private:lines-in-edito.png?200|Polygons and polylines}}
===== Upgrading lig files (and additional files) into single opf files =====
It would be interesting to have a **lig2opf** tool to transform the legacy AMAP lig files added in an Edito Scene with all their related files (smb, dta, brc, arc...) into single standard opf files.
This could be an on-demand tool, like Tools > Convert .lig to .opf