11 files changed, 190 insertions, 51 deletions

diff --git a/doc/project-report.md b/doc/project-report.md
index e0339d6..e48c204 100644
--- a/doc/project-report.md
+++ b/doc/project-report.md
@@ -1,30 +1,152 @@
 ---
-title: "Morphing in C"
+title: "BSc IN S5 / Advanced C programming / Morphing"
 author: [Pacien TRAN-GIRARD, Adam NAILI]
-date: 2017-11-09
+date: 2017-12-28
 ...
 
 # Project description
 
+The goal of this project is to develop a graphical application capable of generating morphing animations given two
+images and constraint parameters.
+
+Being part of the "Advanced C programming" course at [UPEM](http://www.u-pem.fr/), this application has been entirely
+written in C and makes use of the C standard library and the university's graphical application wrapper library. 
+
 ## Licensing
 
+This work is licensed under the terms of the
+[Creative Commons BY-NC-SA 4.0 license](https://creativecommons.org/licenses/by-nc-sa/4.0/) by its authors:
+Pacien TRAN-GIRARD and Adam NAILI.
+
+Build-time and run-time dependencies of this program are licensed under their own respective terms.
+
 ## Credits
 
----
+This report has been generated using the [Eisvogel template](https://github.com/Wandmalfarbe/pandoc-latex-template),
+licensed under the BSD 3-Clause License.
+
+\newpage
 
 # Compilation and usage
 
 ## Building the project
 
+The different parts of the project can be built using the make targets listed in `topics/Build.txt`.
+
+Compilation of the program requires gcc (>=6.3), libc (>=2.24) and libMLV (=2.0.2).
+
+Natural Docs (=1.51) and Pandoc are needed to generate the HTML API documentation and the project PDF report
+respectively.
+
+The whole build process has been tested and is known to work on Debian 9.
+
 ## Running the program
 
----
+The executable binary file resulting from the compilation of the project accepts two arguments: the base and the target
+images. Accepted file formats are ICO, CUR, BMP, PNM, XPM, LBM, PCX, GIF, JPEG, PNG, TGA, TIFF, and XV. Both base and
+target images must have the same dimension.
+
+The graphical interface of the application lets the user define constraint points on the two images, as well as define
+parameters such as the number of desired frames and visualise the morphing animation.
+
+The program has been tested on Debian 9 and is known to run correctly on this platform.
+
+## Additional features
+
+The program supports pairs of pictures of variable sizes.
+
+It also offers the possibility to save morphing animations in GIF format.
+
+## Bugs
+
+Incorrect Delaunay triangulations may be generated with large images of 10k² pixels or more, due to possible 64-bits
+integer overflows during the computation of such triangulations.
+
+Known bugs in the MLV library may prevent the graphical user interface from working correctly on Windows and MacOS.
+
+\newpage
 
 # Implementation details
 
+## Considerations
+
+### API and documentation
+
+Auxiliary functions have been kept module-private to avoid context pollution in the absence of namespaces.
+Exported functions and data types have been prefixed and documented properly.
+
+Natural Docs has been selected as the documentation generator for this projects for its simplicity.
+
+Some MLV library functions have been partly wrapped to ensure the coherence with the internally defined types. 
+
+### Unit testing
+
+_"Sir, the testing?"_, Caroline reminds.
+Almost all utility, logic and mathematical functions have been covered by automatic unit tests to reduce the risk of
+small-but-yet-critical mistakes and regressions during the development. Graphical unit tests requiring human validation
+have also been written in order to test the graphical user interface at the component level.
+
+Assertions have also been used within the module implementations, enforcing pre- and post-conditions inside functions.
+
 ## Modules
 
-## Additional features
+The application has been broken down into several sub-modules, each of which responsible for a well-defined and
+semantically related set of tasks, with little or no coupling between each of those parts.
+
+Following an object-oriented-like paradigm, APIs of said modules are centered around struct data type.
+Furthermore, the number of exposed functions has been kept minimal to ensure the containment of the implementations.
+
+The development of the underlying logic and the graphical interface has been delegated respectively to Pacien and Adam.
+
+\newpage
+
+### Common
+
+The common module contains utility functions for memory management and error handling, as well as common generic
+geometric and time type definitions meant to be used by the other modules, while not being semantically tied to them.
+
+### Morpher
+
+The morpher module holds the type definitions and functions related to a morphing, that is an abstract set of mapping
+constraints represented as a triangulation of a rectangle.
+
+The underlying triangulation maintains the Delaunay criteria and the positive orientation of the triangle vertices in
+the decreasing-y plane throughout the addition of new constraint point mappings.
+
+A neighbourhood graph and a linked list of those subsections are also kept up to date, respectively allowing a faster
+triangle lookup from arbitrarily given coordinates and a simple way of traversing all the triangles.
+
+### Painter
+
+The painter module provides functions to apply a previously constructed morphing to a base and a target image,
+generating a morphed image as the output.
+
+A per-triangle rasterisation algorithm has been implemented instead of the suggested per-pixel triangle lookup for
+performance reasons, as the whole process was meant to run in a single thread on the CPU, not benefiting the massive
+parallelisation possibility that a GPU would have offered.
+
+The colour of each pixel resulting from the rasterisation is interpolated taking care of the compression applied to the
+RBGa vectors from the two base images: each component is square-rooted back to its raw value before blending.
+
+### GUI
+
+TODO: modular component-based architecture, wrapping libMLV low level functions\
+      based on delegated click handlers and painting functions\
+      computing intermediate morphing between each frame, combined with a times, thus not using MLV_Animation
+
+\newpage
+
+## Miscellaneous notes
+
+The animation export feature relies on the MLV library for exporting the frames and ImageMagick for generating the final
+animated GIF. This utility library is called as an external command line tool as its direct use as a C library was not
+permitted.
 
-## Notes
+# References
 
+1. [MLV Library reference manual](http://www-igm.univ-mlv.fr/~boussica/mlv/api/French/html/index.html), A. Boussicault and M. Zipstein, September 2015
+1. [Natural Docs 1.x reference manual](https://web.archive.org/web/20170504223714/http://www.naturaldocs.org:80/documenting/reference.html), Greg Valure, May 2017 
+1. [Barycentric coordinate system](https://en.wikipedia.org/w/index.php?title=Barycentric_coordinate_system&oldid=816475141), Wikipedia contributors, December 2017
+1. [Delaunay triangulation](https://en.wikipedia.org/w/index.php?title=Delaunay_triangulation&oldid=817290072), Wikipedia contributors, December 2017
+1. [Computer Color is Broken](https://www.youtube.com/watch?v=LKnqECcg6Gw), Minute Physics, March 2015
+1. [Software Rasterization Algorithms for Filling Triangles](http://www.sunshine2k.de/coding/java/TriangleRasterization/TriangleRasterization.html), Sunshine, May 2012
diff --git a/doc/topics/build.txt b/doc/topics/build.txt
index 979d172..adcd6a8 100644
--- a/doc/topics/build.txt
+++ b/doc/topics/build.txt
@@ -5,14 +5,18 @@ List of the make targets. The global `make all` and `make clean` are also define
 
 About: Compiling
 
-> make source
+> make objects
 
 Compiles all modules.
 
+> make build
+
+Compiles the application executable file.
+
 
 About: Automatic tests
 
-> make test
+> make check
 
 Compiles and runs all unit tests.
 
@@ -28,7 +32,7 @@ About: Project report
 
 > make report
 
-Generates the project report using Pandoc.
+Generates the project report using Pandoc and generate a commit log file.
 
 
 About: Project archive
diff --git a/include/common/error.h b/include/common/error.h
index 22c2630..69104cb 100644
--- a/include/common/error.h
+++ b/include/common/error.h
@@ -13,7 +13,7 @@
 #define OUT_OF_MEMORY_ERROR "Out of memory"
 
 /**
- * Function: rage quit
+ * Function: rage_quit
  * Logs the supplied error message to stderr before exiting the program with an error status code.
  *
  * Parameters:
diff --git a/include/morpher/matrix.h b/include/morpher/matrix.h
index 8118727..e3d5517 100644
--- a/include/morpher/matrix.h
+++ b/include/morpher/matrix.h
@@ -3,10 +3,8 @@
 
 /**
  * File: matrix.h