Генерация и чтение QR‑кодов на Python

Создайте, настройте и декодируйте QR-коды в Python: пошаговая установка окружения, примеры генерации и кастомизации, декодирование из файла и из веб-камеры, рекомендации по отладке и безопасному использованию.

QR-код на мобильном устройстве

QR‑код (Quick Response) — это матричный штрих‑код, который хранит закодированные данные. Его часто используют на афишах, в журналах, в кинотеатрах, на сайтах и в рекламных материалах. С помощью Python вы можете автоматически генерировать QR‑коды, настраивать их внешний вид и декодировать данные из изображений или потока с веб‑камеры.

Важно: в примерах используется библиотека qrcode для генерации и OpenCV для декодирования. Для работы с изображениями применяется Pillow (модуль Image).

К чему это применимо

Быстрая генерация ссылок, contact card (vCard), текстов, Wi‑Fi данных.
Интеграция в сайты, печатную продукцию, POS‑системы и мобильные приложения.

Установка окружения Python

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

Создание виртуального окружения (рекомендуется venv)

Создайте папку для проекта: mkdir my-qr-project
Перейдите в папку: cd my-qr-project
Создайте venv: python3 -m venv venv
Активируйте виртуальное окружение:
- На Windows: venv\Scripts\activate
- На macOS/Linux: source venv/bin/activate

Примечание: можно использовать virtualenv или Anaconda; venv встроен в Python 3 и подходит для большинства задач.

Установка необходимых пакетов

Рекомендуемая команда (внутри активированного venv):

pip install opencv-python qrcode numpy Pillow

Короткие пояснения:

opencv-python — библиотека для обработки изображений и детекции QR‑кодов.
qrcode — упрощённая библиотека для генерации QR‑кодов.
numpy — для работы с матрицами и выводом размеров.
Pillow — современная реализация PIL, предоставляет модуль Image.

Важно: на некоторых системах для OpenCV могут потребоваться системные зависимости (например, libjpeg, libpng); если возникают ошибки, проверьте вывод pip и установите необходимые пакеты через менеджер пакетов ОС.

Простая генерация QR‑кода

Создайте файл generate_qr.py и вставьте следующий код. Он создаст PNG‑файл с QR‑кодом для URL.

import qrcode

# Данные для QR-кода
data = "https://www.makeuseof.com/"

# Имя выходного файла
QRCodefile = "MUOQRCode.png"

# Генерация QR-кода и сохранение
QRimage = qrcode.make(data)
QRimage.save(QRCodefile)

После выполнения в текущей папке появится MUOQRCode.png.

Кастомизация QR‑кода

Библиотека qrcode позволяет тонко настраивать параметры: версию матрицы, размер коробок (box_size), цвет заливки и фон, толщину границы.

Изменение размера матрицы и box_size

version задаёт «версию» QR‑кода от 1 до 40 (1 ≈ 21×21, 40 ≈ 185×185). Если данных больше, чем вмещает выбранная версия, объект автоматически расширится.

# Пример: указание версии и box_size
import qrcode
import numpy as np

data = "https://www.makeuseof.com/"
QRCodefile = "CustomisedImgBoxQRCode.png"

qrObject = qrcode.QRCode(version=1, box_size=12)
qrObject.add_data(data)
qrObject.make()

image = qrObject.make_image()
image.save(QRCodefile)

print("Size of the QR image(Version):")
print(np.array(qrObject.get_matrix()).shape)

Пример вывода:

Size of the QR image(Version):
(33, 33)

Изменение цвета заливки и фона

# Изменение цвета заливки
import qrcode

data = "https://www.makeuseof.com/"
QRCodefile = "CustomisedFillColorQRCode.png"

qr = qrcode.QRCode()
qr.add_data(data)
qr.make()
image = qr.make_image(fill_color="red")
image.save(QRCodefile)

# Изменение фонового цвета
QRCodefile2 = "CustomisedBGColorQRCode.png"
qr2 = qrcode.QRCode()
qr2.add_data(data)
qr2.make()
image2 = qr2.make_image(back_color="blue")
image2.save(QRCodefile2)

Изменение толщины границы

# Изменение border
import qrcode

data = "https://www.makeuseof.com/"
QRCodefile = "CustomisedBorderQRCode.png"

qr = qrcode.QRCode(border=10)
qr.add_data(data)
qr.make()
image = qr.make_image()
image.save(QRCodefile)

Встраивание логотипа (альтернатива)

Если нужно поместить логотип в центр QR‑кода, лучше сохранять высокое разрешение и аккуратно накладывать изображение логотипа, не закрывая позиции обнаружения. Пример с Pillow:

from PIL import Image
import qrcode

data = "https://example.com/"
qr = qrcode.QRCode(error_correction=qrcode.constants.ERROR_CORRECT_H)
qr.add_data(data)
qr.make()
img_qr = qr.make_image(fill_color="black", back_color="white").convert('RGB')
logo = Image.open('logo.png')

# Подгоняем логотип под размер
box_size = 80  # пиксели для логотипа
logo.thumbnail((box_size, box_size))

