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
153
154
155
156
157
|
---
title: "BSc IN S5 / Advanced C programming / Morphing"
author: [Pacien TRAN-GIRARD, Adam NAILI]
date: 2018-01-09
...
# 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.
## 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 used during the development 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.
\newpage
### GUI
The Graphical User Interface is designed with a modular component-based architecture. That architecture implies an
Object-Oriented Programming's vision that makes the application very flexible for adding components and
placing them. The components created are groups, buttons, and picture frames that are all based on a common structure
called Component. Groups federate Components of any type and place them by a margin management.
Click handlers and printing functions stored inside Components make possible to perform the actions on
click or to paint the component without knowing what is stored inside the group. The group is a component that handles
clicks and is able to paint itself by using the click handler and the painter function of the Component contained inside
its list. In other words, it delegates to the Components the action to perform.
It also wraps some libMLV low level functions to create basic application features that can be used to create coherent
state for the application and components. The rendering process is done by computing intermediate morphing between each
frame combined with a time. This implementation replaces the usage of MLV_Animation which implies higher memory usage
and lower fluidity due to the needed pre-calculation.
\newpage
# 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
|