Coordinate e bounding box

Claude può individuare ed etichettare regioni di un'immagine (ad esempio, restituendo "bounding box" (riquadri di delimitazione) 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 riquadri e punti si allineino con la tua immagine originale.

Ne avrai bisogno per pipeline OCR, estrazione di moduli, analisi di grafici, localizzazione 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 (vedi Come Claude ridimensiona e aggiunge padding alle immagini). Per ottenere coordinate che puoi usare direttamente, pre-ridimensiona la tua immagine in modo che le coordinate corrispondano uno a uno all'immagine che hai (vedi Ridimensiona la tua immagine prima del caricamento), oppure riscala le coordinate che Claude restituisce (vedi 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 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 alti 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 presumere 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 aggiunge poi "padding" (riempimento) 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 l'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.

Per prima cosa verifica a quale livello di risoluzione appartiene il tuo modello (vedi 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 massima 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 "How Claude resizes and pads images":
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 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 Submit 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 e non per le dimensioni con padding.

Trasforma il ridimensionamento in un errore con transformations

Il pre-ridimensionamento protegge le tue coordinate solo finché la tua pipeline continua a produrre le dimensioni corrette. Una nuova sorgente di immagini o il passaggio a un modello di un livello di risoluzione diverso può reintrodurre silenziosamente il ridimensionamento lato server. Per trasformare questa deriva silenziosa in un errore visibile, imposta il campo opzionale transformations su un blocco di contenuto immagine in una richiesta Messages:

{
  "type": "image",
  "source": { "type": "base64", "media_type": "image/png", "data": "..." },
  "transformations": { "oversized_image": "error" }
}

Una richiesta la cui immagine contrassegnata (qualsiasi blocco che imposta "oversized_image": "error") verrebbe ridimensionata viene rifiutata con un errore 400 invalid_request_error che indica le dimensioni dell'immagine e le dimensioni massime che rientrano nei limiti. Se un'immagine attiva il rifiuto dipende dai limiti di ogni modello indicato nella richiesta: l'esempio 1920×1080 qui sotto viene rifiutato da un modello del livello standard ma rientra nel livello ad alta risoluzione:

messages.0.content.0: image dimensions 1920x1080 exceed the maximum image size of a model named on this request and would be downsized to 1456x819; scale the image to at most 1456x819 or set the image's oversized_image setting to "downsize"

Riscala alla dimensione di destinazione indicata e invia di nuovo: la destinazione è la dimensione più grande, con le proporzioni della tua immagine, che ogni modello indicato nella richiesta accetta. Il modo in cui le immagini contrassegnate interagiscono con la beta del fallback lato server è descritto insieme a quella funzionalità; in ogni modalità, un'immagine contrassegnata non viene mai servita ridimensionata.

L'impostazione è per singola immagine. "oversized_image": "downsize" (il valore predefinito quando il campo è omesso) mantiene il ridimensionamento automatico come descritto in questa pagina. Ogni blocco immagine viene verificato solo rispetto alla propria impostazione, quindi una singola richiesta può combinare immagini le cui dimensioni sono determinanti (uno screenshot su cui farai clic) con immagini per cui il ridimensionamento è innocuo (un logo). Cosa cambia e cosa non cambia con questa impostazione:

• Il padding (che non scarta mai contenuto), la conversione di formato e la correzione dell'orientamento procedono come di consueto.
• I limiti rigidi (8000 px sul lato più lungo e il limite per immagine più restrittivo nelle richieste con molte immagini) sono rifiuti separati; questa impostazione non permette mai a un'immagine di superarli.
• Le immagini fornite tramite URL o ID file vengono verificate una volta recuperati i loro byte; questi rifiuti riportano lo stesso messaggio senza la posizione iniziale, quindi non identificano quale immagine ha fallito; solo le immagini base64 incorporate vengono indicate per posizione nell'errore.
• Le pagine PDF vengono rasterizzate lato server a dimensioni che non controlli; il blocco document non accetta il campo (un blocco immagine annidato nel contenuto di un documento lo accetta come qualsiasi altro).
• Un'immagine contrassegnata le cui dimensioni non possono essere determinate viene rifiutata anziché lasciata passare: quel rifiuto segnala che le dimensioni di origine dell'immagine non hanno potuto essere determinate, non il messaggio di ridimensionamento citato sopra. Nessuna immagine che imposta "error" raggiunge il modello ridimensionata.

Anche l'endpoint di conteggio dei token rispetta transformations, rifiutando un'immagine incorporata esattamente come farebbe la Messages API, così puoi verificare se un'immagine incorporata rientra nei limiti senza essere ridimensionata, prima di eseguire l'inferenza. Il conteggio rifiuta le immagini fornite tramite URL o ID file anziché recuperarle, quindi un'immagine contrassegnata proveniente da queste sorgenti viene verificata solo al momento della chiamata Messages.

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. A meno che un'immagine non scelga invece un errore, Claude ridimensiona le immagini troppo grandi anziché rifiutarle, fino ai limiti delle richieste dell'API. Oltre questi 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 le dimensioni ridimensionate sbagliate 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.

Gli screenshot e le immagini di zoom che restituisci ai set di strumenti di computer use e browser use sono un'eccezione al ridimensionamento automatico. L'API rifiuta un'immagine tool_result che supera i limiti del modello con un errore di validazione invece di ridimensionarla. Ridimensiona queste immagini nella tua applicazione prima di restituirle, quindi riscala le coordinate che Claude restituisce alle dimensioni del tuo schermo.

# 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 ed è sufficiente una riscalatura lineare per asse. Limita le coordinate restituite alle dimensioni ridimensionate prima di riscalare, in modo che un punto leggermente fuori dall'immagine non possa essere mappato fuori dal tuo 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 Computer use trattano questo schema.

Prossimi passi