{"id":28951921,"url":"https://github.com/yongsk0066/qr-visualizer","last_synced_at":"2026-05-09T06:35:15.056Z","repository":{"id":300612496,"uuid":"998154749","full_name":"yongsk0066/qr-visualizer","owner":"yongsk0066","description":"QR 코드 생성 및 디코딩 과정을 단계별로 시각화하는 교육용 React 애플리케이션 🎓","archived":false,"fork":false,"pushed_at":"2025-11-25T00:05:57.000Z","size":40224,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-23T00:09:18.404Z","etag":null,"topics":["computer-vision","education","educational-tool","iso-18004","opencv","qr-code","react","reed-solomon","typescript","visualization"],"latest_commit_sha":null,"homepage":"https://yongsk0066.github.io/qr-visualizer/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yongsk0066.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-08T01:27:53.000Z","updated_at":"2025-11-20T15:31:17.000Z","dependencies_parsed_at":"2025-06-22T18:39:46.600Z","dependency_job_id":null,"html_url":"https://github.com/yongsk0066/qr-visualizer","commit_stats":null,"previous_names":["yongsk0066/qr-visualizer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yongsk0066/qr-visualizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yongsk0066%2Fqr-visualizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yongsk0066%2Fqr-visualizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yongsk0066%2Fqr-visualizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yongsk0066%2Fqr-visualizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yongsk0066","download_url":"https://codeload.github.com/yongsk0066/qr-visualizer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yongsk0066%2Fqr-visualizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32809836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision","education","educational-tool","iso-18004","opencv","qr-code","react","reed-solomon","typescript","visualization"],"created_at":"2025-06-23T16:01:14.366Z","updated_at":"2026-05-09T06:35:14.784Z","avatar_url":"https://github.com/yongsk0066.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QR Visualizer\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"src/assets/mascot.gif\" width=\"240\" height=\"240\" alt=\"QR Visualizer Mascot\"\u003e\n  \n  QR 코드 생성 및 디코딩 과정을 단계별로 시각화하여 교육하는 React 웹 애플리케이션입니다.\n  \n  🔗 **[Live Demo](https://yongsk0066.github.io/qr-visualizer/)**\n\u003c/div\u003e\n\n## 📋 프로젝트 개요\n\n**QR Visualizer**는 ISO/IEC 18004 표준을 따라 QR 코드가 어떻게 만들어지고 해석되는지 단계별로 보여주는 교육용 도구입니다.\n\n### 주요 기능\n\n- **Encoding Process**: QR 코드 생성 과정 7단계 시각화\n- **Detection Process**: QR 코드 이미지 인식 과정 6단계 시각화\n- **Decode Process**: QR 코드 데이터 디코딩 과정 6단계 시각화\n\n## 🚀 기술 스택\n\n- **Frontend**: React 19.1.0 with TypeScript\n- **Build Tool**: Vite with experimental React Compiler\n- **Styling**: Tailwind CSS 4.1.8\n- **Package Manager**: Yarn Berry (4.9.2)\n- **Testing**: Vitest 3.2.2 (380개 테스트)\n- **Utilities**: @mobily/ts-belt (함수형 프로그래밍)\n- **Computer Vision**: OpenCV.js (QR 검출 알고리즘)\n\n## 📁 프로젝트 구조\n\n```\nsrc/\n├── qr-encode/              # QR 코드 인코딩 로직\n│   ├── analysis/           # 1단계: 데이터 분석\n│   ├── encoding/           # 2단계: 데이터 인코딩\n│   ├── error-correction/   # 3단계: 에러 정정\n│   ├── message-construction/ # 4단계: 메시지 구성\n│   ├── module-placement/   # 5단계: 모듈 배치 (8개 세부 단계)\n│   ├── masking/           # 6단계: 마스킹 패턴\n│   ├── final-generation/  # 7단계: 최종 QR 생성\n│   └── qrPipeline.ts      # 전체 파이프라인 통합\n├── qr-decode/             # QR 코드 디코딩 로직\n│   ├── detect/            # Detection Process (이미지 → tri-state 행렬)\n│   │   ├── image-processing/  # 이미지 처리\n│   │   ├── binarization/      # 이진화\n│   │   ├── finder-detection/  # Finder 패턴 검출\n│   │   ├── homography/        # 원근 변환\n│   │   ├── sampling/          # 모듈 샘플링\n│   │   └── detectPipeline.ts  # Detection 파이프라인\n│   ├── decode/            # Decode Process (tri-state → 데이터)\n│   │   ├── format-extraction/    # 포맷 정보 추출\n│   │   ├── version-extraction/   # 버전 정보 추출\n│   │   ├── mask-removal/         # 마스크 패턴 제거\n│   │   ├── data-reading/         # 데이터 모듈 읽기\n│   │   ├── error-correction/     # Reed-Solomon 에러 정정\n│   │   ├── data-extraction/      # 데이터 추출 및 디코딩\n│   │   └── decodePipeline.ts     # Decode 파이프라인\n│   └── types.ts           # 디코딩 관련 타입\n├── components/            # UI 컴포넌트\n│   ├── QREncodingProcess.tsx\n│   ├── QRDetectProcess.tsx\n│   ├── QRDecodeProcess.tsx\n│   ├── encode/            # Encoding UI 컴포넌트\n│   ├── detect/            # Detection UI 컴포넌트\n│   └── decode/            # Decode UI 컴포넌트\n└── shared/               # 공통 모듈 (타입, 상수, 유틸리티, 훅)\n```\n\n## 🚀 시작하기\n\n### 요구사항\n\n- Node.js 22 이상\n- Yarn Berry (4.9.2)\n\n### 설치 및 실행\n\n```bash\n# 저장소 클론\ngit clone https://github.com/yongsk0066/qr-visualizer.git\ncd qr-visualizer\n\n# 의존성 설치\nyarn install\n\n# 개발 서버 시작 (http://localhost:5173)\nyarn dev\n```\n\n### 기타 명령어\n\n```bash\n# 프로덕션 빌드\nyarn build\n\n# 테스트 실행\nyarn test\n\n# 린팅 실행\nyarn lint\n\n# TypeScript 타입 검사\nyarn tsc --build\n\n# 프로덕션 빌드 미리보기\nyarn preview\n```\n\n## 🎨 주요 특징\n\n- **교육적 시각화**: 각 단계별 상세한 시각적 피드백\n- **실시간 처리**: 입력 변경 시 즉시 모든 단계 재계산\n- **완벽한 표준 준수**: ISO/IEC 18004 표준 완벽 구현\n- **다양한 입력 방식**: 텍스트 입력, 파일 업로드, 카메라, 3D 가상 카메라\n- **상호작용적 UI**: 각 단계별 설명과 시각화 제공\n- **모든 QR 버전 지원**: 버전 1-40까지 완벽 지원\n\n## 🧪 테스트 현황\n\n총 **346개** 테스트로 모든 QR 로직을 검증:\n\n### 인코딩 테스트 (202개)\n\n- 데이터 분석: 39개\n- 데이터 인코딩: 21개\n- 에러 정정: 37개\n- 메시지 구성: 10개\n- 모듈 배치: 77개\n- 마스킹 패턴: 19개\n\n### 디코딩 테스트 (75개)\n\n- 이미지 처리 및 검출: 20개\n- 포맷/버전 추출: 20개\n- 마스크 제거 및 데이터 읽기: 21개\n- 에러 정정 및 추출: 14개\n\n### 통합 및 성능 테스트 (69개)\n\n- 전체 파이프라인 테스트: 62개\n- 성능 측정: 6개\n- 유틸리티: 13개\n\n## 🏗️ 구현 현황\n\n### ✅ Encoding Process (완료)\n\n모든 7단계 완전 구현:\n\n1. 데이터 분석 및 모드 선택\n2. 데이터 인코딩 (비트 스트림 생성)\n3. Reed-Solomon 에러 정정\n4. 최종 메시지 구성\n5. 모듈 배치 (8개 세부 단계)\n6. 마스킹 패턴 적용\n7. 포맷/버전 정보 추가\n\n### ✅ Detection Process (완료)\n\n모든 6단계 완전 구현:\n\n1. 이미지 입력 (파일 업로드, 카메라, 가상 카메라)\n2. 그레이스케일 변환 (ITU-R BT.709 표준)\n3. 이진화 (Sauvola 적응 임계값)\n4. Finder 패턴 검출 (OpenCV.js 윤곽선 기반)\n5. 원근 변환 (Homography with refinement)\n6. 모듈 샘플링 (tri-state 행렬 생성)\n\n### ✅ Decode Process (완료)\n\n모든 6단계 완전 구현:\n\n1. 포맷 정보 추출 (BCH 에러 정정 포함)\n2. 버전 정보 추출 (v7+ QR 코드)\n3. 마스크 패턴 제거 (8가지 패턴)\n4. 데이터 모듈 읽기 (지그재그 패턴)\n5. Reed-Solomon 에러 정정 (위치 매핑 수정)\n6. 데이터 추출 (다중 모드 지원)\n\n## 🆕 향후 추가 예정 기능\n\n- **한글(Kanji) 모드 지원**: 현재 미구현된 한글 인코딩 모드 추가\n- **ECI 모드 지원**: Extended Channel Interpretation 모드\n- **Micro QR 코드**: 작은 크기의 QR 코드 형식 지원\n- **자동 모드 감지**: 카메라 모드에서 자동 QR 코드 감지 및 디코딩\n- **다국어 지원**: UI 및 설명 다국어화\n- **QR 코드 생성 다운로드**: SVG/PNG 형식으로 QR 코드 다운로드\n\n## 🤝 기여하기\n\n이 프로젝트는 교육적 목적으로 만들어졌으며, 기여를 환영합니다!\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## 📄 라이선스\n\nMIT License - 자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.\n\n## 🎯 교육적 목표\n\n이 프로젝트는 다음을 목표로 합니다:\n\n- QR 코드의 내부 구조와 동작 원리 이해\n- ISO/IEC 18004 표준의 실제 구현 방법 학습\n- 컴퓨터 비전과 오류 정정 알고리즘 체험\n- 단계별 시각화를 통한 직관적 학습\n\n## 👥 만든 사람\n\n- **Yongseok JANG** - [@yongsk0066](https://github.com/yongsk0066)\n\n## 🙏 감사의 말\n\n- QR 코드 표준을 만든 DENSO WAVE\n- 오픈소스 커뮤니티\n- 이 프로젝트를 사용하고 피드백을 주신 모든 분들\n\n---\n\n_QR Code is a registered trademark of DENSO WAVE INCORPORATED._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyongsk0066%2Fqr-visualizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyongsk0066%2Fqr-visualizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyongsk0066%2Fqr-visualizer/lists"}