좌표와 바운딩 박스

Claude는 이미지의 영역을 찾아 레이블을 지정할 수 있습니다(예: 표, 양식 필드, 차트 요소 또는 UI 컴포넌트에 대한 바운딩 박스 반환). 이 가이드는 Claude가 이미지를 처리하기 전에 어떻게 리사이즈하는지, 그리고 반환된 픽셀 좌표를 다루는 방법을 설명하여 박스와 포인트가 원본 이미지와 정확히 일치하도록 돕습니다.

OCR 파이프라인, 양식 추출, 차트 파싱, UI 요소 위치 파악, 그리고 이미지의 특정 영역에 대해 작업을 수행하는 모든 태스크에 이 내용이 필요합니다. 이미지 전송, 지원되는 형식, 모델별 해상도 제한에 대해서는 Vision을 참조하세요.

좌표는 표준 이미지 규칙을 따릅니다. 원점 (0, 0)은 이미지의 왼쪽 상단 모서리이며, x는 오른쪽으로 갈수록 증가하고 y는 아래로 갈수록 증가합니다. Claude가 반환하는 좌표는 Claude가 보는 이미지, 즉 모델의 기본 해상도에 맞게 Claude가 리사이즈한 이미지의 픽셀 위치입니다(Claude가 이미지를 리사이즈하고 패딩하는 방식 참조). 직접 사용할 수 있는 좌표를 얻으려면, 좌표가 보유한 이미지에 일대일로 매핑되도록 이미지를 미리 리사이즈하거나(업로드 전에 이미지 리사이즈하기 참조), Claude가 반환한 좌표를 재조정하세요(미리 리사이즈할 수 없을 때 좌표 재조정하기 참조).



Claude가 이미지를 리사이즈하고 패딩하는 방식

Claude는 모델의 두 가지 이미지 제한을 모두 만족하는, 종횡비를 유지하는 가장 큰 크기를 찾습니다.

1. 가장자리 제한: 어느 변도 최대 가장자리 길이를 초과하지 않습니다(표준 티어에서는 1568 px, 고해상도 티어에서는 2576 px).
2. 비주얼 토큰 제한: 이미지의 토큰 비용 ⌈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)

1. resized_size가 반환한 크기로 이미지를 리사이즈하세요. 이미지가 이미 모델의 제한 내에 있으면 resized_size는 크기를 변경하지 않고 그대로 반환하므로 리사이즈가 필요하지 않습니다.
2. 리사이즈된 이미지를 API로 전송하세요. 직접 패딩하지 마세요. Claude가 패딩을 처리하며, 패딩은 좌표 원점을 이동시키지 않습니다.
3. 프롬프트에서 픽셀 좌표를 명시적으로 요청하세요. 예: "각 표의 바운딩 박스를 픽셀 좌표로 [x1, y1, x2, y2] 형식으로 반환하세요."
4. 반환된 좌표를 전송한 이미지에 직접 사용하세요. 정규화된 좌표가 필요한 경우, 원본 이미지의 크기나 패딩된 크기가 아니라 전송한 이미지의 크기로 나누세요.



미리 리사이즈할 수 없을 때 좌표 재조정하기

미리 리사이즈할 수 없는 경우(예: 수정할 수 없는 업스트림 시스템에서 이미지가 제공되는 경우), 업로드 전에 이미지 리사이즈하기의 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)

패딩은 하단과 오른쪽 가장자리에만 적용되므로 원점이 이동하지 않으며, 축별 선형 재조정으로 충분합니다.



관련 항목

• 컴퓨터 사용 도구는 스크린샷이 이미 이미지 크기 제한 내에 있어야 합니다(크기를 초과한 스크린샷은 리사이즈되지 않고 거부됩니다). 클라이언트 측 리사이즈 및 좌표 스케일링 패턴에 대해서는 해당 스케일링 가이드를 참조하세요.
• PDF 지원: 페이지는 사용자가 제어할 수 없는 크기로 서버 측에서 래스터화되므로, PDF 콘텐츠에서 좌표가 필요한 경우 페이지를 직접 래스터화하고 사전 리사이즈 방식을 사용하세요.