diff --git a/doc/the_floatimg_hack.tex b/doc/the_floatimg_hack.tex index b84d237..67c76a2 100644 --- a/doc/the_floatimg_hack.tex +++ b/doc/the_floatimg_hack.tex @@ -20,6 +20,11 @@ \usepackage{xspace} \usepackage[verbose]{layout} + +\setlength{\textheight}{640pt} +\setlength{\textwidth}{422pt} +\setlength{\marginparwidth}{10pt} + \makeindex % ------ a few new commands @@ -45,7 +50,8 @@ Ceci dit, on trouve parfois des images codées sur 16 bits par composante, mais c'est loin d'être le cas général. J'ai donc souhaité aller plus loin, et coder chaque canal de chaque pixel en virgule flottante sur 32bits, le type -\texttt{float}\index{float} du langage C. +\texttt{float}\index{float} du langage C. Ce qui correspond +à la norme IEEE 754-1985. \vspace{1em} @@ -62,8 +68,11 @@ IRC de Freenode. \tableofcontents \pagebreak +\layout +\pagebreak + % ------------------------------------------------------------------- -\section{Premier example}\index{example}\label{example} +\section{Premier exemple}\index{exemple}\label{exemple} \textsc{FloatImg} a débuté sous la forme de quelques fonctions basiques en C, gérant la structure des données d'image en mémoire @@ -151,6 +160,7 @@ lesquels sont décrits en page \pageref{outils}. Vous devez, en dehors des outils classiques (bash, gcc, make\dots), avoir quelques bibliothèques installées\footnote{Les \texttt{-dev} pour Debian et dérivées}~: libv4l2, libpnglite, libtiff, libnetpbm, +libz, et probablement d'autres choses. \vspace{1em} @@ -185,14 +195,15 @@ faciliter un peu la chose. Il prend également en compte la copie des divers binaires du dossier \texttt{tools/} (cf. page \pageref{outils}) dans le répertoire prévu à cet effet : \texttt{/usr/local/bin}. -% ------------------------------------------------------------------- +% ================================================================= + \section{Utilisation coté codeur}\label{codaz} -Classiquement, il y a un fichier \texttt{.h} à inclure dans chacun de code -source, +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, -de constantes\footnote{À l'ancienne, via le pré-processur} +de constantes\footnote{À l'ancienne, via le pré-processeur} et les prototypes des fonctions utilisables par vos logiciels. \vspace{1em} @@ -226,20 +237,25 @@ Les deux premiers champs sont \textsl{obvious}. Le troisième est le type d'image : pour le moment, il y en a trois qui sont définis\footnote{et plus ou moins bien gérés\dots} : gris, rgb et rgba\index{rgba}. +Les constantes adéquates sont dans \texttt{floatimg.h} \begin{verbatim} #define FIMG_TYPE_GRAY 1 #define FIMG_TYPE_RGB 3 #define FIMG_TYPE_RGBA 4 +#define FIMG_TYPE_RGBZ 99 \end{verbatim} Un peu plus loin, nous avons les pointeurs vers les différents \textsl{pixmaps} de l'image. En principe l'organisation interne de ces zones est improbable, puisque elle dérive -d'idées approximatives. +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} +Mais revenons aux choses sérieuses\dots Les deux champs suivants (fval et count) sont à la disposition du \textsl{yuser} qui peut jouer avec à loisir pour faire, par exemple, ce genre de @@ -258,31 +274,62 @@ toutes les informations nécessaires pour exploiter au mieux la dynamique de notre image dans les étapes ultérieures, puisque la valeur maximale théorique est égale à $fval * count$. -\vspace{1em} +Une bonne partie des fonctions que nous allons voir est indéterministe. +Ce qui veut dire, en langage de tous les soirs, que ça risque de ne +pas être la même chose dans l'avenir. -\textsl{Il est vraiment dommage que ces deux données auxiliaires -ne puisse être stockée dans les dumps d'image. \index{XXX}} +% ---------------------------------- -\subsection{lib/}\index{lib/} +\subsection{Les fondations}\index{lib/} -Première chose, la gestion dynamique de la mémoire occupées -par tous ces pixels flottants est faite par ces deux fonctions~: +La première chose à voir est la gestion dynamique de la mémoire occupée +par tous ces pixels flottants, ce est un sujet parois +délicat\footnote{GC}. +Elle est donc faite, à la base, par ces deux fonctions~: \begin{verbatim} int fimg_create(FloatImg *fimg, int w, int h, int type); int fimg_destroy(FloatImg *fimg); \end{verbatim} -Les types d'images actuellement gérés sont les trois grands -classiques : gray, rgb et rgba. Les constantes adéquates sont -dans \texttt{floatimg.h} et expliquées quelques lignes plus haut. -Les codes d'erreur sont disparates -et non documentés. +L'appelant doit lui-même gérer le descripteur d'image (une structure +C décrite plus haur) en le considérant comme un type semi-opaque dont +la forme peut varier. 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. + \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 +reste des transits ram/ps. + +\begin{verbatim} +int fimg_dump_to_file(FloatImg *fimg, char *fname, int notused); +int fimg_load_from_dump(char *fname, FloatImg *where); +\end{verbatim} + +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 +pré-allouée. Mias comment peut-on connaitre ces valeurs ? + +\begin{verbatim} +int fimg_fileinfos(char *fname, int *datas); +\end{verbatim} + + + +% _________ + +\subsection{Dessiner} + Bon, vous avez une image latente, et vous souhaitez dessiner dessus (ou dedans ?) avec vos encres flottantes ? -Il y a une fonction pour ça. +Il y a des fonctions pour ça, par exemple~: \begin{verbatim} int fimg_plot_rgb (FloatImg *head, int x, int y, @@ -292,11 +339,14 @@ int fimg_plot_rgb (FloatImg *head, int x, int y, Les paramètres sont explicites, mais leur validité doit être sévèrement controlée par l'appelant. Il y a une fonction soeur, \texttt{fimg\_add\_rgb}\index{fimg\_add\_rgb}, -qui ajoute du rgb à un pixel, laquelle a d'ailleurs été +qui ajoute du rgb à un pixel, laquelle fonction a d'ailleurs été à la base de la seconde génération de la photographie\index{photographie} en cumul\index{cumul}. -\subsubsection{Contraste}\index{contraste} + +% ---------------------------------- + +\subsection{Contraste}\index{contraste}\label{contraste} Certaines opérations d'ajustement du contraste d'une image semblent cohérents avec la notion d'image flottante. @@ -325,6 +375,8 @@ 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 @@ -349,20 +401,70 @@ une égalisation\index{égalisation} par histogramme\index{histogramme} qui respecte, dans toute sa futilité, le concept\index{concept} de pixel flottant. -\subsection{funcs/}\index{funcs/}\label{funcs} +% ---------------------------------- -Une bonne partie de ces fonctions est indéterministe. Ce qui -veut dire, en langage de tous les soirs, que ça risque de ne -pas être la même chose dans l'avenir. +\subsection{Exportation}\index{export}\label{export} -\vspace{1em} +Notre format de fichier étant totalement inconnu, il nous +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. -On y trouve pêle-mêle de l'import/export de fichiers, de l'analyse -de chaines de caractères, du tracé de choses bizarres\dots -Plein de trucs qu'il faudra bien expliquer un jour\footnote{Mais -il fait trop froid dans le dd2\index{dd2}}. +\subsubsection{Vers PNM}\index{PNM} -\subsection{Exemple de fonction}\index{example} +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. + +\begin{verbatim} +int fimg_save_as_pnm(FloatImg *head, char *fname, int flags); +\end{verbatim} + +Le bit \texttt{0} du paramètre \texttt{flags} mis à \texttt{1} demande +à la fonction de faire la mise à l'échelle avec le couple +\textsl{fvalue/count} décrit plus haut dans cette doc. +Et si il est à zéro, c'est la fonction de recherche de valeur +maximale (cf page \pageref{contraste}) qui est utilisée. + +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. + +\subsubsection{Vers TIFF}\index{TIFF} + +To be done\index{XXX} + +\subsection{Utilitaires} + +\begin{verbatim} +int parse_WxH(char *str, int *pw, int *ph) +int parse_double(char *str, double *dptr) +int format_from_extension(char *fname) +\end{verbatim} + +To be continued\index{XXX} + + +\subsection{Effets}\index{sfx} + +To be done\index{XXX} + + +% ---------------------------------- + + +\subsection{Filtrages} + +To be done\index{XXX} + + +% ---------------------------------- + +\subsection{Exemple de fonction}\index{exemple} Nous allons écrire une fonction qui va faire quelque chose à partir d'une image source et d'une valeur, et écrire le @@ -416,23 +518,32 @@ Ces machins ont en commun deux options bien pratiques~: et \texttt{-v} qui augmente la puissance de bavardage. 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 (ou pas). Cette notion de teinte est assez inconsistante pour le moment, +mais ça n'est pas si grave que ça. \begin{verbatim} -tth@debian:~/Devel/FloatImg/tools$ ./mkfimg -v -h +tth@debian:~/Devel/FloatImg/tools$ ./mkfimg -h Usage: mkfimg [options] quux.fimg width height -k N.N give a float parameter -t bla howto make the pic black, drand48... -v increase verbosity -*** FloatImg library, alpha v73 (Sep 28 2019, 23:34:29) \end{verbatim} +\begin{itemize} +\item black / gray / grey +\item drand48 +\item hdeg / vdeg +\end{itemize} + + +% --------------------- \subsection{png2fimg}\index{png2fimg}\label{png2fimg} @@ -465,15 +576,13 @@ Puis nous rajouterons\footnote{Les patchs sont les bienvenus} le calcul de la variance\index{variance}. Les compétences de \texttt{schmod777} sont attendues au dd2\index{dd2}. +% --------------------- + \subsection{fimgfx}\index{fimgfx}\label{fimgfx} -\textit{En cours de création\index{XXX}. -Attention, je vais expérimenter un parsing un peu étrange -sur les arguments de la ligne de commande. coredump expected.} - -\vspace{1em} - -À l'heure actuelle\footnote{décembre 2019, vers 13:37}, nous avons +Ce programme, \textit{en cours de création\index{XXX}}, applique +un effet spécial à une image. +À l'heure actuelle\footnote{janvier 2019, vers 13:37}, nous avons déja quelques ajustements basiques de contraste, qui ne tiennent pas vraiment compte du contenu de l'image. @@ -483,6 +592,17 @@ tth@daubian:~/Devel/FloatImg/tools$ ./fimgfx -v -h cos01 cos010 pow2 sqrt \end{verbatim} +Certaines de ces opérations ont besoin d'un paramètre flottant. +Celui-ci peut être fixé avec l'option \texttt{-k}. +Une liste détaillée des opérations possibles +sera lisible avec le sélecteur \texttt{-L}. + +\begin{itemize} +\item Ajustements de contraste : cos01 cos010 pow2 sqrt +\item Distorsions chromatiques : +\item Déformations géométriques : +\end{itemize} + \subsection{fimgops}\index{fimgops}\label{fimgops} Quelques opérations diverses entre deux images, qui doivent être @@ -516,7 +636,8 @@ La véracité mathématique n'est pas garantie. Quelques petits proggies pour exporter notre format\index{.fimg} secret vers des choses plus directement utilisables. À condition que le -code soit écrit et documenté. Peut-être en page \pageref{funcs}\dots +code soit écrit et documenté. + \vspace{1em} D'un autre coté, écrire un greffon d'import/export pour @@ -550,7 +671,7 @@ Il reste plein de choses à faire pour que ce soit vraiment utilisable. \end{itemize} % ------------------------------------------------------------------- -\section{Exemples pour yusers}\index{example} +\section{Exemples pour yusers}\index{exemple} Nous allons \textsl{essayer d'improviser} un exemple presque réel, avec un peu de rache\index{rache} dedans. Ce qui est autorisé dans