tTh
/
FloatImg
2
2
Fork 1
Code Issues 2 Pull Requests Releases Wiki Activity

documentation++

This commit is contained in:
tTh 2023-01-21 11:49:11 +01:00
parent b79f6851f5
commit 63bc4ed7af
1 changed files with 52 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
doc/the_floatimg_hack.tex
View File

@ -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}~: