Coordenadas e bounding boxes

Claude pode localizar e rotular regiões de uma imagem (por exemplo, retornando "bounding boxes" (caixas delimitadoras) para tabelas, campos de formulário, elementos de gráficos ou componentes de UI). Este guia cobre como Claude redimensiona imagens antes de processá-las e como trabalhar com as coordenadas de pixel que ele retorna, para que caixas e pontos fiquem alinhados com sua imagem original.

Você precisará disso para pipelines de OCR, extração de formulários, análise de gráficos, localização de elementos de UI e qualquer tarefa em que você atue sobre uma região específica de uma imagem. Para envio de imagens, formatos suportados e limites de resolução por modelo, consulte Visão.

As coordenadas seguem a convenção padrão de imagens: a origem (0, 0) é o canto superior esquerdo da imagem, com x aumentando para a direita e y aumentando para baixo. As coordenadas que Claude retorna são posições de pixel na imagem que Claude vê: sua imagem depois que Claude a redimensiona para caber na resolução nativa do modelo (consulte Como Claude redimensiona e preenche imagens). Para obter coordenadas que você possa usar diretamente, redimensione previamente sua imagem para que as coordenadas correspondam um a um à imagem que você tem (consulte Redimensione sua imagem antes de fazer upload), ou reescale as coordenadas que Claude retorna (consulte Reescale coordenadas quando não puder redimensionar previamente).



Como Claude redimensiona e preenche imagens

Claude encontra o maior tamanho que preserva a proporção e satisfaz ambos os limites de imagem do modelo:

1. Limite de borda: nenhum lado excede o comprimento máximo de borda (1568 px no nível padrão, 2576 px no nível de alta resolução).
2. Limite de tokens visuais: o custo em tokens da imagem ⌈width / 28⌉ × ⌈height / 28⌉ não excede o orçamento de tokens visuais do modelo (1568 tokens no nível padrão, 4784 no nível de alta resolução).

Consulte Resolução e custo de tokens para saber quais modelos estão em qual nível.

Para quase todas as fotos e capturas de tela, o limite de tokens visuais é o que determina o tamanho final. O limite de borda assume o controle apenas para imagens alongadas, como panoramas ou capturas de tela altas de celular. Calcule o tamanho com a implementação de referência em vez de escalar para o comprimento de borda manualmente: uma captura de tela de 1920×1080 é redimensionada para 1456×819, não 1568×882, e assumir o limite de borda deixa cada coordenada visivelmente fora do alvo.

O limite de tokens também pode acionar um redimensionamento quando nenhum dos lados excede o limite de borda. Ignorar isso é a causa mais comum de coordenadas desalinhadas. Por exemplo, uma página A4 digitalizada a 130 DPI tem 1075×1520 pixels: ambos os lados estão abaixo de 1568 px, mas ela custa 39 × 55 = 2145 tokens visuais, então Claude a redimensiona para 924×1307.

Claude então preenche toda imagem, redimensionada ou não, até o próximo múltiplo de 28 pixels nas bordas inferior e direita (924×1307 se torna 924×1316 no exemplo). O preenchimento não contém conteúdo: Claude percebe a imagem preenchida, mas o conteúdo da página só ocupa a região redimensionada sem preenchimento. Sempre normalize ou reescale pelas dimensões redimensionadas, não pelas dimensões preenchidas; dividir pelas dimensões preenchidas escala cada coordenada por uma pequena quantidade.



Redimensione sua imagem antes de fazer upload

A abordagem mais confiável é redimensionar sua imagem você mesmo antes de fazer upload, para que a imagem que você tem seja exatamente a imagem que Claude vê e as coordenadas que Claude retorna não precisem de conversão.

Primeiro verifique em qual nível de resolução seu modelo está (consulte Resolução e custo de tokens) e passe os limites de borda e de tokens correspondentes. A seguinte implementação de referência calcula o tamanho exato para o qual Claude redimensiona uma imagem:

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)

    # Busca binária ao longo da borda maior pelo maior tamanho que preserva
    # a proporção e cabe no limite.
    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))


# O exemplo A4 de "Como o Claude redimensiona e preenche imagens":
print(resized_size(1075, 1520))  # (924, 1307)

# Para aplicar o redimensionamento, use sua biblioteca de imagens, por exemplo Pillow:
# image.resize(resized_size(*image.size))

1. Redimensione a imagem para as dimensões retornadas pelo helper de redimensionamento. Se a imagem já couber dentro dos limites do modelo, o helper retorna suas dimensões inalteradas e nenhum redimensionamento é necessário.
2. Envie a imagem redimensionada para a API. Não a preencha você mesmo. Claude cuida do preenchimento, e o preenchimento não desloca a origem das coordenadas.
3. No seu prompt, peça explicitamente por coordenadas de pixel. Por exemplo: "Retorne o ponto de clique do botão Enviar como [x, y] em coordenadas de pixel."
4. Use as coordenadas retornadas diretamente na imagem que você enviou. Se precisar de coordenadas normalizadas, divida pelas dimensões da imagem que você enviou, não pelas dimensões da imagem original e não pelas dimensões preenchidas.



Reescale coordenadas quando não puder redimensionar previamente

Se você não puder redimensionar previamente (por exemplo, quando a imagem vem de um sistema upstream que você não pode modificar), use o helper de redimensionamento de Redimensione sua imagem antes de fazer upload para recuperar as dimensões que Claude viu, e então mapeie as coordenadas que Claude retorna para coordenadas normalizadas ou de volta para sua imagem original. Claude redimensiona imagens grandes demais em vez de rejeitá-las, até os limites de requisição da API. Além desses limites, a requisição falha com um erro de validação. Passe os limites do nível que correspondem ao modelo que você chamou: os limites do nível errado recuperam as dimensões redimensionadas erradas e deslocam silenciosamente cada coordenada. Essa abordagem requer conhecer as dimensões em pixels da imagem que você enviou, então ela não se aplica a uploads de PDF.

# Este helper chama resized_size do exemplo de redimensionamento nesta página.
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)


# Um canto de tabela que o Claude retorna em (462, 653.5) na página A4 redimensionada
# é mapeado de volta para o original 1075x1520 assim:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

O preenchimento é aplicado apenas às bordas inferior e direita, então a origem não se desloca e um reescalonamento linear por eixo é suficiente. Limite (clamp) as coordenadas retornadas às dimensões redimensionadas antes de reescalar, para que um ponto ligeiramente fora da imagem não possa ser mapeado para fora da sua original.

As coordenadas relativas se multiplicam contra qualquer superfície sobre a qual você atue: a imagem original, uma digitalização em resolução completa ou uma tela. Quando você atua sobre uma tela e os pixels da captura de tela diferem das coordenadas lógicas (displays HiDPI), divida também pelo fator de escala do display. A orientação de escalonamento da ferramenta de uso do computador cobre esse padrão.



Próximos passos