IPython：显示本地图片与数组图像

在 Jupyter 等支持富输出的前端中，IPython.display 可以把图片对象作为图像显示。普通终端通常只显示文字表示，因此“Python 代码运行成功”和“前端已经画出图片”需要分开确认。

原记录的 Image(path=...) 参数应改为 filename=...；脚本中也应显式导入 display。本文示例使用 Python 3.11、IPython 9.17.1、Pillow 12.3.0、NumPy 2.4.6。

显示本地图片

下面的完整例子先在临时目录生成一张小图，再从文件构造显示对象，因此无需准备外部图片。临时文件删除后，已经嵌入的图片数据仍在对象中。

display_file.py

from pathlib import Path
from tempfile import TemporaryDirectory

from IPython.display import Image, display
from PIL import Image as PillowImage

with TemporaryDirectory() as directory:
    filename = Path(directory) / "sample.png"
    PillowImage.new("RGB", (4, 3), color=(30, 120, 210)).save(filename)
    picture = Image(filename=str(filename), width=160)
    assert picture.data == filename.read_bytes()

assert picture.format == "png"
display(picture)

替换为自己的文件时，可以使用 Image(filename="path/to/img.png")。Windows 路径也可以写成原始字符串 Image(filename=r"C:\images\img.png")，避免普通字符串中的 \t、\n 被解释成制表符、换行符。文件路径相对于 Python 当前工作目录解析，未必相对于笔记本或脚本文件所在位置。

显示数组中的像素

display(array_image) 并不保证把 NumPy 数组解释成图像。普通数组默认提供的是数值文字表示。对于下面这个形状为 (2, 3, 3)、类型为 uint8 的 RGB 数组，先通过 Pillow 转换成图片，再编码为 PNG。

display_array.py

from io import BytesIO

import numpy as np
from IPython.display import Image, display
from PIL import Image as PillowImage

array_image = np.array(
    [
        [[255, 0, 0], [0, 255, 0], [0, 0, 255]],
        [[255, 255, 255], [128, 128, 128], [0, 0, 0]],
    ],
    dtype=np.uint8,
)
assert array_image.shape == (2, 3, 3)
pixels = PillowImage.fromarray(array_image)
assert pixels.mode == "RGB" and pixels.size == (3, 2)

buffer = BytesIO()
pixels.save(buffer, format="PNG")
picture = Image(data=buffer.getvalue(), format="png", width=240)
display(picture)

这里的 data= 接收 PNG 编码后的字节，并非任意数组的原始内存。浮点数组、灰度图或 RGBA 图需要按实际数据范围和通道解释处理，不能把这个 RGB 示例机械套用到所有数组。

图片来源与前端边界

输入	构造方式	数据在哪里
本地图片文件	Image(filename=...)	读取后嵌入显示对象
PNG 等编码后的字节	Image(data=..., format="png")	已在内存中，可直接嵌入
远程图片地址	Image(url=...)	默认引用远程地址，显示时依赖前端及网络

url= 默认不嵌入；需要嵌入时明确设置 embed=True，这会读取远程内容。上述两段例子只处理本地产生的数据。IPython 的参数与嵌入规则见 Image API。

函数或循环内部应调用 display(picture)；只写变量名通常只有在交互单元的末尾才会触发自动展示。若终端输出 <IPython.core.display.Image object>，先确认前端是否支持图片输出，再检查文件与数据，不能据此认定图片已经损坏。

这些示例验证了图片字节、像素尺寸与富输出数据生成；没有把普通终端执行记录当作浏览器里的视觉验收。环境与 Notebook 内核的对应关系见 Conda 环境与导出。