消息图像与视觉

坐标与边界框

Claude 如何调整图像大小，以及如何处理其返回的用于边界框、点和 UI 元素的像素坐标。

Claude 可以定位并标注图像中的区域（例如，返回表格、表单字段、图表元素或 UI 组件的边界框）。本指南介绍 Claude 在处理图像之前如何调整图像大小，以及如何处理其返回的像素坐标，以便边界框和点能够与您的原始图像对齐。

在 OCR 流程、表单提取、图表解析、UI 元素定位以及任何需要对图像特定区域进行操作的任务中，您都会用到这些内容。有关发送图像、支持的格式以及各模型的分辨率限制，请参阅视觉。

**Claude 最擅长处理绝对像素坐标。**请在提示中明确要求使用绝对像素坐标。例如："以像素坐标形式返回每个表格的边界框，格式为 [x1, y1, x2, y2]。" 当您要求返回归一化坐标时，Claude 的表现不佳，例如："返回 0 到 1000 之间的边界框坐标。" 请始终要求返回像素坐标，如有需要，再在您自己的代码中进行归一化。

坐标遵循标准图像约定：原点 (0, 0) 位于图像的左上角，x 向右递增，y 向下递增。Claude 返回的坐标是 Claude 所见图像中的像素位置：即您的图像经 Claude 调整大小以适应模型原生分辨率后的图像（参见 Claude 如何调整图像大小和填充）。要获得可直接使用的坐标，您可以预先调整图像大小，使坐标与您手中的图像一一对应（参见上传前调整图像大小），或者对 Claude 返回的坐标进行重新缩放（参见无法预先调整大小时重新缩放坐标）。

Claude 的空间推理能力存在局限（参见局限性）。当您在提示中明确说明预期的坐标格式，并在大规模处理前对结果进行可视化抽查时，坐标准确性最佳。对于 PDF 支持，页面会在服务器端以您无法控制的尺寸光栅化为图像，因此返回的坐标无法可靠地映射回页面。如需在 PDF 内容上使用坐标，请自行将页面光栅化为图像，并使用预先调整大小的方法。

Claude 如何调整图像大小和填充

Claude 会找到同时满足模型两项图像限制的最大保持宽高比的尺寸：

**边长限制：**任一边都不超过最大边长（标准层级为 1568 px，高分辨率层级为 2576 px）。
**视觉令牌限制：**图像的令牌成本 ⌈width / 28⌉ × ⌈height / 28⌉ 不超过模型的视觉令牌预算（标准层级为 1568 个令牌，高分辨率层级为 4784 个令牌）。

有关各模型所属层级的信息，请参阅分辨率与令牌成本。

对于大多数照片和屏幕截图，触发调整大小的是边长限制。对于纵向文档，通常是视觉令牌限制先被触发，而忽略这一点是导致坐标错位的最常见原因。例如，以 130 DPI 扫描的 A4 页面为 1075×1520 像素：两边都小于 1568 px，但其成本为 39 × 55 = 2145 个视觉令牌，因此 Claude 会将其调整为 924×1307。

随后，无论图像是否经过调整大小，Claude 都会在底部和右侧边缘将每张图像填充至 28 像素的下一个倍数（在上述示例中，924×1307 变为 924×1316）。填充区域不包含任何内容：Claude 感知的是填充后的图像，但页面内容始终只占据未填充的调整后区域。请始终按调整后的尺寸（而非填充后的尺寸）进行归一化或重新缩放；如果除以填充后的尺寸，会使每个坐标产生微小的缩放偏差。

上传前调整图像大小

最可靠的方法是在上传前自行调整图像大小，这样您手中的图像就与 Claude 所见的图像完全一致，Claude 返回的坐标无需任何转换。

以下参考实现计算 Claude 将图像调整到的确切尺寸：

import math


