Commencez par créer un dossier dédié aux exercices de cette matière.
Ensuite, choisissez un nom pour votre crate et créez un nouveau projet en Rust.
Téléchargez le dossier data.zip et ajoutez-le à votre projet, à côté du dossier src.
Il contient des images que nous utiliserons par la suite.

N’oubliez pas de remettre en œuvre toutes les bonnes pratiques apprises au semestre précédent.
Pour cela, vous pouvez notamment utiliser le linter.

À sa création, votre projet ne contient qu’un fichier main.rs et son exécution fait simplement apparaître à l’écran la salutation :

Hello, world!

Assurez-vous d’avoir atteint ce premier objectif avant d’avancer.

Commençons simplement.
Ajoutez un nouveau module à votre projet, il doit s’appeler image (fichier image.rs).
Une image est constituée d’un ensemble de pixels et chaque pixel est une couleur codifiée en RGB.

Déclarez une structure Color.
Une couleur est définie par la valeur (comprise entre 0 et 255) de ses trois composantes rouge, verte et bleue.
En conséquence, la structure doit avoir trois attributs de type u8 : red, green et blue.

Le type Color doit figurer dans le module dédié aux images et être précédé par la directive : pour permettre son affichage de débogage, son clonage et sa recopie implicite✍.

Étant donné que Color est une simple structure sans invariant✍ nous n’avons pas besoin d’appliquer l’encapsulation, tous ses membres peuvent être déclarés pub (publics).

Testez le nouveau type Color dans le programme principal.
Instanciez deux objets de type Color, un rouge (255,0,0) et un bleu (0,0,255).
Évidement, pour que le type Color soit connu dans le main(), il faudra d’abord que lui même ait été déclaré public et que l’inclusion du module image dans main.rs ait été explicitement indiquée.
Pour cela, il faut écrire : au début du fichier main.rs et utilisez le mot clef use pour faciliter l’utilisation de votre nouveau type.

Affichez à l’écran les deux objets (servez-vous de l’affichage de débogage).
Compilez et lancez l’application.

Ajoutez dans le même module une nouvelle classe, Image.
Elle doit posséder quatre données membres : Il est fondamental de comprendre que la classe Image doit assurer un invariant.
En effet, le nombre des pixels doit toujours être égal à la dimension de l’image déclarée dans ses attributs width et height.
En d’autres mots :
length of pixels == width * height
Cela implique que les données membres ne doivent surtout pas être accessibles librement et elles doivent être encapsulées.

En Rust, les données membres d’une classe sont encapsulées (c’est à dire privées) par défaut et le contrôle de l’accès aux données se fait au niveau des modules :

En revanche, la classe Image devra être accessible partout, donc n’oubliez pas de la déclarer publique.

Étant donné que les membres de la classe Image sont privés, nous devons fournir tous les services qui lui sont spécifiques.
En Rust, comme en C++, il est possible de définir les services d’une classe à travers des fonctions membres et des fonctions non-membres.
Étant donné qu’en Rust, toutes les données membres d’une structure sont librement accessibles partout dans le même module, il n’y a pas vraiment de raison pour choisir d’utiliser un type de fonction par rapport à l’autre.
Nous suivrons alors une règle très simple et nous nous forcerons d’écrire des fonctions membres pour tout service qui est propre au type de donnée représenté par la classe.
Une fonction qui aura juste besoin de se servir d’objets de ce type, sera plutôt définie comme fonction non-membre.

Pour rappel, toute fonction membre d’une classe est définie dans son implémentation, c’est à dire de son bloc impl.

Écrivez le bloc impl et définissez une première fonction membre qui permet la création et l’initialisation d’une image.
Cette fonction doit s’appeler new_unicolor(), doit recevoir en paramètre tout ce qu’il faut pour initialiser les données membres de l’image (nom, largeur, hauteur et une couleur) et doit retourner un Self (un objet du type concerné).
Attention ! Évidemment, il faudra remplir le vecteur pixels de width*height couleurs toutes pareilles (la même que celle passée en paramètre).

