documentation++

doc/the_floatimg_hack.tex

@@ -173,13 +173,15 @@ quelques milliers d'images standard à 256 niveaux, sans trop avoir
 
 Dynamique, précision et \textsl{macheps} ? Peu de gens connaissent
 la fourbitude des calculs en virgule flottante avec les ordinateurs.
-Moi-même compris.
+Moi-même compris. Il est évident qu'une étude théorique doit être
+effectuée afin d'éviter les potentiels inconvénients.
 
 \subsection{Pixel négatif ?}
 
 Il est très difficle d'imaginer une lumière négative. Sauf peut-être
 si nous songeons à des coefficients d'absorption, ou un canal
-\textsl{alpha} qui inverserait les valeurs ? 
+\textsl{alpha} qui inverserait les valeurs ? Un domaine dont
+l'exploration peut confiner au mysticisme.
 
 % ===================================================================
 
@@ -200,8 +202,8 @@ Pour commencer par quelque 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.
+à l'instant même\footnote{Enfin, non, il y a déja longtemps,
-Enfin, non, il y a déja longtemps, avant la grande pandémie.
+avant la grande pandémie.}
 
 Tout d'abord, nous devons déclarer et garnir quelques variables
 pour gérer la machinerie interne.
@@ -216,7 +218,8 @@ Ensuite, nous enchainerons trois étapes : la création de l'image
 en mémoire centrale, l'initialisation des valeurs de chaque pixel à 0.0
 (une valeur que certains associent au noir complet, et d'autres à une
 impossibilité quantique),
-et pour conclure, l'enregistrement dans un fichier\footnote{Au format
+et pour conclure, l'enregistrement de cette image dans un
+fichier\footnote{Au format
 ésotérique, mais très véloce.} binaire.
 
 \begin{lstlisting}
