wouaou, what a nicer documentation

doc/mkdoc.sh

@@ -2,6 +2,8 @@
 
 DOC=the_floatimg_hack
 
+bash ./mkgraf.sh
+
 pdflatex $DOC.tex
 
 makeindex $DOC

doc/mkgraf.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+PI=" 3.141592654 "
+OUT="foo.tex"
+
+gnuplot << __EOF__
+
+set term latex
+set output "$OUT"
+set title "COS010"
+
+plot					\
+	[0:1] [0:1]			\
+	(0.5 - 0.5 * cos(x*$PI))	\
+	with line
+
+__EOF__
+
+wc $OUT

doc/the_floatimg_hack.tex

@@ -21,6 +21,7 @@
 
 \setlength \parskip {0.40em}
 
+\setlength{\hoffset}{0em}
 \setlength{\textheight}{640pt}
 \setlength{\textwidth}{422pt}
 \setlength{\marginparwidth}{10pt}
@@ -82,8 +83,6 @@ 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
@@ -99,7 +98,8 @@ IEEE 754-1985.
 
 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.
+à se soucier des éventuelles pertes de précision. Mais ça demande
+à être confirmé par des esprits supérieurs.
 
 % -------------------------------------------------------------------
 
@@ -109,19 +109,15 @@ quelques milliers d'images standard à 256 niveaux, sans trop avoir
 basiques en C, gérant la structure des données d'image en mémoire
 et sur disque. Ça a été imaginé de façon presque empirique,
 mais nous sommes tous là pour améliorer les choses, dans
-la mesure de nos moyes.
+la mesure de nos moyens.
 Nous allons donc directement rentrer au cœur du problème.
 
-% XXX XXX XXX\vspace{1em}
-
 Pour commencer par quelques chose de simple, 
 nous allons créer une image RGB\index{RGB} complètement noire,
 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.
 
-% XXX XXX XXX\vspace{1em}
-
 Tout d'abord, nous devons déclarer et garnir quelques variables
 pour gérer la machinerie interne.
 
@@ -173,8 +169,6 @@ 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}. 
 
-% 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
 sous formes d'outils en ligne de commande,
@@ -207,8 +201,6 @@ 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.
 
-% XXX XXX XXX\vspace{1em}
-
 Pour le moment, la procédure d'installation est un peu rude,
 pour ne pas dire clairement sommaire.
 Si le résultat de l'étape compilation vous semble correct,
@@ -278,8 +270,6 @@ 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.
 
-% XXX XXX XXX\vspace{1em}
-
 Mais revenons aux choses sérieuses\dots
 Les deux champs suivants (fval et count) sont à la disposition du
 \textsl{yuser}
@@ -288,8 +278,6 @@ 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...
 
-% XXX XXX XXX\vspace{1em}
-
 Le champ \textsl{count} sera mis à 0 et 
 le champ \textsl{fval} sera initialisé à 15.0
 (qui est la valeur maximale que peut renvoyer le capteur).
@@ -324,8 +312,6 @@ 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.
 
-% 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
 est tout aussi pertinent. Il y a deux opérations qui supportent le
@@ -347,8 +333,11 @@ 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],
+on va trouver la largeur dans \texttt{datas[0]},
-la hauteur dans datas[1] et le type dans datas[2].
+la hauteur dans \texttt{datas[1]} et le type dans \texttt{datas[2]}.
+
+La fonction \texttt{fimg\_type\_is\_valid(int type)} peut
+vous aider.
 
 % 	_________
 
@@ -378,11 +367,13 @@ photographie\index{photographie} en cumul\index{cumul}.
 Certaines opérations d'ajustement du contraste d'une image
 semblent cohérents avec la notion d'image flottante.
 Certains d'entre eux, les plus simples, sont disponibles.
+Les autres sont à imaginer.
 
 Ils prennent chacun trois paramètres, d'abord les images
 source et destination (\texttt{* FloatImg}), et le troisième
 est un nombre en double précision donnant la valeur
-maximale \textsl{supposée} de l'image source.
+maximale \textsl{supposée} de l'image source,
+valeur qui peut être déterminée de plusieurs manières.
 
 \begin{verbatim}
 /* source in lib/contrast.c */
