Coordinate e riquadri di delimitazione

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.

Ti servirà 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 Vision.

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 utilizzabili direttamente, puoi pre-ridimensionare la tua immagine in modo che le coordinate corrispondano uno a uno all'immagine che possiedi (vedi Ridimensiona la tua immagine prima di caricarla), oppure riscalare 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 dei 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 in quello ad alta risoluzione).

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

Per la maggior parte delle foto e degli screenshot è il limite del lato a innescare un ridimensionamento. Per i documenti in formato verticale di solito è il limite dei token visivi a scattare per primo, e trascurarlo è la causa più comune di coordinate disallineate. Ad esempio, una pagina A4 scansionata a 130 DPI è 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 del "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 di caricarla

L'approccio più affidabile è ridimensionare tu stesso l'immagine prima di caricarla, in modo che l'immagine che possiedi sia esattamente l'immagine che Claude vede e le coordinate che Claude restituisce non richiedano alcuna conversione.

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 "How Claude resizes and pads images":
print(resized_size(1075, 1520))  # (924, 1307)

1. Ridimensiona l'immagine alle dimensioni restituite da resized_size. Se l'immagine rientra già nei limiti del modello, resized_size 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, richiedi esplicitamente coordinate in pixel. Ad esempio: "Restituisci il riquadro di delimitazione di ogni tabella come [x1, y1, x2, y2] in coordinate 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.



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 resized_size da Ridimensiona la tua immagine prima di caricarla 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. Questo approccio richiede di conoscere le dimensioni in pixel dell'immagine che hai caricato, quindi non si applica ai caricamenti di 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)


# Per esprimere la coordinata nello spazio dei pixel dell'immagine originale, moltiplica la
# coordinata relativa per le dimensioni originali:
# (rel_x * larghezza_originale, rel_y * altezza_originale)

Il padding viene applicato solo ai bordi inferiore e destro, quindi l'origine non si sposta e una riscalatura lineare per asse è sufficiente.



Risorse correlate

• Lo strumento Computer use richiede che gli screenshot rientrino già nei limiti di dimensione delle immagini (gli screenshot troppo grandi vengono rifiutati, non ridimensionati); consulta le sue indicazioni sul ridimensionamento per il pattern di ridimensionamento lato client e riscalatura delle coordinate.
• Supporto PDF: le pagine vengono rasterizzate lato server a dimensioni che non controlli, quindi rasterizza tu stesso le pagine e usa l'approccio di pre-ridimensionamento quando hai bisogno di coordinate su contenuti PDF.