좌표와 바운딩 박스

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

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

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



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

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

1. 가장자리 제한: 어느 쪽도 최대 가장자리 길이를 초과하지 않습니다(표준 티어에서 1568px, 고해상도 티어에서 2576px).
2. 비주얼 토큰 제한: 이미지의 토큰 비용 ⌈width / 28⌉ × ⌈height / 28⌉이 모델의 비주얼 토큰 예산을 초과하지 않습니다(표준 티어에서 1568 토큰, 고해상도 티어에서 4784 토큰).

어떤 모델이 어떤 티어에 속하는지는 해상도와 토큰 비용을 참조하세요.

거의 모든 사진과 스크린샷의 경우, 최종 크기를 결정하는 것은 비주얼 토큰 제한입니다. 가장자리 제한은 파노라마나 세로로 긴 휴대폰 스크린샷과 같이 길쭉한 이미지에서만 적용됩니다. 가장자리 길이에 맞춰 수동으로 스케일링하지 말고 참조 구현으로 크기를 계산하세요. 1920×1080 스크린샷은 1568×882가 아니라 1456×819로 리사이즈되며, 가장자리 제한을 가정하면 모든 좌표가 눈에 띄게 어긋납니다.

토큰 제한은 어느 쪽도 가장자리 제한을 초과하지 않을 때에도 리사이즈를 유발할 수 있습니다. 이를 간과하는 것이 좌표가 어긋나는 가장 흔한 원인입니다. 예를 들어, 130 DPI로 스캔한 A4 페이지는 1075×1520 픽셀입니다. 양쪽 모두 1568px 미만이지만 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))


# "How Claude resizes and pads images"의 A4 예제:
print(resized_size(1075, 1520))  # (924, 1307)

# 크기 조정을 적용하려면 Pillow 같은 이미지 라이브러리를 사용하세요:
# image.resize(resized_size(*image.size))

1. 리사이즈 헬퍼가 반환한 크기로 이미지를 리사이즈하세요. 이미지가 이미 모델의 제한 내에 있으면 헬퍼는 크기를 변경하지 않고 그대로 반환하며 리사이즈가 필요하지 않습니다.
2. 리사이즈된 이미지를 전송하여 API로 보내세요. 직접 패딩하지 마세요. Claude가 패딩을 처리하며, 패딩은 좌표 원점을 이동시키지 않습니다.
3. 프롬프트에서 픽셀 좌표를 명시적으로 요청하세요. 예: "Submit 버튼의 클릭 지점을 픽셀 좌표로 [x, y] 형식으로 반환하세요."
4. 반환된 좌표를 전송한 이미지에 대해 직접 사용하세요. 정규화된 좌표가 필요하면 원본 이미지의 크기나 패딩된 크기가 아니라 전송한 이미지의 크기로 나누세요.



미리 리사이즈할 수 없을 때 좌표 재스케일링하기

미리 리사이즈할 수 없는 경우(예: 수정할 수 없는 업스트림 시스템에서 이미지가 오는 경우), 업로드 전에 이미지 리사이즈하기의 리사이즈 헬퍼를 사용하여 Claude가 본 크기를 복원한 다음, Claude가 반환하는 좌표를 정규화된 좌표로 매핑하거나 원본 이미지에 다시 매핑하세요. Claude는 API의 요청 제한까지는 크기가 초과된 이미지를 거부하지 않고 리사이즈합니다. 해당 제한을 초과하면 요청은 유효성 검사 오류로 실패합니다. 호출한 모델에 맞는 티어 제한을 전달하세요. 잘못된 티어의 제한은 잘못된 리사이즈 크기를 복원하여 모든 좌표를 조용히 어긋나게 합니다. 이 방식은 업로드한 이미지의 픽셀 크기를 알아야 하므로 PDF 업로드에는 적용되지 않습니다.

# 이 헬퍼는 이 페이지의 크기 조정 예제에 있는 resized_size를 호출합니다.
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)


# 크기 조정된 A4 페이지에서 Claude가 (462, 653.5)로 반환한 표 모서리는
# 1075x1520 원본으로 다음과 같이 매핑됩니다:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

패딩은 하단과 오른쪽 가장자리에만 적용되므로 원점이 이동하지 않으며, 축별 선형 재스케일링으로 충분합니다. 재스케일링하기 전에 반환된 좌표를 리사이즈된 크기로 클램핑하여, 이미지를 약간 벗어난 포인트가 원본 밖으로 매핑되지 않도록 하세요.

상대 좌표는 작업 대상이 되는 어떤 표면에도 곱할 수 있습니다. 원본 이미지, 전체 해상도 스캔, 또는 화면 등입니다. 화면에서 작업하고 스크린샷 픽셀이 논리 좌표와 다른 경우(HiDPI 디스플레이), 디스플레이 스케일 팩터로도 나누세요. 컴퓨터 사용 도구의 스케일링 가이드에서 해당 패턴을 다룹니다.



다음 단계