Browse Source

better documentation

tonton Th 7 months ago
parent
commit
80011c4182
1 changed files with 67 additions and 42 deletions
  1. 67
    42
      doc/the_floatimg_hack.tex

+ 67
- 42
doc/the_floatimg_hack.tex View File

@@ -5,7 +5,6 @@
5 5
 \usepackage[french]{babel}
6 6
 \usepackage[utf8]{inputenc}
7 7
 \usepackage[T1]{fontenc}
8
-% XXX \usepackage{lipsum}
9 8
 \usepackage{makeidx}
10 9
 \usepackage{listings}
11 10
 \usepackage{babel}
@@ -20,6 +19,7 @@
20 19
 \usepackage{xspace}
21 20
 \usepackage[verbose]{layout}
22 21
 
22
+\setlength \parskip {0.40em}
23 23
 
24 24
 \setlength{\textheight}{640pt}
25 25
 \setlength{\textwidth}{422pt}
@@ -41,7 +41,7 @@
41 41
 
42 42
 Mais de quoi parle-t-on exactement ?
43 43
 
44
-\vspace{1em}
44
+% XXX XXX XXX\vspace{1em}
45 45
 
46 46
 Traditionnellement, les valeurs des pixels dans les images
47 47
 informatiques sont mémorisées sur 8 bits, un octet\index{octet},
@@ -53,7 +53,7 @@ chaque pixel en virgule flottante sur 32bits, le type
53 53
 \texttt{float}\index{float} du langage C. Ce qui correspond
54 54
 à la norme IEEE 754-1985. 
55 55
 
56
-\vspace{1em}
56
+% XXX XXX XXX\vspace{1em}
57 57
 
58 58
 Attention, tout le code que nous allons voir ensemble est en
59 59
 perpétuelle évolution\footnote{voir page \pageref{TODO}},
@@ -65,20 +65,41 @@ IRC de Freenode.
65 65
 
66 66
 % -------------------------------------------------------------------
67 67
 
68
+\setlength \parskip {0em}
69
+
68 70
 \tableofcontents
69 71
 \pagebreak
72
+\setlength \parskip {0.40em}
70 73
 
71
-% XXX \layout
72
-% XXX \pagebreak
74
+% \layout \pagebreak
73 75
 
74 76
 % -------------------------------------------------------------------
75 77
 \section{Théorie}\index{théorie}
76 78
 
77
-XXX\index{XXX}
78 79
 
79 80
 Pour le moment, seule la quête de l'empirisme absolu a été
80
-visée. Les justifications mathématiques attendent le retour
81
-du schmod777.
81
+visée. Les justifications mathématiques attendront le retour
82
+du schmod777. Ceci dit, rien ne nous empêche d'aller consulter
83
+Wikipedia~:
84
+
85
+% XXX XXX XXX\vspace{1em}
86
+
87
+\begin{quotation}
88
+An IEEE 754 32-bit base-2 floating-point variable has
89
+a maximum value of
90
+$(2 - 2^{-23}) \times 2^{127} \approx 3.4028235 \times 10^{38}$.
91
+All integers with 7 or fewer decimal digits, and any $2^{n}$ for
92
+a whole number $-149 \leq n \leq 127$, can be converted exactly into
93
+an IEEE 754 single-precision floating-point value.
94
+
95
+In the IEEE 754-2008 standard, the 32-bit base-2 format is
96
+officially referred to as binary32; it was called single in
97
+IEEE 754-1985.
98
+\end{quotation}
99
+
100
+Ce qui nous conduit à estimer qu'il est possible de cumuler environ
101
+quelques milliers d'images standard à 256 niveaux, sans trop avoir
102
+à se soucier des éventuelles pertes de précision.
82 103
 
83 104
 % -------------------------------------------------------------------
84 105
 
@@ -91,7 +112,7 @@ mais nous sommes tous là pour améliorer les choses, dans
91 112
 la mesure de nos moyes.
92 113
 Nous allons donc directement rentrer au cœur du problème.
93 114
 
94
-\vspace{1em}
115
+% XXX XXX XXX\vspace{1em}
95 116
 
96 117
 Pour commencer par quelques chose de simple, 
97 118
 nous allons créer une image RGB\index{RGB} complètement noire,
@@ -99,7 +120,7 @@ puis l'enregistrer dans un fichier \texttt{.fimg}\index{.fimg},
99 120
 un format complètement inconnu, puisque je viens de l'inventer
100 121
 à l'instant même.
101 122
 
102
-\vspace{1em}
123
+% XXX XXX XXX\vspace{1em}
103 124
 
