Pupil:工业级图像处理Python库

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

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

1、什么是 Pupil？

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

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

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

一个最小示例：

from telekinesis import pupilfrom datatypes import datatypes, io# Load an imageimage = io.load_image(filepath=datatypes.String("path/to/image.jpg"))# Apply Gaussian blurblurred_image = pupil.filter_image_using_gaussian_blur(     image=image,     kernel_size=datatypes.Int(5),     sigma_x=datatypes.Float(1.0) )# Save the resultio.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 pupilimport numpy as npfrom 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 lensdistortion_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.0world_T_camera = np.eye(4, dtype=np.float64) world_T_camera[2, 3] = 1.0# Project pixel to world coordinatesworld_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 空间反向投影回图像平面的功能。