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 correctement sur votre image d'origine.

Vous en aurez besoin pour les pipelines 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 complète les images). Pour obtenir des coordonnées directement utilisables, soit vous pré-redimensionnez votre image afin que les coordonnées correspondent exactement à l'image dont vous disposez (voir Redimensionner votre image avant de la téléverser), soit vous remettez à l'échelle les coordonnées que Claude renvoie (voir Remettre à l'échelle les coordonnées lorsque vous ne pouvez pas pré-redimensionner).



Comment Claude redimensionne et complète 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 au niveau standard, 2576 px au niveau 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 au niveau standard, 4784 au niveau haute résolution).

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

Pour la plupart des photos et captures d'écran, c'est la limite de bord qui déclenche un redimensionnement. Pour les documents en orientation portrait, la limite de tokens visuels se déclenche généralement en premier, et l'ignorer est la cause la plus fréquente 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 à 924×1307.

Claude complète 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 complétée, mais le contenu de la page n'occupe jamais que la région redimensionnée non complétée. Normalisez ou remettez toujours à l'échelle en fonction des dimensions redimensionnées, et non des dimensions complétées ; diviser par les dimensions complétées décale chaque coordonnée d'une petite quantité.



Redimensionner 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, afin que l'image dont vous disposez soit exactement celle que Claude voit et que les coordonnées renvoyées par Claude ne nécessitent aucune conversion.

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 côté long pour la plus grande taille préservant
    # le ratio d'aspect qui tient.
    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 de « Comment Claude redimensionne et complète les images » :
print(resized_size(1075, 1520))  # (924, 1307)

1. Redimensionnez l'image aux dimensions renvoyées par resized_size. Si l'image tient déjà dans les limites du modèle, resized_size renvoie ses dimensions inchangées et aucun redimensionnement n'est nécessaire.
2. Envoyez l'image redimensionnée à l'API. Ne la complétez pas vous-même ; Claude gère le remplissage, et celui-ci ne décale pas l'origine des coordonnées.
3. Dans votre prompt, demandez explicitement des coordonnées en pixels. Par exemple : « Renvoie la boîte englobante de chaque tableau sous la forme [x1, y1, x2, y2] 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, et non par les dimensions de l'image d'origine ni par les dimensions complétées.



Remettre à 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 resized_size de la section Redimensionner votre image avant de la téléverser pour retrouver les dimensions que Claude a vues, puis mappez les coordonnées renvoyées par Claude en coordonnées normalisées ou sur votre image d'origine. 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.

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)


# Pour exprimer la coordonnée dans l'espace de pixels de votre image d'origine, multipliez la
# coordonnée relative par vos dimensions d'origine :
# (rel_x * largeur_originale, rel_y * hauteur_originale)

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 est suffisante.



Voir aussi

• L'outil Computer use exige que les captures d'écran tiennent déjà dans les limites de taille d'image (les captures d'écran trop grandes sont rejetées, pas redimensionnées) ; consultez ses recommandations de mise à l'échelle pour le modèle de redimensionnement côté client et de mise à l'échelle des coordonnées.
• Prise en charge des PDF : les pages sont rastérisées côté serveur à des dimensions que vous ne contrôlez pas, donc rastérisez vous-même les pages et utilisez l'approche de pré-redimensionnement lorsque vous avez besoin de coordonnées sur du contenu PDF.