104 125
 Tout d'abord, nous devons déclarer et garnir quelques variables
105 126
 pour gérer la machinerie interne.
@@ -152,7 +173,7 @@ Nous avons donc sous la main une mécanique qui ne demande qu'à
152 173
 faire des trucs futiles et des images qui clignotent.
153 174
 La suite vers la page \pageref{codaz}. 
154 175
 
155
-\vspace{1em}
176
+% XXX XXX XXX\vspace{1em}
156 177
 
157 178
 Vous trouverez dans le répertoire \texttt{tools/}\index{tools/}
158 179
 d'autres exemples de mise en œuvre des fonctions disponibles
@@ -164,7 +185,6 @@ lesquels sont décrits en page \pageref{outils}.
164 185
 
165 186
 \textit{Attention, ça devient un peu gore.}
166 187
 
167
-
168 188
 \subsection{Prérequis}
169 189
 
170 190
 Vous devez, en dehors des outils classiques (bash, gcc, make\dots), 
@@ -173,8 +193,6 @@ pour Debian et dérivées}~: libv4l2, libpnglite, libtiff, libnetpbm,
173 193
 libz,
174 194
 et probablement d'autres choses.
175 195
 
176
-\vspace{1em}
177
-
178 196
 Il est même quasiment certain que Bash soit indispensable, tout
179 197
 comme \textsc{gnu}/make\index{make}.
180 198
 Une connaissance de base de l'utilisation du shell\index{shell}
@@ -189,7 +207,7 @@ Dans chacun des répertoires à traiter, ce script devrait trouver
189 207
 un Makefile et un fichier \texttt{t.c} qui est le source de la cible
190 208
 par défaut du make.
191 209
 
192
-\vspace{1em}
210
+% XXX XXX XXX\vspace{1em}
193 211
 
194 212
 Pour le moment, la procédure d'installation est un peu rude,
195 213
 pour ne pas dire clairement sommaire.
