INTRO (3I) version 4.6.9 March 2022

User Intro Liste des programmes Liste des manuels Généralités

Table of Contents

NAME
SYNOPSIS
DÉFINITION D'UNE IMAGE
PROGRAMMATION
FILES
SEE ALSO

NAME

intro - introduction à la programmation avec Inrimage

SYNOPSIS

#include <inrimage/image.h>
pour les accès aux images et les définitions de types.

#include <inrimage/flt_type.h>
pour les transformations de formats flottant.

#include <inrimage/dialog.h>
pour certains programmes de dialogue.

#include <inrimage/error.h>
pour le traitement des erreurs.

Une image est une structure de données organisée en un certain nombre de plans ayant tous le même nombre de lignes de longueur identique. Les lignes sont composées d'éléments appelés pixels qui sont des vecteurs de dimensions égales (un la plupart du temps). Toutes les valeurs (composantes de chaque pixel) sont codées de la même façon (par exemple en flottant, ou en virgule fixe sur 8 bits).
Les composantes des pixels sont consécutives. Les pixels sont rangés par lignes, et les lignes d'un même plan sont consécutives.
Le maillage peut être carré ou hexagonal (en pratique, aucun programme ne tient compte du type de maillage).
L'origine correspond au premier point de l'image, qui est repéré par les indices x=1, y=1, z=1. Cette origine peut être affectée d'une translation (rarement utilisée dans les programme).

Le codage des valeurs peut être de type flottant, virgule fixe signée ou virgule fixe non signée. En virgule fixe, toutes les données sont représentées sur le même nombre de bits (qui peut aller de 1 à 32) et ont le même exposant.

Un fichier image se compose d'un en-tête immédiatement suivie des données rangées comme décrit plus haut. : la composante v du pixel x de la ligne y du plan z occupe la position
(z-1)*(ndimv*ndimx*ndimy)+(y-1)*(ndimv*ndimx)+(x-1)*ndimv+(v-1)
Dans le fichier (mais pas dans les données transférées en mémoire) les lignes occupent toujours un nombre entier d'octets.

L'en-tête, dont la taille peut varier, mais reste multiple de 256 octets, contient diverses informations qui caractérisent l'image. En particulier, son format (dimensions, codage, maillage, origine) y figure toujours. Normalement on y trouve aussi l'histoire de l'image (c'est-à-dire la liste des dernières commandes qui l'ont modifiée). Ces informations sont inscrites automatiquement par les programmes d'accès aux fichiers image.
On peut ajouter dans l'en-tête un certain nombre d'autres indications, sous forme de texte ascii. Par exemple, certains programmes associent de cette façon des tables couleur à une image.

Le format d'une image est transmis aux programmes, dans le cas le plus général, sous forme d'une structure de type struct nf_fmt. Le plus souvent on n'utilise que la première partie de cette structure, c'est-à-dire un tableau de 9 éléments de type Fort_int (correspondant aux integer Fortran, de longueur 64 bits sur les machines 64 bits).
La structure nf_fmt, définie dans image.h est la suivante :

struct nf_fmt {
	Fort_int lfmt[9]; /* format principal */
	Fort_int offsets[3]; /* décalages d'origine en X,Y,Z */
	Fort_int maille; /* maillage : 0=rect., 1= hexagonal */
	float bias;   /* constante a rajouter a chaque pixel (virg. fixe) */
	float scale;  /* coeff multiplicatif (virg. fixe) */
};

Le fichier image.h contient diverses macros pour caractériser le tableau format, auquel on donne souvent le nom lfmt. Nous les utiliseront pour décrire ce tableau.

lfmt[0], lfmt[I_DIMX], DIMX: ( = NDIMX*NDIMV ) nombre total de valeurs par ligne.
lfmt[1], lfmt[I_DIMY], DIMY: ( = NDIMY*NDIMZ ) nombre total de lignes.
lfmt[2], lfmt[I_BSIZE], BSIZE: byte ou bit size. Si ce nombre est positif c'est le nombre d'octets pour coder une valeur, s'il est négatif c'est l'opposé du nombre de bits pour coder une valeur.
lfmt[3], lfmt[I_TYPE], TYPE: type du codage :
: 1 (REELLE) pour flottant.
0 (FIXE) pour virgule fixe non packée. Si une "bit-size" n est indiquée dans lfmt[I_BSIZE], chaque valeur occupe les n bits de droite de (n+7)/8 octets.
-1 (PACKEE) virgule fixe packée; chaque valeur occupe exactement le nombre de bits nécessaires.

lfmt[4], lfmt[I_NDIMX], NDIMX: nombre de vecteurs par ligne.
lfmt[5], lfmt[I_NDIMY], NDIMY: nombre de lignes par plan.
lfmt[6], lfmt[I_NDIMV], NDIMV: nombre de composantes du pixel.
lfmt[7], lfmt[I_NDIMZ], NDIMZ: nombre de plans.
lfmt[8], lfmt[I_EXP], EXP: type de flottant d'une image réelle, ou exposant d'une image virgule fixe. Pour un exposant 2**exp, on aura dans lfmt[I_EXP], exp+200 pour une image sans signe, et -(exp+200) pour une image signée. Les bornes acceptées pour exp sont -100 et +100, ce qui donne des valeurs comprises entre 100 et 300 ou -300 et -100 pour lfmt[I_EXP], avec le cas particulier lfmt[I_EXP]=0 correspondant à exp=0 pour une image sans signe.

Nota: En langage Fortran, on utilisera lfmt(1) ... lfmt(9).
Dans le cas où on a besoin de tous les paramètres de l'image (struct nf_fmt), on écrira :


	integer gfmt(18)
	float rfmt(2)
	equivalence (gfmt(14),rfmt(1))

