better documentation

doc/the_floatimg_hack.tex

@@ -5,7 +5,6 @@
 \usepackage[french]{babel}
 \usepackage[utf8]{inputenc}
 \usepackage[T1]{fontenc}
-% XXX \usepackage{lipsum}
 \usepackage{makeidx}
 \usepackage{listings}
 \usepackage{babel}
@@ -20,6 +19,7 @@
 \usepackage{xspace}
 \usepackage[verbose]{layout}
 
+\setlength \parskip {0.40em}
 
 \setlength{\textheight}{640pt}
 \setlength{\textwidth}{422pt}
@@ -41,7 +41,7 @@
 
 Mais de quoi parle-t-on exactement ?
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Traditionnellement, les valeurs des pixels dans les images
 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
 \texttt{float}\index{float} du langage C. Ce qui correspond
 à la norme IEEE 754-1985. 
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Attention, tout le code que nous allons voir ensemble est en
 perpétuelle évolution\footnote{voir page \pageref{TODO}},
@@ -65,20 +65,41 @@ IRC de Freenode.
 
 % -------------------------------------------------------------------
 
+\setlength \parskip {0em}
+
 \tableofcontents
 \pagebreak
+\setlength \parskip {0.40em}
 
-% XXX \layout
-% XXX \pagebreak
+% \layout \pagebreak
 
 % -------------------------------------------------------------------
 \section{Théorie}\index{théorie}
 
-XXX\index{XXX}
 
 Pour le moment, seule la quête de l'empirisme absolu a été
-visée. Les justifications mathématiques attendent le retour
-du schmod777.
+visée. Les justifications mathématiques attendront le retour
+du schmod777. Ceci dit, rien ne nous empêche d'aller consulter
+Wikipedia~:
+
+% XXX XXX XXX\vspace{1em}
+
+\begin{quotation}
+An IEEE 754 32-bit base-2 floating-point variable has
+a maximum value of
+$(2 - 2^{-23}) \times 2^{127} \approx 3.4028235 \times 10^{38}$.
+All integers with 7 or fewer decimal digits, and any $2^{n}$ for
+a whole number $-149 \leq n \leq 127$, can be converted exactly into
+an IEEE 754 single-precision floating-point value.
+
+In the IEEE 754-2008 standard, the 32-bit base-2 format is
+officially referred to as binary32; it was called single in
+IEEE 754-1985.
+\end{quotation}
+
+Ce qui nous conduit à estimer qu'il est possible de cumuler environ
+quelques milliers d'images standard à 256 niveaux, sans trop avoir
+à se soucier des éventuelles pertes de précision.
 
 % -------------------------------------------------------------------
 
@@ -91,7 +112,7 @@ mais nous sommes tous là pour améliorer les choses, dans
 la mesure de nos moyes.
 Nous allons donc directement rentrer au cœur du problème.
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Pour commencer par quelques chose de simple, 
 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},
 un format complètement inconnu, puisque je viens de l'inventer
 à l'instant même.
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Tout d'abord, nous devons déclarer et garnir quelques variables
 pour gérer la machinerie interne.
@@ -152,7 +173,7 @@ Nous avons donc sous la main une mécanique qui ne demande qu'à
 faire des trucs futiles et des images qui clignotent.
 La suite vers la page \pageref{codaz}. 
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Vous trouverez dans le répertoire \texttt{tools/}\index{tools/}
 d'autres exemples de mise en œuvre des fonctions disponibles
@@ -164,7 +185,6 @@ lesquels sont décrits en page \pageref{outils}.
 
 \textit{Attention, ça devient un peu gore.}
 
-
 \subsection{Prérequis}
 
 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,
 libz,
 et probablement d'autres choses.
 
-\vspace{1em}
-
 Il est même quasiment certain que Bash soit indispensable, tout
 comme \textsc{gnu}/make\index{make}.
 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
 un Makefile et un fichier \texttt{t.c} qui est le source de la cible
 par défaut du make.
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Pour le moment, la procédure d'installation est un peu rude,
 pour ne pas dire clairement sommaire.
