Koordinat dan bounding box

Claude dapat menemukan dan melabeli wilayah dari sebuah gambar (misalnya, mengembalikan "bounding box" (kotak pembatas) untuk tabel, bidang formulir, elemen grafik, atau komponen UI). Panduan ini membahas bagaimana Claude mengubah ukuran gambar sebelum memprosesnya dan cara bekerja dengan koordinat piksel yang dikembalikannya, sehingga kotak dan titik sejajar dengan gambar asli Anda.

Anda akan membutuhkan ini untuk pipeline OCR, ekstraksi formulir, parsing grafik, penentuan lokasi elemen UI, dan tugas apa pun di mana Anda bertindak pada wilayah tertentu dari sebuah gambar. Untuk pengiriman gambar, format yang didukung, dan batas resolusi per model, lihat Vision.

Koordinat mengikuti konvensi gambar standar: titik asal (0, 0) adalah sudut kiri-atas gambar, dengan x bertambah ke kanan dan y bertambah ke bawah. Koordinat yang dikembalikan Claude adalah posisi piksel pada gambar yang dilihat Claude: gambar Anda setelah Claude mengubah ukurannya agar sesuai dengan resolusi native model (lihat Bagaimana Claude mengubah ukuran dan menambahkan padding pada gambar). Untuk mendapatkan koordinat yang dapat Anda gunakan secara langsung, ubah ukuran gambar Anda terlebih dahulu sehingga koordinat terpetakan satu-ke-satu pada gambar yang Anda miliki (lihat Ubah ukuran gambar Anda sebelum mengunggah), atau skalakan ulang koordinat yang dikembalikan Claude (lihat Skalakan ulang koordinat ketika Anda tidak dapat mengubah ukuran terlebih dahulu).



Bagaimana Claude mengubah ukuran dan menambahkan padding pada gambar

Claude mencari ukuran terbesar yang mempertahankan rasio aspek dan memenuhi kedua batas gambar model:

1. Batas sisi: tidak ada sisi yang melebihi panjang sisi maksimum (1568 px pada tingkat standar, 2576 px pada tingkat resolusi tinggi).
2. Batas token visual: biaya token gambar ⌈width / 28⌉ × ⌈height / 28⌉ tidak melebihi anggaran token visual model (1568 token pada tingkat standar, 4784 pada tingkat resolusi tinggi).

Lihat Resolusi dan biaya token untuk mengetahui model mana yang berada di tingkat mana.

Untuk hampir semua foto dan tangkapan layar, batas token visual adalah yang menentukan ukuran akhir. Batas sisi hanya berlaku untuk gambar yang memanjang seperti panorama atau tangkapan layar ponsel yang tinggi. Hitung ukurannya dengan implementasi referensi alih-alih menskalakan ke panjang sisi secara manual: tangkapan layar 1920×1080 diubah ukurannya menjadi 1456×819, bukan 1568×882, dan mengasumsikan batas sisi akan membuat setiap koordinat meleset secara signifikan dari target.

Batas token juga dapat memicu pengubahan ukuran ketika tidak ada sisi yang melebihi batas sisi. Mengabaikan hal ini adalah penyebab paling umum dari koordinat yang tidak sejajar. Misalnya, halaman A4 yang dipindai pada 130 DPI berukuran 1075×1520 piksel: kedua sisinya di bawah 1568 px, tetapi biayanya 39 × 55 = 2145 token visual, sehingga Claude mengubah ukurannya menjadi 924×1307.

Claude kemudian menambahkan "padding" (pengisi) pada setiap gambar, baik yang diubah ukurannya maupun tidak, hingga kelipatan 28 piksel berikutnya pada tepi bawah dan kanan (924×1307 menjadi 924×1316 dalam contoh tersebut). Padding tidak berisi konten apa pun: Claude melihat gambar yang telah diberi padding, tetapi konten halaman hanya menempati wilayah hasil pengubahan ukuran yang tidak diberi padding. Selalu normalisasi atau skalakan ulang berdasarkan dimensi hasil pengubahan ukuran, bukan dimensi yang telah diberi padding; membagi dengan dimensi yang telah diberi padding akan menskalakan setiap koordinat dengan jumlah kecil.



