LIBRARY

Pupil：工业级图像处理Python库

如果你曾在真实机器人上部署过视觉系统，你可能见过一个熟悉的模式。

admin

May 11, 2026 • 9 min read

微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署
AI模型价格对比 | AI工具导航 | ONNX模型库 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

在受控环境中一切看起来都正确。模型表现良好，检测结果稳定，流水线行为如预期。然后你进入真实世界，系统开始以难以解释的方式失败。之前容易检测的物体在略微不同的光照下消失了。边缘变得不稳定。噪声出现在开发时看起来干净的区域。

特别令人沮丧的是，模型通常不是根本原因。在许多情况下，问题始于流水线中更早的阶段，即原始传感器输入层面。

这是视觉系统中往往被低估的部分。

1、什么是Pupil？

Pupil是Telekinesis Agentic Skill Library的图像处理模块。它旨在处理位于原始相机输入和检测、分割、跟踪等高级感知系统之间的低级操作。

Pupil不是引入另一个基于学习的模型，而是专注于更基础的事情：使图像数据稳定、结构化且更易于推理。

它为滤波、增强、几何变换、色彩空间操作和基本特征提取等核心操作提供一致的接口。目标很简单：提高信号质量，使下游系统在真实世界条件下表现更可靠。

一个最小示例：

from telekinesis import pupil
from datatypes import datatypes, io

# Load an image
image = io.load_image(filepath=datatypes.String("path/to/image.jpg"))

# Apply Gaussian blur
blurred_image = pupil.filter_image_using_gaussian_blur(
    image=image,
    kernel_size=datatypes.Int(5),
    sigma_x=datatypes.Float(1.0)
)

# Save the result
io.save_image(image=blurred_image, filepath=datatypes.String("output.jpg"))

2、图像滤波

Pupil中的图像滤波专注于使原始传感器输入在到达目标检测或分割等高级感知组件之前更加稳定。

Gabor滤波示例：

from telekinesis import pupil

filtered_image = pupil.filter_image_using_gabor(
    image=image,
    kernel_size=21,
    standard_deviation=5.0,
    orientation=0.0,
    wavelength=10.0,
    aspect_ratio=0.5,
    phase_offset=0.0,
)

它包括标准的平滑技术，如高斯、中值和双边滤波，可以帮助减少传感器噪声同时保留重要结构。

中值模糊和高斯模糊示例：

from telekinesis import pupil

filtered_image = pupil.filter_image_using_median_blur(
    image=image,
    kernel_size=5,
)
from telekinesis import pupil

blurred_image = pupil.filter_image_using_gaussian_blur(
    image=image,
    kernel_size=7,
    sigma_x=3.0,
    sigma_y=3.0,
    border_type="default",
)

除了基本平滑，Pupil还暴露了边缘敏感和结构感知的滤波器，如 Sobel、Scharr、Laplacian和Gabor，适用于提取梯度、纹理和方向模式。

Scharr滤波示例：

from telekinesis import pupil

gradient_image = pupil.filter_image_using_scharr(
    image=image,
    dx=1,
    dy=0,
    scale=1.0,
    delta=0.0,
    output_format="64bit",
    border_type="default",
)

更专业的滤波器如 Frangi或基于Hessian的方法将其进一步扩展到结构化特征检测，包括管状和脊状区域。

Hessian滤波示例：

from telekinesis import pupil

vessels = pupil.filter_image_using_hessian(
    image=image,
    scale_start=1,
    scale_end=10,
    scale_step=2,
    detect_black_ridges=True,
    border_type="reflect",
    constant_value=0.0,
)

在实践中，这些操作用于使视觉信号在帧之间更加一致，特别是在噪声和光照变化不可避免的环境中。

形态学黑帽示例：

from telekinesis import pupil

filtered_image = pupil.filter_image_using_morphological_blackhat(
    image=image,
    kernel_size=15,
    kernel_shape="ellipse",
    iterations=1,
    border_type="default",
)

3、图像增强

Pupil中的图像增强解决不同的问题：不是噪声，而是在变化条件下的可见性和一致性。

CLAHE 示例：

from telekinesis import pupil

enhanced_image = pupil.enhance_image_using_clahe(
    image=image,
    clip_limit=10.0,
    tile_grid_size=4,
    color_space="lab",
)

像 CLAHE这样的技术可以改善不均匀光照环境中的局部对比度，使隐藏的细节更可见，而不会过度放大全局亮度。Gamma校正提供了对整体亮度的受控调整，而白平衡校正消除了不同光源引入的不需要的色偏。

Gamma校正示例：

from telekinesis import pupil

corrected_image = pupil.enhance_image_using_auto_gamma_correction(
    image=image
)

白平衡示例：

from telekinesis import pupil

balanced_image = pupil.enhance_image_using_white_balance(image=image)

