Koordinaten und Bounding Boxes

Claude kann Bereiche eines Bildes lokalisieren und beschriften (zum Beispiel „bounding boxes" (Begrenzungsrahmen) 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 Rahmen und Punkte mit deinem Originalbild übereinstimmen.

Du benötigst dies für OCR-Pipelines, Formularextraktion, Diagrammanalyse, UI-Element-Lokalisierung und jede Aufgabe, bei der du auf einen bestimmten Bereich eines Bildes reagierst. Informationen zum Senden von Bildern, zu unterstützten Formaten und zu den Auflösungslimits pro Modell 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 auf die native Auflösung des Modells skaliert hat (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 Bildlimits des Modells erfüllt:

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

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

Bei den meisten Fotos und Screenshots ist das Kantenlimit das, was eine Skalierung auslöst. Bei Dokumenten im Hochformat wird normalerweise zuerst das Visual-Token-Limit ausgelöst, und dies zu übersehen ist die häufigste Ursache für falsch ausgerichtete Koordinaten. Zum Beispiel ist eine A4-Seite, die mit 130 DPI gescannt wurde, 1075×1520 Pixel groß: Beide Seiten liegen unter 1568 px, aber sie kostet 39 × 55 = 2145 Visual-Token, sodass Claude sie auf 924×1307 skaliert.

Claude füllt dann jedes Bild, ob skaliert oder nicht, am unteren und rechten Rand bis zum nächsten Vielfachen von 28 Pixeln auf (924×1307 wird im Beispiel zu 924×1316). Das Padding enthält keinen Inhalt: Claude nimmt das aufgefüllte Bild wahr, aber der Seiteninhalt belegt immer nur den nicht aufgefüllten skalierten Bereich. Normalisiere oder rechne immer anhand der skalierten Abmessungen um, nicht anhand der aufgefüllten Abmessungen; das Teilen 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 selbst vor dem Hochladen zu skalieren, sodass das Bild, das du hast, genau das Bild ist, das Claude sieht, und die von Claude zurückgegebenen Koordinaten keine Umrechnung benötigen.

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äre Suche entlang der langen Kante nach der größten seitenverhältnis-
    # erhaltenden 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 „How Claude resizes and pads images“:
print(resized_size(1075, 1520))  # (924, 1307)

1. Skaliere das Bild auf die von resized_size zurückgegebenen Abmessungen. Wenn das Bild bereits innerhalb der Limits des Modells liegt, gibt resized_size seine Abmessungen unverändert zurück und keine Skalierung ist erforderlich.
2. Sende das skalierte Bild an die API. Fülle es nicht selbst auf; Claude übernimmt das Padding, und Padding verschiebt den Koordinatenursprung nicht.
3. Fordere in deinem Prompt explizit Pixelkoordinaten an. Zum Beispiel: „Gib die Bounding Box jeder Tabelle als [x1, y1, x2, y2] in Pixelkoordinaten zurück."
4. Verwende die zurückgegebenen Koordinaten direkt auf dem Bild, das du gesendet hast. Wenn du normalisierte Koordinaten benötigst, teile durch die Abmessungen des Bildes, das du gesendet hast, 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 von einem vorgelagerten System kommt, das du nicht ändern kannst), verwende resized_size aus Skaliere dein Bild vor dem Hochladen, um die Abmessungen zu ermitteln, die Claude gesehen hat, und mappe dann die von Claude zurückgegebenen Koordinaten in normalisierte Koordinaten oder zurück auf dein Originalbild. Dieser Ansatz erfordert, dass du die Pixelabmessungen des hochgeladenen Bildes kennst, daher gilt er nicht für PDF-Uploads.

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)


# Um die Koordinate im Pixelraum deines Originalbildes auszudrücken, multipliziere die
# relative Koordinate mit deinen ursprünglichen Abmessungen:
# (rel_x * original_width, rel_y * original_height)

Padding wird nur am unteren und rechten Rand angewendet, sodass sich der Ursprung nicht verschiebt und eine lineare Umrechnung pro Achse ausreicht.



Verwandte Themen

• Das Computer-Use-Tool erfordert, dass Screenshots bereits innerhalb der Bildgrößenlimits liegen (zu große Screenshots werden abgelehnt, nicht skaliert); siehe dessen Skalierungshinweise für das clientseitige Skalierungs- und Koordinatenumrechnungsmuster.
• PDF-Unterstützung: Seiten werden serverseitig mit Abmessungen gerastert, die du nicht kontrollierst, also rastere Seiten selbst und verwende den Ansatz mit vorheriger Skalierung, wenn du Koordinaten auf PDF-Inhalten benötigst.