PROGRAMMATION

Interface Fortran - C :

Certains programmes des bibliothèques Inrimage peuvent être appelés en Fortran. Tous les programmes de type Fortran peuvent être utilisés en C, si l'on respecte les règles suivantes, valables sur la plupart des systèmes :

-: Le nom du programme est obtenu en ajoutant un caractère underscore ('_') à son nom Fortran.
-: Les arguments doivent être passés par adresse, ce qui ne change rien pour les tableaux mais oblige à utiliser des pointeurs ou des variables précédées du caractère & pour les scalaires.
-: Utiliser le type Fort_int pour les objets de type entier. En effet ce type correspond au type integer du Fortran qui est de longueur 8 octets sur les systèmes 64 bits, alors que le type int du C reste 32 bits.

Pour rendre le passage d'arguments plus agréable en C, on trouvera pour certains de ces programmes une version "appelable C", dont le nom commence par c_ (et sans '_' terminal, par exemple lect_ et c_lect).

Programme principal :

Il est important d'appeler inr_init (ou à la rigueur initopts) avant toute autre fonction Inrimage (Cf inr_init(3i) )
On traitera les options de l'application avec les fonctions Inrimage prévues à cet effet, à savoir : infileopt, outfileopt (Cf inr_init(3i) ) pour les noms de fichiers non précédé d'une option, et igetopt0, igetopt0x, igetopt1, igetopt2 (ou à la rigueur igetopt) pour les autres options (Cf igetopt(3i) ) . Cette méthode permet notamment l'utilisation de l'application dans KHOROS.

Si le programme principal (main) est écrit en C, il doit avoir la structure suivante (Ucmd et Udetail décrivent brièvement les arguments de l'application) :


#include <inrimage/image.h>

static char Ucmd[]=
"[-D] [-k nb_Ko] [-sc scale] [input | -] [output]";
static char Udetail[]=
"\tblablabla";

main(argc, argv)
int argc;
char **argv;
{
	char in_name[80], out_name[80];
	......
	inr_init(argc,argv,"1.0-beta",Ucmd,Udetail);
	.....
	igetopt1("-sc","%f",&scale);
	infileopt(in_name);
	outfileopt(out_name);
	....

	return 0;   
}

L'appel à inr_init permet d'effectuer diverses initialisations (en particulier celle du mécanisme de traitement des options par igetopt) et prend en compte les arguments -D -k -Help -help -vers (voir inr_init(3i) , igetopt(3i) ).
Note : on remarquera le programme se termine par return 0; pour garantir un exit-code d'application bien défini.
On trouvera des exemples plus détaillés dans le répertoire Exemples/ de la distribution.

Dans certains cas, (quand l'édition de liens utilise certains modules Fortran), il peut être nécessaire d'utiliser un programme principal en Fortran. Dans ce cas, il suffit de transformer légèrement le programme principal C et d'ajouter un programme Fortran très simple, tel que celui qu'on trouve dans Inrimage (inrimage/src/bin-src/fmain.f, inrimage/lib/libinrfort.a) :


	call inifsg
	call fcmain
	stop
	end

Le programme principal C devient :


#include <inrimage/image.h>

static char Ucmd[]=
"[-D] [-k nb_Ko] [-sc scale] [image-in | -] [image-out]";
static char Udetail[]=
"\tblablabla";

fcmain_()
{
	char in_name[80], out_name[80];
	.....
	inr_init(0,0,"1.0-beta",Ucmd,Udetail);
	.....
	igetopt1("-sc","%f",&scale);
	infileopt(in_name);
	outfileopt(out_name);
	....

	return 0;   
}

Accès aux images :

Dans un programme, les images ne sont désignées que par des pointeurs vers des structures de type "struct image" (définie dans image.h).
Pour garantir la portabilité d'une version à l'autre, il faut considérer ces pointeurs comme des objets opaques, et ne pas utiliser directement le contenu de la structure. Les références aux paramètres des images se feront par l'intermédiaire de la structure struct nf_fmt ou du tableau de format lfmt[9], dont les contenus sont compatibles d'une version à l'autre.

L'ouverture d'une image se fait par la procédure image_ qui retourne un pointeur vers une structure de type struct image. C'est ce pointeur qui sera utilisé par toutes les procédures d'accès aux images.

Pour la lecture et l'écriture aux données on utilisera exclusivement les fonctions Inrimage appropriées, telles que lect et ecr en Fortran, ou c_lect et c_ecr en C (voir lect(3i) ).

outils divers :

L'allocation dynamique de tableaux est effectuée par les procédures exec et imexec (voir imexec(3i) ).

Les programmes interactifs devront soit utiliser les fonctions de dialogue Inrimage (voir liste ci-dessous), soit utiliser les fonctions d'entrée-sortie standard Unix, mais surtout ne pas mélanger les 2 en entrée.

L'impression des messages doit se faire sur stderr, et l'entrée de réponses sur stdin (d'où incompatibilité avec la lecture d'image sur stdin).

Les procédures interactives Inrimage lisent généralement "mot par mot" et acceptent comme caractère de fin de mot indifféremment espace, TAB et newline.

FILES

/user/inrimage/lib/inrimage ou /usr/local/lib/libinrimage.a : bibliothèque de base pour la programmation Inrimage.
/user/inrimage/lib/oldvsys ou /usr/local/lib/liboldvsys.a : bibliothèque des programmes à ne plus utiliser, mais maintenus pour la compatibilité avec d'anciennes versions.
/user/inrimage/Exemples : quelques exemples de programmes C et de makefile.