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

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

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

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



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

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

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

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

Для большинства фотографий и снимков экрана изменение размера вызывается ограничением по стороне. Для документов портретной ориентации обычно первым срабатывает ограничение по визуальным токенам, и его игнорирование — самая частая причина несовпадения координат. Например, страница формата A4, отсканированная с разрешением 130 DPI, имеет размер 1075×1520 пикселей: обе стороны меньше 1568 пикселей, но она стоит 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)

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



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

Если вы не можете заранее изменить размер (например, когда изображение поступает из вышестоящей системы, которую вы не можете модифицировать), используйте resized_size из раздела Измените размер изображения перед загрузкой, чтобы восстановить размеры, которые видел Claude, а затем преобразуйте координаты, возвращённые Claude, в нормализованные координаты или обратно на ваше исходное изображение. Этот подход требует знания пиксельных размеров загруженного вами изображения, поэтому он неприменим к загрузкам 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)


# Чтобы выразить координату в пиксельном пространстве исходного изображения, умножьте
# относительную координату на исходные размеры:
# (rel_x * original_width, rel_y * original_height)

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



Связанные материалы

• Инструмент Computer use требует, чтобы снимки экрана уже укладывались в ограничения размера изображения (снимки экрана слишком большого размера отклоняются, а не уменьшаются); см. его рекомендации по масштабированию для шаблона изменения размера на стороне клиента и пересчёта координат.
• Поддержка PDF: страницы растеризуются на стороне сервера с размерами, которые вы не контролируете, поэтому растеризуйте страницы самостоятельно и используйте подход с предварительным изменением размера, когда вам нужны координаты в содержимом PDF.