@@ -198,8 +216,6 @@ vous pouvez copier les deux fichiers \texttt{floatimg.h} et \texttt{libfloatimg.
198 216
 dans un emplacement approprié, par exemple
199 217
 \texttt{/usr/local/include} et \texttt{/usr/local/lib}.
200 218
 
201
-\vspace{1em}
202
-
203 219
 Le script \texttt{install.sh}, à la racine du projet, est censé
204 220
 faciliter un peu la chose. Il prend également en compte la copie
205 221
 des divers binaires du dossier \texttt{tools/} (cf. page \pageref{outils})
@@ -215,7 +231,6 @@ de vos codes source,
215 231
 contenant un certain nombre de définition de structures, de macros, 
216 232
 de constantes\footnote{À l'ancienne, via le pré-processeur} 
217 233
 et les prototypes des fonctions utilisables par vos logiciels.
218
-\vspace{1em}
219 234
 
220 235
 Au niveau du code source, ces fonctions sont approximativement
221 236
 classées en deux catégories : \texttt{lib/} et \texttt{funcs/}.
@@ -263,7 +278,7 @@ d'idées approximatives. C'est cette utilisation constructive de larache
263 278
 qui fait que seuls les champs documentés de cette structure ne sont
264 279
 pas explosifs.
265 280
 
266
-\vspace{1em}
281
+% XXX XXX XXX\vspace{1em}
267 282
 
268 283
 Mais revenons aux choses sérieuses\dots
269 284
 Les deux champs suivants (fval et count) sont à la disposition du
@@ -273,7 +288,7 @@ chose : imaginons un périphérique de capture qui nous fournisse des
273 288
 images en gris sur 4 bits. Et que nous voulions cumuler\index{cumul}
274 289
 quelques images...
275 290
 
276
-\vspace{1em}
291
+% XXX XXX XXX\vspace{1em}
277 292
 
278 293
 Le champ \textsl{count} sera mis à 0 et 
279 294
 le champ \textsl{fval} sera initialisé à 15.0
@@ -309,7 +324,7 @@ documentés dans ce document, et les autres sont dangereux à
309 324
 toucher. Les types d'images actuellement gérés sont les trois grands
310 325
 classiques : gray, rgb et rgba.  et expliquées quelques lignes plus haut.
311 326
 
312
-\vspace{1em}
327
+% XXX XXX XXX\vspace{1em}
313 328
 
314 329
 C'est bien beau d'être enfin résident en mémoire centrale, mais
315 330
 pouvoir aussi exister à long terme en étant stocké dans la matrice
@@ -328,10 +343,12 @@ ait précisément les mêmes caractéristiques
328 343
 pré-allouée. Mias comment peut-on connaitre ces valeurs ?
329 344
 
330 345
 \begin{verbatim}
331
-int fimg_fileinfos(char *fname, int *datas);
346
+int fimg_fileinfos(char *fname, int datas[3]);
332 347
 \end{verbatim}
333 348
 
334
-
349
+Si tout s'est bien passé (valeur retournée égale à 0),
350
+on va trouver la largeur dans datas[0],
351
+la hauteur dans datas[1] et le type dans datas[2].
335 352
 
336 353
 % 	_________
337 354
 
@@ -343,7 +360,7 @@ Il y a des fonctions pour ça, par exemple~:
343 360
 
344 361
 \begin{verbatim}
345 362
 int fimg_plot_rgb (FloatImg *head, int x, int y, 
346
-                                   float r, float g, float b);
363
+                                          float r, float g, float b);
347 364
 \end{verbatim}
348 365
 
349 366
 Les paramètres sont explicites, mais leur validité doit être
@@ -385,8 +402,6 @@ maximale du capteur, et le second sert à compter le
385 402
 nombre de capture\footnote{Et c'est bien géré aussi
386 403
 dans l'upscaling.} effectuées.
387 404
 
388
-\vspace{1em}
389
-
390 405
 La fonction
391 406
 \texttt{fimg\_normalize(FloatImg *fi, double maxima, int notused);}
392 407
 tente de gérer ce cas d'utilisation. Son ajout au captureur d'images
@@ -395,8 +410,6 @@ floues sera probablement le bienvenue. Je me suis bien rendu compte
395 410
 censé faire des films flous à partir d'images floues} en situation
396 411
 festive qu'il manquait des données dans la chaine de traitement.
397 412
 
398
-\vspace{1em}
399
-
400 413
 L'autre façon de procéder est d'explorer notre image à la
401 414
 recherche de la valeur maximale.
402 415
 La fonction \texttt{float fimg\_get\_maxvalue(\&fimg)} est
@@ -404,8 +417,6 @@ faite pour ça.
404 417
 C'est actuellement la méthode utilisée par l'outil qui
405 418
 sert à faire les modifications de contraste (page \pageref{fimgfx}).
406 419
 
407
-\vspace{1em}
408
-
409 420
 La prochaine étape consistera à trouver une façon de faire
410 421
 une égalisation\index{égalisation} par histogramme\index{histogramme}
411 422
 qui respecte, dans toute sa futilité,  le concept\index{concept}
@@ -436,12 +447,15 @@ faut bien exporter nos images en quelque chose de plus
436 447
 connu. Bien entendu, c'est toujours affaire de compromis
437 448
 entre précision de valeurs et taille des fichiers.
438 449
 
450
+Il faut aussi reconnaitre que c'est un peu la jungle dans les
451
+formats de fichiers d'image\dots 
452
+
439 453
 \subsubsection{Vers PNM}\index{PNM}
440 454
 
441 455
 Nous avons ici 16 bits par composante, mais au prix
442 456
 d'une taille énorme sur les fichiers. D'autre coté,
443 457
 l'utilisation du codage \textsc{ascii}\index{ascii}
444
-(alors qu'on peut mettre du binaire) y est pour quelque chose.
458
+(alors qu'on pourrait mettre du binaire, plus compact) y est pour quelque chose.
445 459
 
446 460
 \begin{verbatim}
447 461
 int fimg_save_as_pnm(FloatImg *head, char *fname, int flags);
@@ -457,8 +471,12 @@ Les autres bits ne sont pas utilisés et doivent être à zéro.
457 471
 
458 472
 \subsubsection{Vers PNG}\index{PNG}
459 473
 
460
-Actuellement, uniquement en 8 bits par composante, mais bonne
461
-compression.
474
+Actuellement, on peut enregistrer uniquement en mode 8 bits par composante,
475
+mais avec une bonne compression.
476
+
477
+\begin{verbatim}
478
+int fimg_save_as_png(FloatImg *src, char *outname, int flags)
479
+\end{verbatim}
462 480
 
463 481
 \subsubsection{Vers TIFF}\index{TIFF}
464 482
 
@@ -542,7 +560,7 @@ in-fine sur des objets que l'on peut considérer comme « physiques »,
542 560
 il est important de passer à une utilisation
543 561
 normale\footnote{Il y a une vie en dehors de git.} et construire
544 562
 des trucs qui mettent en action le code primitif.
545
-\vspace{1em}
563
+% XXX XXX XXX\vspace{1em}
546 564
 
547 565
 Ces machins ont en commun deux options bien pratiques~:
548 566
 \texttt{-h} pour avoir un résumé des options disponibles
@@ -674,7 +692,7 @@ Quelques petits proggies pour exporter notre format\index{.fimg} secret
674 692
 vers des choses plus directement utilisables. À condition que le
675 693
 code soit écrit et documenté.
676 694
 
677
-\vspace{1em}
695
+% XXX XXX XXX\vspace{1em}
678 696
 
679 697
 D'un autre coté, écrire un greffon d'import/export pour
680 698
 Gimp\index{Gimp} ou Imagemagick\index{Imagemagick} ou Krita\index{Krita}
@@ -684,7 +702,7 @@ ne devrait pas être trop difficile. Des volontaires ?
684 702
 
685 703
 Nous avons vu dans ce document que chaque image flottante pouvait
686 704
 avoir plusieurs plans de réalité. Il ne faut en négliger aucun.
687
-\vspace{1em}
705
+% XXX XXX XXX\vspace{1em}
688 706
 
689 707
 Il faut quand même deviner que pour passer de l'espace RGB\index{RGB}
690 708
 à une abstraction linéaire mono-dimensionnelle, il existe une foultitude
@@ -694,7 +712,8 @@ de méthodes, toutes plus légitimes que les autres.
694 712
 \section{TODO}\index{TODO}\label{TODO}
695 713
 
696 714
 Il reste plein de choses à faire pour que ce soit vraiment utilisable.
697
-\vspace{1em}
715
+
716
+% XXX XXX XXX\vspace{1em}
698 717
 
699 718
 \begin{itemize} 
700 719
 
@@ -714,7 +733,7 @@ avec un peu de rache\index{rache} dedans. Ce qui est autorisé dans
714 733
 les exemples, mais dans la vrai vie, il ne faut jamais négliger
715 734
 le traitement des éventuelles erreurs.
716 735
 
717
-\vspace{1em}
736
+% XXX XXX XXX\vspace{1em}
718 737
 
719 738
 Nous savons générer une image contenant des pixels aux valeurs
720 739
 probablement aléatoires (drand48\index{drand48}). Que se passe-t-il si 
@@ -758,7 +777,8 @@ Projet externe en cours d'expérimentation.
758 777
 Donc, maintenant, nous savons un peu tripoter ces images flottantes.
759 778
 Et nous devons nous poser une question fondamentale\footnote{primitive ?}
760 779
 sur la provenance de ces données prétendant être des images.
761
-\vspace{1em}
780
+
781
+% XXX XXX XXX\vspace{1em}
762 782
 
763 783
 En fait, notre désir secret est la découverte des choses cachées du
764 784
 monde qui nous entoure. Nous voulons des images du \textbf{réel} et
@@ -794,9 +814,13 @@ L'option \texttt{-s} doit correspondre à une des
794 814
 résolutions possibles de votre capteur. Le type du
795 815
 fichier en sortie (option \texttt{-o}) est déterminé par
796 816
 l'extension, actuellement 
797
-seulement \texttt{.fimg} et \texttt{.pnm} sont reconnus.
817
+seulement \texttt{.fimg}, \texttt{.pnm} et \texttt{.png}
818
+sont reconnus.
819
+
798 820
 La conversion en gris (option \texttt{-g}) mérite un
799 821
 peu plus de travail, et une paramétrisation plus facile.
822
+L'ajustement de contraste (option\texttt{-c}) est
823
+vaguement expliqué page \pageref{contraste}.
800 824
 
801 825
 L'option \texttt{-X} me permet d'intégrer des \textit{fritures}
802 826
 expérimentales dans le binaire, et ne doit donc pas être
@@ -815,7 +839,7 @@ Pour être rigoureux dans la prise de vue, ce $N$ doit
815 839
 N'hésitez pas à faire des essais, le résultat est parfois
816 840
 aléatoire, surtout avec une caméra qui bouge.
817 841
 
818
-\vspace{1em}
842
+% XXX XXX XXX\vspace{1em}
819 843
 
820 844
 \textbf{Là, il manque un schéma\dots}
821 845
 
@@ -848,7 +872,8 @@ un Linux\index{Linux}, et ça \textsl{juste marche}.
848 872
 Sauf que c'est quand même un peu galère à déplacer, il faut
849 873
 avoir un shell pour déclencher, c'est pas facile à utiliser
850 874
 en mode portnawak\dots
851
-\vspace{1em}
875
+
876
+% XXX XXX XXX\vspace{1em}
852 877
 
853 878
 L'idée est donc de construire un appareil autonome, basé sur un Raspi et
854 879
 une webcam \textsc{usb}\index{USB}, pilotable par \textsc{lirc}\index{LIRC},

Loading…
Cancel
Save