From 80011c41824427f2771e48dd790b7e7c43581075 Mon Sep 17 00:00:00 2001 From: tonton Th Date: Wed, 19 Feb 2020 17:08:33 +0100 Subject: [PATCH] better documentation --- doc/the_floatimg_hack.tex | 109 +++++++++++++++++++++++--------------- 1 file changed, 67 insertions(+), 42 deletions(-) diff --git a/doc/the_floatimg_hack.tex b/doc/the_floatimg_hack.tex index df6181e8..fa9e42b5 100644 --- a/doc/the_floatimg_hack.tex +++ b/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},