w, h = img_qr.size
lw, lh = logo.size
pos = ((w - lw) // 2, (h - lh) // 2)
img_qr.paste(logo, pos, mask=logo if logo.mode=='RGBA' else None)
img_qr.save('qr_with_logo.png')

Примечание: используйте уровень коррекции ошибок ERROR_CORRECT_H или Q, чтобы QR‑код оставался читаемым при наличии логотипа.

Декодирование QR‑кода из файла с помощью OpenCV

OpenCV имеет встроенный детектор QR‑кодов (QRCodeDetector). Пример чтения из файла:

# Импорт библиотеки
import cv2

# Имя файла
filename = "MUOQRCode.png"

# Чтение изображения
image = cv2.imread(filename)

# Инициализация детектора
detector = cv2.QRCodeDetector()

# Детекция и декодирование
data, vertices_array, binary_qrcode = detector.detectAndDecode(image)

if vertices_array is not None:
    print("QRCode data:")
    print(data)
else:
    print("Не удалось распознать QR-код")

Если изображение содержит валидный QR‑код, в консоли появится декодированная строка.

Декодирование в реальном времени через веб‑камеру

Пример сканирования QR‑кода с веб‑камеры:

import cv2

cap = cv2.VideoCapture(0)
detector = cv2.QRCodeDetector()

while True:
    ret, img = cap.read()
    if not ret:
        break

    data, vertices_array, _ = detector.detectAndDecode(img)
    if vertices_array is not None and data:
        print("QR Code detected, data:", data)

    cv2.imshow("img", img)
    if cv2.waitKey(1) == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

Советы для стабильной работы с камерой:

Используйте корректный индекс камеры (0, 1 и т. д.).
Обратите внимание на автояркость и автофокус камеры.
Для мобильных камер можно уменьшить разрешение, чтобы повысить скорость обработки.

Частые причины ошибок и способы их устранения

Низкое разрешение или размытие — увеличить качество изображения или приблизить камеру.
Низкий контраст (цвета близки по яркости) — используйте чёрный/белый или обеспечьте контрастный фон.
Альфа‑канал / прозрачность — конвертируйте PNG в RGB.
Логотип закрывает ключевые маркеры — уменьшите логотип или увеличьте коррекцию ошибок.
Неправильный формат файла — убедитесь, что OpenCV может открыть изображение (cv2.imread возвращает не None).

Альтернативные библиотеки и совместимость

pyzbar — часто используется для декодирования штрих‑кодов и QR и хорошо работает для простых задач.
pylibdmtx — для Data Matrix кодов (не для QR).
ZXing (через обёртки) — кроссплатформенная Java‑библиотека, доступна порой через subprocess.

Миграционные рекомендации: если требуется высокая производительность на сервере, рассмотрите использование серверных сервисов сканирования или нативных библиотек в C++/Java, вызываемых из Python.

Безопасность и конфиденциальность

Не выполняйте автоматически URL‑адреса, полученные из незнакомых QR‑кодов.
Валидируйте и нормализуйте входные данные перед обработкой (проверка схемы, домена, длины и т. д.).
Для конфиденциальных данных шифруйте содержимое QR‑кода и управляйте ключами безопасно.

Важно: QR‑код — это носитель данных, он не гарантирует безопасность передаваемой информации.

Тесты и критерии приёмки

Критерии приёмки для модуля генерации и чтения QR:

Генерация: при подаче X различных строк модуль создаёт X файлов PNG, каждый валиден и считывается инструментом декодирования.
Кастомизация: корректно применяются параметры fill_color, back_color, box_size и border.
Декодирование файла: для N тестовых изображений детектор возвращает ожидаемые строки.
Декодирование с камеры: успешное распознавание при устойчивом кадре и контрасте.

Примеры тест‑кейсов:

Генерация URL, текста, vCard и Wi‑Fi конфигурации — проверка обратного декодирования.
Негативные тесты: повреждённые изображения, сильно затемнённые, частично обрезанные QR.

Роли и чек‑лист перед выпуском

Разработчик:

Реализовать генератор и декодер.
Добавить логирование ошибок и тесты.

QA:

Проверить читабельность при разных размерах и цветах.
Проверить поведение при вставке логотипа.

Ops:

Обеспечить установку системных зависимостей OpenCV.
Настроить CI для автоматических тестов генерации/декодирования.

Когда подход не сработает (ограничения)

Когда требуется сканирование с большого расстояния или очень мелкий код — нужен более крупный модуль/другое оборудование.
При печати на текстурированной поверхности или при сильных деформациях код может стать нечитаемым.

Краткая методика внедрения (Mini‑methodology)

Разработать генератор с параметрами по умолчанию.
Написать набор тестов (генерация → декодирование).
Добавить обработку ошибок и логирование.
Оптимизировать для целевого окружения (сервер/клиент/встраиваемое устройство).
Добавить меры безопасности (валидация, шифрование при необходимости).

1‑строчный глоссарий

QR‑код — двумерный штрих‑код для хранения текстовых данных; быстро читается камерой.
vCard — формат контактной карточки, часто кодируется в QR.
Pillow — современная библиотека для работы с изображениями в Python (замена PIL).

MUO QR пример

Итог

Использование Python и доступных библиотек позволяет быстро добавить поддержку QR‑кодов в проекты: от массовой генерации файлов до онлайн‑сканеров на базе веб‑камеры. Начните с простой генерации, затем поэтапно добавляйте кастомизацию, тестирование и меры безопасности.

Важно: тестируйте на целевых устройствах и в реальных условиях печати/съёмки — это ключ к надёжному распознаванию QR‑кодов.