Skip to content

Latest commit

 

History

History
811 lines (570 loc) · 42.1 KB

README_RU.md

File metadata and controls

811 lines (570 loc) · 42.1 KB

Chrome Lens API для Python

English | Русский

Этот проект предоставляет библиотеку Python и CLI инструмент для взаимодействия с функциональностью OCR Google Lens через API, используемое в Chromium. Это позволяет обрабатывать изображения и извлекать текстовые данные, включая полный текст, координаты и сшитый текст, используя различные методы.

Возможности

  • Извлечение полного текста: Извлекайте полный текст с изображения.
  • Извлечение координат: Извлекайте текст вместе с его координатами.
  • Сшитый текст: Восстанавливайте текст из блоков координат, используя различные методы:
    • Старый метод: Последовательное сшивание текста.
    • Новый метод: Улучшенное сшивание текста за счет расчета их по строчкам. Не рекомендуется на повернутых текстах. Используйте прошлый.
  • Сканирование изображений по URL: Обрабатывайте изображения напрямую по URL без необходимости предварительно их загружать.
  • Управление куки: Загружайте и управляйте куки из файла в формате Netscape или напрямую через конфигурацию.
  • Поддержка прокси: Поддержка HTTP, HTTPS и SOCKS4/5 прокси для выполнения запросов через разные сети.

PS: У Google Lens есть проблема с отображением полного текста, поэтому добавлены методы, которые сшивают текст из координат.

Установка

Вы можете установить пакет, используя pip:

Из PyPI

pip install chrome-lens-py

Обновление через PyPI

pip install -U chrome-lens-py

Из GIT

pip install git+https://github.com/bropines/chrome-lens-py.git

Из исходников

Клонируйте репозиторий и установите пакет:

git clone https://github.com/bropines/chrome-lens-api-py.git
cd chrome-lens-api-py
pip install -r requirements.txt
pip install .

Использование

Вы можете использовать команду lens_scan в CLI для обработки изображений и извлечения текстовых данных, или вы можете использовать Python API для интеграции этой функциональности в ваши собственные проекты.

Использование CLI 
lens_scan <image_source> <data_type>
  • <image_source>: Путь к файлу изображения или URL.
  • <data_type>: Тип данных для извлечения (см. ниже).

Типы данных

  • all: Получить все данные (полный текст, координаты и сшитый текст с использованием обоих методов).
  • full_text_default: Получить только полный текст по умолчанию.
  • full_text_old_method: Получить сшитый текст с использованием старого последовательного метода.
  • full_text_new_method: Получить сшитый текст с использованием нового улучшенного метода.
  • coordinates: Получить текст вместе с координатами.

Примеры

Извлечение текста с использованием нового метода сшивания из локального файла:

lens_scan path/to/image.jpg full_text_new_method

Извлечение текста с использованием нового метода сшивания по URL:

lens_scan https://example.com/image.jpg full_text_new_method

Получение всех доступных данных из локального файла:

lens_scan path/to/image.jpg all

Получение всех доступных данных по URL:

lens_scan https://example.com/image.jpg all

CLI Справка

Вы можете использовать опцию -h или --help, чтобы вывести справочную информацию:

lens_scan -h
Использование API

В дополнение к CLI инструменту, этот проект предоставляет Python API, который можно использовать в ваших скриптах.

Базовое использование API

Сначала импортируйте класс LensAPI:

from chrome_lens_py import LensAPI

Пример использования API

  1. Создание экземпляра API:

    api = LensAPI()

  2. Обработка изображения:

    • Получение всех данных из локального файла:

      result = api.get_all_data('path/to/image.jpg')
print(result)

    • Получение всех данных по URL:

      result = api.get_all_data('https://example.com/image.jpg')
print(result)

    • Получение полного текста из локального файла:

      result = api.get_full_text('path/to/image.jpg')
print(result)

    • Получение полного текста по URL:

      result = api.get_full_text('https://example.com/image.jpg')
print(result)

    • Получение сшитого текста с использованием старого метода из локального файла:

      result = api.get_stitched_text_sequential('path/to/image.jpg')