这些方法在机器人领域特别重要，因为真实世界环境很少提供一致的照明。增强有助于标准化输入，使下游模型不必自行补偿这些变化。

4、裁剪

Pupil中的裁剪不仅是调整区域大小的工具；它是一种定义图像中真正重要部分的方式。

边界框裁剪示例：

from telekinesis import pupil

cropped_images = pupil.crop_image_using_bounding_boxes(
    image=image,
    bounding_boxes=bounding_boxes,
    retain_coordinates=False,
)
crop_list = cropped_images.to_list()

该库支持基于中心的裁剪、边界框提取和基于多边形的掩码，允许精确隔离感兴趣区域。这在机器人设置中特别有用，因为只有图像的一小部分包含可操作信息，例如杂乱箱中的物体或传送带上的目标区域。

图像中心裁剪示例：

from telekinesis import pupil

cropped_image = pupil.crop_image_center(
    image=image,
    crop_width=256,
    crop_height=256,
    pad_value=0,
)

通过将处理区域减少到相关区域，裁剪还提高了效率并减少了不必要的计算。

5、几何变换

Pupil中的几何变换处理图像的空间修改，同时保留结构含义。

旋转图像示例：

from telekinesis import pupil

rotated_image = pupil.rotate_image(
    image=image,
    angle_in_deg=33.0,
    interpolation_method="linear",
    keep_image_size=True,
)

包括带或不带纵横比约束的缩放、旋转、平移、填充和基于金字塔的缩放。

平移图像示例：

from telekinesis import pupil

translated_image = pupil.translate_image(
    image=image,
    dx=50,
    dy=-30,
    border_type="constant",
    fill_value=0,
    interpolation_method="linear",
)

这些操作通常用于标准化不同相机系统的输入、增强训练数据或将图像适配到下游模型的预期输入格式。在机器人应用中，它们还在对齐视角和补偿相机放置或朝向变化方面发挥作用。

6、色彩空间变换

色彩空间变换通过将亮度与颜色信息分离，提供了一种更稳健的解释视觉数据的方式。

转换为灰度示例：

from telekinesis import pupil

converted_image = pupil.convert_image_color_space(
    image=image,
    source_color_space="BGR",
    target_color_space="RGBA",
)

Pupil支持RGB、HSV、LAB和YCrCb等常见表示之间的转换，以及用于分离和合并通道以及标准化强度分布的工具。

这种分离很重要，因为许多感知任务在直接操作RGB空间时对光照变化敏感。在替代色彩空间中工作通常可以提高分割和检测任务的稳定性，特别是在不受控环境中。

7、位运算

Pupil中的位运算直接操作像素级表示，使其适用于掩码操作和图像合成。

图像差分示例：

from telekinesis import pupil

result = pupil.bitwise_difference_images(image_1=image, image_2=image_2)

AND、OR、XOR和差分操作等功能允许组合或比较二进制掩码。反转和加权叠加将其进一步扩展到可视化和合成工作流。

位运算OR 示例：

from telekinesis import pupil

result = pupil.bitwise_or_images(image_1=image, image_2=image_2)

位运算NOT 示例：

from telekinesis import pupil

result = pupil.bitwise_not_image(image=image)

这些操作通常用于分割流水线，其中多个掩码或预测需要随时间合并、精炼或比较。

8、世界空间与像素空间之间的投影

Pupil中的投影工具将2D图像空间与3D空间表示连接起来。

from telekinesis import pupil
import numpy as np
from loguru import logger

# Camera intrinsics (obtained from camera calibration)
camera_intrinsics = np.array(
    [[500.0, 0, 320.0], [0, 500.0, 240.0], [0, 0, 1.0]],
    dtype=np.float64,
)

# Distortion coefficients for camera lens
distortion_coefficients = np.array([0.0, 0.0, 0.0, 0.0, 0.0], dtype=np.float64)
pixel = np.array([320.0, 240.0], dtype=np.float64)
depth = 1.0
world_T_camera = np.eye(4, dtype=np.float64)
world_T_camera[2, 3] = 1.0

# Project pixel to world coordinates
world_T_point = pupil.project_pixel_to_world_point(
    camera_intrinsics=camera_intrinsics,
    distortion_coefficients=distortion_coefficients,
    pixel=pixel,
    depth=depth,
    world_T_camera=world_T_camera,
)

logger.success(
    "Projected pixel to world point. world_T_point shape: {}",
    np.asarray(world_T_point.matrix).shape if hasattr(world_T_point, "matrix") else "N/A",
)

该库提供了使用深度信息将点从像素坐标投影到相机和世界坐标的功能，以及从3D空间反向投影回图像平面的功能。

这种能力在机器人系统中至关重要，因为感知必须转化为物理交互。无论是抓取、导航还是场景理解，这些投影构成了相机所见与机器人所能做之间的桥梁。

原文链接: Pupil: A Production-Grade Image Processing Library in Python

汇智网翻译整理，转载请标明出处