better documentation

This commit is contained in:
tonton Th 2020-02-19 17:08:33 +01:00
vanhempi 8873521b90
commit 80011c4182
1 muutettua tiedostoa jossa 67 lisäystä ja 42 poistoa

Näytä tiedosto

@ -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},