@@ -392,6 +383,11 @@ int fimg_cos_01(FloatImg *s, FloatImg *d, double maxval);
 int fimg_cos_010(FloatImg *s, FloatImg *d, double maxval);
 \end{verbatim}
 
+\begin{figure}
+\input{foo.tex}				% XXX XXX XXX 
+\caption{Correcteur cos01}
+\end{figure}
+
 Rappelons qu'il est possible pour un logiciel applicatif
 comme \texttt{grabvidseq} (Cf page \pageref{grabvidseq})
 de renseigner deux champs du descripteur d'image avec des
@@ -471,11 +467,11 @@ Les autres bits ne sont pas utilisés et doivent être à zéro.
 
 \subsubsection{Vers PNG}\index{PNG}
 
-Actuellement, on peut enregistrer uniquement en mode 8 bits par composante,
+Actuellement, on peut enregistrer uniquement en mode RGB, 8 bits par composante,
-mais avec une bonne compression.
+mais on a quand même une bonne compression, ça compense.
 
 \begin{verbatim}
-int fimg_save_as_png(FloatImg *src, char *outname, int flags)
+int fimg_save_as_png(FloatImg *src, char *outname, int flags);
 \end{verbatim}
 
 \subsubsection{Vers TIFF}\index{TIFF}
@@ -515,12 +511,20 @@ To be done\index{XXX}
 
 \subsection{Exemple de fonction}\index{exemple}
 
-Nous allons écrire une fonction qui va faire quelque chose
+Nous allons maintenant écrire une fonction intégrable dans
+le répertoire \texttt{funcs/}.
+Elle aura donc accès aux \textsl{internals}%
+\footnote{que je peux décider de changer n'importe quand}
+de \textsc{FloatImg},
+une chose qui est en principe interdit aux programmes
+\textsl{enduser}. Soyez prudents.
+
+Cette fonction va faire quelque chose
 à partir d'une image source et d'une valeur, et écrire le
 résultat dans une image de destination.
 Pour simplifier les choses, nous n'allons traiter que les
 images de type \textsc{FIMG\_TYPE\_RGB}, de loin le plus
-répandu.
+répandu par les temps qui courent.
 
 \begin{verbatim}
 int fimg_example(FloatImg *s, FloatImg *d, float value)
@@ -528,6 +532,7 @@ int fimg_example(FloatImg *s, FloatImg *d, float value)
 int     size, index;
 
 if ( s->type!=FIMG_TYPE_RGB || d->type!=FIMG_TYPE_RGB) {
+        perror("fimg_example");
         return -1;
         }
 
@@ -560,19 +565,19 @@ 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.
-% XXX XXX XXX\vspace{1em}
 
-Ces machins ont en commun deux options bien pratiques~:
+Ces machins ont en commun quelques options bien pratiques~:
-\texttt{-h} pour avoir un résumé des options disponibles
+\texttt{-h} pour avoir un résumé des options disponibles,
-et \texttt{-v} qui augmente la puissance de bavardage.
+\texttt{-v} qui augmente la puissance de bavardage, et
+\texttt{-K nn.nn} pour un paramètre flottant.
 Dans un avenir incertain, il existera des pages de man\index{man}.
 
 %		---------------------
 
 \subsection{mkfimg}\index{mkfimg}\label{mkfimg}
 
-Création d'un fichier contenant une image de « teinte » constante
+Propose la création d'un fichier contenant une image de « teinte »
-(ou pas).
+constante (ou pas).
 Cette notion de teinte est assez inconsistante pour le moment,
 mais ça n'est pas si grave que ça.
 
@@ -589,7 +594,7 @@ La plupart des types d'image générée prennent un paramètre flottant qui
 devra être donné avec l'option \texttt{-k F.F} avec une valeur par défaut
 à $1.0$.
 
-\begin{description}
+\begin{description}	\index{XXX}
 \item [black/gray/grey:] efface avec 0.0 (black) ou avec la valeur
 		\texttt{-k} (gray).
 \item [drand48:] beaucoup de bruit dans chacun des canaux.
@@ -643,7 +648,7 @@ pas vraiment compte du contenu de l'image.
 \begin{verbatim}
 tth@daubian:~/Devel/FloatImg/tools$ ./fimgfx -v -h
 --- fimg special effects ---
-        cos01 cos010 pow2 sqrt 
+        cos01 cos010 pow2 sqrt gray0 xper
 \end{verbatim}
 
 Certaines de ces opérations ont besoin d'un paramètre flottant.
@@ -681,7 +686,9 @@ options:
 
 Pour des operateurs paramétrable (comme \texttt{mix}), le paramêtre
 flottant doit être fourni en utilisant l'option \texttt{-k}.
-La véracité mathématique n'est pas garantie.
+La véracité mathématique n'est pas garantie. Et n'oubliez pas que
+les valeurs négatives peuvent être la cause de \textsl{glitches}
+de qualitay.
 
 \subsection{fimg2png, fimg2pnm, fimg2tiff}
 		\index{fimg2png}\label{fimg2png}
@@ -692,8 +699,6 @@ Quelques petits proggies pour exporter notre format\index{.fimg} secret
 vers des choses plus directement utilisables. À condition que le
 code soit écrit et documenté.
 
-% 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}
 ne devrait pas être trop difficile. Des volontaires ?
