5.7. Composition d’images

Les primitives de dessin de la page précédente peignent des marques géométriques sur une image – une ligne, un rectangle, un fragment de texte. Cela couvre la plupart des annotations qu’un algorithme a besoin de rendre visibles, mais pas toutes. Parfois, l’annotation est elle-même une image : une trame de référence capturée à afficher côte à côte avec la trame courante, une miniature d’une capture précédente affichée dans un coin de l’aperçu, un gabarit stocké précédemment visualisé par-dessus une trame en direct pour le calibrage. Le mécanisme permettant de dessiner une image sur une autre est une méthode unique – draw_image() – dotée de suffisamment de paramètres pour gérer la position, la mise à l’échelle, la palette de couleurs et la transparence qu’exige une composition réelle.

5.7.1. L’appel de base

Dans sa forme la plus simple, draw_image prend une autre Image et une position où la dessiner :

reference = image.Image("/sdcard/reference.bmp")
img.draw_image(reference, x=10, y=10)

La destination est img ; la source est reference ; le pixel en haut à gauche de la source se place en (10, 10) de img, et le reste des pixels de la source suit vers la droite et vers le bas à partir de là. Les pixels de la destination que la source recouvre sont écrasés par les pixels correspondants de la source ; les pixels en dehors de l’emprise de la source restent intacts.

Si la source dépasse le bord de la destination, les parties qui débordent sont silencieusement rognées – le même comportement indulgent que set_pixel affiche pour les positions hors plage. Le code applicatif n’a pas à contraindre la position aux dimensions de l’image au préalable ; il peut transmettre la position souhaitée et laisser la méthode gérer le rognage.

5.7.2. Charger un fichier directement

draw_image accepte un chemin de fichier à la place de l’argument Image et charge le fichier avant de le composer :

img.draw_image("/sdcard/reference.bmp", x=10, y=10)

Cela ressemble à une commodité – une ligne au lieu de deux – et c’en est une, mais la différence va au-delà de la syntaxe. Construire une Image à partir d’un fichier alloue un tampon pour contenir les pixels décodés, et ce tampon subsiste jusqu’à ce que le ramasse-miettes le libère. Transmettre le chemin directement à draw_image permet au module de décoder le fichier dans un tampon temporaire, de composer à partir de celui-ci et de libérer le tampon au retour de l’appel, sans que le code applicatif ait à conserver une référence vers une Image distincte entre les trames.

5.7.3. Mise à l’échelle

Lorsque la source et la destination ont des tailles différentes – une capture en basse résolution composée sur un canevas en plus haute résolution, ou une miniature qui doit être dimensionnée à une fraction particulière de la trame – deux paramètres d’échelle se chargent de redimensionner la source au moment où elle est dessinée :

img.draw_image(reference, x=10, y=10, x_scale=2.0, y_scale=2.0)

x_scale et y_scale sont des flottants indépendants ; transmettre la même valeur pour les deux applique une mise à l’échelle uniforme, tandis que transmettre des valeurs différentes étire ou rétrécit la source selon un axe. La mise à l’échelle se produit au moment du dessin ; la source reference n’est pas modifiée.

Un masque de bits d’indicateurs d”indication détermine comment la mise à l’échelle interpole réellement entre les pixels. image.BILINEAR produit des résultats plus lisses au prix de davantage de calculs ; image.BICUBIC produit des résultats encore plus lisses et coûte encore davantage ; la valeur par défaut utilise le plus proche voisin, qui est la moins coûteuse et le bon choix lorsque la source est déjà à la résolution en pixels de la destination. Les indicateurs de gestion du rapport d’aspect – SCALE_ASPECT_KEEP, SCALE_ASPECT_EXPAND, SCALE_ASPECT_IGNORE – décident de ce qu’il faut faire lorsque le rapport d’aspect de la source ne correspond pas au rectangle dans lequel elle est dessinée.

5.7.4. Fusion alpha

Par défaut, draw_image remplace les pixels de destination par les pixels de la source. Lorsque l’objectif est une superposition translucide – de sorte que la destination transparaisse à travers la source – le paramètre alpha contrôle la manière dont les deux sont mélangés. alpha=0 n’affiche que la destination (pas de source) ; alpha=255 est la valeur par défaut et n’affiche que la source (remplacement complet) ; les valeurs intermédiaires mélangent les deux proportionnellement :

img.draw_image(overlay, x=0, y=0, alpha=128)

Un argument distinct alpha_palette est le seul mécanisme d’alpha par pixel du module. Il prend une image GRAYSCALE dont les valeurs sont utilisées comme alpha à la position correspondante dans la source – une carte de chaleur dont l’alpha varie avec son intensité, par exemple. L’alpha doit être fourni sous la forme de cet argument distinct en niveaux de gris ; une image source qui porte son propre canal alpha (un PNG avec transparence, par exemple) ne le transmet pas automatiquement.

5.7.5. ROI source et palette

Deux paramètres supplémentaires complètent le mécanisme de composition :

• roi=(x, y, w, h) restreint la source à un sous-rectangle d’elle-même, de sorte que seul ce rectangle soit composé sur la destination. Utile pour recadrer au sein du même appel, sans préparer d’intermédiaire recadré.

• color_palette substitue la valeur de chaque pixel source au travers d’une table de correspondance avant le dessin – le même mécanisme qu’utilisent to_rainbow() et to_ironbow(), exposé ici pour qu’une superposition puisse être palettisée sur son chemin vers la destination sans passe de conversion distincte.

Les deux se composent avec tout le reste de l’appel : la mise à l’échelle, l’alpha, l’argument mask côté destination, et le paramètre roi côté destination qui restreint l”écriture à un rectangle de la destination.