wouaou, what a nicer documentation

This commit is contained in:
tth 2020-02-20 00:07:03 +01:00
parent b5fa68864a
commit a78d6c2a75
3 changed files with 92 additions and 51 deletions

View File

@ -2,6 +2,8 @@
DOC=the_floatimg_hack
bash ./mkgraf.sh
pdflatex $DOC.tex
makeindex $DOC

19
doc/mkgraf.sh Normal file
View File

@ -0,0 +1,19 @@
#!/bin/bash
PI=" 3.141592654 "
OUT="foo.tex"
gnuplot << __EOF__
set term latex
set output "$OUT"
set title "COS010"
plot \
[0:1] [0:1] \
(0.5 - 0.5 * cos(x*$PI)) \
with line
__EOF__
wc $OUT

View File

@ -21,6 +21,7 @@
\setlength \parskip {0.40em}
\setlength{\hoffset}{0em}
\setlength{\textheight}{640pt}
\setlength{\textwidth}{422pt}
\setlength{\marginparwidth}{10pt}
@ -82,8 +83,6 @@ 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
@ -99,7 +98,8 @@ IEEE 754-1985.
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.
à se soucier des éventuelles pertes de précision. Mais ça demande
à être confirmé par des esprits supérieurs.
% -------------------------------------------------------------------
@ -109,19 +109,15 @@ quelques milliers d'images standard à 256 niveaux, sans trop avoir
basiques en C, gérant la structure des données d'image en mémoire
et sur disque. Ça a été imaginé de façon presque empirique,
mais nous sommes tous là pour améliorer les choses, dans
la mesure de nos moyes.
la mesure de nos moyens.
Nous allons donc directement rentrer au cœur du problème.
% XXX XXX XXX\vspace{1em}
Pour commencer par quelques 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.
% XXX XXX XXX\vspace{1em}
Tout d'abord, nous devons déclarer et garnir quelques variables
pour gérer la machinerie interne.
@ -173,8 +169,6 @@ 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}.
% 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
sous formes d'outils en ligne de commande,
@ -207,8 +201,6 @@ 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.
% XXX XXX XXX\vspace{1em}
Pour le moment, la procédure d'installation est un peu rude,
pour ne pas dire clairement sommaire.
Si le résultat de l'étape compilation vous semble correct,
@ -278,8 +270,6 @@ 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.
% XXX XXX XXX\vspace{1em}
Mais revenons aux choses sérieuses\dots
Les deux champs suivants (fval et count) sont à la disposition du
\textsl{yuser}
@ -288,8 +278,6 @@ 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...
% XXX XXX XXX\vspace{1em}
Le champ \textsl{count} sera mis à 0 et
le champ \textsl{fval} sera initialisé à 15.0
(qui est la valeur maximale que peut renvoyer le capteur).
@ -324,8 +312,6 @@ 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.
% 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
est tout aussi pertinent. Il y a deux opérations qui supportent le
@ -347,8 +333,11 @@ 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].
on va trouver la largeur dans \texttt{datas[0]},
la hauteur dans \texttt{datas[1]} et le type dans \texttt{datas[2]}.
La fonction \texttt{fimg\_type\_is\_valid(int type)} peut
vous aider.
% _________
@ -378,11 +367,13 @@ photographie\index{photographie} en cumul\index{cumul}.
Certaines opérations d'ajustement du contraste d'une image
semblent cohérents avec la notion d'image flottante.
Certains d'entre eux, les plus simples, sont disponibles.
Les autres sont à imaginer.
Ils prennent chacun trois paramètres, d'abord les images
source et destination (\texttt{* FloatImg}), et le troisième
est un nombre en double précision donnant la valeur
maximale \textsl{supposée} de l'image source.
maximale \textsl{supposée} de l'image source,
valeur qui peut être déterminée de plusieurs manières.
\begin{verbatim}
/* source in lib/contrast.c */
@ -392,6 +383,11 @@ int fimg_cos_01(FloatImg *s, FloatImg *d, double maxval);
int fimg_cos_010(FloatImg *s, FloatImg *d, double maxval);
\end{verbatim}
\begin{figure}
\input{foo.tex} % XXX XXX XXX
\caption{Correcteur cos01}
\end{figure}
Rappelons qu'il est possible pour un logiciel applicatif
comme \texttt{grabvidseq} (Cf page \pageref{grabvidseq})
de renseigner deux champs du descripteur d'image avec des
@ -471,11 +467,11 @@ Les autres bits ne sont pas utilisés et doivent être à zéro.
\subsubsection{Vers PNG}\index{PNG}
Actuellement, on peut enregistrer uniquement en mode 8 bits par composante,
mais avec une bonne compression.
Actuellement, on peut enregistrer uniquement en mode RGB, 8 bits par composante,
mais on a quand même une bonne compression, ça compense.
\begin{verbatim}
int fimg_save_as_png(FloatImg *src, char *outname, int flags)
int fimg_save_as_png(FloatImg *src, char *outname, int flags);
\end{verbatim}
\subsubsection{Vers TIFF}\index{TIFF}
@ -515,12 +511,20 @@ To be done\index{XXX}
\subsection{Exemple de fonction}\index{exemple}
Nous allons écrire une fonction qui va faire quelque chose
Nous allons maintenant écrire une fonction intégrable dans
le répertoire \texttt{funcs/}.
Elle aura donc accès aux \textsl{internals}%
\footnote{que je peux décider de changer n'importe quand}
de \textsc{FloatImg},
une chose qui est en principe interdit aux programmes
\textsl{enduser}. Soyez prudents.
Cette fonction va faire quelque chose
à partir d'une image source et d'une valeur, et écrire le
résultat dans une image de destination.
Pour simplifier les choses, nous n'allons traiter que les
images de type \textsc{FIMG\_TYPE\_RGB}, de loin le plus
répandu.
répandu par les temps qui courent.
\begin{verbatim}
int fimg_example(FloatImg *s, FloatImg *d, float value)
@ -528,6 +532,7 @@ int fimg_example(FloatImg *s, FloatImg *d, float value)
int size, index;
if ( s->type!=FIMG_TYPE_RGB || d->type!=FIMG_TYPE_RGB) {
perror("fimg_example");
return -1;
}
@ -560,19 +565,19 @@ 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.
% XXX XXX XXX\vspace{1em}
Ces machins ont en commun deux options bien pratiques~:
\texttt{-h} pour avoir un résumé des options disponibles
et \texttt{-v} qui augmente la puissance de bavardage.
Ces machins ont en commun quelques options bien pratiques~:
\texttt{-h} pour avoir un résumé des options disponibles,
\texttt{-v} qui augmente la puissance de bavardage, et
\texttt{-K nn.nn} pour un paramètre flottant.
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).
Propose la 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.
@ -589,7 +594,7 @@ La plupart des types d'image générée prennent un paramètre flottant qui
devra être donné avec l'option \texttt{-k F.F} avec une valeur par défaut
à $1.0$.
\begin{description}
\begin{description} \index{XXX}
\item [black/gray/grey:] efface avec 0.0 (black) ou avec la valeur
\texttt{-k} (gray).
\item [drand48:] beaucoup de bruit dans chacun des canaux.
@ -643,7 +648,7 @@ pas vraiment compte du contenu de l'image.
\begin{verbatim}
tth@daubian:~/Devel/FloatImg/tools$ ./fimgfx -v -h
--- fimg special effects ---
cos01 cos010 pow2 sqrt
cos01 cos010 pow2 sqrt gray0 xper
\end{verbatim}
Certaines de ces opérations ont besoin d'un paramètre flottant.
@ -681,7 +686,9 @@ options:
Pour des operateurs paramétrable (comme \texttt{mix}), le paramêtre
flottant doit être fourni en utilisant l'option \texttt{-k}.
La véracité mathématique n'est pas garantie.
La véracité mathématique n'est pas garantie. Et n'oubliez pas que
les valeurs négatives peuvent être la cause de \textsl{glitches}
de qualitay.
\subsection{fimg2png, fimg2pnm, fimg2tiff}
\index{fimg2png}\label{fimg2png}
@ -692,8 +699,6 @@ Quelques petits proggies pour exporter notre format\index{.fimg} secret
vers des choses plus directement utilisables. À condition que le
code soit écrit et documenté.
% 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}
ne devrait pas être trop difficile. Des volontaires ?
@ -702,7 +707,6 @@ 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.
% 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
@ -713,8 +717,6 @@ de méthodes, toutes plus légitimes que les autres.
Il reste plein de choses à faire pour que ce soit vraiment utilisable.
% XXX XXX XXX\vspace{1em}
\begin{itemize}
\item Import/export au format \textsc{tiff}\index{tiff}.
@ -733,8 +735,6 @@ 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.
% 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
nous faisons la somme de plusieurs centaines\footnote{Des erreurs toxiques ?}
@ -762,14 +762,40 @@ que votre \texttt{drand48} n'est pas si drand que ça. Séquence angoisse.
\subsection{Scripts}\index{scripts}\label{scripts}
Le script bash\index{bash} \texttt{shoot.sh} est un front-end rudimentaire
Le script bash\index{bash} \texttt{scripts/shoot.sh} est un front-end
encore un peu rudimentaire
vers le programme de capture d'image décrit page \pageref{grabvidseq}.
Il utilise deux fichiers dans le répertoire de travail~:
\textit{reglages} et \textit{compteur}.
\textit{reglages} et \textit{compteur}. Le premier est, en fait,
un bout de shell affectant quelques variables, ou plutôt, les surchargent.
\begin{verbatim}
OPTIONS="${OPTIONS} -v -c pow2 "
SHOW="yes"
NBRE=1000
PERIOD=0
OFORMAT="p_%04d.png"
\end{verbatim}
La première ligne demande, en plus des options par défaut, plus de
bavardage, et un changement de contraste. La seconde demande
l'affichage de la photo. Les deux suivantes demandent la
capture de 1000 images à la cadence méga-blast.
La dernière est moins simple~: \texttt{man sprintf}\index{printf}
pour comprendre.
Quand au second fichier, il contient un compteur (stocké en ascii) qui
est incrémenté après chaque capture réussie. Et ce compteur est
utilisable par la variable \texttt{OFORMAT} que nous avons
vue quelques lignes plus haut.
\subsection{Fonderie}\index{fonderie}\label{fonderie}
Projet externe en cours d'expérimentation.
Ce projet externe\footnote{... pour le moment, j'ai des soucis sur
l'architecture du \textbf{pipdeprod} à adopter\dots} est destiné à la confection
de films flous\index{film} à partir de photos floues.
Le script \texttt{scripts/echomix.sh} est une première expérimentation
en bash, utilisant deux outils en \textsc{cli}.
% -------------------------------------------------------------------
\section{Video for Linux}\index{v4l2}
@ -778,8 +804,6 @@ 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.
% 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
pour cela, l'outil le plus commun, le plus répandu,
@ -839,8 +863,6 @@ 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.
% XXX XXX XXX\vspace{1em}
\textbf{Là, il manque un schéma\dots}
\subsection{video-infos}\index{video-infos}\label{video-infos}
@ -873,8 +895,6 @@ 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
% 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},
alimenté par une (grosse) batterie et permettant d'aller