Coordenadas e bounding boxes

O 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 aborda como o Claude redimensiona imagens antes de processá-las e como trabalhar com as coordenadas de pixel que ele retorna, para que as caixas e pontos se alinhem 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 o Claude retorna são posições de pixel na imagem que o Claude vê: sua imagem depois que o Claude a redimensiona para se ajustar à resolução nativa do modelo (consulte Como o Claude redimensiona e preenche imagens). Para obter coordenadas que você possa usar diretamente, pré-redimensione sua imagem para que as coordenadas mapeiem um-para-um na imagem que você tem (consulte Redimensione sua imagem antes de fazer upload), ou reescale as coordenadas que o Claude retorna (consulte Reescale coordenadas quando não for possível pré-redimensionar).



Como o Claude redimensiona e preenche imagens

O Claude encontra o maior tamanho que preserva a proporção e que 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 a maioria das fotos e capturas de tela, o limite de borda é o que aciona um redimensionamento. Para documentos em formato retrato, o limite de tokens visuais geralmente é acionado primeiro, e ignorá-lo é 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 o Claude a redimensiona para 924×1307.

O Claude então preenche cada 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: o Claude percebe a imagem preenchida, mas o conteúdo da página ocupa apenas 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 desloca 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 o Claude vê e as coordenadas que o Claude retorna não precisem de conversão.

A implementação de referência a seguir calcula o tamanho exato para o qual o 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 para o maior tamanho que preserva
    # a proporção e ainda cabe.
    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)

1. Redimensione a imagem para as dimensões retornadas por resized_size. Se a imagem já couber dentro dos limites do modelo, resized_size retorna suas dimensões inalteradas e nenhum redimensionamento é necessário.
2. Envie a imagem redimensionada para a API. Não a preencha você mesmo; o Claude cuida do preenchimento, e o preenchimento não desloca a origem das coordenadas.
3. No seu prompt, peça explicitamente coordenadas de pixel. Por exemplo: "Retorne a bounding box de cada tabela como [x1, y1, x2, y2] 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 for possível pré-redimensionar

Se você não puder pré-redimensionar (por exemplo, quando a imagem vem de um sistema upstream que você não pode modificar), use resized_size de Redimensione sua imagem antes de fazer upload para recuperar as dimensões que o Claude viu, e então mapeie as coordenadas que o Claude retorna para coordenadas normalizadas ou de volta para sua imagem original. Essa abordagem requer conhecer as dimensões em pixels da imagem que você enviou, portanto não se aplica a uploads de 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)


# Para expressar a coordenada no espaço de pixels da sua imagem original, multiplique a
# coordenada relativa pelas dimensões originais:
# (rel_x * original_width, rel_y * original_height)

O preenchimento é aplicado apenas às bordas inferior e direita, então a origem não se desloca e um reescalonamento linear por eixo é suficiente.



Relacionados

• A ferramenta de uso de computador exige que as capturas de tela já caibam dentro dos limites de tamanho de imagem (capturas de tela muito grandes são rejeitadas, não redimensionadas); consulte suas orientações de escalonamento para o padrão de redimensionamento no lado do cliente e escalonamento de coordenadas.
• Suporte a PDF: as páginas são rasterizadas no lado do servidor em dimensões que você não controla, então rasterize as páginas você mesmo e use a abordagem de pré-redimensionamento quando precisar de coordenadas em conteúdo de PDF.