Koordinaten und Bounding Boxes

Claude kann Regionen eines Bildes lokalisieren und beschriften (zum Beispiel Bounding Boxes für Tabellen, Formularfelder, Diagrammelemente oder UI-Komponenten zurückgeben). Dieser Leitfaden behandelt, wie Claude Bilder vor der Verarbeitung skaliert und wie du mit den zurückgegebenen Pixelkoordinaten arbeitest, damit Boxen und Punkte mit deinem Originalbild übereinstimmen.

Du brauchst das für OCR-Pipelines, Formularextraktion, Diagramm-Parsing, die Lokalisierung von UI-Elementen und jede Aufgabe, bei der du auf eine bestimmte Region eines Bildes reagierst. Informationen zum Senden von Bildern, zu unterstützten Formaten und zu modellspezifischen Auflösungsgrenzen findest du unter Vision.

Koordinaten folgen der Standard-Bildkonvention: Der Ursprung (0, 0) ist die obere linke Ecke des Bildes, wobei x nach rechts und y nach unten zunimmt. Die Koordinaten, die Claude zurückgibt, sind Pixelpositionen in dem Bild, das Claude sieht: dein Bild, nachdem Claude es skaliert hat, um es an die native Auflösung des Modells anzupassen (siehe Wie Claude Bilder skaliert und auffüllt). Um Koordinaten zu erhalten, die du direkt verwenden kannst, skaliere entweder dein Bild vorab, sodass die Koordinaten eins zu eins auf das Bild abgebildet werden, das du hast (siehe Skaliere dein Bild vor dem Hochladen), oder rechne die von Claude zurückgegebenen Koordinaten um (siehe Koordinaten umrechnen, wenn du nicht vorab skalieren kannst).



Wie Claude Bilder skaliert und auffüllt

Claude findet die größte seitenverhältniserhaltende Größe, die beide Bildgrenzen des Modells erfüllt:

1. Kantenlimit: Keine Seite überschreitet die maximale Kantenlänge (1568 px auf der Standardstufe, 2576 px auf der hochauflösenden Stufe).
2. Visuelles Token-Limit: Die Token-Kosten des Bildes ⌈width / 28⌉ × ⌈height / 28⌉ überschreiten nicht das visuelle Token-Budget des Modells (1568 Token auf der Standardstufe, 4784 auf der hochauflösenden Stufe).

Siehe Auflösung und Token-Kosten, um zu erfahren, welche Modelle zu welcher Stufe gehören.

Für nahezu alle Fotos und Screenshots bestimmt das visuelle Token-Limit die endgültige Größe. Das Kantenlimit greift nur bei länglichen Bildern wie Panoramen oder hohen Smartphone-Screenshots. Berechne die Größe mit der Referenzimplementierung, anstatt von Hand auf die Kantenlänge zu skalieren: Ein 1920×1080-Screenshot wird auf 1456×819 skaliert, nicht auf 1568×882, und die Annahme des Kantenlimits verschiebt jede Koordinate merklich vom Ziel.

Das Token-Limit kann auch dann eine Skalierung auslösen, wenn keine Seite das Kantenlimit überschreitet. Dies zu übersehen ist die häufigste Ursache für falsch ausgerichtete Koordinaten. Zum Beispiel hat eine mit 130 DPI gescannte A4-Seite 1075×1520 Pixel: Beide Seiten liegen unter 1568 px, aber sie kostet 39 × 55 = 2145 visuelle Token, also skaliert Claude sie auf 924×1307.

Claude füllt dann jedes Bild, ob skaliert oder nicht, an den unteren und rechten Kanten bis zum nächsten Vielfachen von 28 Pixeln auf (924×1307 wird im Beispiel zu 924×1316). Die Auffüllung enthält keinen Inhalt: Claude nimmt das aufgefüllte Bild wahr, aber der Seiteninhalt belegt immer nur die nicht aufgefüllte skalierte Region. Normalisiere oder rechne immer anhand der skalierten Abmessungen um, nicht anhand der aufgefüllten Abmessungen; die Division durch die aufgefüllten Abmessungen skaliert jede Koordinate um einen kleinen Betrag.



Skaliere dein Bild vor dem Hochladen

