Provide a plugin tutorial structure (FloodAR as archetype)

[EricBoix]

Issue by frogsapo Tuesday Apr 19, 2016 at 14:33 GMT Originally opened as https://github.com/MEPP-team/VCity/issues/99

---

Pre-requisite: issue #96

A plugin is a GUI oriented type of wrapping of an underlying process. A process (an algorithm taking an in memory data structure and processing it to yield a resulting in memory data structure) can also be wrapped in a main() function to be used from the command line or in a scripting language (e.g. Python) to be composed with other processes in a programmatic manner.

This multi-usage (multi-wrapping) strategy requires some technical organization:

• the process must be cleanly defined separately (and placed within the libfilters library).
• the plugin wrapper must use it
• the CLI must use it
• the associated tests (e.g. with ctest) must use it
• the possible Python wrappers must use this process.

The demand: provide a first reference example of such an process/wrappers organization to be used as reference example.

[EricBoix]

Comment by frogsapo Tuesday Apr 19, 2016 at 15:13 GMT

---

We shall consider the upcoming FloodAR plugin as example.

Context elements:

the ARC/Info ascii grid format (to be placed somewhere in VCity documentation)

• ARC/Info ascii grid format is one of ESRI non-proprietary formats. Within VCity files of this format as referred as being "ASC" files.
• BTW, GDAL offers an implementation driver for this format. Since VCity heavily depends on GDAL why not re-use this code instead of using VCity own implementation ?
• VCity src/gui/osg/osgMNT defines its own class MNT to deal with ASC files.

FloodAR treatment pipeline

1. Tile the ASC inputs (both water and terrain)
   • Code: ascCut.Cpp
   • Limitations:
     • this code blends the tile processing per se with the writing (to files) of the process results.
     • Additionally the code writes all the tiles at once (i.e. it is not modular enough to be called for producing a single tile)
     • although the MNT class provides a writer, ascCut.Cpp provides its own one
2. Tile the textures (orthophoto)
   • Code: cutPicture() global function (within the FloodAR Plugin)
   • Limitations:
     • Code is QT dependent because it uses QT to read and write pictures
     • cutPicture() misses a destination directory argument
     • cutPicture() hardwires it knowledge of the file hierarchy (refer to issue 90)
3. Blend ASC with textures (at tile scale) to obtain CityGML
   • Code: FloodARTools.Cxx
   • Algorithm: for each tile
     • read ASC and convert it to CityGML with src/libCityGML/improt/ImporterASC.cpp
     • "point" (refer to file located in Appearance sub-directory) the CityGML to the orthophoto corresponding tile
     • write the resulting CityGML to a file
4. Use ShapeExtrusion process to extrude buildings
5. Do some stuff concerning OBJ files (ask FloodAR author)

Work to do

Stage 1: processify ASC tiling

• Start by building a process example on stage 1 (i.e. tiling of ASC file)
• Move OSGMNT.cpp from src/gui/osg to new directory src/DataStructures/DEM (for Digital Elevation Model)
• Change VCity code accordingly
• Remove MNT::sauve_log(), MNT::sauve_partie() and MNT::sauve_partie_XML() unused methods.
• Add the ad-hoc setters, change altitudes to float...
• Replace them with a MNT::write(filename) method with the code coming from ascCut.Cpp
• Place the remaining part of ascCut.Cpp code within new directory src/libfilters/Tiling
• Within ascCut.cpp split the code in order to provide a method enabling the building of a single tile. The prototype for that method is MNT* BuildTile( MNT* in, int size_x, int size y, int tile_x, int tile_y).
• Move the main current method of ascCut.cpp to the plugin code, and rewrite it on top of the above process method: this will include
  • reading the ASC file with the MNT class,
  • building two nested loops (on X and Y) that invoke the BuildTile method and then (within the loops) write the files (with MNT class write method) where they belong.
• Make a pull request.

Stage 2: same thing (mutatis mutandis) with the texture tiling

What will remain to do

• Rename MNT class to DEM_ASC (for Digital Elevation Model)
• Use the resulting processes as use cases for issue 92