Coordenadas y cuadros delimitadores

Claude puede localizar y etiquetar regiones de una imagen (por ejemplo, devolviendo "bounding boxes" (cuadros delimitadores) para tablas, campos de formulario, elementos de gráficos o componentes de interfaz de usuario). Esta guía explica cómo Claude redimensiona las imágenes antes de procesarlas y cómo trabajar con las coordenadas de píxeles que devuelve, de modo que los cuadros y puntos se alineen con tu imagen original.

Necesitarás esto para pipelines de OCR, extracción de formularios, análisis de gráficos, localización de elementos de interfaz de usuario y cualquier tarea en la que actúes sobre una región específica de una imagen. Para el envío de imágenes, los formatos compatibles y los límites de resolución por modelo, consulta Visión.

Las coordenadas siguen la convención estándar de imágenes: el origen (0, 0) es la esquina superior izquierda de la imagen, con x aumentando hacia la derecha e y aumentando hacia abajo. Las coordenadas que Claude devuelve son posiciones de píxeles en la imagen que Claude ve: tu imagen después de que Claude la redimensiona para ajustarse a la resolución nativa del modelo (consulta Cómo Claude redimensiona y rellena las imágenes). Para obtener coordenadas que puedas usar directamente, redimensiona previamente tu imagen para que las coordenadas se correspondan uno a uno con la imagen que tienes (consulta Redimensiona tu imagen antes de subirla), o reescala las coordenadas que Claude devuelve (consulta Reescala las coordenadas cuando no puedas redimensionar previamente).



Cómo Claude redimensiona y rellena las imágenes

Claude encuentra el tamaño más grande que preserva la relación de aspecto y que satisface ambos límites de imagen del modelo:

1. Límite de borde: ningún lado excede la longitud máxima de borde (1568 px en el nivel estándar, 2576 px en el nivel de alta resolución).
2. Límite de tokens visuales: el costo en tokens de la imagen ⌈width / 28⌉ × ⌈height / 28⌉ no excede el presupuesto de tokens visuales del modelo (1568 tokens en el nivel estándar, 4784 en el nivel de alta resolución).

Consulta Resolución y costo en tokens para saber qué modelos están en cada nivel.

Para la mayoría de las fotos y capturas de pantalla, el límite de borde es lo que desencadena un redimensionamiento. Para documentos en formato vertical, el límite de tokens visuales suele activarse primero, y pasarlo por alto es la causa más común de coordenadas desalineadas. Por ejemplo, una página A4 escaneada a 130 DPI tiene 1075×1520 píxeles: ambos lados están por debajo de 1568 px, pero cuesta 39 × 55 = 2145 tokens visuales, por lo que Claude la redimensiona a 924×1307.

Luego, Claude rellena cada imagen, redimensionada o no, hasta el siguiente múltiplo de 28 píxeles en los bordes inferior y derecho (924×1307 se convierte en 924×1316 en el ejemplo). El relleno no contiene contenido: Claude percibe la imagen rellenada, pero el contenido de la página solo ocupa la región redimensionada sin relleno. Normaliza o reescala siempre usando las dimensiones redimensionadas, no las dimensiones con relleno; dividir por las dimensiones con relleno escala cada coordenada por una pequeña cantidad.



Redimensiona tu imagen antes de subirla

El enfoque más fiable es redimensionar tu imagen tú mismo antes de subirla, de modo que la imagen que tienes sea exactamente la imagen que Claude ve y las coordenadas que Claude devuelve no necesiten conversión.

La siguiente implementación de referencia calcula el tamaño exacto al que Claude redimensiona una imagen:

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)

    # Búsqueda binaria a lo largo del borde largo para hallar el mayor tamaño
    # que conserve la relación de aspecto y quepa.
    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))


# El ejemplo A4 de "Cómo Claude redimensiona y rellena imágenes":
print(resized_size(1075, 1520))  # (924, 1307)

1. Redimensiona la imagen a las dimensiones devueltas por resized_size. Si la imagen ya cabe dentro de los límites del modelo, resized_size devuelve sus dimensiones sin cambios y no se necesita redimensionar.
2. Envía la imagen redimensionada a la API. No la rellenes tú mismo; Claude se encarga del relleno, y el relleno no desplaza el origen de coordenadas.
3. En tu prompt, pide explícitamente coordenadas de píxeles. Por ejemplo: "Devuelve el cuadro delimitador de cada tabla como [x1, y1, x2, y2] en coordenadas de píxeles."
4. Usa las coordenadas devueltas directamente sobre la imagen que enviaste. Si necesitas coordenadas normalizadas, divide por las dimensiones de la imagen que enviaste, no por las dimensiones de la imagen original ni por las dimensiones con relleno.



Reescala las coordenadas cuando no puedas redimensionar previamente

Si no puedes redimensionar previamente (por ejemplo, cuando la imagen proviene de un sistema externo que no puedes modificar), usa resized_size de Redimensiona tu imagen antes de subirla para recuperar las dimensiones que Claude vio, y luego mapea las coordenadas que Claude devuelve a coordenadas normalizadas o de vuelta a tu imagen original. Este enfoque requiere conocer las dimensiones en píxeles de la imagen que subiste, por lo que no aplica a cargas 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 expresar la coordenada en el espacio de píxeles de tu imagen original, multiplica la
# coordenada relativa por tus dimensiones originales:
# (rel_x * ancho_original, rel_y * alto_original)

El relleno se aplica solo a los bordes inferior y derecho, por lo que el origen no se desplaza y un reescalado lineal por eje es suficiente.



Relacionado

• La herramienta de uso de computadora requiere que las capturas de pantalla ya quepan dentro de los límites de tamaño de imagen (las capturas de pantalla demasiado grandes se rechazan, no se redimensionan); consulta su guía de escalado para el patrón de redimensionamiento y escalado de coordenadas del lado del cliente.
• Soporte de PDF: las páginas se rasterizan en el servidor con dimensiones que no controlas, así que rasteriza las páginas tú mismo y usa el enfoque de redimensionamiento previo cuando necesites coordenadas en contenido PDF.