print(result)

    • Получение сшитого текста с использованием старого метода по URL:

      result = api.get_stitched_text_sequential('https://example.com/image.jpg')
print(result)

    • Получение сшитого текста с использованием нового метода из локального файла:

      result = api.get_stitched_text_smart('path/to/image.jpg')
print(result)

    • Получение сшитого текста с использованием нового метода по URL:

      result = api.get_stitched_text_smart('https://example.com/image.jpg')
print(result)

    • Получение текста с координатами из локального файла:

      result = api.get_text_with_coordinates('path/to/image.jpg')
print(result)

    • Получение текста с координатами по URL:

      result = api.get_text_with_coordinates('https://example.com/image.jpg')
print(result)

Параметры конфигурации

Вы можете настроить поведение LensAPI, передав словарь config при создании экземпляра класса. Это позволяет вам контролировать различные аспекты API, такие как заголовки, прокси, управление файлами cookie, отладку и время запроса.

В словаре config можно использовать следующие ключи:

  • header_type: выбирает набор заголовков, которые будут использоваться для запросов.

    • 'default': использует набор заголовков по умолчанию.
    • 'custom': использует собственный набор заголовков.
    API = LensAPI(config={'header_type': 'custom'})

  • proxy: указывает прокси-сервер для отправки запросов. Поддерживает прокси-серверы HTTP, HTTPS и SOCKS.

    api = LensAPI(config={'proxy': 'socks5://127.0.0.1:2080'})

  • cookies: управляет файлами cookie для сеанса. Может быть путем к файлу cookie формата Netscape, строке cookie или словарю cookie.

    api = LensAPI(config={'cookies': '/path/to/cookie_file.txt'})
    api = LensAPI(config={'cookies': '__Secure-ENID=...; NID=...'})
    api = LensAPI(config={'cookies': {'__Secure-ENID': {'name': '...', 'value': '...', 'expires': ...}, 'NID ': {'имя': '...', 'значение': '...', 'истекает': ...}}})

  • sleep_time: устанавливает задержку в миллисекундах между последовательными запросами API. Это особенно полезно при пакетной обработке, чтобы избежать перегрузки сервера.

    api = LensAPI(config={'sleep_time': 500}) # Установите задержку 500 мс

  • debug_out: указывает путь к файлу для сохранения необработанного ответа API для целей отладки, когда уровень ведения журнала установлен на DEBUG.

    api = LensAPI(config={'debug_out': '/path/to/response_debug.txt'})
Управление куки

Этот проект поддерживает управление куки через различные методы.

Для получения куки в формате Netscape вы можете использовать следующие расширения:

  1. Загрузка куки из файла в формате Netscape:

    • Вы можете загрузить куки из файла в формате Netscape, указав путь к файлу.

    Программный API:

    config = {
    'headers': {
        'cookie': '/path/to/cookie_file.txt'
    }
}
api = LensAPI(config=config)

    CLI:

    lens_scan path/to/image.jpg all -c /path/to/cookie_file.txt

  2. Передача куки напрямую в виде строки:

    • Вы также можете передавать куки напрямую в виде строки через конфигурацию.

    Программный API:

    config = {
    'headers': {
        'cookie': '__Secure-ENID=17.SE=-dizH-; NID=511=---bcDwC4fo0--lgfi0n2-'
    }
}
api = LensAPI(config=config)

    или

    config = {
    'headers': {
        'cookie': {
            '__Secure-ENID': {
                'name': '__Secure-ENID',
                'value': '',
                'expires': 1756858205,
            },
            'NID': {
                'name': 'NID',
                'value': '517=4.......',
                'expires': 1756858205,
            }
        }
    }
}
api = LensAPI(config=config)
Поддержка прокси

Вы можете выполнять запросы через прокси-сервер, используя API или CLI. Библиотека поддерживает HTTP, HTTPS и SOCKS4/5 прокси.

  • Установка прокси в API:

    config = {
    'proxy': 'socks5://127.0.0.1:2080'
}
api = LensAPI(config=config)

  • Установка прокси в CLI:

    lens_scan path/to/image.jpg all -p socks5://127.0.0.1:2080
