====== GroIMP module - Developers notes ======


Yongzhi Ong and Sébastien Griffon spent 9 days to develop a connection between GroIMP and AMAPstudio. A new GroIMP module has been created in Xplo. This module calls GroIMP with an XL script file and saves each step of the simulation into an ArchiTree.

===== Technical details =====

==== Conversion from GroIMP graph to ArchiTree ====

Conversion is done in several steps :

1- For each GroIMP graph node a global transformation matrix is computed.

2- Check if the GroIMP graph is multi-scale.

3- Traverse the GroIMP graph on the finest scale. For each step in this traversal, we get a pair of Nodes (linked by succession or branching edges), then a recursive function is called to reach the complex scales of the current nodes. ArchiNodes are created each time we reach a new GroIMP Node and a Map<Node, ArchiNode> is maintained.

4- Succession and Branching links between ArchiNodes are established when a common complex is encountered. Refinement (or Composition) links in ArchiTree must only be created for the first component Node(that is when a complex ArchiNode has no yet refinements (or components)).

5- The conversion of some GroIMP Node types has been implemented : Rotation nodes (RU,RL,RH), F (cylinder), Sphere.
Types conversion hierarchy must be completed in jeeb.xplo.module.groimp.model.types. The function copyValues() must be overridden and must call super.copyValues().

==== XL script requirements ====

An XL script must include 2 compulsory methods : init() and run().

==== Needed Jars ====

Some jars are needed to call GroIMP from Xplo : antlr-rt.jar, commons-math-2.2.jar, GroImp.jar (version 3434), jna.jar.
They are located in ext/groimp directory.


===== How to use it ? =====

Start Xplo and run module GroIMP (Menu Project -> New)

A panel is displayed where user can select the folder with the XL script files, then set the number of simulation step (Age) and the output step frequency (Output Step = 1 means each simulation steps are saved), then press OK.

You can find XL script examples in data/xplo/groimp :
 
 * xl-plant is a single mono-scale structure

 * xl-multiscale is a single multi-scale structure

 * xl-scene is a scene with several mono-scale structures.

{{:soft:xplo:groimp.jpg?400|}} //Xl-scene simulation result for step 8//



===== Todo list =====

In Xplo :

 * Fix XL compiler bug for custom module

 * Copy attributes from this custom modules to ArchiNodes (and add a flag in parameters to copy or not the hierarchy types attributes)

 * Enable multiple XL script files

 * Normal mesh computation  

 * Add new GITypes : See {{:soft:xplo:20131011_161916.jpg?100|}}