Writing an HDR Shop Plugin

Retour aux didacticiels HDRSHOP
Sommaire du Site

Ecrire un Plugin pour HDRShop

Attention cette section nécéssite des connaissances en language C ou C++.

HDRShop supporte une architecture d'implémentation de plugins très flexible qui permet à un utilisateur d'écrire un nouveau type de traitement d'image et de l'intégrer dans l'interface de HDRshop. Les Plug-ins sont de petits programmes spéciaux fonctionnant par lignes de commandes et indépendants ; ils reçoivent leurs paramètres via des arguments qu'on leur passe par lignes de commandes.
En raison de cette structure particulière, càd un interfaçage avec HDRShop qui s'effectue par passage d'arguments en lignes de commandes et utilisation des canaux standard, un plugin peut être écrit dans n'importe quel language et effectuer tout type de traitements sur une image, Pour ce didacticiel, nous présumons que le language choisit est le C++.

Nous allons illustrer la façon d'écrire un plugin avec un exemple simple : un plug-in qui blur(brouille) une image et qui optionnellement réduit aussi sa taille de moitié.

Le plug-in communique avec HDRshop via le 'stream'(courant) stdin. Quand le plugin est appellé avec un unique argument en ligne de commande "--help" ou "/?" il doit envoyer en sortie sa liste de paramètres dans un format spécifique et quitter. Notre plug-in va envoyer le message suivant vers stderr :

Ceci est un simple plugin de test qui brouille une image.
HDRSHOPFLAGS:
HDRSHOPVERSION: 1.0.1
USAGE: sample_plugin [input.pfm] [output.pfm] [options]
OPTIONS:
	/V:[int=10]  		Blur Variance
	/D			Downsample 50%

Le plugin doit lister les informations le concernant dans les blocks suivants:

Le premier block contient les données utilisateur, tel que les instructions, description générale, autres infos, etc. HDRShop ignore ce block, sauf pour le présenter à l'utilisateur quand le plug-in est appellé.
HDRSHOPFLAGS: Devrait être vide pour l'instant. Les versions future l'utiliserons.
HDRSHOPVERSION: Devrait être la version de HDRShop avec laquelle a été écrite le plug-in.
USAGE: Devrait lister, dans cet ordre, le fichier executable du plugin, [input.pfm] si le plugin prend une image en entrée (au format .pfm), [output.pfm] si le plugin envoie une image en sortie(au format .pfm ), et [options] si le plugin prend des options.
OPTIONS: les options en ligne de commande acceptées par le plug-in. Ces données sont analysées par HDRShop pour créer une UI (Interface Utilisateur) celle-ci permettra à l'utilisateur d'entrer les options.

Les options sont spécifiées une par ligne. Chaque option à une chaîne identifiante, un descripteur de paramètre optionnel, et une chaîne de description. Chaque ligne devrait commencer avec (ignorant les espaces) une chaîne identifiante. Par exemple, "/V:" et "/D" sont les chaînes identifiantes dans notre plugin de test. L'identifiant est terminé par soit un espace ou un descripteur de paramètres. Cela nous laisse un peu de marge sur la façon dont on veut spécifier nos options; si nous le voulions, nous pourrions utiliser soit "--variance=", soit "-downsample" comme identifiants.

Les descripteurs de paramètres sont inscrit entre crochets: [], sauf pour les sélections multiple, qui sont inscrites entre accolade: {}. A l'intérieur des crochets figure le type de descripteur, suivit par une valeur par défaut optionnelle. Si une valeur par défaut est spécifié, alors HDRShop va initialiser l'interface Utilisateur générée par les options à cette valeur. Les types de descripteurs de paramètres disponibles sont :

Type Descripteur Défaut Exemple(identifiant + descripteur) Notes

boolean false /downsample Si cette option est présente en ligne de commande, la valeur est vrai, autrement elle est fausse.

integer [integer=X],[int=X] X --iterations=[int=6]

string [string=X],[str=X] X /greeting:[string=Hello World!]

float [float=X] X /pi=[float] Dans tous les cas, si l'utilisateur ne donne aucune valeur pour une option,
Cette option n'est pas envoyée comme argument en ligne de commande.

nom de fichier
en Entrée [inputfilename=X] X /C:[inputfilename=my default.cfg] Indique un fichier qui sera lu par le plugin

nom de fichier
en Sortie [outputfilename=X] X /debugout=[outputfilename=debug.txt] Indique un fichier qui sera écrit par le plugin

rectangle [selection] See notes /s[selection] L'interface Utilisateur pour cette option est une boite de contrôle, par défaut coché.
Si coché, la sélection courante dans HDRShop sera envoyée au plugin,
Au format: 100,100,200,200 (Ceci pour : Haut,Gauche,Bas,Droite).
Si il n'y a pas de sélection, la taille de l'image entière est retournée.

Choix multiple
{String1|String2|...|StringN} String1 --algorithm:{|fast|accurate|weird} Sélection multiple à partir de la liste de chaînes donnée.
La première valeur est celle par défaut.