Методы программного API
  • get_all_data(image_source): Возвращает все доступные данные для данного источника изображения (путь к файлу или URL).
  • get_full_text(image_source): Возвращает только полный текст с источника изображения.
  • get_text_with_coordinates(image_source): Возвращает текст вместе с его координатами в формате JSON с источника изображения.
  • get_stitched_text_smart(image_source): Возвращает сшитый текст с использованием улучшенного метода с источника изображения.
  • get_stitched_text_sequential(image_source): Возвращает сшитый текст с использованием базового последовательного метода с источника изображения.
Работа с координатами

Работа с координатами

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

  1. Y координата: Первое значение в массиве координат представляет вертикальное положение верхнего левого угла текстового региона на изображении. Значение выражается как доля от общей высоты изображения, где 0.0 соответствует верхнему краю, а 1.0 — нижнему.
  2. X координата: Второе значение указывает горизонтальное положение верхнего левого угла текстового региона. Значение выражается как доля от общей ширины изображения, где 0.0 соответствует левому краю, а 1.0 — правому.
  3. Ширина: Третье значение представляет ширину текстового региона как долю от общей ширины изображения. Это значение определяет, сколько горизонтального пространства займет текст.
  4. Высота: Четвертое значение указывает высоту текстового региона как долю от общей высоты изображения.
  5. Пятый параметр: В текущих данных этот параметр всегда равен нулю и, по-видимому, не используется. Возможно, он зарезервирован для будущего использования или специфических модификаций текста.
  6. Шестой параметр: Задает угол вращения текстового региона в градусах. Положительные значения указывают на вращение по часовой стрелке, отрицательные — против часовой стрелки.

Координаты измеряются от верхнего левого угла изображения. Это означает, что (0.0, 0.0) соответствует самому верхнему левому углу изображения, а (1.0, 1.0) — самому нижнему правому.

Пример использования координат

{
    "text": "Пример текста",
    "coordinates": [
        0.5,
        0.5,
        0.3,
        0.1,
        0,
        -45
    ]
}

В этом примере:

  • 0.5 — Y координата (50% от высоты изображения, текст выровнен по центру вертикально).
  • 0.5 — X координата (50% от ширины изображения, текст выровнен по центру горизонтально).
  • 0.3 — ширина текстового региона (30% от ширины изображения).
  • 0.1 — высота текстового региона (10% от высоты изображения).
  • 0 — не используется, значение по умолчанию (возможно, зарезервировано для будущего использования).
  • -45 — угол поворота текста против часовой стрелки на 45 градусов.

Эти значения используются для точного размещения, масштабирования и отображения текста на изображении.

Использование формата координат

Вы можете выбрать формат вывода координат: в процентах или в пикселях. По умолчанию координаты выводятся в процентах, но вы можете переключиться на пиксели с помощью соответствующих настроек.

В консоли

При использовании командной строки вы можете указать формат координат с помощью флага --coordinate-format. Допустимые значения: 'percent' или 'pixels'.

Примеры использования:

  • Вывод координат в процентах (по умолчанию):

    lens_scan image.jpg coordinates

  • Вывод координат в пикселях:

    lens_scan image.jpg coordinates --coordinate-format=pixels
В API

При использовании программного API вы можете передать параметр coordinate_format в методы класса LensAPI. Допустимые значения: 'percent' или 'pixels'.

Пример использования:

from lens_api import LensAPI

api = LensAPI()

# Путь к изображению
image_path = 'image.jpg'

# Получение данных с координатами в пикселях
result = api.get_all_data(image_path, coordinate_format='pixels')

print(result)

Важно

  • При выборе формата 'pixels' координаты будут рассчитаны относительно исходных размеров изображения, даже если изображение было уменьшено для обработки.
  • Если формат не указан, координаты по умолчанию выводятся в процентах.
  • При работе с координатами в пикселях убедитесь, что вы используете исходное изображение для корректного отображения текстовых регионов.
Отладка и Логирование

При использовании инструмента командной строки lens_scan вы можете управлять уровнем логирования с помощью флага --debug. Доступны два уровня:

  • --debug=info: Включает логирование информационных сообщений, которые содержат общую информацию о этапах обработки.
  • --debug=debug: Включает подробные отладочные сообщения, включая детальный вывод и сохранение сырого ответа от API в файл response_debug.txt в текущей директории.

