Coordinate e bounding box

Claude può individuare ed etichettare regioni di un'immagine (ad esempio, restituendo bounding box per tabelle, campi di moduli, elementi di grafici o componenti dell'interfaccia utente). Questa guida spiega come Claude ridimensiona le immagini prima di elaborarle e come lavorare con le coordinate in pixel che restituisce, in modo che box e punti siano allineati con la tua immagine originale.

Ne avrai bisogno per pipeline OCR, estrazione di moduli, analisi di grafici, individuazione di elementi dell'interfaccia utente e qualsiasi attività in cui agisci su una regione specifica di un'immagine. Per l'invio di immagini, i formati supportati e i limiti di risoluzione per modello, consulta Visione.

Le coordinate seguono la convenzione standard delle immagini: l'origine (0, 0) è l'angolo in alto a sinistra dell'immagine, con x che aumenta verso destra e y che aumenta verso il basso. Le coordinate che Claude restituisce sono posizioni in pixel nell'immagine che Claude vede: la tua immagine dopo che Claude l'ha ridimensionata per adattarla alla risoluzione nativa del modello (consulta Come Claude ridimensiona e aggiunge padding alle immagini). Per ottenere coordinate che puoi usare direttamente, puoi pre-ridimensionare la tua immagine in modo che le coordinate corrispondano una a una all'immagine che hai (consulta Ridimensiona la tua immagine prima del caricamento), oppure riscalare le coordinate che Claude restituisce (consulta Riscala le coordinate quando non puoi pre-ridimensionare).



Come Claude ridimensiona e aggiunge padding alle immagini

Claude trova la dimensione più grande che preserva le proporzioni e che soddisfa entrambi i limiti di immagine del modello:

1. Limite del lato: nessun lato supera la lunghezza massima del lato (1568 px nel livello standard, 2576 px nel livello ad alta risoluzione).
2. Limite di token visivi: il costo in token dell'immagine ⌈width / 28⌉ × ⌈height / 28⌉ non supera il budget di token visivi del modello (1568 token nel livello standard, 4784 nel livello ad alta risoluzione).

Consulta Risoluzione e costo in token per sapere quali modelli appartengono a quale livello.

Per quasi tutte le foto e gli screenshot, è il limite di token visivi a determinare la dimensione finale. Il limite del lato prevale solo per immagini allungate come panorami o screenshot verticali di telefoni. Calcola la dimensione con l'implementazione di riferimento invece di scalare manualmente alla lunghezza del lato: uno screenshot 1920×1080 viene ridimensionato a 1456×819, non a 1568×882, e assumere il limite del lato sposta ogni coordinata sensibilmente fuori bersaglio.

Il limite di token può anche attivare un ridimensionamento quando nessun lato supera il limite del lato. Trascurare questo aspetto è la causa più comune di coordinate disallineate. Ad esempio, una pagina A4 scansionata a 130 DPI è di 1075×1520 pixel: entrambi i lati sono sotto i 1568 px, ma costa 39 × 55 = 2145 token visivi, quindi Claude la ridimensiona a 924×1307.

Claude poi aggiunge padding a ogni immagine, ridimensionata o meno, fino al successivo multiplo di 28 pixel sui bordi inferiore e destro (924×1307 diventa 924×1316 nell'esempio). Il padding non contiene alcun contenuto: Claude percepisce l'immagine con padding, ma il contenuto della pagina occupa sempre e solo la regione ridimensionata senza padding. Normalizza o riscala sempre in base alle dimensioni ridimensionate, non alle dimensioni con padding; dividere per le dimensioni con padding scala ogni coordinata di una piccola quantità.



Ridimensiona la tua immagine prima del caricamento

L'approccio più affidabile è ridimensionare tu stesso la tua immagine prima del caricamento, in modo che l'immagine che hai sia esattamente l'immagine che Claude vede e le coordinate che Claude restituisce non richiedano alcuna conversione.

Verifica prima a quale livello di risoluzione appartiene il tuo modello (consulta Risoluzione e costo in token) e passa i limiti di lato e di token corrispondenti. La seguente implementazione di riferimento calcola la dimensione esatta a cui Claude ridimensiona un'immagine:

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)

    # Ricerca binaria lungo il lato maggiore per la dimensione più grande che
    # preserva le proporzioni e rientra nei limiti.
    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'esempio A4 da "Come Claude ridimensiona e riempie le immagini":
print(resized_size(1075, 1520))  # (924, 1307)

# Per applicare il ridimensionamento, usa la tua libreria di immagini, ad esempio Pillow:
# image.resize(resized_size(*image.size))

1. Ridimensiona l'immagine alle dimensioni restituite dall'helper di ridimensionamento. Se l'immagine rientra già nei limiti del modello, l'helper restituisce le sue dimensioni invariate e non è necessario alcun ridimensionamento.
2. Invia l'immagine ridimensionata all'API. Non aggiungere il padding tu stesso. Claude gestisce il padding, e il padding non sposta l'origine delle coordinate.
3. Nel tuo prompt, chiedi esplicitamente coordinate in pixel. Ad esempio: "Restituisci il punto di clic per il pulsante Invia come [x, y] in coordinate in pixel."
4. Usa le coordinate restituite direttamente sull'immagine che hai inviato. Se hai bisogno di coordinate normalizzate, dividi per le dimensioni dell'immagine che hai inviato, non per le dimensioni dell'immagine originale né per le dimensioni con padding.



Riscala le coordinate quando non puoi pre-ridimensionare

Se non puoi pre-ridimensionare (ad esempio, quando l'immagine proviene da un sistema a monte che non puoi modificare), usa l'helper di ridimensionamento di Ridimensiona la tua immagine prima del caricamento per recuperare le dimensioni che Claude ha visto, quindi mappa le coordinate che Claude restituisce in coordinate normalizzate o di nuovo sulla tua immagine originale. Claude ridimensiona le immagini troppo grandi invece di rifiutarle, fino ai limiti di richiesta dell'API. Oltre tali limiti la richiesta fallisce invece con un errore di validazione. Passa i limiti del livello corrispondenti al modello che hai chiamato: i limiti del livello sbagliato recuperano dimensioni ridimensionate errate e spostano silenziosamente ogni coordinata. Questo approccio richiede di conoscere le dimensioni in pixel dell'immagine che hai caricato, quindi non si applica ai caricamenti di PDF.

# Questo helper chiama resized_size dall'esempio di ridimensionamento in questa pagina.
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 angolo di tabella che Claude restituisce a (462, 653.5) sulla pagina A4 ridimensionata
# si mappa sull'originale 1075x1520 così:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

Il padding viene applicato solo ai bordi inferiore e destro, quindi l'origine non si sposta e una riscalatura lineare per asse è sufficiente. Limita (clamp) le coordinate restituite alle dimensioni ridimensionate prima di riscalare, in modo che un punto leggermente al di fuori dell'immagine non possa essere mappato al di fuori della tua immagine originale.

Le coordinate relative si moltiplicano per qualsiasi superficie su cui agisci: l'immagine originale, una scansione a piena risoluzione o uno schermo. Quando agisci su uno schermo e i pixel dello screenshot differiscono dalle coordinate logiche (display HiDPI), dividi anche per il fattore di scala del display. Le indicazioni sulla scalatura dello strumento per l'uso del computer trattano questo schema.



Prossimi passi