1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
---
title: "BSc IN S5 / Advanced C programming / Morphing"
author: [Pacien TRAN-GIRARD, Adam NAILI]
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
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.
# 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
|