Coordonnées et boîtes englobantes

Claude peut localiser et étiqueter des régions d'une image (par exemple, renvoyer des « bounding boxes » (boîtes englobantes) pour des tableaux, des champs de formulaire, des éléments de graphique ou des composants d'interface utilisateur). Ce guide explique comment Claude redimensionne les images avant de les traiter et comment travailler avec les coordonnées en pixels qu'il renvoie, afin que les boîtes et les points s'alignent avec votre image d'origine.

Vous en aurez besoin pour les pipelines d'OCR, l'extraction de formulaires, l'analyse de graphiques, la localisation d'éléments d'interface utilisateur, et toute tâche où vous agissez sur une région spécifique d'une image. Pour l'envoi d'images, les formats pris en charge et les limites de résolution par modèle, consultez Vision.

Les coordonnées suivent la convention standard des images : l'origine (0, 0) est le coin supérieur gauche de l'image, avec x croissant vers la droite et y croissant vers le bas. Les coordonnées que Claude renvoie sont des positions en pixels dans l'image que Claude voit : votre image après que Claude l'a redimensionnée pour correspondre à la résolution native du modèle (voir Comment Claude redimensionne et remplit les images). Pour obtenir des coordonnées que vous pouvez utiliser directement, soit pré-redimensionnez votre image afin que les coordonnées correspondent une à une à l'image que vous avez (voir Redimensionnez votre image avant de la téléverser), soit remettez à l'échelle les coordonnées que Claude renvoie (voir Remettez à l'échelle les coordonnées lorsque vous ne pouvez pas pré-redimensionner).



Comment Claude redimensionne et remplit les images

Claude trouve la plus grande taille préservant le rapport d'aspect qui satisfait les deux limites d'image du modèle :

1. Limite de bord : aucun côté ne dépasse la longueur de bord maximale (1568 px sur le palier standard, 2576 px sur le palier haute résolution).
2. Limite de tokens visuels : le coût en tokens de l'image ⌈width / 28⌉ × ⌈height / 28⌉ ne dépasse pas le budget de tokens visuels du modèle (1568 tokens sur le palier standard, 4784 sur le palier haute résolution).

Consultez Résolution et coût en tokens pour savoir quels modèles appartiennent à quel palier.

Pour presque toutes les photos et captures d'écran, c'est la limite de tokens visuels qui détermine la taille finale. La limite de bord ne prend le relais que pour les images allongées telles que les panoramas ou les captures d'écran de téléphone en hauteur. Calculez la taille avec l'implémentation de référence plutôt que de mettre à l'échelle manuellement vers la longueur de bord : une capture d'écran de 1920×1080 est redimensionnée en 1456×819, et non en 1568×882, et supposer la limite de bord décale sensiblement chaque coordonnée par rapport à sa cible.

La limite de tokens peut également déclencher un redimensionnement lorsqu'aucun côté ne dépasse la limite de bord. Négliger ce point est la cause la plus courante de coordonnées mal alignées. Par exemple, une page A4 numérisée à 130 DPI fait 1075×1520 pixels : les deux côtés sont inférieurs à 1568 px, mais elle coûte 39 × 55 = 2145 tokens visuels, donc Claude la redimensionne en 924×1307.

Claude remplit ensuite chaque image, redimensionnée ou non, jusqu'au multiple de 28 pixels suivant sur les bords inférieur et droit (924×1307 devient 924×1316 dans l'exemple). Le remplissage ne contient aucun contenu : Claude perçoit l'image remplie, mais le contenu de la page n'occupe jamais que la région redimensionnée non remplie. Normalisez ou remettez toujours à l'échelle en utilisant les dimensions redimensionnées, pas les dimensions remplies ; diviser par les dimensions remplies met à l'échelle chaque coordonnée d'une petite quantité.



Redimensionnez votre image avant de la téléverser