Примеры использования:

  • Запуск с информационным логированием:

    lens_scan path/to/image.jpg all --debug=info

  • Запуск с подробным отладочным логированием:

    lens_scan path/to/image.jpg all --debug=debug

При использовании --debug=debug библиотека сохранит сырой ответ от API в файл response_debug.txt в текущей рабочей директории. Это может быть полезно для глубокой отладки и понимания точного ответа от API.

Программная Отладка

При использовании API в ваших Python-скриптах вы можете управлять уровнем логирования, настраивая модуль logging и передавая параметр logging_level при создании экземпляра класса LensAPI.

Пример использования:

import logging
from chrome_lens_py import LensAPI

# Настройка логирования
logging.basicConfig(level=logging.DEBUG)

# Создаем экземпляр API с нужным уровнем логирования
api = LensAPI(logging_level=logging.DEBUG)

# Обрабатываем изображение
result = api.get_all_data('path/to/image.jpg')
print(result)

Параметр logging_level принимает стандартные уровни логирования из модуля logging, такие как logging.INFO, logging.DEBUG и т.д.

Когда уровень логирования установлен на DEBUG, библиотека будет выводить подробную отладочную информацию и сохранять сырой ответ от API в файл response_debug.txt в текущей директории.

Флаг --debug-out позволит указать путь, где сохранить ответ от сервера, в случае уровня отладки DEBUG. По уполчанию он сохраняется, как описано выше, в папке откуда запущена консоль, то есть в CWD

Примечания об Уровнях Логирования

  • Уровень INFO: Предоставляет общую информацию о процессе, такую как отправка запросов и получение ответов.
  • Уровень DEBUG: Предоставляет подробную информацию, полезную для отладки, включая внутреннее состояние и сохраненные ответы.
Управление конфигурацией

Приоритет конфигурации

При запуске CLI-инструмента lens_scan приложение определяет настройки на основе следующего приоритета (от самого высокого к самому низкому):

  1. Аргументы командной строки (CLI): Опции, указанные непосредственно при запуске команды, имеют наивысший приоритет.
  2. Переменные окружения: Если настройка не указана в CLI, приложение проверит соответствующие переменные окружения.
  3. Файл конфигурации: Если настройка не найдена в аргументах CLI или переменных окружения, приложение обратится к файлу конфигурации.
  4. Значения по умолчанию: Если настройка не указана ни в одном из вышеперечисленных мест, используются значения по умолчанию.

Файл конфигурации по умолчанию

  • Файл конфигурации по умолчанию находится в директории конфигурации пользователя, которая зависит от операционной системы:
    • Windows: C:\Users\<ВашеИмяПользователя>\.config\chrome-lens-py\config.json
    • Unix/Linux: /home/<ВашеИмяПользователя>/.config/chrome-lens-py/config.json
    • macOS: /Users/<ВашеИмяПользователя>/Library/Application Support/chrome-lens-py/config.json

Указание пользовательского файла конфигурации

  • Вы можете указать пользовательский файл конфигурации с помощью флага --config-file:

    lens_scan --config-file путь/до/вашего/config.json <image_source> <data_type>

  • Когда указан пользовательский файл конфигурации, он считается только для чтения и не будет изменен приложением.

Настройки конфигурации

Файл конфигурации представляет собой JSON-файл, который может включать следующие настройки:

  • proxy: Укажите прокси-сервер для маршрутизации запросов.

    {
  "proxy": "socks5://username:[email protected]:1080"
}

  • cookies: Укажите cookies для использования в запросах. Это может быть путь к файлу cookies или строка cookies.

    {
  "cookies": "путь/до/вашего/cookie_file.txt"
}

    или

    {
  "cookies": "__Secure-ENID=17.SE=-dizH-; NID=511=---bcDwC4fo0--lgfi0n2-"
}

  • coordinate_format: Установите формат вывода координат. Допустимые значения: "percent" или "pixels".

    {
  "coordinate_format": "pixels"
}

  • debug: Установите уровень логирования. Допустимые значения: "info" или "debug".

    {
  "debug": "debug"
}

  • data_type: Установите тип выходных данных.

    {
  "data_type": "all"
}

