Координаты и ограничивающие рамки

Claude может находить и размечать области изображения (например, возвращать ограничивающие рамки для таблиц, полей форм, элементов диаграмм или компонентов пользовательского интерфейса). В этом руководстве рассматривается, как Claude изменяет размер изображений перед их обработкой и как работать с пиксельными координатами, которые он возвращает, чтобы рамки и точки совпадали с вашим исходным изображением.

Это понадобится вам для конвейеров OCR, извлечения данных из форм, разбора диаграмм, определения местоположения элементов пользовательского интерфейса и любых задач, где вы работаете с конкретной областью изображения. Об отправке изображений, поддерживаемых форматах и ограничениях разрешения для каждой модели см. Зрение.

Координаты следуют стандартному соглашению для изображений: начало координат (0, 0) — это верхний левый угол изображения, где x увеличивается вправо, а y увеличивается вниз. Координаты, которые возвращает Claude, — это пиксельные позиции в изображении, которое видит Claude: ваше изображение после того, как Claude изменил его размер, чтобы оно соответствовало нативному разрешению модели (см. Как Claude изменяет размер и дополняет изображения). Чтобы получить координаты, которые можно использовать напрямую, либо предварительно измените размер вашего изображения, чтобы координаты отображались один к одному на имеющееся у вас изображение (см. Измените размер изображения перед загрузкой), либо пересчитайте координаты, которые возвращает Claude (см. Пересчитывайте координаты, когда предварительное изменение размера невозможно).



Как Claude изменяет размер и дополняет изображения

Claude находит наибольший размер с сохранением пропорций, который удовлетворяет обоим ограничениям модели для изображений:

1. Ограничение по стороне: ни одна из сторон не превышает максимальную длину стороны (1568 px на стандартном уровне, 2576 px на уровне высокого разрешения).
2. Ограничение визуальных токенов: стоимость изображения в токенах ⌈width / 28⌉ × ⌈height / 28⌉ не превышает бюджет визуальных токенов модели (1568 токенов на стандартном уровне, 4784 на уровне высокого разрешения).

См. Разрешение и стоимость в токенах, чтобы узнать, какие модели относятся к какому уровню.

Почти для всех фотографий и снимков экрана именно ограничение визуальных токенов определяет итоговый размер. Ограничение по стороне вступает в силу только для вытянутых изображений, таких как панорамы или высокие снимки экрана телефона. Вычисляйте размер с помощью эталонной реализации, а не масштабируя до длины стороны вручную: снимок экрана 1920×1080 изменяется до 1456×819, а не до 1568×882, и предположение об ограничении по стороне заметно смещает каждую координату от цели.

Ограничение по токенам также может вызвать изменение размера, когда ни одна из сторон не превышает ограничение по стороне. Упущение этого — самая распространённая причина несовпадающих координат. Например, страница A4, отсканированная при 130 DPI, имеет размер 1075×1520 пикселей: обе стороны меньше 1568 px, но она стоит 39 × 55 = 2145 визуальных токенов, поэтому Claude изменяет её размер до 924×1307.

Затем Claude дополняет каждое изображение, изменённое или нет, до следующего кратного 28 пикселям по нижнему и правому краям (924×1307 становится 924×1316 в этом примере). Дополнение не содержит содержимого: Claude воспринимает дополненное изображение, но содержимое страницы всегда занимает только недополненную область изменённого размера. Всегда нормализуйте или пересчитывайте по размерам после изменения, а не по дополненным размерам; деление на дополненные размеры масштабирует каждую координату на небольшую величину.



Измените размер изображения перед загрузкой

Самый надёжный подход — изменить размер изображения самостоятельно перед загрузкой, чтобы имеющееся у вас изображение было в точности тем изображением, которое видит Claude, и координаты, которые возвращает Claude, не требовали преобразования.

Сначала проверьте, на каком уровне разрешения находится ваша модель (см. Разрешение и стоимость в токенах), и передайте соответствующие ограничения по стороне и токенам. Следующая эталонная реализация вычисляет точный размер, до которого Claude изменяет изображение:

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)

    # Бинарный поиск по длинной стороне: наибольший размер с сохранением
    # пропорций, который помещается.
    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))


# Пример с A4 из раздела «Как Claude изменяет размер и дополняет изображения»:
print(resized_size(1075, 1520))  # (924, 1307)

# Для изменения размера используйте библиотеку изображений, например Pillow:
# image.resize(resized_size(*image.size))

1. Измените размер изображения до размеров, возвращённых вспомогательной функцией изменения размера. Если изображение уже укладывается в ограничения модели, функция возвращает его размеры без изменений, и изменение размера не требуется.
2. Отправьте изображение с изменённым размером в API. Не дополняйте его самостоятельно. Claude выполняет дополнение сам, и дополнение не смещает начало координат.
3. В вашей подсказке явно запрашивайте пиксельные координаты. Например: «Верни точку нажатия для кнопки Submit как [x, y] в пиксельных координатах».
4. Используйте возвращённые координаты напрямую с изображением, которое вы отправили. Если вам нужны нормализованные координаты, делите на размеры отправленного вами изображения, а не на размеры исходного изображения и не на дополненные размеры.



Пересчитывайте координаты, когда предварительное изменение размера невозможно

Если вы не можете предварительно изменить размер (например, когда изображение поступает из вышестоящей системы, которую вы не можете изменить), используйте вспомогательную функцию изменения размера из раздела Измените размер изображения перед загрузкой, чтобы восстановить размеры, которые видел Claude, а затем отобразите координаты, которые возвращает Claude, в нормализованные координаты или обратно на ваше исходное изображение. Claude изменяет размер слишком больших изображений, а не отклоняет их, вплоть до ограничений запросов API. За пределами этих ограничений запрос завершается ошибкой валидации. Передавайте ограничения уровня, соответствующие модели, которую вы вызвали: ограничения неправильного уровня восстанавливают неправильные размеры после изменения и незаметно смещают каждую координату. Этот подход требует знания пиксельных размеров загруженного вами изображения, поэтому он не применим к загрузкам PDF.

# Эта вспомогательная функция вызывает resized_size из примера на этой странице.
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)


# Угол таблицы, который Claude возвращает в (462, 653.5) на уменьшенной странице
# A4, отображается обратно на оригинал 1075x1520 так:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

Дополнение применяется только к нижнему и правому краям, поэтому начало координат не смещается, и достаточно линейного пересчёта по каждой оси. Ограничивайте возвращённые координаты размерами после изменения перед пересчётом, чтобы точка, находящаяся немного за пределами изображения, не могла отобразиться за пределы вашего оригинала.

Относительные координаты умножаются на любую поверхность, с которой вы работаете: исходное изображение, скан в полном разрешении или экран. Когда вы работаете с экраном и пиксели снимка экрана отличаются от логических координат (дисплеи HiDPI), также делите на коэффициент масштабирования дисплея. Этот шаблон описан в руководстве по масштабированию инструмента использования компьютера.



Следующие шаги