Enregistrer le tableau NumPy en tant qu'image en Python

Un tableau NumPy peut être enregistré dans un fichier image avec Pillow, imageio, Matplotlib ou OpenCV. Le choix dépend de la bibliothèque déjà utilisée dans votre projet et de la manière dont votre tableau représente les pixels. Un tableau à deux dimensions représente généralement des pixels en niveaux de gris ; un tableau à trois dimensions représente généralement les canaux de couleur sous la forme hauteur × largeur × canaux. Les données RGB comportent trois canaux dans la dernière dimension, tandis que RGBA en ajoute un pour l’alpha.

Pour les images courantes sur 8 bits, les valeurs numpy.uint8 comprises entre 0 et 255 constituent un point de départ pratique. Chaque bibliothèque peut interpréter ou redimensionner différemment un tableau à virgule flottante : vérifiez donc la plage attendue par la fonction d’écriture avant l’enregistrement. Les exemples exécutables ci-dessous utilisent de petits tableaux et des chemins PNG temporaires. Si nécessaire, installez NumPy et la bibliothèque utilisée dans l’exemple (pour Pillow, par exemple, exécutez python -m pip install numpy pillow).

Préparer un tableau NumPy pour l’enregistrement d’une image

Choisissez une forme de tableau adaptée aux données de l’image : (height, width) pour les niveaux de gris, (height, width, 3) pour RGB ou (height, width, 4) pour RGBA, lorsque la fonction d’écriture attend les canaux en dernière position. La forme décrit l’organisation des données, mais ne précise pas la signification des canaux. Avant de transmettre des pixels couleur à une bibliothèque, vérifiez si les données source sont en RGB ou en BGR.

Utilisez un type et une plage numériques pris en charge à la fois par le format d’image et par la fonction d’écriture choisie. Pour une sortie standard sur 8 bits, numpy.uint8 avec des valeurs comprises entre 0 et 255 est largement accepté. Si les valeurs source sont à virgule flottante ou utilisent une autre plage, convertissez-les ou redimensionnez-les intentionnellement : selon la fonction d’écriture, elles peuvent être tronquées, redimensionnées ou refusées.

Utiliser la fonction Image.fromarray() pour enregistrer un tableau NumPy en tant qu’image

La fonction Image.fromarray() de Pillow crée une image à partir d’un tableau, puis Image.save() l’enregistre dans un fichier. Un tableau uint8 à deux dimensions représente des données en niveaux de gris. Pour une image couleur, fournissez un tableau adapté à trois canaux dans l’ordre RGB. Cet exemple enregistre un petit tableau en niveaux de gris sous le nom gray.png :

from pathlib import Path
from tempfile import TemporaryDirectory

import numpy as np
from PIL import Image

pixels = np.array([[0, 64, 128], [192, 224, 255]], dtype=np.uint8)
with TemporaryDirectory() as directory:
    output_path = Path(directory) / "gray.png"
    image = Image.fromarray(pixels)
    image.save(output_path)
    print("Saved gray.png")

Saved gray.png

Le répertoire temporaire rend l’exemple autonome. Pour une image couleur, vous pouvez utiliser un tableau de forme (height, width, 3) avec les canaux dans l’ordre RGB ; Pillow peut déduire le mode RGB à partir d’un tableau à trois canaux approprié.

Utiliser la fonction imageio.imwrite() pour enregistrer un tableau NumPy en tant qu’image

imageio.imwrite() écrit un tableau à l’emplacement indiqué par son premier argument. L’extension du nom de fichier sélectionne généralement la fonction d’écriture ; choisissez donc une extension prise en charge par les plugins imageio installés. Cet exemple autonome crée son propre tableau en niveaux de gris et conserve le chemin de sortie dans le répertoire temporaire pendant toute l’écriture. Les résultats d’exécution fournis ne couvrent pas cet exemple avec imageio ; installez NumPy et imageio (par exemple, avec python -m pip install numpy imageio) pour l’exécuter dans votre environnement.

from pathlib import Path
from tempfile import TemporaryDirectory

import numpy as np

pixels = np.array([[0, 64, 128], [192, 224, 255]], dtype=np.uint8)
try:
    import imageio.v2 as imageio
except ImportError:
    print("imageio is unavailable; install imageio to write the image.")
else:
    with TemporaryDirectory() as directory:
        output_path = Path(directory) / "gray.png"
        imageio.imwrite(output_path, pixels)
        print("Saved gray.png")