Полный пример файла конфигурации

Вот пример файла конфигурации, который включает все возможные параметры конфигурации:

{
  "proxy": "socks5://username:[email protected]:1080",
  "cookies": "путь/до/вашего/cookie_file.txt",
  "coordinate_format": "pixels",
  "data_type": "all",
  "debug": "debug"
}

Обновление файла конфигурации

  • Чтобы обновить файл конфигурации по умолчанию с новыми настройками из CLI, используйте флаг -uc или --update-config.

    lens_scan <image_source> <data_type> [опции] -uc

  • Примечание: Файл конфигурации будет обновлен только в том случае, если это файл конфигурации по умолчанию (т.е. не указан через --config-file).

  • Обновляются только определенные настройки:

    • Настройки, которые могут быть обновлены:

      • coordinate_format
      • debug

    • Настройки, которые не будут обновлены:

      • proxy
      • cookies
      • image_source
      • data_type

  • Это позволяет сохранять определенные настройки между запусками без изменения критических конфигураций, таких как прокси или cookies.

Примеры использования

  • Обновление формата координат в файле конфигурации по умолчанию:

    lens_scan путь/до/image.jpg all --coordinate_format=pixels -uc
    • Эта команда установит формат координат в пикселях для текущего запуска и обновит файл конфигурации по умолчанию, чтобы в будущих запусках также использовались пиксели как формат координат.

  • Использование прокси без обновления файла конфигурации:

    lens_scan путь/до/image.jpg all -p socks5://127.0.0.1:2080
    • Настройка прокси будет использована для этого запуска, но не будет сохранена в файл конфигурации.

  • Указание пользовательского файла конфигурации (только для чтения):

    lens_scan --config-file путь/до/config.json путь/до/image.jpg all
    • Приложение будет использовать настройки из указанного файла конфигурации, но не будет изменять его, даже если используется флаг -uc.

Переменные окружения

Вы также можете указывать настройки через переменные окружения:

  • LENS_SCAN_PROXY: Установите прокси-сервер.

    export LENS_SCAN_PROXY="socks5://username:[email protected]:1080"

  • LENS_SCAN_COOKIES: Предоставьте cookies.

    export LENS_SCAN_COOKIES="__Secure-ENID=17.SE=-dizH-; NID=511=---"

  • LENS_SCAN_CONFIG_PATH: Укажите пользовательский файл конфигурации.

    export LENS_SCAN_CONFIG_PATH="путь/до/вашего/config.json"
Пакетная Обработка

Пакетная обработка нескольких изображений

Этот проект поддерживает пакетную обработку изображений, когда вместо одного файла изображения указан путь к каталогу. Приложение обработает все файлы изображений в указанном каталоге.

Использование CLI

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

lens_scan путь/к/каталогу <data_type> [опции]
  • путь/к/каталогу: Путь к каталогу, содержащему файлы изображений.
  • <data_type>: Тип данных для извлечения (например, all, full_text_default и т.д.).
  • [опции]: Дополнительные опции, такие как --out-txt.

Пример:

lens_scan /путь/к/изображениям all --out-txt=per_file

Опции вывода с помощью --out-txt

Флаг --out-txt позволяет контролировать, как сохраняется вывод при обработке нескольких изображений:

  • --out-txt=per_file: Сохраняет каждый результат в отдельный текстовый файл на основе имени изображения в том же каталоге.
  • --out-txt=имя_файла.txt: Сохраняет все результаты в один текстовый файл с указанным именем в том же каталоге.
  • Без флага --out-txt: По умолчанию все результаты сохраняются в файл с именем output.txt в том же каталоге.

Примеры:

  1. Вывод в отдельные файлы для каждого изображения:

    lens_scan /путь/к/изображениям all --out-txt=per_file

    Эта команда обрабатывает все изображения в /путь/к/изображениям и сохраняет каждый результат в отдельный текстовый файл с именем изображения (например, image1.txt, image2.txt).

  2. Вывод всех результатов в один файл:

    lens_scan /путь/к/изображениям all --out-txt=результаты.txt

    Эта команда обрабатывает все изображения и сохраняет все результаты в результаты.txt в том же каталоге.

  3. Вывод по умолчанию (output.txt):

    lens_scan /путь/к/изображениям all

    Без указания --out-txt результаты сохраняются в output.txt в том же каталоге.