@@ -702,7 +707,6 @@ 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.
-% 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
@@ -713,8 +717,6 @@ de méthodes, toutes plus légitimes que les autres.
 
 Il reste plein de choses à faire pour que ce soit vraiment utilisable.
 
-% XXX XXX XXX\vspace{1em}
-
 \begin{itemize} 
 
 \item	Import/export au format \textsc{tiff}\index{tiff}.
@@ -733,8 +735,6 @@ 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.
 
-% 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 
 nous faisons la somme de plusieurs centaines\footnote{Des erreurs toxiques ?}
@@ -762,14 +762,40 @@ que votre \texttt{drand48} n'est pas si drand que ça. Séquence angoisse.
 
 \subsection{Scripts}\index{scripts}\label{scripts}
 
-Le script bash\index{bash} \texttt{shoot.sh} est un front-end rudimentaire
+Le script bash\index{bash} \texttt{scripts/shoot.sh} est un front-end
+encore un peu rudimentaire
 vers le programme de capture d'image décrit page \pageref{grabvidseq}.
 Il utilise deux fichiers dans le répertoire de travail~:
-\textit{reglages} et \textit{compteur}.
+\textit{reglages} et \textit{compteur}. Le premier est, en fait,
+un bout de shell affectant quelques variables, ou plutôt, les surchargent.
+
+\begin{verbatim}
+OPTIONS="${OPTIONS} -v -c pow2 "
+SHOW="yes"
+NBRE=1000
+PERIOD=0
+OFORMAT="p_%04d.png"
+\end{verbatim}
+
+La première ligne demande, en plus des options par défaut, plus de
+bavardage, et un changement de contraste. La seconde demande
+l'affichage de la photo. Les deux suivantes demandent la
+capture de 1000 images à la cadence méga-blast.
+La dernière est moins simple~: \texttt{man sprintf}\index{printf}
+pour comprendre.
+
+Quand au second fichier, il contient un compteur (stocké en ascii) qui
+est incrémenté après chaque capture réussie. Et ce compteur est
+utilisable par la variable \texttt{OFORMAT} que nous avons
+vue quelques lignes plus haut.
 
 \subsection{Fonderie}\index{fonderie}\label{fonderie}
 
-Projet externe en cours d'expérimentation.
+Ce projet externe\footnote{... pour le moment, j'ai des soucis sur
+l'architecture du \textbf{pipdeprod} à adopter\dots} est destiné à la confection
+de films flous\index{film} à partir de photos floues.
+Le script \texttt{scripts/echomix.sh} est une première expérimentation
+en bash, utilisant deux outils en \textsc{cli}. 
 
 % -------------------------------------------------------------------
 \section{Video for Linux}\index{v4l2}
@@ -778,8 +804,6 @@ 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.
 
-% 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
 pour cela, l'outil le plus commun, le plus répandu,
@@ -839,8 +863,6 @@ 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.
 
-% XXX XXX XXX\vspace{1em}
-
 \textbf{Là, il manque un schéma\dots}
 
 \subsection{video-infos}\index{video-infos}\label{video-infos}
@@ -873,8 +895,6 @@ 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
 
-% 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},
 alimenté par une (grosse) batterie et permettant d'aller