def count_image_tokens(width: int, height: int) -> int:
    """Visual tokens consumed by an image: one token per 28x28 pixel patch."""
    return math.ceil(width / 28) * math.ceil(height / 28)


def resized_size(
    width: int,
    height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[int, int]:
    """The size Claude resizes an image to before padding.

    Defaults are for the standard resolution tier. For high-resolution-tier
    models, use max_edge=2576 and max_tokens=4784. Returns (width, height).
    Images that already fit within the limits are returned unchanged.
    """

    def fits(w: int, h: int) -> bool:
        return (
            math.ceil(w / 28) * 28 <= max_edge
            and math.ceil(h / 28) * 28 <= max_edge
            and count_image_tokens(w, h) <= max_tokens
        )

    if fits(width, height):
        return (width, height)
    if height > width:
        resized_h, resized_w = resized_size(height, width, max_edge, max_tokens)
        return (resized_w, resized_h)

    # 沿长边进行二分查找，找出保持宽高比且能容纳的最大尺寸。
    # 
    aspect_ratio = width / height
    lo, hi = 1, width  # lo always fits; hi never fits
    while lo + 1 < hi:
        mid = (lo + hi) // 2
        if fits(mid, max(round(mid / aspect_ratio), 1)):
            lo = mid
        else:
            hi = mid
    return (lo, max(round(lo / aspect_ratio), 1))


# 来自"Claude 如何调整图像大小和填充"的 A4 示例：
print(resized_size(1075, 1520))  # (924, 1307)

将图像调整为 resized_size 返回的尺寸。如果图像已经符合模型的限制，resized_size 会原样返回其尺寸，无需调整大小。
将调整大小后的图像发送到 API。不要自行填充；Claude 会处理填充，且填充不会移动坐标原点。
在提示中明确要求返回像素坐标。例如："以像素坐标形式返回每个表格的边界框，格式为 [x1, y1, x2, y2]。"
直接将返回的坐标用于您发送的图像。如果您需要归一化坐标，请除以您发送的图像的尺寸，而不是原始图像的尺寸，也不是填充后的尺寸。

无法预先调整大小时重新缩放坐标

如果您无法预先调整大小（例如，图像来自您无法修改的上游系统），请使用上传前调整图像大小中的 resized_size 来恢复 Claude 所见的尺寸，然后将 Claude 返回的坐标映射为归一化坐标或映射回您的原始图像。此方法需要知道您上传的图像的像素尺寸，因此不适用于 PDF 上传。

def to_relative_coordinates(
    x: float,
    y: float,
    original_width: int,
    original_height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[float, float]:
    """Map a pixel coordinate returned by Claude to relative coordinates in [0, 1].

    Pass the dimensions of the image you uploaded. For high-resolution-tier
    models, use max_edge=2576 and max_tokens=4784.
    """
    resized_w, resized_h = resized_size(
        original_width, original_height, max_edge, max_tokens
    )
    return (x / resized_w, y / resized_h)


# 要在原始图像的像素空间中表示该坐标，请将
# 相对坐标乘以原始尺寸：
# (rel_x * original_width, rel_y * original_height)

填充仅应用于底部和右侧边缘，因此原点不会移动，按轴进行线性重新缩放即可。

坐标与边界框

Claude 如何调整图像大小，以及如何处理其返回的用于边界框、点和 UI 元素的像素坐标。

Claude 如何调整图像大小和填充

Claude 会找到同时满足模型两项图像限制的最大保持宽高比的尺寸：

**边长限制：**任一边都不超过最大边长（标准层级为 1568 px，高分辨率层级为 2576 px）。
**视觉令牌限制：**图像的令牌成本 ⌈width / 28⌉ × ⌈height / 28⌉ 不超过模型的视觉令牌预算（标准层级为 1568 个令牌，高分辨率层级为 4784 个令牌）。

有关各模型所属层级的信息，请参阅分辨率与令牌成本。

上传前调整图像大小

最可靠的方法是在上传前自行调整图像大小，这样您手中的图像就与 Claude 所见的图像完全一致，Claude 返回的坐标无需任何转换。

以下参考实现计算 Claude 将图像调整到的确切尺寸：

import math


def count_image_tokens(width: int, height: int) -> int:
    """Visual tokens consumed by an image: one token per 28x28 pixel patch."""
    return math.ceil(width / 28) * math.ceil(height / 28)


def resized_size(
    width: int,
    height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[int, int]:
    """The size Claude resizes an image to before padding.

    Defaults are for the standard resolution tier. For high-resolution-tier
    models, use max_edge=2576 and max_tokens=4784. Returns (width, height).
    Images that already fit within the limits are returned unchanged.
    """

    def fits(w: int, h: int) -> bool:
        return (
            math.ceil(w / 28) * 28 <= max_edge
            and math.ceil(h / 28) * 28 <= max_edge
            and count_image_tokens(w, h) <= max_tokens
        )

    if fits(width, height):
        return (width, height)
    if height > width:
        resized_h, resized_w = resized_size(height, width, max_edge, max_tokens)
        return (resized_w, resized_h)

    # 沿长边进行二分查找，找出保持宽高比且能容纳的最大尺寸。
    # 
    aspect_ratio = width / height
    lo, hi = 1, width  # lo always fits; hi never fits
    while lo + 1 < hi:
        mid = (lo + hi) // 2
        if fits(mid, max(round(mid / aspect_ratio), 1)):
            lo = mid
        else:
            hi = mid
    return (lo, max(round(lo / aspect_ratio), 1))


# 来自"Claude 如何调整图像大小和填充"的 A4 示例：
print(resized_size(1075, 1520))  # (924, 1307)

将图像调整为 resized_size 返回的尺寸。如果图像已经符合模型的限制，resized_size 会原样返回其尺寸，无需调整大小。
将调整大小后的图像发送到 API。不要自行填充；Claude 会处理填充，且填充不会移动坐标原点。
在提示中明确要求返回像素坐标。例如："以像素坐标形式返回每个表格的边界框，格式为 [x1, y1, x2, y2]。"
直接将返回的坐标用于您发送的图像。如果您需要归一化坐标，请除以您发送的图像的尺寸，而不是原始图像的尺寸，也不是填充后的尺寸。

无法预先调整大小时重新缩放坐标

def to_relative_coordinates(
    x: float,
    y: float,
    original_width: int,
    original_height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[float, float]:
    """Map a pixel coordinate returned by Claude to relative coordinates in [0, 1].

    Pass the dimensions of the image you uploaded. For high-resolution-tier
    models, use max_edge=2576 and max_tokens=4784.
    """
    resized_w, resized_h = resized_size(
        original_width, original_height, max_edge, max_tokens
    )
    return (x / resized_w, y / resized_h)


# 要在原始图像的像素空间中表示该坐标，请将
# 相对坐标乘以原始尺寸：
# (rel_x * original_width, rel_y * original_height)

填充仅应用于底部和右侧边缘，因此原点不会移动，按轴进行线性重新缩放即可。

坐标与边界框

Claude 如何调整图像大小和填充

上传前调整图像大小

无法预先调整大小时重新缩放坐标

相关内容

坐标与边界框

Claude 如何调整图像大小和填充

上传前调整图像大小

无法预先调整大小时重新缩放坐标

相关内容

Claude 如何调整图像大小和填充

上传前调整图像大小

无法预先调整大小时重新缩放坐标

相关内容

Claude 如何调整图像大小和填充

上传前调整图像大小

无法预先调整大小时重新缩放坐标

相关内容

Claude 如何调整图像大小和填充

上传前调整图像大小

无法预先调整大小时重新缩放坐标

相关内容

Claude 如何调整图像大小和填充

上传前调整图像大小

无法预先调整大小时重新缩放坐标

相关内容