Pour tester cette première fonction, instanciez dans le main() un objet de type Image en lui passant comme couleur une des deux couleurs instanciées précédemment.
Affichez à l’écran le nom et les dimensions de l’image.
Par exemple :

Image "red" with size 3×2

Vous remarquerez tout de suite que le compilateur n’accepte pas d’accéder directement aux données membres de la classe.
En effet, la fonction main() est hors du module déclarant le type Image et donc, à cause de l’encapsulation, n’a le droit ni de consulter ni de modifier directement les données membres de la classe Image.
L’implémentation d’Image devra alors permettre la consultation du nom et des dimensions (ne définissez qu’une seule fonction pour lire la largeur et la hauteur et renvoyez un tuple).
Pour rappel, il est tout à fait normal que le compilateur vous informe que le membre pixels n’est pas encore utilisé.

Il est bien sympathique de créer des nouvelles images, mais il le serait encore plus si l’on pouvait aussi les voir.
Pour cela, ajoutez une fonction membre qui permet de sauvegarder l’image dans un fichier en format PPM.
Ce format est très simple, vous pouvez le voir en ouvrant dans un éditeur de texte un des fichiers .ppm qui vous sont fournis dans le dossier data.
La première ligne du fichier contient (et doit contenir) la chaîne de caractères : P3.
La seconde ligne contient la largeur et la hauteur de l'image séparées par une espace.
La troisième ligne contient la valeur maximale des composantes des pixels, normalement 255.
Les lignes suivantes contiennent les valeurs des trois composantes RGB de chaque pixel.
Cette section contient un exemple sur comment écrire dans un fichier ligne par ligne.
Ajoutez un dossier results à la racine de votre projet et assurez-vous que toute image soit enregistrée dans ce dossier.
Le nom du fichier sera le même que celui de l’image suivi de l’extension .ppm.

Testez cette nouvelle fonction dans le main() en sauvegardant votre image de couleur unie crée précédemment.

Ajoutez une deuxième fonction d’initialisation, appelez new_random(), qui reçoit en paramètre le nom, la hauteur et la largeur de l’image et qui affecte à chaque pixel une couleur aléatoire.
Pour obtenir des valeurs aléatoires, vous avez besoin d’un générateur et d’une distribution uniforme✍.

Il faut aussi déclarer la dépendance au crate rand pour pouvoir l’utiliser.
Pour cela, il faut ajouter la ligne suivante : dans le fichier Cargo.toml, tout de suite après [dependencies].

Testez cette nouvelle fonction dans le main() et sauvegardez l’image aléatoire créée.

Dotez maintenant la classe Image d’une fonction qui permet de créer un objet du même type à partir d’un fichier.
Appelez la fonction new_from_rgb() et passez lui en paramètre la string-slice contenant le chemin pour atteindre l’image à charger.
Attention ! L’ouverture d’un fichier peut échouer ; la fonction doit alors propager l’erreur si cela se vérifie.
Le type de retour de cette fonction doit être Result<Image, Box<dyn std::error::Error>>.

Le format de fichier que nous utilisons, le PPM, a été expliqué préalablement.
Vous devez lire correctement les informations contenues dans le fichier et les stocker dans les attributs width, height et pixels.
Le nom de l’image sera le nom du fichier privé de chemin et d’extension✍.
Cette section contient un exemple de lecture du contenu global d’un fichier.

Conseil : il sera utile d'exploiter un itérateur renvoyant un-à-un les mots du fichier, en ignorant les éventuels commentaires✍ : Pour faire avancer l’itérateur d’un élément à l’autre, utilisez la fonction next().
Attention ! Cette fonction renvoie une Option<T>, donc il faudra à chaque fois contrôler qu’il y ait bien une donnée renvoyée.
Pour convertir une string en entier (usize), utilisez la fonction parse().
Par exemple, si s est la string, alors : renvoie l’entier décrit par s, si c'est le cas, et une erreur autrement.
La présence du point d’interrogation permet de propager l’erreur.