Pour cette tâche, utilisez une bibliothèque d’écriture d’images telle que imageio. L’exemple historique avec scipy.io.imsave() n’est pas présenté comme une recommandation actuelle ; cet article ne s’appuie pas sur des affirmations historiques ou liées à la dépréciation des API SciPy.

Utiliser la fonction matplotlib.pyplot.imsave() pour enregistrer un tableau NumPy en tant qu’image

Matplotlib écrit directement les tableaux avec matplotlib.pyplot.imsave(). Pour un tableau 2D, transmettez cmap="gray" afin de demander une sortie en niveaux de gris. Sans carte de couleurs explicite, Matplotlib peut associer des couleurs aux valeurs scalaires. Les tableaux à trois canaux sont interprétés comme des données RGB. Cet exemple enregistre des valeurs en niveaux de gris avec une carte de couleurs grises explicite :

from pathlib import Path
from tempfile import TemporaryDirectory

import matplotlib.pyplot as plt
import numpy as np

pixels = np.array([[0, 64, 128], [192, 224, 255]], dtype=np.uint8)
with TemporaryDirectory() as directory:
    output_path = Path(directory) / "gray.png"
    plt.imsave(output_path, pixels, cmap="gray")
    print("Saved gray.png")

Saved gray.png

Pour des données scalaires dont la plage numérique a une signification, choisissez délibérément la normalisation et la carte de couleurs. Vous distinguez ainsi l’association de couleurs utilisée pour la visualisation des canaux de pixels d’origine.

Utiliser la fonction cv2.imwrite() pour enregistrer un tableau NumPy en tant qu’image

La fonction cv2.imwrite() d’OpenCV choisit un encodeur d’après l’extension du nom de fichier et renvoie une valeur booléenne indiquant si l’écriture a réussi. Vérifiez cette valeur, en particulier si le répertoire de sortie ou le codec risque de ne pas être disponible. Par convention, OpenCV utilise l’ordre de canaux BGR pour les tableaux couleur. Si vous souhaitez que les couleurs enregistrées correspondent à la source, convertissez les données RGB avant l’écriture. Un tableau 2D en niveaux de gris ne nécessite aucune conversion de l’ordre des canaux. L’exemple crée un chemin de sortie encore valide et gère aussi bien un retour False que l’absence d’OpenCV, en affichant un message utile. Les résultats d’exécution fournis ne couvrent pas cet exemple avec OpenCV ; installez NumPy et opencv-python (par exemple, avec python -m pip install numpy opencv-python) pour l’exécuter dans votre environnement.

from pathlib import Path
from tempfile import TemporaryDirectory

import numpy as np

pixels = np.array([[0, 64, 128], [192, 224, 255]], dtype=np.uint8)
try:
    import cv2
except ImportError:
    print("OpenCV is unavailable; install opencv-python to write the image.")
else:
    with TemporaryDirectory() as directory:
        output_path = Path(directory) / "gray.png"
        written = cv2.imwrite(str(output_path), pixels)
        if written:
            print("Saved gray.png")
        else:
            print(f"Could not write {output_path}; check the directory and image encoder.")

Pour des données couleur RGB, convertissez-les avec cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR) avant d’appeler cv2.imwrite(). Veillez à ce que la conversion et la disposition du tableau restent cohérentes avec les données source.

Choisir un format de sortie et vérifier l’image

L’extension du nom de fichier détermine ou indique généralement le format de sortie, mais les formats et options pris en charge varient selon la bibliothèque et les plugins installés. PNG est sans perte ; JPEG est avec perte et ne préserve pas la transparence. Vérifiez que la fonction d’écriture choisie prend en charge l’extension souhaitée.

Vérifiez la valeur de retour lorsque l’API en fournit une, comme le fait OpenCV. Pour confirmer le résultat, rouvrez le fichier enregistré et vérifiez ses dimensions, son mode ou son nombre de canaux, ainsi que ses valeurs de pixels. Des couleurs inattendues peuvent signaler un ordre de canaux RGB/BGR incorrect ; une sortie en niveaux de gris colorée peut indiquer que Matplotlib a appliqué une carte de couleurs. Si l’image ne paraît pas correcte, comparez la forme, le type, la plage et l’ordre des canaux du tableau aux attentes de la fonction d’écriture.