@@ -235,9 +238,9 @@ if (foo) {
 \end{lstlisting}
 
 
-Une fois ce code enrobé dans un \texttt{main()}, compilé et exécuté,
+Une fois ce code enrobé dans un \texttt{main()}, compilé puis exécuté,
 nous pouvons entrevoir, grâce au logiciel
-\texttt{fimgstats} (voir page \pageref{fimgstats}),
+\texttt{fimgstats} (décrit en page \pageref{fimgstats}),
 le résultat sous forme de chiffres divers, et/ou inutiles~:
 
 \begin{verbatim}
@@ -261,9 +264,9 @@ Avec un bon script bash, il y a déja de quoi faire.
 La suite vers la page \pageref{codaz}. 
 
 Vous trouverez dans le répertoire \texttt{tools/}\index{tools/}
-d'autres exemples de mise en œuvre des fonctions disponibles
+d'autres exemples de mise en œuvre de quelques fonctions disponibles
 sous formes d'outils en ligne de commande,
-lesquels sont approximativement décrits en page \pageref{outils}.
+lesquels outils sont approximativement décrits en page \pageref{outils}.
 
 % ===================================================================
 \section{Installation}
@@ -279,15 +282,15 @@ soucis de boutisme.
 \subsection{Prérequis}
 
 Vous devez, en dehors des outils classiques (gcc, Awk, make\dots), 
-avoir quelques bibliothèques installées\footnote{Les \texttt{-dev}
+avoir quelques bibliothèques installées~:
-en plus pour Debian et dérivées}~:
 \textsf{
 libv4l2, libpnglite, libtiff,
 libnetpbm\footnote{package libnetpbm10-dev},
 libz\footnote{package zlib1g-dev}, libcurses,
-libcfitsio-dev
+libcfitsio...
 } % end of textsf
-éventuellement avec le \textsf{-dev} correspondant,
+éventuellement avec le \textsf{-dev} correspondant, qui contient, entre
+autres, les fichiers \texttt{.h} associés
 et probablement d'autres choses.
 
 Il est même quasiment certain que Bash soit indispensable, tout
@@ -296,7 +299,8 @@ Une connaissance de base de l'utilisation du shell\index{shell}
 et de l'écriture de Makefile's sera un plus.
 
 Il faut aussi savoir où trouver le code. Il est dans le Git du
-Tetalab. Mais comme je ne comprend rien à Git, c'est pas la peine
+Tetalab\footnote{\texttt{https://git.tetalab.org/tTh/FloatImg}}.
+Mais comme je ne comprend rien à Git, c'est pas la peine
 de m'envoyer des trucs genre \textsl{pull-request} auquels je ne
 comprend rien.
 
@@ -338,7 +342,7 @@ Faites-en ce que vous voulez.
 Classiquement, il y a un fichier \texttt{.h} à inclure dans chacun
 de vos codes source,
 \texttt{floatimg.h}, généralement logé dans \texttt{/usr/local/include}
-contenant un certain nombre de définition de structures, de macros, 
+et 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.
 
@@ -347,7 +351,7 @@ classées en deux catégories : \texttt{lib/} et \texttt{funcs/}.
 La première contient les choses qui sont relativement figées,
 et la seconde celles qui risquent de bouger. Cette classification
 est en fait indécement arbitraire.
-D'autant plus qu'il y a aussi un répertoire nommé « experiemental ».
+D'autant plus qu'il y a aussi un répertoire nommé « experimental ».
 
 \subsection{Structures, macros\dots}
 
@@ -406,7 +410,7 @@ quelques images...
 
 Le champ \textsl{count} sera mis à 0 et 
 le champ \textsl{fval} sera initialisé à 15.0
-(qui est la valeur maximale que peut renvoyer ce capteur).
+(ce qui est la valeur maximale que peut renvoyer ce capteur).
 Ensuite, dans la boucle capture/cumul, \textsl{count} sera
 incrémenté à chaque passe, et nous aurons donc, en finale, 
 toutes les informations nécessaires pour exploiter au mieux la dynamique
@@ -445,15 +449,16 @@ avant le moindre usage\footnote{\texttt{man 3 memset}}.
 Certains membres de cette structure sont
 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.
+classiques : niveau de gris, rouge-vert-bleu et rgb avec un canal alpha, 
+et expliquées quelques lignes plus haut.
 
 Comme vous allez le voir plus loin, il y a plein de fonctions qui
-prennent en argument deux images: une source et une destination.
+prennent en argument deux images: la source et la destination.
-Et dans la plupart des cas, ces deux images doivent être compatibles,
+Dans la plupart des cas, ces deux images doivent être compatibles,
 c'est à dire même type et mêmes dimensions.
 
 \begin{lstlisting}
-/* return 0 if compatible */
+/* return 0 if pictures are compatible */
 int fimg_images_not_compatible(FloatImg *a, FloatImg *b);
 \end{lstlisting}
 
@@ -462,7 +467,7 @@ C'est bien beau d'être enfin une image résidente 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 reste des transits ram/ps.
-Le format des fichiers est décrit page \pageref{formatfimg}.
+Le format de ces fichiers est décrit page \pageref{formatfimg}.
 
 \begin{lstlisting}
 int fimg_dump_to_file(FloatImg *fimg, char *fname, int notused);
@@ -472,7 +477,7 @@ int fimg_load_from_dump(char *fname, FloatImg *where);
 Recharger une image depuis un fichier nécessite que celle-ci et
 l'image de destination en mémoire 
 ait précisément les mêmes caractéristiques
-(taille, type...), donc l'image en ram doit être
+(taille, type...), donc l'image en mémoire centrale doit être
 pré-allouée. On peut connaitre ces valeurs en appelant
 \texttt{int fimg\_fileinfos(char *fname, int datas[3])}.
 
@@ -497,6 +502,8 @@ foo = fimg_create_from_dump("lena.fimg", &head);
 Si la valeur retournée est différente de 0, c'est que quelque
 chose s'est probablement mal passé.
 Certains messages sont parfois  explicites. Mais parfois non.
+Quand aux valeurs retournées en cas d'erreur, c'est le désordre
+intégral.
 
 % 	_________
 
@@ -526,7 +533,8 @@ $x$ et $y$ de la demande.
 Quand au canal \textsl{alpha}\index{alpha}, il est pour le moment
 superbement ignoré. Ceci dit, on vient de me faire remarquer qu'il
 peut être utilisable aussi pour faire du
-\textsl{z-buffer}\index{z-buffer}\index{rgbz}\dots
+\textsl{z-buffer}\index{z-buffer}\index{rgbz}, une technique
+classique dans la génération d'images en trois dimensions.\dots
 
 %		----------------------------------
 
@@ -646,7 +654,8 @@ aux bonnes dimensions (échange W et H).
 D'un design très empirique, c'est certainement à revoir pour l'avenir.
 Tout d'abord pour normaliser l'endianess et le packing dans les structs%
 \footnote{Ce qui n'est pas encore fait}, et surtout l'ajout
-de données sur la prise de vue.
+de données sur la prise de vue, du genre type de capteur, date et heure,
+réglages divers\dots
 
 \begin{lstlisting}
 typedef struct {
@@ -655,9 +664,6 @@ typedef struct {
 	} FimgFileHead;
 \end{lstlisting}
 
-\dots Mais aussi pour faciliter l'ajout de métadonnées, telles que
-la valeur maximale, la date de création, une longueur d'onde,
-et bien plus encore.
 
 Le champ \texttt{magic[8]} doit contenir une valeur magique~:
 les quatre premier octets doivent contenir les quatre caractères
@@ -674,11 +680,11 @@ fichier \texttt{floatimg.h}, et quelques informations
 \subsection{Métadonnées}
 \index{metadata} \index{timestamp}
 
-Attention, ce n'est pas encore une version déinitive, beaucoup de
+Attention, ce n'est pas encore une version définitive, beaucoup de
 choses restent à préciser sur le contenu de cette structure, mais
 l'essentiel est déja là. On reconnait un fichier avec metadata
 quand l'octet \texttt{magic[4]} du premier header est égal à
-\texttt{'a'}.
+la lettre \texttt{'a'}.
 
 \begin{lstlisting}
 typedef struct {
@@ -695,6 +701,8 @@ Voyons maintenant chacun des champs de cette structure, en prenant bien
 en compte qu'à ce moment\footnote{4 avril 2022}, tout n'est pas figé.
 Ceci dit, nous allons aussi retrouver de vieilles connaissances.
 
+\textbf{to be continued}
+
 %		----------------------------------
 
 \subsection{Exportation \& Importation}\index{export}\label{export}
@@ -710,7 +718,7 @@ Et dans le sens inverse, il serait bien de savoir importer
 le monde extérieur dans nos sombres caves à pixel.
 Il faut quand même reconnaitre que c'est un peu la jungle dans les
 formats de fichiers d'image, ce qui explique le retard
-dans ce domaine\dots 
+du développement dans ce domaine\dots 
 
 \subsubsection{Vers PNM}\index{PNM}
 
@@ -746,7 +754,8 @@ mais on a quand même une bonne compression, ça compense.
 
 J'utilise \textsl{libpnglite} avec qui j'ai un peu de mal à suivre.
 Mais je me soigne. Le mode 16 bits va bientôt arriver.
-On peut aussi songer à l'export des metadatas.
+On peut aussi songer à l'export des metadonnées, pour celles qui
+sont compatibles avec le standard PNG.
 
 \begin{lstlisting}
 int fimg_save_as_png(FloatImg *src, char *outname, int flags);
@@ -754,8 +763,8 @@ int fimg_save_as_png(FloatImg *src, char *outname, int flags);
 
 Tous les flags doivent être à zéro. Sinon, ça foire parfois.
 Et en fait (mars 2021) je ne suis pas très content de 
-\texttt{pnglite}, donc un de ces jours\footnote{Rendez-nous notre
+\texttt{pnglite}, donc un de ces jours, je prendrais cinq jours pour
-Mixou !}, je prendrais cinq jours pour régler le souci.
+régler ce souci en passant à la bibliothèque canonique
 
 \subsubsection{Vers TIFF}\index{TIFF}
 
@@ -879,7 +888,8 @@ int fimg_filter_3x3(FloatImg *src, FloatImg *dst, FimgFilter3x3 *filtr)
 \end{lstlisting}
 
 Comme dans la plupart des cas, la gestion des valeurs négatives
-de pixel est laissé au hasard. Quoique, il doit bien exister
+de pixel est laissé au hasard, qui fait souvent du portnawak.
+Quoique, il doit bien exister
 quelques solutions de contournement : clamping ou shift ?
 
 \textsl{To be continued\index{XXX}\dots}
@@ -1079,7 +1089,7 @@ les valeurs négatives peuvent être la cause de \textsl{glitches}
 de qualitay.
 
 La liste des opérations est susceptible d'être agrémenté de quelques
-possibilités bie féroce\footnote{Stau tuned, flim at 11.}.
+possibilités bien féroces\footnote{Stay tuned, flim at 11.}.
 
 %		-------------------------
 
@@ -1564,12 +1574,15 @@ Ajustement \textsl{Brightness Contrast Saturation Hue\dots}
 \section{À l'extérieur}
 
 Il existe une foultitude de logiciels (composants ou end-yuser) et
-il est souvent nécessaire de pouvoir comminiquer facilement
+il est souvent nécessaire de pouvoir communiquer facilement
-avec eux.
+avec eux. Nous avons déja quelques possibilité d'exportation,
+mais passer par cette étape intermédiaire est parfois délicat
+à gérer dans un \textsl{pipedeprod} autrement bien huilé.
 
 \subsection{ImageMagick}\index{ImageMagick}
 
-Pour afficher notre format .fimg exotique avec \texttt{display}, vous
+Pour afficher notre format .fimg exotique avec \texttt{display}, un
+des éléments du package ImageMagick, vous
 devez mettre ce bout de XML\index{XML} dans le fichier
 \texttt{\$HOME/.magick/delegates.xml}~: