HOWTO · Matplotlib
Convertir un array de NumPy en una imagen PIL en Python
Este tutorial explica cómo podemos convertir un array NumPy en una imagen PIL usando el Image.fromarray() del paquete PIL.
En esta página
Usa Image.fromarray() de Pillow para crear una imagen PIL a partir de un array de NumPy. Un array bidimensional representa píxeles en escala de grises; los arrays con forma (height, width, 3) o (height, width, 4) representan píxeles RGB o RGBA. El tipo de dato (dtype) y los valores del array también importan, así que revísalos antes de convertirlo. PIL es el nombre de importación habitual, mientras que Pillow es la biblioteca que se mantiene actualmente.
Para una imagen RGB, crea un array uint8 con tres canales y pásalo a Image.fromarray(). La salida indica el modo de la imagen, su tamaño (width, height) y el píxel de la esquina superior izquierda.
El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.
import numpy as np
from PIL import Image
pixels = np.array(
[[[255, 0, 0], [0, 255, 0]], [[0, 0, 255], [255, 255, 255]]],
dtype=np.uint8,
)
image = Image.fromarray(pixels)
print(image.mode, image.size, image.getpixel((0, 0)))
RGB (2, 2) (255, 0, 0)
La imagen resultante es un objeto de Pillow en memoria. Puedes consultar su modo y sus dimensiones, y después mostrarla en un entorno compatible con vistas previas de imágenes o guardarla en un archivo.
Convertir un array de NumPy en una imagen PIL con Image.fromarray()
Image.fromarray(array) infiere el modo de la imagen a partir de la forma y el tipo de dato del array. Para datos en escala de grises, usa un array bidimensional con forma (height, width). Para datos RGB, usa (height, width, 3); un cuarto canal opcional produce RGBA. Las dos primeras dimensiones corresponden a filas y columnas, así que un array de 40 filas por 60 columnas crea una imagen de 60 píxeles de ancho y 40 de alto.
Usa np.uint8 para muestras de imagen normales de 8 bits cuando sus valores ya sean enteros entre 0 y 255. No conviertas el tipo de dato a ciegas: al convertir datos de punto flotante se truncan las partes fraccionarias, y los valores fuera del intervalo representable pueden desbordarse. Si los datos están medidos en otra escala, decide cómo deben corresponderse con la intensidad de visualización antes de convertirlos. Por ejemplo, los datos del intervalo 0–1 se pueden multiplicar por 255 y redondear; para otros intervalos hace falta una normalización explícita que tenga en cuenta su significado.
Preparar la forma, el tipo de dato y el rango de valores del array
Un array con forma (height, width) representa una imagen en escala de grises. Los arrays RGB y RGBA añaden una dimensión final para los canales, con tres o cuatro valores por píxel. Una forma como (height, width, 1) no es la forma bidimensional habitual para una imagen en escala de grises; si ese último eje unitario representa los tonos de gris, elimínalo con array[..., 0]. Antes de convertir el array, comprueba array.shape, array.dtype y sus valores mínimo y máximo. Debe contener una cuadrícula rectangular regular: las listas anidadas con longitudes desiguales no son datos de imagen.
Este ejemplo autónomo convierte un array a escala de grises. Sus valores están directamente dentro del rango de 8 bits, por lo que no hace falta escalarlos. La imagen resultante usa el modo de escala de grises L y tiene un tamaño de (3, 2).
El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.
import numpy as np
from PIL import Image
gray = np.array([[0, 64, 128], [32, 160, 255]], dtype=np.uint8)
image = Image.fromarray(gray)
print(image.mode, image.size)
L (3, 2)
Si la fuente es un array de punto flotante con valores entre 0 y 1, conviértelo de forma deliberada con np.round(array * 255).astype(np.uint8). Esta transformación solo es adecuada cuando esos valores son intensidades normalizadas. Para medidas como temperaturas o puntuaciones arbitrarias, elige límites inferior y superior con sentido, recorta o normaliza los valores a ese intervalo y documenta la correspondencia; de lo contrario, el contraste y los valores de los píxeles pueden inducir a error.
Aplicar un mapa de color de Matplotlib antes de crear una imagen PIL
Usa un mapa de color de Matplotlib cuando la fuente sea un campo escalar bidimensional y quieras que el color represente sus valores. Normaliza los datos al intervalo que espera el mapa de color elegido y convierte el resultado en un array RGB o RGBA de 8 bits. El mapa de color plasma devuelve canales normalizados de rojo, verde, azul y alfa; al descartar el alfa con [..., :3], se obtiene un array RGB. Este paso es independiente de Image.fromarray(): el mapa de color asigna los colores y Pillow envuelve esos píxeles en una imagen.
El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.
import numpy as np
import matplotlib
from PIL import Image
values = np.array([[0.0, 0.25], [0.75, 1.0]])
colors = matplotlib.colormaps["plasma"](values)[..., :3]
rgb = np.round(colors * 255).astype(np.uint8)
image = Image.fromarray(rgb)
print(image.mode, image.size)
RGB (2, 2)
Este ejemplo supone que values ya está normalizado entre 0 y 1. Si el rango escalar real es distinto, normaliza los valores con límites de datos adecuados antes de aplicar el mapa de color. Un mapa de color es útil para visualizar, pero transforma los valores escalares en colores de visualización; no debe sustituir las medidas originales cuando las necesites para el análisis. La imagen resultante es RGB y tiene un tamaño de (2, 2).
Redimensionar y guardar la imagen PIL
Después de la conversión, redimensiona la imagen con image.resize((width, height)); Pillow recibe el nuevo tamaño en el orden ancho y luego alto. Guardar es distinto de mostrar: show() abre una vista previa usando el entorno local, mientras que save() escribe un archivo de imagen. Elige una extensión de archivo que corresponda al formato deseado, como .png para una salida sin pérdida o .jpg para JPEG.
El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.
import numpy as np
from PIL import Image
pixels = np.zeros((20, 30, 3), dtype=np.uint8)
pixels[:, :15] = [255, 80, 0]
pixels[:, 15:] = [20, 90, 220]
image = Image.fromarray(pixels)
resized = image.resize((60, 40))
resized.save("resized-image.png")
print(resized.size)
El ejemplo crea la entrada en memoria y escribe resized-image.png en el directorio de trabajo actual. En una aplicación, usa una ruta adecuada para la ubicación de salida. Guardar no modifica el array de NumPy, y redimensionar cambia las dimensiones en píxeles de la imagen de Pillow.
Problemas comunes al convertir
- Modo inesperado o forma rechazada: revisa
array.shape. Usa(height, width)para escala de grises y tres o cuatro canales en la última dimensión para RGB o RGBA. Elimina un canal unitario no deseado o reordena los canales si la fuente usa otra convención. - Brillo o colores incorrectos: revisa el rango de valores antes de la conversión. Los valores de punto flotante entre 0 y 1 necesitan un escalado deliberado para una imagen de 8 bits; los valores que ya están entre 0 y 255 no se deben volver a multiplicar. Para otros rangos, normaliza usando límites documentados.
- Tipo de dato inesperado: revisa
array.dtypey decide cómo convertirlo. Cambiar el tipo por sí solo no reescala los datos; conserva una copia de la fuente si importa mantener la precisión original. - El mapa de color produce un resultado extraño: confirma que la entrada escalar se normalizó como se esperaba y comprueba si el resultado tiene tres canales RGB o cuatro canales RGBA. Convierte los canales de color normalizados a
uint8antes de crear la imagen. - No se crea el archivo de imagen: llama a
save()con una ruta donde se pueda escribir y una extensión compatible. Usashow()solo si quieres una vista previa; no guarda la imagen.