Quand le plugin est sélectionné par l'utilisateur, HDRShop va éxecuter "sample_plugin --help" et analyse le texte résultant. HDRShop va créer un boite de dialogue où l'utilisateur va pouvoir entrer des valeurs pour toutes les options du plugin. Quand l'utilisateur a sélectionné les options et clique "Execute", HDRShop va appeller le plugin à nouveau, cette fois avec toutes les options emballées en tant qu'arguments en ligne de commande. Les options sont passées au plugin dans le même format que spécifié ci-dessus. Par exemple, si l'utilisateur sélectionne une valeur de 15 pour l'option "Blur Variance", HDRShop va passer l'argument en ligne de commande suivant : /V:15. Si l'utilisateur a sélectionné l'option "Downsample", HDRShop va passer l'argument /D, autrement il va laisser l'argument désactivé.

Pour les plugins qui manipulent des images, HDRShop les passe au format .pfm . Voir ci-dessous pour les détails sur la façon d'analyser ces fichiers. HDRShop écrit l'image courante dans un fichier .pfm temporaire, qu'il passe au plugin. Si le plug-in est supposé renvoyer une image à HDRShop, HDRShop indique le nom du fichier temporaire dans lequel le plugin devrait sauvegarder le fichier .pfm.

Maintenant regardons le véritable code source pour le plugin:

int main(int argc, char *argv[])
{
	char *inputfilename = 0;
	char *outputfilename = 0;
	int downsample = 0;
	int variance = 10;

	if (argc == 1)	{
		printHelp();
		exit(0);
	}

	for (x = 1; x < argc; x++) {
		if (argv[x][0] == '-') {
			if (argv[x][1] == '-') {
				if (strncmp("help", &argv[x][2], 4) == 0) {
					printHelp();
					exit(0);
				}
			}
		}
		else if (argv[x][0] == '/') {
			switch(argv[x][1]) {
			case '?':
				printHelp();
				exit(0);
				break;
			case 'V':
				variance = atoi(argv[x]+3);
				break;
			case 'D':
				downsample = 1;
				break;
			}
		}
		else  {
			if (inputfilename == 0) 
				inputfilename = argv[x];
			else 
				outputfilename = argv[x];
		}
	}
	...

Cette section analyse les arguments en lignes de commande. Si on passe au programme /? ou --help, il appelle printHelp() qui imprime le message détaillé ci-dessus vers stderr puis sort des lignes de commande. Autrement, le programme cherche le premier repère "barre oblique de devant" pour indiquer les options de ligne de commande. Si l'option est ?, il imprime le message d'aide. Autrement, si l'option est V, il analyse la partie restante de la chaîne pour trouver la valeur sous forme d'entier de la Variance. Si l'option est D, il fixe le repère de downsample à vrai. Finalement, si l'argument en ligne de commande n'est pas une option, il est considéré comme étant le nom du fichier à prendre en Entrée. Si le nom du fichier à prendre en Entrée a déjà été lu, l'argument rencontré est alors supposé être le nom du fichier à inscrire en sortie.

	if (!inputfilename)
		doError(1);
	if (!outputfilename)
		doError(2);

	floatimage fimg;
	if (!fimg.LoadPFM(inputfilename))
		doError(3);

	fimg.fast_gaussian_blur(variance);
	if (downsample)
		fimg.halfsize();
	
	if (!fimg.SavePFM(outputfilename))
		doError(4);

	return 0;
}

La fonction doError() imprime juste une chaîne d'erreur vers stderr et ensuite appelle exit() avec une valeur différente de zéro pour indiquer à HDRshop qu'une erreur est survenue. HDRshop va afficher tout ce qui a été sortie vers stderr vers l'utilisateur sous forme de message d'erreur. La class "floatimage" est une class utility. Elle fournit un certain nombre de fonctions utiles comme file(fichier) i/o à partir de formats variés, lectures des pixels antialiasés, bluring(brouillage), convolution(enroulement), et autres utilitaires. Le code source complet pour floatimage et ce plug-in d'exemple sont disponible au téléchargement ici .

Une fois le plug-in compilé en un éxécutable qui fonctionne, il doit être placé dans le sous-répertoire appellé "plugins" lequel se trouve dans le même répertoire que l'éxécutable HDRShop. Le nom du plug-in va apparaître dans le Menu "Plugins" qui se trouve dans la barre de menu de la fenêtre principale.

Retour aux didacticiels

Type	Descripteur	Défaut	Exemple(identifiant + descripteur)	Notes
boolean		false	/downsample	Si cette option est présente en ligne de commande, la valeur est vrai, autrement elle est fausse.
integer	[integer=X],[int=X]	X	--iterations=[int=6]
string	[string=X],[str=X]	X	/greeting:[string=Hello World!]
float	[float=X]	X	/pi=[float]	Dans tous les cas, si l'utilisateur ne donne aucune valeur pour une option, Cette option n'est pas envoyée comme argument en ligne de commande.
nom de fichier en Entrée	[inputfilename=X]	X	/C:[inputfilename=my default.cfg]	Indique un fichier qui sera lu par le plugin
nom de fichier en Sortie	[outputfilename=X]	X	/debugout=[outputfilename=debug.txt]	Indique un fichier qui sera écrit par le plugin
rectangle	[selection]	See notes	/s[selection]	L'interface Utilisateur pour cette option est une boite de contrôle, par défaut coché. Si coché, la sélection courante dans HDRShop sera envoyée au plugin, Au format: 100,100,200,200 (Ceci pour : Haut,Gauche,Bas,Droite). Si il n'y a pas de sélection, la taille de l'image entière est retournée.
Choix multiple	{String1\|String2\|...\|StringN}	String1	--algorithm:{\|fast\|accurate\|weird}	Sélection multiple à partir de la liste de chaînes donnée. La première valeur est celle par défaut.