파이썬 `qrcode` 라이브러리를 활용한 QR 코드 생성 및 해독
QR 코드(Quick Response Code)는 빠른 정보 응답을 가능하게 하는 2차원 바코드의 한 형태로, 모바일 결제, 전자 티켓, 정보 공유 등 다양한 디지털 환경에서 핵심적인 역할을 수행하고 있습니다. 파이썬 개발 환경에서는 qrcode 라이브러리를 사용하여 이러한 QR 코드를 손쉽게 생성할 수 있으며, 생성된 QR 코드 이미지는 Pillow와 pyzbar 라이브러리의 조합을 통해 그 내용을 해독할 수 있습니다. 이 문서에서는 해당 라이브러리들을 활용하여 QR 코드 생성과 해독의 기본 원리 및 실용적인 예제를 소개합니다.
필수 라이브러리 설치
본격적인 작업에 앞서, QR 코드 생성 및 해독에 필요한 라이브러리들을 설치해야 합니다. 명령 프롬프트나 터미널에서 다음 pip 명령어를 실행하여 설치를 완료합니다.
pip install qrcode Pillow pyzbar
여기서 qrcode는 QR 코드 이미지 생성 로직을 담당하며, Pillow는 파이썬에서 이미지 파일을 다루는 데 사용되는 라이브러리입니다. 그리고 pyzbar는 QR 코드 및 다양한 바코드 형식의 이미지 데이터를 분석하고 해독하는 기능을 제공합니다.
간단한 QR 코드 이미지 생성
qrcode 라이브러리를 이용하면 최소한의 코드로 텍스트나 URL을 QR 코드 이미지로 변환할 수 있습니다. 다음 파이썬 코드는 특정 웹사이트 주소와 간단한 메시지를 각각 별개의 QR 코드 이미지 파일로 저장하는 예시입니다.
import qrcode
def generate_basic_qr_image(payload_data: str, output_path: str):
"""
주어진 문자열 데이터를 QR 코드로 인코딩하여 이미지 파일로 저장합니다.
:param payload_data: QR 코드에 담을 원본 문자열 데이터 (예: URL, 일반 텍스트)
:param output_path: 생성될 QR 코드 이미지 파일의 저장 경로 및 파일명 (예: 'my_website_qr.png')
"""
try:
# qrcode.make() 함수는 기본 설정을 사용하여 QR 코드 객체를 생성하고 이미지를 반환합니다.
qr_graphic = qrcode.make(payload_data)
qr_graphic.save(output_path)
print(f"'{output_path}' 경로에 QR 코드가 성공적으로 생성되었습니다.")
except Exception as e:
print(f"QR 코드 생성 중 예외 발생: {e}")
# 예제 1: 구글 웹사이트 링크를 QR 코드로 생성
target_url = "https://www.google.com"
url_qr_filename = "google_link_qr.png"
generate_basic_qr_image(target_url, url_qr_filename)
# 예제 2: 단순 텍스트 메시지를 QR 코드로 생성
simple_text = "Python으로 만드는 QR 코드 예제!"
text_qr_filename = "python_text_qr.png"
generate_basic_qr_image(simple_text, text_qr_filename)
이 코드를 실행하면 현재 스크립트가 실행되는 디렉토리에 google_link_qr.png와 python_text_qr.png 두 개의 이미지 파일이 생성됩니다. 생성된 QR 코드는 스마트폰 등의 스캐너 앱을 통해 내용을 확인할 수 있습니다.
QR 코드 이미지로부터 데이터 해독
생성된 QR 코드 이미지 파일로부터 원본 데이터를 다시 추출하는 과정은 Pillow와 pyzbar 라이브러리를 통해 처리됩니다. 다음 코드는 이미지 파일 내의 QR 코드를 스캔하여 인코딩된 문자열을 출력하는 함수를 보여줍니다.
from PIL import Image
from pyzbar.pyzbar import decode as pyzbar_decode
import os # 파일 존재 여부 확인을 위한 os 모듈 임포트
def extract_data_from_qr_image(image_filepath: str) -> str:
"""
지정된 이미지 파일에서 QR 코드를 찾아 그 내용을 해독하여 반환합니다.
:param image_filepath: 해독할 QR 코드 이미지 파일의 경로
:return: 해독된 문자열 데이터; QR 코드를 찾지 못했거나 오류 발생 시 빈 문자열
"""
if not os.path.exists(image_filepath):
print(f"오류: '{image_filepath}' 파일을 찾을 수 없습니다. 경로를 확인해주세요.")
return ""
try:
# Pillow를 사용하여 이미지 파일을 엽니다.
image_object = Image.open(image_filepath)
# pyzbar.decode() 함수로 이미지에서 바코드/QR 코드를 스캔하고 디코딩합니다.
decoded_results = pyzbar_decode(image_object)
if decoded_results:
# 첫 번째로 발견된 QR 코드의 데이터를 UTF-8 형식으로 디코딩하여 반환
return decoded_results[0].data.decode('utf-8')
else:
print(f"'{image_filepath}' 파일에서 유효한 QR 코드를 찾을 수 없습니다.")
return ""
except Exception as e:
print(f"QR 코드 해독 중 예외 발생: {e}")
return ""
# 예제 1: 이전에 생성한 URL QR 코드 해독
decoded_url_content = extract_data_from_qr_image("google_link_qr.png")
if decoded_url_content:
print(f"해독된 URL: {decoded_url_content}")
# 예제 2: 이전에 생성한 텍스트 QR 코드 해독
decoded_text_content = extract_data_from_qr_image("python_text_qr.png")
if decoded_text_content:
print(f"해독된 텍스트: {decoded_text_content}")
# 존재하지 않는 파일에 대한 해독 시도
extract_data_from_qr_image("non_existent_qr.png")
이 함수는 이미지 파일을 읽고 pyzbar_decode를 호출하여 이미지 내의 QR 코드 데이터를 추출합니다. pyzbar는 이미지 내의 여러 QR 코드 또는 바코드를 동시에 감지할 수 있으며, 이 경우 decoded_results 리스트에 각 코드가 포함됩니다.
세부 설정을 통한 QR 코드 맞춤형 생성
qrcode 라이브러리의 QRCode 클래스를 활용하면 QR 코드의 시각적 속성(크기, 테두리, 색상) 및 데이터 복원력(오류 정정 수준)을 더욱 세밀하게 제어할 수 있습니다. 이는 특정 브랜드 가이드라인을 따르거나, 훼손에 강한 QR 코드를 만들고자 할 때 유용합니다.
import qrcode
def generate_custom_qr_code(data_payload: str, output_filename: str,
pixel_box_size: int = 10, border_modules: int = 4,
error_level=qrcode.constants.ERROR_CORRECT_L,
fill_color_hex: str = "black", background_color_hex: str = "white"):
"""
사용자 정의 설정을 적용하여 QR 코드 이미지를 생성하고 저장합니다.
:param data_payload: QR 코드에 인코딩할 데이터
:param output_filename: 생성될 이미지 파일의 이름 (예: 'custom_qr.png')
:param pixel_box_size: QR 코드 내 각 '모듈' (작은 정사각형)의 픽셀 크기 (기본값: 10)
:param border_modules: QR 코드 주변 테두리의 두께 (모듈 단위, 기본값: 4)
:param error_level: 오류 정정 수준 (L, M, Q, H 중 선택, 기본값: L)
:param fill_color_hex: QR 코드의 데이터 부분 색상 (HTML 색상 코드, 기본값: 검정)
:param background_color_hex: QR 코드의 배경 색상 (HTML 색상 코드, 기본값: 흰색)
"""
qr_config = qrcode.QRCode(
version=1, # QR 코드 버전 (1-40, None 설정 시 데이터 양에 따라 자동 선택)
error_correction=error_level,
box_size=pixel_box_size,
border=border_modules,
)
qr_config.add_data(data_payload)
qr_config.make(fit=True) # 데이터에 맞게 QR 코드 크기를 자동으로 조정
# make_image를 호출하여 색상 설정이 적용된 이미지를 생성합니다.
custom_image = qr_config.make_image(fill_color=fill_color_hex, back_color=background_color_hex)
custom_image.save(output_filename)
print(f"사용자 정의 QR 코드 '{output_filename}'이(가) 성공적으로 생성되었습니다.")
# 예제 1: 높은 오류 정정 수준과 청록색 QR 코드
generate_custom_qr_code(
"이 코드는 높은 오류 정정 수준을 가집니다.",
"high_error_correction_qr.png",
error_level=qrcode.constants.ERROR_CORRECT_H, # 최고 오류 정정 수준 (30% 복원)
fill_color_hex="teal",
background_color_hex="#E0FFFF", # 연한 하늘색 배경
pixel_box_size=12
)
# 예제 2: 두꺼운 테두리와 작은 모듈 크기를 가진 QR 코드
generate_custom_qr_code(
"두꺼운 테두리와 특정 메시지.",
"thick_border_small_modules_qr.png",
border_modules=8, # 8 모듈 두께의 테두리
pixel_box_size=6, # 각 모듈 6x6 픽셀
fill_color_hex="darkgreen"
)
error_correction 매개변수는 QR 코드의 손상에 대한 복원력을 지정합니다. ERROR_CORRECT_L(약 7% 복원), M(약 15%), Q(약 25%), H(약 30%) 중에서 선택할 수 있습니다. 오류 정정 수준이 높을수록 QR 코드에 더 많은 복원 데이터가 추가되어 코드의 크기가 커지게 됩니다.
QR 코드 라이브러리 사용 시 고려사항 및 대안
qrcode 라이브러리는 대부분의 QR 코드 생성 요구사항을 충족하지만, 특정 시나리오에서는 몇 가지 제한사항이나 다른 라이브러리가 더 적합할 수 있습니다.
데이터 용량과 QR 코드 크기
QR 코드는 저장할 수 있는 데이터의 양에 제한이 있습니다. 데이터 양이 증가하면 QR 코드의 버전(복잡도)이 높아지고 물리적인 크기가 커져, 스캔이 어렵거나 가독성이 저하될 수 있습니다. 매우 방대한 데이터를 인코딩해야 한다면 QR 코드보다는 Data Matrix와 같은 다른 2차원 바코드 형식을 고려해야 할 수도 있습니다.
오류 정정 수준과 효율성
오류 정정 수준을 높이면 QR 코드가 물리적으로 손상되더라도 데이터를 복원할 가능성이 커지지만, 이는 코드 내에 추가적인 중복 데이터를 포함시키므로 QR 코드의 전체 크기를 증가시킵니다. 따라서 데이터 용량과 훼손 방지 능력 사이에서 적절한 균형을 찾는 것이 중요합니다.
유용한 다른 라이브러리들
pyzbar: QR 코드 및 다양한 바코드 해독에 특화된 파이썬 라이브러리입니다. 본 문서의 해독 예제에서 사용되었으며, 이미지에서 여러 바코드를 효율적으로 감지하고 디코딩할 수 있습니다.PyQRCode(GitHub):qrcode와 마찬가지로 QR 코드 생성을 위한 파이썬 라이브러리입니다. SVG나 EPS와 같은 벡터 그래픽 형식으로 QR 코드를 출력하는 데 강점이 있으며,qrcode와는 다른 방식의 커스터마이징 옵션을 제공하기도 합니다.- ZXing (Zebra Crossing) (GitHub): 구글에서 개발한 오픈소스 다중 포맷 1D/2D 바코드 이미지 처리 라이브러리입니다. 주로 Java 및 C++ 기반이지만, 다양한 언어의 포팅 버전이나 래퍼 라이브러리를 통해 파이썬에서도 강력한 바코드 및 QR 코드 생성/해독 기능을 활용할 수 있습니다.