Testez cette fonction.
Toute image doit être lue du dossier data et sauvegardée dans le dossier results pour éviter tout écrasement accidentel.

Pour comprendre l’importance de l’encapsulation, faisons une expérience...
Déclarez la largeur de l’image publique (faire le test sur une seule données faisant partie de l’invariant sera suffisant, le concept sera toujours le même).
Ensuite, dans le test que vous venez de faire, modifiez la largeur de l’image avant de la sauvegarder, par exemple, donnez-lui une valeur plus petite (par exemple, 100).
Vous verrez que l’image sauvegardée n’aura plus rien à voir avec celle d’origine.
En accédant, librement à la donnée width de la structure Image, nous avons pu altérer de façon arbitraire sa valeur, en conséquence nous avons rendu les données incohérentes.
Même si le code compile et il s’exécute, il est incorrect et source d’erreurs.
Appliquez à nouveau l’encapsulation.

Nous pouvons fournir quelques services qui peuvent modifier une image ; par exemple, la transformer en niveaux de gris.
Pour ce faire, commencez par fournir à la structure Color une fonction qui, à partir d’une couleur donnée, renvoie un nouveau Color contenant le niveau de gris correspondant à la couleur d’origine.
Pour avoir une couleur grise, il faut simplement que ses trois composantes RGB aient toutes la même valeur.
Le niveau de gris se calcule comme suit pour une couleur RGB donnée :

Ajoutez maintenant une fonction membre grey() à la classe Image qui permet de modifier l’image en la transformant en niveaux de gris.
Évidemment elle doit modifier tous les pixels de l’image en les remplaçant avec le niveau de gris correspondant.
Pour éviter tout écrasement d’image, ajoutez à son nom la chaîne "_grey".

Écrire le test pour vérifier que votre fonction transforme l’image comme voulu.

Prenons un problème pratique et concret et essayons de le résoudre en améliorant le code que nous avons implémenté.
Les robots Nao codent les images captées par leurs caméras en format YUV.
Elles sont sauvegardées dans des fichiers binaires .yuyv qui ne peuvent pas être visualisés directement dans un visualiseur d’images.
Nous voulons lire ces images, pour les convertir en format RGB et les sauvegarder dans des fichiers PPM qui, eux, peuvent être visualisés.

Commencez par fournir une nouvelle fonction membre new_from_yuv() à la structure Color.
Cette fonction crée un objet de type Color initialisé avec les composantes r, g et b obtenues en convertissant les composantes y, u et v reçues en paramètre.
Les composantes y, u et v sont aussi de type u8.
Voici ce qu’il faut savoir pour coder la conversion : Attention ! La valeur de red, green et blue doit être limitée entre 0 et 255.
Conseil : utiliser la fonction clamp().

Nous sommes prêts maintenant à modifier la classe Image pour qu’elle soit capable de charger d’un fichier binaire une image en format YUV et de la convertir en format RGB.
Ajoutez une nouvelle fonction d’initialisation new_from_yuv() qui prend en paramètre une string path, contenant le chemin qui mène à un fichier .yuyv.
Les fichier YUV fournis sont très différents des fichiers PPM puisqu'il s'agit de fichiers binaires ne contenant pas d’information sur la dimension des images.
Les images générées par le robot Nao ont ici une taille fixe : 640x480.
En outre, chaque ensemble de 4 octets représente 2 pixels, donc il faudra lire les octets dans le fichier par groupes de 4 pour obtenir les composantes y, u et v de deux pixels à la fois. (la couleur du premier pixel est composée par les valeurs y0, u et v et celle du deuxième par les valeurs y1, u et v).
Évidemment, il faudra convertir ces composants en RGB à l’aide de la fonction new_from_yuv() de la structure Color.
L’image doit s’appeler comme le fichier sans extension.

Testez cette nouvelle fonctionnalité.