diff options
author | pacien | 2017-12-29 21:21:43 +0100 |
---|---|---|
committer | pacien | 2017-12-29 21:21:43 +0100 |
commit | 00eb3d02d350b7dd28afabfa160304dff4d5efb7 (patch) | |
tree | 9b1a2f1fab806f3aaf4b4d2171dbb16a35b24f9e | |
parent | b1eec2f9af2412b29719bc898a96d60379501b42 (diff) | |
download | morpher-00eb3d02d350b7dd28afabfa160304dff4d5efb7.tar.gz |
Describing modules
Signed-off-by: pacien <pacien.trangirard@pacien.net>
-rw-r--r-- | doc/project-report.md | 65 |
1 files changed, 56 insertions, 9 deletions
diff --git a/doc/project-report.md b/doc/project-report.md index c798107..e48c204 100644 --- a/doc/project-report.md +++ b/doc/project-report.md | |||
@@ -25,7 +25,7 @@ Build-time and run-time dependencies of this program are licensed under their ow | |||
25 | This report has been generated using the [Eisvogel template](https://github.com/Wandmalfarbe/pandoc-latex-template), | 25 | This report has been generated using the [Eisvogel template](https://github.com/Wandmalfarbe/pandoc-latex-template), |
26 | licensed under the BSD 3-Clause License. | 26 | licensed under the BSD 3-Clause License. |
27 | 27 | ||
28 | --- | 28 | \newpage |
29 | 29 | ||
30 | # Compilation and usage | 30 | # Compilation and usage |
31 | 31 | ||
@@ -43,15 +43,28 @@ The whole build process has been tested and is known to work on Debian 9. | |||
43 | ## Running the program | 43 | ## Running the program |
44 | 44 | ||
45 | The executable binary file resulting from the compilation of the project accepts two arguments: the base and the target | 45 | The executable binary file resulting from the compilation of the project accepts two arguments: the base and the target |
46 | images. Accepted file formats are ICO, CUR, BMP, PNM, XPM, LBM, PCX, GIF, JPEG, PNG, TGA, TIFF, and XV. | 46 | images. Accepted file formats are ICO, CUR, BMP, PNM, XPM, LBM, PCX, GIF, JPEG, PNG, TGA, TIFF, and XV. Both base and |
47 | target images must have the same dimension. | ||
47 | 48 | ||
48 | The graphical interface of the application let the user define constraint points on the two images, as well as define | 49 | The graphical interface of the application lets the user define constraint points on the two images, as well as define |
49 | parameters such as the number of desired frames and visualise the morphing animation. | 50 | parameters such as the number of desired frames and visualise the morphing animation. |
50 | 51 | ||
51 | The program has been tested on Debian 9. Known bugs in the MLV library may prevent it from running correctly on other | 52 | The program has been tested on Debian 9 and is known to run correctly on this platform. |
52 | Linux distributions and operating systems. | ||
53 | 53 | ||
54 | --- | 54 | ## Additional features |
55 | |||
56 | The program supports pairs of pictures of variable sizes. | ||
57 | |||
58 | It also offers the possibility to save morphing animations in GIF format. | ||
59 | |||
60 | ## Bugs | ||
61 | |||
62 | Incorrect Delaunay triangulations may be generated with large images of 10k² pixels or more, due to possible 64-bits | ||
63 | integer overflows during the computation of such triangulations. | ||
64 | |||
65 | Known bugs in the MLV library may prevent the graphical user interface from working correctly on Windows and MacOS. | ||
66 | |||
67 | \newpage | ||
55 | 68 | ||
56 | # Implementation details | 69 | # Implementation details |
57 | 70 | ||
@@ -77,23 +90,57 @@ Assertions have also been used within the module implementations, enforcing pre- | |||
77 | 90 | ||
78 | ## Modules | 91 | ## Modules |
79 | 92 | ||
80 | The application has been broken down into several sub-modules, each of which responsible for a well defined and | 93 | The application has been broken down into several sub-modules, each of which responsible for a well-defined and |
81 | semantically related set of tasks, with little or no coupling between each of those parts. | 94 | semantically related set of tasks, with little or no coupling between each of those parts. |
82 | 95 | ||
83 | Following an object-oriented-like paradigm, APIs of said modules are centered around struct data type. | 96 | Following an object-oriented-like paradigm, APIs of said modules are centered around struct data type. |
84 | Furthermore, the number of exposed functions has been kept minimal to ensure the containment of the implementations. | 97 | Furthermore, the number of exposed functions has been kept minimal to ensure the containment of the implementations. |
85 | 98 | ||
99 | The development of the underlying logic and the graphical interface has been delegated respectively to Pacien and Adam. | ||
100 | |||
101 | \newpage | ||
102 | |||
86 | ### Common | 103 | ### Common |
87 | 104 | ||
105 | The common module contains utility functions for memory management and error handling, as well as common generic | ||
106 | geometric and time type definitions meant to be used by the other modules, while not being semantically tied to them. | ||
107 | |||
88 | ### Morpher | 108 | ### Morpher |
89 | 109 | ||
110 | The morpher module holds the type definitions and functions related to a morphing, that is an abstract set of mapping | ||
111 | constraints represented as a triangulation of a rectangle. | ||
112 | |||
113 | The underlying triangulation maintains the Delaunay criteria and the positive orientation of the triangle vertices in | ||
114 | the decreasing-y plane throughout the addition of new constraint point mappings. | ||
115 | |||
116 | A neighbourhood graph and a linked list of those subsections are also kept up to date, respectively allowing a faster | ||
117 | triangle lookup from arbitrarily given coordinates and a simple way of traversing all the triangles. | ||
118 | |||
90 | ### Painter | 119 | ### Painter |
91 | 120 | ||
121 | The painter module provides functions to apply a previously constructed morphing to a base and a target image, | ||
122 | generating a morphed image as the output. | ||
123 | |||
124 | A per-triangle rasterisation algorithm has been implemented instead of the suggested per-pixel triangle lookup for | ||
125 | performance reasons, as the whole process was meant to run in a single thread on the CPU, not benefiting the massive | ||
126 | parallelisation possibility that a GPU would have offered. | ||
127 | |||
128 | The colour of each pixel resulting from the rasterisation is interpolated taking care of the compression applied to the | ||
129 | RBGa vectors from the two base images: each component is square-rooted back to its raw value before blending. | ||
130 | |||
92 | ### GUI | 131 | ### GUI |
93 | 132 | ||
94 | ## Additional features | 133 | TODO: modular component-based architecture, wrapping libMLV low level functions\ |
134 | based on delegated click handlers and painting functions\ | ||
135 | computing intermediate morphing between each frame, combined with a times, thus not using MLV_Animation | ||
95 | 136 | ||
96 | --- | 137 | \newpage |
138 | |||
139 | ## Miscellaneous notes | ||
140 | |||
141 | The animation export feature relies on the MLV library for exporting the frames and ImageMagick for generating the final | ||
142 | animated GIF. This utility library is called as an external command line tool as its direct use as a C library was not | ||
143 | permitted. | ||
97 | 144 | ||
98 | # References | 145 | # References |
99 | 146 | ||