View source for MVD2

The goal of this project is to develop a new version of the Monteverdi software. Il will not be an upgrade of Monteverdi 1.x, but a complete redesign of it.

Monteverdi 1.x was a great success. It was a great tool to expose the OrfeoToolbox remote sensing functionalities for users not familiar with development or C++, 
but this tool has some lacks and using it is not always straightforward for the users.

For the developer’s point of view, the great number of modules developed makes Monteverdi hard to maintain. Also, using FLTK for the GUI part puts some limitations 
in the development process. In addition, Monteverdi 1.x does not allow using the [http://wiki.orfeo-toolbox.org/index.php/Main_Page applications] plugins already available.

It is time to move on to a new Monteverdi.


== What's new ==

Thanks to the user feedbacks, the new Monteverdi version will use a database to store several information. It will allow considering all the user products as a collection of images and vectors, avoiding opening them via a browser each time the image is loaded.

Most of the information stored in the Database will be extracted from the image metadata. Informations used for the rendering (histogram boundaries, channels order) will be persisted.

When the software is launched, a control panel will show the collection of the user. The user can add an image/directory to be added to the collection if not already persisted.
All the necessary files (such as Quicklook, or a pyramid for multi-resolution visualization) will be persisted too.

The developement of the GUI will be done using the Qt framework

== Documentation and HMI (Human-Machine Interaction) localization ==
The objective are to find best way to provide:
* a high-quality documentation with support a multiple language. 
* a HMI which support language localization
and promote contribution to the documentation with user friendly tools and workflow. 
   
Some usefull links to find the new documentation tools:
* [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html the reStructuredText specification] for user friendly documentation 
* [http://sphinx-doc.org/ Sphynx] document generator
* [http://docs.qgis.org/html/en/user_manual/ QGIS HTML documentation] example
* [https://github.com/qgis/QGIS-Documentation QGIS source documentation] example and readme
* [http://hub.qgis.org/projects/quantum-gis/wiki/Manual_Translation#First-notes-for-the-new-translation-workflow-based-on-rst-gettext QGIS note about new translation workflow] and an interesting list of tools
* [http://translate.sourceforge.net/wiki/ Translate Toolkit and Pootle] based on get text but which support Qt doc format
* [http://translate.sourceforge.net/wiki/toolkit/formats list of formats] used for translation and status regards Pootle
* [http://projects.gnome.org/gtranslator/features.html Gtranslator] another translation tool which support .ts and .po
=== Mv&sup2; &mdash; Monteverdi2 Viewer ===
==== Keyboard and mouse shortcut mappings ====
===== Overall =====
{|
|+Overall keymap
|-
!!!!!Key!!Action
|-
|||CTRL+||O||: '''O'''pen file(s)
|-
|||CTRL+||Q||: '''Q'''uit application
|-
|}
===== Histogram view =====
{|
|+Histogram-View keymap
|-
!!!!!Key!!Action
|-
|||||Left-button horizontal-drag||: Read histogram values (Intensity at cursor position, bin [min, Max[ and value for RGB bands)
|-
|||||Middle-button vertical-drag||: Scale histogram view
|-
|||||Right-button horizontal-drag||: Shift histogram-view towards lo/high
|-
|||||Wheel||: Scale histogram-view
|-
|}

===== Image view =====
{|
|+Image-View keymap
|-
!!!!!Key!!Action
|-
|||ALT+||wheel||: Adjust effect brush size
|-
|SHIFT+||ALT+||wheel||: Adjust effect parameter value
|-
|||||wheel||: Rotate layers
|-
|||CTRL+||wheel||: Zoom in/out
|-
|||CTRL+ALT+||wheel||: Shift dynamics range towards low/high
|-
|SHIFT+||CTRL+ALT+||wheel||: Scale dynamics range around it's mean value.
|-
|||META+||wheel||: Adjust translucency
|-
|SHIFT+||META+||wheel||: Adjust gamma correction
|-
!!!!!Key!!Action
|-
|||||+||: Zoom in
|-
|||||-||: Zoom out
|-
|||||1||: Zoom to full resolution (1:1)
|-
|||||2||: Zoom to selected layer extent
|-
|||||3||: Zoom to all layers extent
|-
|||||A||: Apply selected layer settings to '''A'''ll layers
|-
|||||P||: Use selected layer '''P'''rojection as reference projection
|-
|||||Q||: Apply 2% '''Q'''uantiles to viewed area of selected image layer
|-
|SHIFT+||||Q||: Apply 2% '''Q'''uantiles to full area of selected image layer
|-
!!!!!Key!!Action
|-
|||||C||: Switch to '''C'''hessboard effect
|-
|||||D||: Switch to local '''D'''ynamics or local contrast effect
|-
|||||G||: Switch to '''G'''radient effect
|-
|||||H||: Switch to '''H'''orizontal swipe effect
|-
|||||N||: Switch to '''N'''o effect
|-
|||||S||: Switch to '''S'''pectral angle effect
|-
|||||T||: Switch to local '''T'''ranslucency effect
|-
|||||V||: Switch to '''V'''ertical swipe effect
|-
|}

== Software design ==
=== Tools ===
Software is designed in UML (http://en.wikipedia.org/wiki/Unified_Modeling_Language) using the Java-based modelling tool ArgoUML from Tigris (http://argouml.tigris.org).

ArgoUML is availaible as free download but, for ease of use, can be be launched directly from the its homepage (http://argouml.tigris.org) or by clicking on this link: http://argouml-downloads.tigris.org/jws/argouml-latest-stable.jnlp .

=== Model ===
The UML model is accessible via the Monteverdi2 Mercurial repository (http://hg.orfeo-toolbox.org/Monteverdi2/). Please, load [http://hg.orfeo-toolbox.org/Monteverdi2/file/854962e29fab/Documentation/Design/MVD2.zargo ./Monteverdi2/Documentation/Design/MVD2.zargo].
=== Cute Qt practices ===
==== Tips & tricks ====
* Write <code>// TODO: task to do later.</code> in source code for easy grepping.
* <code>http://hg.orfeo-toolbox.org/Monteverdi2/file/d33df223ee93/Code/Common/mvdMyClass.h</code> and <code>http://hg.orfeo-toolbox.org/Monteverdi2/file/d33df223ee93/Code/Common/mvdMyClass.cxx</code> skeleton-files can be copy-pasted when inserting new files in the project repository. These skeleton-files are included in the build configuration to make sure they are syntactically correct.
==== Object-Oriented Programming ====
* Always declare destructors as <code>virtual</code> in derived-classes.
:<u>Reason</u>: derived-classes destructors are not <code>virtual</code> by default as opposed to member functions.
* Declare non-<code>public</code> scoped members (methods and attributes) in <code>private</code> scope by default.
* Promote <code>private</code> -scoped members (methods and attributes) to <code>protected</code> scope only when needed in derived-classes.
* Promote <code>private</code> or <code>protected</code> -scoped members (methods and attributes) to <code>public</code> scope only when needed.
:<u>N.B.</u>: Attributes should generally be declared in <code>private</code> scope and accessed via <code>protected</code> or <code>public</code> scope.
* Declare <code>virtual</code> methods in <code>protected</code> scope and declare an <code>inline</code> calling wrapper in <code>public</code>:
<pre>
class MyAbstractClass : public MyBaseClass
{
public:
  MyClass();
  virtual ~MyClass();
  inline bool fooAlgorithm()
  {
  // ...
  virtualFoo1();
  // ...
  virtualFoo2();
  }

protected:
  virtual bool virtualFoo1() =0;
  virtual bool virtualFoo2() const =0;

private:
};

class MyConcreteClass : public MyAbstractClass
{
public:
  MyConcreteClass();
  virtual ~MyConcreteClass();

protected:
  bool virtualFoo1();
  bool virtualFoo2() const;

private:
};
</pre>

==== Allocation ====
* Do not mix up <code>QObject</code> (parent-children) allocation system with ITK (smart-pointer) allocation system!
:<u>Reason</u>: <code>QObject</code> instances (allocated using standard C++ operator <code>::new()</code> or <code>::new[]()</code>), especially widgets, are linked together using a parent-children tree hierarchy. When a <code>QObject</Code> instance is deallocated (using the standard C++ operator <code>::delete()</code> or <code>::delete[]()</code>), its (virtual) destructor <i>automatically</i> deallocates its linked children.
* Do link <code>QObject</code> child instances to their parent parent instance using the <code>QObject(QObject* parent=0)</code> constructor by passing a non <code>NULL parent</code> as argument.
* TODO: Write <i>shallow-copy</i> mecanism information.
* TODO: Write <i>private-implementation</i> pattern informaion.

==== Internationalization ====
===== Translation workflow process =====
* Testing shell script [OBSOLETE]:
<pre>
#!/bin/sh
#
# Setup test
cd
SOMEWHERE=test
mkdir $SOMEWHERE
#
# Go somewhere
cd $SOMEWHERE
#
# Create source tree.
mkdir ./src
cd ./src
git clone https://git.orfeo-toolbox.org/otb.git
#
# Return to $SOMEWHERE
cd ..
#
# Create install tree.
mkdir -p ./install/OTB
#
# Create build tree.
mkdir -p ./build/OTB
#
# Configure OTB and build Monteverdi modules (need opengl,glew, qt, qwt...) build to merge source code strings into .ts translation files.
# /!\ 'make clean' WILL DELETE ALL ../../src/Monteverdi2/i18n/*.ts FILES!
cd ./build/Monteverdi2
cmake -DCMAKE_INSTALL_PREFIX:STRING=$HOME/$SOMEWHERE/install/OTB -DOTB_I18N_MERGE_TS:BOOL=ON ../../src/Monteverdi2
cat CMakeCache.txt | grep -e CMAKE_INSTALL_PREFIX -e OTB_I18N_MERGE_TS
#
# Uncomment line below to delete .ts translation files and regenerate them from scratch (thus loosing all translations).
ls -l ../../src/OTB/i18n/
#make clean
ls -l ../../src/OTB/i18n/
#
# Compile source code and merge .ts files.
make
ls -l ../../src/OTB/i18n/
less ../../src/OTB/i18n/fr_FR.ts
#
# Configure Monteverdi2 build for normal development & translation production.
# /!\ MERGE_TS:BOOL=OFF is the default value if CMakeCache.txt has not previously set it to ON.
cmake -DCMAKE_INSTALL_PREFIX:STRING=$HOME/$SOMEWHERE/install/Monteverdi2 -DMERGE_TS:BOOL=OFF ../../src/Monteverdi2
cat CMakeCache.txt | grep -e CMAKE_INSTALL_PREFIX -e MERGE_TS
#
# Edit .ts file(s) and translate application.
linguist ../../src/Monteverdi2/i18n/fr_FR.ts
#
# Build &ndash; application and .qm binary translation file(s) & and install
make && make install
#
# Testing install
cd ../../install/Monteverdi2
env LD_LIBRARY_PATH="./lib/otb" LANG="en_US.UTF-8" ./bin/monteverdi2
env LD_LIBRARY_PATH="./lib/otb" LANG="fr_FR.UTF-8" ./bin/monteverdi2
</pre>

===== User-Interface files =====
* Remind setting the <code>locale</code> property of user-interface root component to POSIX i.e. language: <code>C</code>; country: <code>QLocale::AnyCountry</code> when designing user-interface components (.ui files).
: <u>Reason</u>: This informs the Qt library that components texts are written in english and will be translated by the program.
* <span style="color:red"><u>/!\</u></span> Reming to prefix <code>objectName()</code> of root widget of .ui file with <code>"mvd::"</code> to notice Qt library of the namespace context where the component will be included into the source code.
: <u>Reason</u>: This is necessary for the Qt <code>lupdate</code> tool (which generates .ts translation files) to correctly manage C++ namespaces.

===== Source code strings =====
*Use [http://qt-project.org/doc/qt-4.8/qobject.html#tr <code>static QString QObject::tr(const char* sourceText, const char* disambiguation =0, int n =-1)</code>] to encapsulate strings which must be translated.
:<u>Examples</u>:
:# Basic string: <code>tr("My string to translate")</code>
:# Basic parametrized string <code>tr("My '%1' string to translate").arg("parametrized")</code>
:# Basic string with context: <code>tr("My string to translate", "Context of 'My string to translate' usefull for the translator)</code>.
:# Plural string with context: <code>tr("My plural %n string(s) to translate", "Context of 'My plural %n string to translate usefull for the translator'", count)</code>
:# Keyboard accelerators: <code>tr("Ctrl-Q", "Quit")</code>

*Use:<br />[http://qt-project.org/doc/qt-4.8/qcoreapplication.html#translate-2 <code>static QString QCoreApplication::translate(const char* context, const char* sourceText, const char* disambiguation=0, Encoding encoding=CodecForTr)</code>] or;<br />[http://qt-project.org/doc/qt-4.8/qcoreapplication.html#translate <code>static QString QCoreApplication::translate(const char* context, const char* sourceText, const char* disambiguation=0, Encoding encoding=CodecForTr, int n)</code>]<br />to translate strings outside of <code>QObject</code>-derived classes and withing global functions.

*Use [http://qt-project.org/doc/qt-4.8/qtglobal.html#QT_TR_NOOP <code>QT_TR_NOOP(sourceText)</code>] or[http://qt-project.org/doc/qt-4.8/qtglobal.html#QT_TRANSLATE_NOOP <code>QT_TRANSLATE_NOOP(context, sourceText)</code>] to translate strings completely outside of functions.

*Use <code>QString("L%1").arg(numeric)</code> to format numerical argument using system locale setting.

===== Source code comments =====
* <span style="color:red"><u>/!\</u></span> Provide class information to Qt <code>lupdate</code> tool when implementing classes, especially classes nested in namespaces (see <code>mvdMyClass.h</code> and <code>mvdMyClass.cxx</code> skelleton files in [[#Tips & tricks|Tips & tricks]] section):
<pre>/*
     TRANSLATOR MyNamespace::MyClass

     Necessary for lupdate to be aware of C++ namespaces.

     Context information of class for human translator.
 */</pre>

*Providing context information to the translator:
: <code>//: Context information for translator.</code>
: <code>/*: Context information for translator.</code>

===== Links to relevant Qt docmentation =====
* [http://qt-project.org/doc/qt-4.8/linguist-manual.html Qt Linguist manual];
* [http://qt-project.org/doc/qt-4.8/linguist-programmers.html Qt Linguist for programmers].