Coordenadas y cuadros delimitadores

Claude puede localizar y etiquetar regiones de una imagen (por ejemplo, devolviendo "bounding boxes" (cuadros delimitadores) para tablas, campos de formularios, elementos de gráficos o componentes de UI). Esta guía cubre cómo Claude redimensiona las imágenes antes de procesarlas y cómo trabajar con las coordenadas de píxeles que devuelve, para 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 UI y cualquier tarea en la que actúes sobre una región específica de una imagen. Para el envío de imágenes, formatos compatibles y 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 imágenes). Para obtener coordenadas que puedas usar directamente, redimensiona previamente tu imagen para que las coordenadas se correspondan una a una 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 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 casi todas las fotos y capturas de pantalla, el límite de tokens visuales es lo que determina el tamaño final. El límite de borde solo entra en juego para imágenes alargadas como panorámicas o capturas de pantalla altas de teléfono. Calcula el tamaño con la implementación de referencia en lugar de escalar a la longitud del borde a mano: una captura de pantalla de 1920×1080 se redimensiona a 1456×819, no a 1568×882, y asumir el límite de borde desplaza notablemente cada coordenada de su objetivo.

El límite de tokens también puede provocar un redimensionamiento cuando ningún lado excede el límite de borde. Pasar esto por alto es la causa más común de coordenadas desalineadas. Por ejemplo, una página A4 escaneada a 130 DPI mide 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 por las dimensiones redimensionadas, no por 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 confiable 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.

Primero verifica en qué nivel de resolución está tu modelo (consulta Resolución y costo en tokens) y pasa los límites de borde y de tokens correspondientes. 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 el mayor tamaño que preserva
    # la relación de aspecto y 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))


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

# Para aplicar el redimensionamiento, usa tu biblioteca de imágenes, por ejemplo Pillow:
# image.resize(resized_size(*image.size))

1. Redimensiona la imagen a las dimensiones devueltas por el helper de redimensionamiento. Si la imagen ya se ajusta a los límites del modelo, el helper 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 punto de clic para el botón Enviar como [x, y] 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 anterior que no puedes modificar), usa el helper de redimensionamiento 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. Claude redimensiona las imágenes demasiado grandes en lugar de rechazarlas, hasta los límites de solicitud de la API. Más allá de esos límites, la solicitud falla con un error de validación. Pasa los límites del nivel que correspondan al modelo que llamaste: los límites del nivel incorrecto recuperan dimensiones redimensionadas incorrectas y desplazan silenciosamente cada coordenada. Este enfoque requiere conocer las dimensiones en píxeles de la imagen que subiste, por lo que no aplica a las cargas de PDF.

# Este helper llama a resized_size del ejemplo de redimensionamiento en esta 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)


# Una esquina de tabla que Claude devuelve en (462, 653.5) en la página A4 redimensionada
# se mapea de vuelta al original de 1075x1520 así:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

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. Limita (clamp) las coordenadas devueltas a las dimensiones redimensionadas antes de reescalar, para que un punto ligeramente fuera de la imagen no pueda mapearse fuera de tu original.

Las coordenadas relativas se multiplican contra cualquier superficie sobre la que actúes: la imagen original, un escaneo a resolución completa o una pantalla. Cuando actúes sobre una pantalla y los píxeles de la captura de pantalla difieran de las coordenadas lógicas (pantallas HiDPI), divide también por el factor de escala de la pantalla. La guía de escalado de la herramienta de uso de computadora cubre ese patrón.



Próximos pasos