L'approche la plus fiable consiste à redimensionner vous-même votre image avant de la téléverser, de sorte que l'image que vous avez soit exactement l'image que Claude voit et que les coordonnées que Claude renvoie ne nécessitent aucune conversion.

Vérifiez d'abord sur quel palier de résolution se trouve votre modèle (voir Résolution et coût en tokens) et passez les limites de bord et de tokens correspondantes. L'implémentation de référence suivante calcule la taille exacte à laquelle Claude redimensionne une image :

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)

    # Recherche binaire sur le grand côté pour trouver la plus grande taille
    # préservant le ratio qui tient dans les limites.
    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))


# L'exemple A4 tiré de « Comment Claude redimensionne et remplit les images » :
print(resized_size(1075, 1520))  # (924, 1307)

# Pour appliquer le redimensionnement, utilisez votre bibliothèque d'images, par exemple Pillow :
# image.resize(resized_size(*image.size))

1. Redimensionnez l'image aux dimensions renvoyées par l'assistant de redimensionnement. Si l'image tient déjà dans les limites du modèle, l'assistant renvoie ses dimensions inchangées et aucun redimensionnement n'est nécessaire.
2. Envoyez l'image redimensionnée à l'API. Ne la remplissez pas vous-même. Claude gère le remplissage, et le remplissage ne décale pas l'origine des coordonnées.
3. Dans votre prompt, demandez explicitement des coordonnées en pixels. Par exemple : « Renvoie le point de clic pour le bouton Soumettre sous la forme [x, y] en coordonnées de pixels. »
4. Utilisez les coordonnées renvoyées directement sur l'image que vous avez envoyée. Si vous avez besoin de coordonnées normalisées, divisez par les dimensions de l'image que vous avez envoyée, pas par les dimensions de l'image d'origine ni par les dimensions remplies.



Remettez à l'échelle les coordonnées lorsque vous ne pouvez pas pré-redimensionner

Si vous ne pouvez pas pré-redimensionner (par exemple, lorsque l'image provient d'un système en amont que vous ne pouvez pas modifier), utilisez l'assistant de redimensionnement de Redimensionnez votre image avant de la téléverser pour retrouver les dimensions que Claude a vues, puis convertissez les coordonnées que Claude renvoie en coordonnées normalisées ou reportez-les sur votre image d'origine. Claude redimensionne les images surdimensionnées plutôt que de les rejeter, jusqu'aux limites de requête de l'API. Au-delà de ces limites, la requête échoue avec une erreur de validation. Passez les limites du palier correspondant au modèle que vous avez appelé : les limites du mauvais palier retrouvent les mauvaises dimensions redimensionnées et décalent silencieusement chaque coordonnée. Cette approche nécessite de connaître les dimensions en pixels de l'image que vous avez téléversée, elle ne s'applique donc pas aux téléversements de PDF.

# Cette fonction appelle resized_size de l'exemple de redimensionnement sur cette page.
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)


# Un coin de tableau que Claude renvoie en (462, 653.5) sur la page A4 redimensionnée
# se reporte sur l'original 1075x1520 comme suit :
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

Le remplissage n'est appliqué qu'aux bords inférieur et droit, donc l'origine ne se décale pas et une remise à l'échelle linéaire par axe suffit. Bornez les coordonnées renvoyées aux dimensions redimensionnées avant la remise à l'échelle, afin qu'un point légèrement en dehors de l'image ne puisse pas être reporté en dehors de votre original.

Les coordonnées relatives se multiplient par la surface sur laquelle vous agissez : l'image d'origine, une numérisation en pleine résolution ou un écran. Lorsque vous agissez sur un écran et que les pixels de la capture d'écran diffèrent des coordonnées logiques (écrans HiDPI), divisez également par le facteur d'échelle de l'affichage. Les conseils de mise à l'échelle de l'outil d'utilisation de l'ordinateur couvrent ce schéma.



Prochaines étapes