@@ -198,8 +216,6 @@ vous pouvez copier les deux fichiers \texttt{floatimg.h} et \texttt{libfloatimg.
 dans un emplacement approprié, par exemple
 \texttt{/usr/local/include} et \texttt{/usr/local/lib}.
 
-\vspace{1em}
-
 Le script \texttt{install.sh}, à la racine du projet, est censé
 faciliter un peu la chose. Il prend également en compte la copie
 des divers binaires du dossier \texttt{tools/} (cf. page \pageref{outils})
@@ -215,7 +231,6 @@ de vos codes source,
 contenant un certain nombre de définition de structures, de macros, 
 de constantes\footnote{À l'ancienne, via le pré-processeur} 
 et les prototypes des fonctions utilisables par vos logiciels.
-\vspace{1em}
 
 Au niveau du code source, ces fonctions sont approximativement
 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
 qui fait que seuls les champs documentés de cette structure ne sont
 pas explosifs.
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Mais revenons aux choses sérieuses\dots
 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
 images en gris sur 4 bits. Et que nous voulions cumuler\index{cumul}
 quelques images...
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Le champ \textsl{count} sera mis à 0 et 
 le champ \textsl{fval} sera initialisé à 15.0
@@ -309,7 +324,7 @@ documentés dans ce document, et les autres sont dangereux à
 toucher. Les types d'images actuellement gérés sont les trois grands
 classiques : gray, rgb et rgba.  et expliquées quelques lignes plus haut.
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 C'est bien beau d'être enfin résident en mémoire centrale, mais
 pouvoir aussi exister à long terme en étant stocké dans la matrice
@@ -328,10 +343,12 @@ ait précisément les mêmes caractéristiques
 pré-allouée. Mias comment peut-on connaitre ces valeurs ?
 
 \begin{verbatim}
-int fimg_fileinfos(char *fname, int *datas);
+int fimg_fileinfos(char *fname, int datas[3]);
 \end{verbatim}
 
-
+Si tout s'est bien passé (valeur retournée égale à 0),
+on va trouver la largeur dans datas[0],
+la hauteur dans datas[1] et le type dans datas[2].
 
 % 	_________
 
@@ -343,7 +360,7 @@ Il y a des fonctions pour ça, par exemple~:
 
 \begin{verbatim}
 int fimg_plot_rgb (FloatImg *head, int x, int y, 
-                                   float r, float g, float b);
+                                          float r, float g, float b);
 \end{verbatim}
 
 Les paramètres sont explicites, mais leur validité doit être
@@ -385,8 +402,6 @@ maximale du capteur, et le second sert à compter le
 nombre de capture\footnote{Et c'est bien géré aussi
 dans l'upscaling.} effectuées.
 
-\vspace{1em}
-
 La fonction
 \texttt{fimg\_normalize(FloatImg *fi, double maxima, int notused);}
 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
 censé faire des films flous à partir d'images floues} en situation
 festive qu'il manquait des données dans la chaine de traitement.
 
-\vspace{1em}
-
 L'autre façon de procéder est d'explorer notre image à la
 recherche de la valeur maximale.
 La fonction \texttt{float fimg\_get\_maxvalue(\&fimg)} est
@@ -404,8 +417,6 @@ faite pour ça.
 C'est actuellement la méthode utilisée par l'outil qui
 sert à faire les modifications de contraste (page \pageref{fimgfx}).
 
-\vspace{1em}
-
 La prochaine étape consistera à trouver une façon de faire
 une égalisation\index{égalisation} par histogramme\index{histogramme}
 qui respecte, dans toute sa futilité,  le concept\index{concept}
@@ -436,12 +447,15 @@ faut bien exporter nos images en quelque chose de plus
 connu. Bien entendu, c'est toujours affaire de compromis
 entre précision de valeurs et taille des fichiers.
 
+Il faut aussi reconnaitre que c'est un peu la jungle dans les
+formats de fichiers d'image\dots 
+
 \subsubsection{Vers PNM}\index{PNM}
 
 Nous avons ici 16 bits par composante, mais au prix
 d'une taille énorme sur les fichiers. D'autre coté,
 l'utilisation du codage \textsc{ascii}\index{ascii}
-(alors qu'on peut mettre du binaire) y est pour quelque chose.
+(alors qu'on pourrait mettre du binaire, plus compact) y est pour quelque chose.
 
 \begin{verbatim}
 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.
 
 \subsubsection{Vers PNG}\index{PNG}
 
-Actuellement, uniquement en 8 bits par composante, mais bonne
-compression.
+Actuellement, on peut enregistrer uniquement en mode 8 bits par composante,
+mais avec une bonne compression.
+
+\begin{verbatim}
+int fimg_save_as_png(FloatImg *src, char *outname, int flags)
+\end{verbatim}
 
 \subsubsection{Vers TIFF}\index{TIFF}
 
@@ -542,7 +560,7 @@ in-fine sur des objets que l'on peut considérer comme « physiques »,
 il est important de passer à une utilisation
 normale\footnote{Il y a une vie en dehors de git.} et construire
 des trucs qui mettent en action le code primitif.
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Ces machins ont en commun deux options bien pratiques~:
 \texttt{-h} pour avoir un résumé des options disponibles
@@ -674,7 +692,7 @@ Quelques petits proggies pour exporter notre format\index{.fimg} secret
 vers des choses plus directement utilisables. À condition que le
 code soit écrit et documenté.
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 D'un autre coté, écrire un greffon d'import/export pour
 Gimp\index{Gimp} ou Imagemagick\index{Imagemagick} ou Krita\index{Krita}
@@ -684,7 +702,7 @@ ne devrait pas être trop difficile. Des volontaires ?
 
 Nous avons vu dans ce document que chaque image flottante pouvait
 avoir plusieurs plans de réalité. Il ne faut en négliger aucun.
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Il faut quand même deviner que pour passer de l'espace RGB\index{RGB}
 à une abstraction linéaire mono-dimensionnelle, il existe une foultitude
@@ -694,7 +712,8 @@ de méthodes, toutes plus légitimes que les autres.
 \section{TODO}\index{TODO}\label{TODO}
 
 Il reste plein de choses à faire pour que ce soit vraiment utilisable.
-\vspace{1em}
+
+% XXX XXX XXX\vspace{1em}
 
 \begin{itemize} 
 
@@ -714,7 +733,7 @@ avec un peu de rache\index{rache} dedans. Ce qui est autorisé dans
 les exemples, mais dans la vrai vie, il ne faut jamais négliger
 le traitement des éventuelles erreurs.
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 Nous savons générer une image contenant des pixels aux valeurs
 probablement aléatoires (drand48\index{drand48}). Que se passe-t-il si 
@@ -758,7 +777,8 @@ Projet externe en cours d'expérimentation.
 Donc, maintenant, nous savons un peu tripoter ces images flottantes.
 Et nous devons nous poser une question fondamentale\footnote{primitive ?}
 sur la provenance de ces données prétendant être des images.
-\vspace{1em}
+
+% XXX XXX XXX\vspace{1em}
 
 En fait, notre désir secret est la découverte des choses cachées du
 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
 résolutions possibles de votre capteur. Le type du
 fichier en sortie (option \texttt{-o}) est déterminé par
 l'extension, actuellement 
-seulement \texttt{.fimg} et \texttt{.pnm} sont reconnus.
+seulement \texttt{.fimg}, \texttt{.pnm} et \texttt{.png}
+sont reconnus.
+
 La conversion en gris (option \texttt{-g}) mérite un
 peu plus de travail, et une paramétrisation plus facile.
+L'ajustement de contraste (option\texttt{-c}) est
+vaguement expliqué page \pageref{contraste}.
 
 L'option \texttt{-X} me permet d'intégrer des \textit{fritures}
 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
 N'hésitez pas à faire des essais, le résultat est parfois
 aléatoire, surtout avec une caméra qui bouge.
 
-\vspace{1em}
+% XXX XXX XXX\vspace{1em}
 
 \textbf{Là, il manque un schéma\dots}
 
@@ -848,7 +872,8 @@ un Linux\index{Linux}, et ça \textsl{juste marche}.
 Sauf que c'est quand même un peu galère à déplacer, il faut
 avoir un shell pour déclencher, c'est pas facile à utiliser
 en mode portnawak\dots
-\vspace{1em}
+
+% XXX XXX XXX\vspace{1em}
 
 L'idée est donc de construire un appareil autonome, basé sur un Raspi et
 une webcam \textsc{usb}\index{USB}, pilotable par \textsc{lirc}\index{LIRC},