Формат вывода

При выводе в один файл (поведение по умолчанию или при указании имени файла с помощью --out-txt) формат файла вывода следующий:

#filename1.jpg
Извлеченный текст из filename1.jpg

#filename2.png
Извлеченный текст из filename2.png

...

Извлеченный текст из каждого изображения предваряется символом #, за которым следует имя файла, и текст сохраняет исходное форматирование, включая символы новой строки.

Время задержки между запросами

Чтобы избежать перегрузки API и соблюдения политики ограничения скорости, библиотека вводит задержку между обработкой каждого изображения. По умолчанию время задержки установлено на 1000 миллисекунд (1 секунда). Вы можете настроить эту задержку с помощью флага -st или --sleep-time, указав время в миллисекундах.

Пример:

lens_scan /путь/к/изображениям all -st 500

Эта команда устанавливает время задержки в 500 миллисекунд между обработкой каждого изображения.

Программное использование API

Вы также можете выполнить пакетную обработку с помощью Python API, предоставив путь к каталогу методам.

Пример:

from chrome_lens_py import LensAPI

api = LensAPI(sleep_time=500)  # Установите время задержки в 500 миллисекунд

# Путь к каталогу, содержащему изображения
directory_path = '/путь/к/изображениям'

# Обработайте каталог для извлечения полного текста из каждого изображения
results = api.get_full_text(directory_path)

# Переберите результаты
for filename, text in results.items():
    if 'error' in text:
        print(f"Ошибка при обработке {filename}: {text['error']}")
    else:
        print(f"# {filename}")
        print(text)
        print()

Примечания:

  • Поддерживаемые файлы изображений: Обрабатываются только файлы изображений с поддерживаемыми MIME-типами. Неформатированные файлы или неподдерживаемые форматы будут игнорированы.
  • Настройка времени задержки: Время задержки между запросами можно настроить в соответствии с вашими потребностями, но будьте осторожны при его уменьшении, чтобы избежать ограничения по скорости со стороны API.
  • Обработка ошибок: Если при обработке изображения возникает ошибка, сообщение об ошибке будет сохранено в результатах под именем этого файла.
  • Файлы вывода: При использовании --out-txt=per_file текстовые файлы вывода будут сохранены в том же каталоге, что и изображения, с тем же базовым именем файла и расширением .txt.

Структура проекта

/chrome-lens-api-py
│
├── /src
│   ├── /chrome_lens_py
│   │   ├── __init__.py           # Инициализация пакета
│   │   ├── constants.py          # Константы, используемые в проекте
│   │   ├── utils.py              # Вспомогательные функции
│   │   ├── image_processing.py   # Модуль обработки изображений
│   │   ├── request_handler.py    # Модуль обработки запросов API
│   │   ├── text_processing.py    # Модуль обработки текста
│   │   ├── lens_api.py           # Интерфейс API для использования в других скриптах
│   │   └── main.py               # Точка входа CLI инструмента
│
├── setup.py                      # Установка проекта
├── README.md                     # Описание проекта и руководство по использованию
└── requirements.txt              # Зависимости проекта

Благодарности

Особая благодарность dimdenGD за метод извлечения текста, использованный в этом проекте. Вы можете ознакомиться с его работой в репозитории chrome-lens-ocr. Этот проект вдохновлен их подходом к использованию функциональности OCR Google Lens.

TODO

  • Добавить "scan by url"
  • Добавить вывод в пикселях
  • Перенести все методы из chrome-lens-ocr
    • cookie!?
  • Сделать код чуть более читабельным...
  • Еще кое-что очень, очень важное...

Лицензия

Этот проект лицензирован на условиях лицензии MIT. Подробнее см. в файле LICENSE.

Отказ от ответственности

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

Автор

Bropines - Почта / Telegram

Спешал фор рускоговорящих. Да, ридми был написан GPT-шкой. Мне было ооооооочень лень его писать ручками :)