Ubah ukuran gambar Anda sebelum mengunggah

Pendekatan yang paling andal adalah mengubah ukuran gambar Anda sendiri sebelum mengunggah, sehingga gambar yang Anda miliki persis sama dengan gambar yang dilihat Claude dan koordinat yang dikembalikan Claude tidak memerlukan konversi.

Pertama, periksa tingkat resolusi model Anda (lihat Resolusi dan biaya token) dan berikan batas sisi dan token yang sesuai. Implementasi referensi berikut menghitung ukuran persis yang digunakan Claude untuk mengubah ukuran gambar:

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)

    # Pencarian biner di sepanjang sisi panjang untuk ukuran terbesar yang mempertahankan
    # rasio aspek dan masih muat.
    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))


# Contoh A4 dari "How Claude resizes and pads images":
print(resized_size(1075, 1520))  # (924, 1307)

# Untuk menerapkan pengubahan ukuran, gunakan pustaka gambar Anda, misalnya Pillow:
# image.resize(resized_size(*image.size))

1. Ubah ukuran gambar ke dimensi yang dikembalikan oleh helper pengubah ukuran. Jika gambar sudah sesuai dengan batas model, helper mengembalikan dimensinya tanpa perubahan dan tidak diperlukan pengubahan ukuran.
2. Kirim gambar yang telah diubah ukurannya ke API. Jangan tambahkan padding sendiri. Claude menangani padding, dan padding tidak menggeser titik asal koordinat.
3. Dalam prompt Anda, minta koordinat piksel secara eksplisit. Misalnya: "Kembalikan titik klik untuk tombol Submit sebagai [x, y] dalam koordinat piksel."
4. Gunakan koordinat yang dikembalikan secara langsung terhadap gambar yang Anda kirim. Jika Anda memerlukan koordinat yang dinormalisasi, bagi dengan dimensi gambar yang Anda kirim, bukan dengan dimensi gambar asli dan bukan dengan dimensi yang telah diberi padding.



Skalakan ulang koordinat ketika Anda tidak dapat mengubah ukuran terlebih dahulu

Jika Anda tidak dapat mengubah ukuran terlebih dahulu (misalnya, ketika gambar berasal dari sistem hulu yang tidak dapat Anda modifikasi), gunakan helper pengubah ukuran dari Ubah ukuran gambar Anda sebelum mengunggah untuk memulihkan dimensi yang dilihat Claude, lalu petakan koordinat yang dikembalikan Claude menjadi koordinat yang dinormalisasi atau kembali ke gambar asli Anda. Claude mengubah ukuran gambar yang terlalu besar alih-alih menolaknya, hingga batas permintaan API. Di luar batas tersebut, permintaan akan gagal dengan kesalahan validasi. Berikan batas tingkat yang sesuai dengan model yang Anda panggil: batas tingkat yang salah akan memulihkan dimensi hasil pengubahan ukuran yang salah dan secara diam-diam menggeser setiap koordinat. Pendekatan ini memerlukan pengetahuan tentang dimensi piksel gambar yang Anda unggah, sehingga tidak berlaku untuk unggahan PDF.

# Helper ini memanggil resized_size dari contoh pengubahan ukuran di halaman ini.
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)


# Sudut tabel yang dikembalikan Claude di (462, 653.5) pada halaman A4 yang diubah ukurannya
# dipetakan kembali ke gambar asli 1075x1520 seperti ini:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

Padding hanya diterapkan pada tepi bawah dan kanan, sehingga titik asal tidak bergeser dan penskalaan ulang linear per sumbu sudah cukup. Batasi (clamp) koordinat yang dikembalikan ke dimensi hasil pengubahan ukuran sebelum menskalakan ulang, sehingga titik yang sedikit berada di luar gambar tidak dapat terpetakan di luar gambar asli Anda.

Koordinat relatif dikalikan dengan permukaan apa pun yang Anda gunakan: gambar asli, hasil pindaian resolusi penuh, atau layar. Ketika Anda bertindak pada layar dan piksel tangkapan layar berbeda dari koordinat logis (tampilan HiDPI), bagi juga dengan faktor skala tampilan. Panduan penskalaan alat computer use membahas pola tersebut.



Langkah selanjutnya