QR Visualizer는 ISO/IEC 18004 표준을 따라 QR 코드가 어떻게 만들어지고 해석되는지 단계별로 보여주는 교육용 도구입니다.
- Encoding Process: QR 코드 생성 과정 7단계 시각화
- Detection Process: QR 코드 이미지 인식 과정 6단계 시각화
- Decode Process: QR 코드 데이터 디코딩 과정 6단계 시각화
- Frontend: React 19.1.0 with TypeScript
- Build Tool: Vite with experimental React Compiler
- Styling: Tailwind CSS 4.1.8
- Package Manager: Yarn Berry (4.9.2)
- Testing: Vitest 3.2.2 (380개 테스트)
- Utilities: @mobily/ts-belt (함수형 프로그래밍)
- Computer Vision: OpenCV.js (QR 검출 알고리즘)
src/
├── qr-encode/ # QR 코드 인코딩 로직
│ ├── analysis/ # 1단계: 데이터 분석
│ ├── encoding/ # 2단계: 데이터 인코딩
│ ├── error-correction/ # 3단계: 에러 정정
│ ├── message-construction/ # 4단계: 메시지 구성
│ ├── module-placement/ # 5단계: 모듈 배치 (8개 세부 단계)
│ ├── masking/ # 6단계: 마스킹 패턴
│ ├── final-generation/ # 7단계: 최종 QR 생성
│ └── qrPipeline.ts # 전체 파이프라인 통합
├── qr-decode/ # QR 코드 디코딩 로직
│ ├── detect/ # Detection Process (이미지 → tri-state 행렬)
│ │ ├── image-processing/ # 이미지 처리
│ │ ├── binarization/ # 이진화
│ │ ├── finder-detection/ # Finder 패턴 검출
│ │ ├── homography/ # 원근 변환
│ │ ├── sampling/ # 모듈 샘플링
│ │ └── detectPipeline.ts # Detection 파이프라인
│ ├── decode/ # Decode Process (tri-state → 데이터)
│ │ ├── format-extraction/ # 포맷 정보 추출
│ │ ├── version-extraction/ # 버전 정보 추출
│ │ ├── mask-removal/ # 마스크 패턴 제거
│ │ ├── data-reading/ # 데이터 모듈 읽기
│ │ ├── error-correction/ # Reed-Solomon 에러 정정
│ │ ├── data-extraction/ # 데이터 추출 및 디코딩
│ │ └── decodePipeline.ts # Decode 파이프라인
│ └── types.ts # 디코딩 관련 타입
├── components/ # UI 컴포넌트
│ ├── QREncodingProcess.tsx
│ ├── QRDetectProcess.tsx
│ ├── QRDecodeProcess.tsx
│ ├── encode/ # Encoding UI 컴포넌트
│ ├── detect/ # Detection UI 컴포넌트
│ └── decode/ # Decode UI 컴포넌트
└── shared/ # 공통 모듈 (타입, 상수, 유틸리티, 훅)
- Node.js 22 이상
- Yarn Berry (4.9.2)
# 저장소 클론
git clone https://github.com/yongsk0066/qr-visualizer.git
cd qr-visualizer
# 의존성 설치
yarn install
# 개발 서버 시작 (http://localhost:5173)
yarn dev# 프로덕션 빌드
yarn build
# 테스트 실행
yarn test
# 린팅 실행
yarn lint
# TypeScript 타입 검사
yarn tsc --build
# 프로덕션 빌드 미리보기
yarn preview- 교육적 시각화: 각 단계별 상세한 시각적 피드백
- 실시간 처리: 입력 변경 시 즉시 모든 단계 재계산
- 완벽한 표준 준수: ISO/IEC 18004 표준 완벽 구현
- 다양한 입력 방식: 텍스트 입력, 파일 업로드, 카메라, 3D 가상 카메라
- 상호작용적 UI: 각 단계별 설명과 시각화 제공
- 모든 QR 버전 지원: 버전 1-40까지 완벽 지원
총 346개 테스트로 모든 QR 로직을 검증:
- 데이터 분석: 39개
- 데이터 인코딩: 21개
- 에러 정정: 37개
- 메시지 구성: 10개
- 모듈 배치: 77개
- 마스킹 패턴: 19개
- 이미지 처리 및 검출: 20개
- 포맷/버전 추출: 20개
- 마스크 제거 및 데이터 읽기: 21개
- 에러 정정 및 추출: 14개
- 전체 파이프라인 테스트: 62개
- 성능 측정: 6개
- 유틸리티: 13개
모든 7단계 완전 구현:
- 데이터 분석 및 모드 선택
- 데이터 인코딩 (비트 스트림 생성)
- Reed-Solomon 에러 정정
- 최종 메시지 구성
- 모듈 배치 (8개 세부 단계)
- 마스킹 패턴 적용
- 포맷/버전 정보 추가
모든 6단계 완전 구현:
- 이미지 입력 (파일 업로드, 카메라, 가상 카메라)
- 그레이스케일 변환 (ITU-R BT.709 표준)
- 이진화 (Sauvola 적응 임계값)
- Finder 패턴 검출 (OpenCV.js 윤곽선 기반)
- 원근 변환 (Homography with refinement)
- 모듈 샘플링 (tri-state 행렬 생성)
모든 6단계 완전 구현:
- 포맷 정보 추출 (BCH 에러 정정 포함)
- 버전 정보 추출 (v7+ QR 코드)
- 마스크 패턴 제거 (8가지 패턴)
- 데이터 모듈 읽기 (지그재그 패턴)
- Reed-Solomon 에러 정정 (위치 매핑 수정)
- 데이터 추출 (다중 모드 지원)
- 한글(Kanji) 모드 지원: 현재 미구현된 한글 인코딩 모드 추가
- ECI 모드 지원: Extended Channel Interpretation 모드
- Micro QR 코드: 작은 크기의 QR 코드 형식 지원
- 자동 모드 감지: 카메라 모드에서 자동 QR 코드 감지 및 디코딩
- 다국어 지원: UI 및 설명 다국어화
- QR 코드 생성 다운로드: SVG/PNG 형식으로 QR 코드 다운로드
이 프로젝트는 교육적 목적으로 만들어졌으며, 기여를 환영합니다!
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
MIT License - 자세한 내용은 LICENSE 파일을 참고하세요.
이 프로젝트는 다음을 목표로 합니다:
- QR 코드의 내부 구조와 동작 원리 이해
- ISO/IEC 18004 표준의 실제 구현 방법 학습
- 컴퓨터 비전과 오류 정정 알고리즘 체험
- 단계별 시각화를 통한 직관적 학습
- Yongseok JANG - @yongsk0066
- QR 코드 표준을 만든 DENSO WAVE
- 오픈소스 커뮤니티
- 이 프로젝트를 사용하고 피드백을 주신 모든 분들
QR Code is a registered trademark of DENSO WAVE INCORPORATED.