Der zuverlässigste Ansatz ist, dein Bild vor dem Hochladen selbst zu skalieren, sodass das Bild, das du hast, genau das Bild ist, das Claude sieht, und die Koordinaten, die Claude zurückgibt, keine Umrechnung benötigen.

Prüfe zuerst, auf welcher Auflösungsstufe dein Modell ist (siehe Auflösung und Token-Kosten) und übergib die passenden Kanten- und Token-Limits. Die folgende Referenzimplementierung berechnet die exakte Größe, auf die Claude ein Bild skaliert:

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)

    # Binärsuche entlang der langen Kante nach der größten seitenverhältnis-
    # treuen Größe, die passt.
    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))


# Das A4-Beispiel aus „Wie Claude Bilder skaliert und auffüllt“:
print(resized_size(1075, 1520))  # (924, 1307)

# Verwende zum Skalieren deine Bildbibliothek, z. B. Pillow:
# image.resize(resized_size(*image.size))

1. Skaliere das Bild auf die vom Resize-Helper zurückgegebenen Abmessungen. Wenn das Bild bereits innerhalb der Grenzen des Modells liegt, gibt der Helper seine Abmessungen unverändert zurück und keine Skalierung ist nötig.
2. Sende das skalierte Bild an die API. Fülle es nicht selbst auf. Claude übernimmt das Auffüllen, und das Auffüllen verschiebt den Koordinatenursprung nicht.
3. Fordere in deinem Prompt explizit Pixelkoordinaten an. Zum Beispiel: „Gib den Klickpunkt für den Absenden-Button als [x, y] in Pixelkoordinaten zurück."
4. Verwende die zurückgegebenen Koordinaten direkt auf dem Bild, das du gesendet hast. Wenn du normalisierte Koordinaten brauchst, dividiere durch die Abmessungen des gesendeten Bildes, nicht durch die Abmessungen des Originalbildes und nicht durch die aufgefüllten Abmessungen.



Koordinaten umrechnen, wenn du nicht vorab skalieren kannst

Wenn du nicht vorab skalieren kannst (zum Beispiel, wenn das Bild aus einem vorgelagerten System stammt, das du nicht ändern kannst), verwende den Resize-Helper aus Skaliere dein Bild vor dem Hochladen, um die Abmessungen zu ermitteln, die Claude gesehen hat, und bilde dann die von Claude zurückgegebenen Koordinaten in normalisierte Koordinaten oder zurück auf dein Originalbild ab. Claude skaliert übergroße Bilder, anstatt sie abzulehnen, bis zu den Anfragelimits der API. Jenseits dieser Limits schlägt die Anfrage stattdessen mit einem Validierungsfehler fehl. Übergib die Stufenlimits, die zu dem von dir aufgerufenen Modell passen: Die Limits der falschen Stufe ermitteln die falschen skalierten Abmessungen und verschieben stillschweigend jede Koordinate. Dieser Ansatz erfordert die Kenntnis der Pixelabmessungen des hochgeladenen Bildes und gilt daher nicht für PDF-Uploads.

# Diese Hilfsfunktion ruft resized_size aus dem Resize-Beispiel dieser Seite auf.
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)


# Eine Tabellenecke, die Claude bei (462, 653.5) auf der skalierten A4-Seite
# zurückgibt, wird so auf das 1075x1520-Original zurückgerechnet:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

Die Auffüllung wird nur an den unteren und rechten Kanten angewendet, sodass sich der Ursprung nicht verschiebt und eine lineare Umrechnung pro Achse ausreicht. Begrenze die zurückgegebenen Koordinaten vor der Umrechnung auf die skalierten Abmessungen, damit ein Punkt, der leicht außerhalb des Bildes liegt, nicht außerhalb deines Originals abgebildet werden kann.

Die relativen Koordinaten werden mit der Fläche multipliziert, auf der du agierst: das Originalbild, ein Scan in voller Auflösung oder ein Bildschirm. Wenn du auf einem Bildschirm agierst und sich Screenshot-Pixel von logischen Koordinaten unterscheiden (HiDPI-Displays), dividiere zusätzlich durch den Anzeigeskalierungsfaktor. Die Skalierungshinweise des Computer-Use-Tools behandeln dieses Muster.



Nächste Schritte