diff --git a/doc/the_floatimg_hack.tex b/doc/the_floatimg_hack.tex index 0b841e6..be61ca8 100644 --- a/doc/the_floatimg_hack.tex +++ b/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. -Enfin, non, il y a déja longtemps, avant la grande pandémie. +à l'instant même\footnote{Enfin, non, il y a déja longtemps, +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} -en plus pour Debian et dérivées}~: +avoir quelques bibliothèques installé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. -Et dans la plupart des cas, ces deux images doivent être compatibles, +prennent en argument deux images: la source et la destination. +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 -Mixou !}, je prendrais cinq jours pour régler le souci. +\texttt{pnglite}, donc un de ces jours, je prendrais cinq jours pour +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 -avec eux. +il est souvent nécessaire de pouvoir communiquer facilement +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}~: