HOWTO · NumPy

NumPy-Array als Bild speichern in Python

Dieses Tutorial zeigt, wie Sie ein NumPy-Array als Bild in Python speichern

Auf dieser Seite

Ein NumPy-Array lässt sich mit Pillow, imageio, Matplotlib oder OpenCV in eine Bilddatei schreiben. Welche Bibliothek sich eignet, hängt davon ab, welche Ihr Projekt bereits verwendet und wie die Pixeldaten im Array angeordnet sind. Ein zweidimensionales Array stellt häufig Graustufenpixel dar; ein dreidimensionales Array enthält häufig Farbkanäle in der Reihenfolge Höhe × Breite × Kanäle. RGB-Daten haben drei Kanäle in der letzten Dimension, RGBA-Daten ergänzen einen Alphakanal.

Für gängige 8-Bit-Bilder sind Werte vom Typ numpy.uint8 im Bereich von 0 bis 255 ein guter Ausgangspunkt. Gleitkomma-Arrays können von den einzelnen Bibliotheken unterschiedlich interpretiert oder skaliert werden. Prüfen Sie daher vor dem Speichern, welchen Wertebereich die jeweilige Schreibfunktion erwartet. Die folgenden ausführbaren Beispiele verwenden kleine Arrays und temporäre PNG-Pfade. Falls NumPy oder die verwendete Bibliothek noch nicht installiert ist, installieren Sie die benötigten Pakete. Für Pillow können Sie beispielsweise python -m pip install numpy pillow ausführen.

Ein NumPy-Array für die Bildausgabe vorbereiten

Wählen Sie eine Array-Form, die zu den Bilddaten passt: (height, width) für Graustufen, (height, width, 3) für RGB oder (height, width, 4) für RGBA, sofern die Schreibfunktion Kanäle am Ende erwartet. Die Form beschreibt die Anordnung, aber nicht die Bedeutung der Kanäle. Prüfen Sie deshalb, ob Ihre Quelldaten RGB oder BGR verwenden, bevor Sie Farbpixel an eine Bibliothek übergeben.

Verwenden Sie einen Datentyp und Wertebereich, die sowohl vom Bildformat als auch von der gewählten Schreibfunktion unterstützt werden. Für eine gewöhnliche 8-Bit-Ausgabe werden numpy.uint8-Werte von 0 bis 255 weithin akzeptiert. Liegen die Quelldaten als Gleitkommazahlen oder in einem anderen Wertebereich vor, konvertieren oder skalieren Sie sie gezielt. Schreibfunktionen können Werte unterschiedlich abschneiden, skalieren oder zurückweisen.

Ein NumPy-Array mit der Funktion Image.fromarray() als Bild speichern

Pillows Image.fromarray() erstellt aus einem Array ein Bild, und Image.save() schreibt es in eine Datei. Ein zweidimensionales uint8-Array stellt Graustufendaten dar. Für Farbbilder verwenden Sie ein geeignetes Array mit drei Kanälen in RGB-Reihenfolge. Dieses Beispiel speichert ein kleines Graustufen-Array als 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

Das temporäre Verzeichnis macht das Beispiel in sich abgeschlossen. Für ein Farbbeispiel können Sie ein Array mit der Form (height, width, 3) und RGB-Kanalreihenfolge verwenden; Pillow kann RGB aus einem geeigneten Array mit drei Kanälen ableiten.

Ein NumPy-Array mit der Funktion imageio.imwrite() als Bild speichern

imageio.imwrite() schreibt ein Array in den Pfad, der als erstes Argument übergeben wird. Die Dateiendung legt üblicherweise die Schreibfunktion fest. Verwenden Sie daher eine Endung, die von den installierten imageio-Plugins unterstützt wird. Dieses eigenständige Beispiel erstellt ein Graustufen-Array und behält den Ausgabepfad während des gesamten Schreibvorgangs im temporären Verzeichnis. Die bereitgestellten Laufzeitergebnisse decken dieses imageio-Beispiel nicht ab. Installieren Sie NumPy und imageio, zum Beispiel mit python -m pip install numpy imageio, um es in Ihrer Umgebung auszuführen.

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")

Verwenden Sie für diese Aufgabe eine Bildbibliothek wie imageio. Das frühere Beispiel mit scipy.io.imsave() wird hier nicht als aktuelle Anleitung übernommen; dieser Artikel stützt sich nicht auf historische Aussagen oder Aussagen zur Veraltung von SciPy-APIs.

Ein NumPy-Array mit der Funktion matplotlib.pyplot.imsave() als Bild speichern

Matplotlib schreibt Arrays direkt mit matplotlib.pyplot.imsave(). Für ein zweidimensionales Array übergeben Sie cmap="gray", um eine Graustufenausgabe anzufordern. Ohne explizite Farbskala kann Matplotlib skalare Werte Farben zuordnen. Eingaben mit drei Kanälen werden als RGB behandelt. Dieses Beispiel speichert Graustufenwerte mit einer ausdrücklich angegebenen grauen Farbskala:

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

Bei skalaren Daten, deren Wertebereich eine Bedeutung hat, sollten Sie Normalisierung und Farbskala bewusst wählen. So bleibt die Farbzuordnung für die Visualisierung von den ursprünglichen Pixelfarbkanälen getrennt.

Ein NumPy-Array mit der Funktion cv2.imwrite() als Bild speichern

OpenCV wählt anhand der Dateiendung einen Encoder für cv2.imwrite() aus. Die Funktion gibt einen booleschen Wert zurück, der angibt, ob das Schreiben erfolgreich war. Prüfen Sie diesen Wert insbesondere dann, wenn das Ausgabeverzeichnis oder der Codec möglicherweise nicht verfügbar ist. OpenCV verwendet für Farb-Arrays üblicherweise die BGR-Kanalreihenfolge. Wenn die gespeicherten Farben der Quelle entsprechen sollen, konvertieren Sie RGB-Daten vor dem Schreiben. Für ein zweidimensionales Graustufen-Array ist keine Umordnung der Kanäle nötig. Das Beispiel erzeugt einen während des Schreibens gültigen Ausgabepfad und gibt sowohl bei einem Rückgabewert False als auch bei einer fehlenden OpenCV-Installation eine hilfreiche Meldung aus. Die bereitgestellten Laufzeitergebnisse decken dieses OpenCV-Beispiel nicht ab. Installieren Sie NumPy und opencv-python, zum Beispiel mit python -m pip install numpy opencv-python, um es in Ihrer Umgebung auszuführen.

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.")

Bei RGB-Farbeingaben konvertieren Sie die Daten mit cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR), bevor Sie cv2.imwrite() aufrufen. Achten Sie darauf, dass Konvertierung und Array-Anordnung zu den Quelldaten passen.

Ein Ausgabeformat wählen und das Bild überprüfen

Die Dateiendung bestimmt oder kennzeichnet üblicherweise das Ausgabeformat. Welche Formate und Optionen unterstützt werden, hängt jedoch von der Bibliothek und den installierten Plugins ab. PNG ist verlustfrei; JPEG ist verlustbehaftet und speichert keine Transparenz. Vergewissern Sie sich, dass die gewählte Schreibfunktion die gewünschte Endung unterstützt.

Prüfen Sie einen Rückgabewert, wenn die API einen bereitstellt, wie es OpenCV tut. Wenn Sie das Ergebnis genauer überprüfen möchten, öffnen Sie die gespeicherte Datei erneut und kontrollieren Sie ihre Abmessungen, ihren Modus oder ihre Kanalzahl sowie die Pixelwerte. Unerwartete Farben können auf eine RGB/BGR-Verwechslung hindeuten; farbige Graustufenausgaben können entstehen, wenn Matplotlib eine Farbskala angewendet hat. Wenn das Ergebnis nicht stimmt, vergleichen Sie Form, Datentyp, Wertebereich und Kanalreihenfolge des Arrays mit den Erwartungen der Schreibfunktion.