[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80874":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":24,"lastSyncTime":25,"discoverSource":26},80874,"CardLens","meiukinn\u002FCardLens","meiukinn","QR-based physical card recognition for digital profile display.",null,"Python",42,6,4,0,7,2.54,false,"main",true,[],"2026-06-12 02:04:07","\u003Cdiv align=\"center\">\n\n# CardLens\n\n### QR-based physical card recognition for digital profile display\n\nCardLens is a Python desktop prototype that reads a QR code from a physical card design, loads the matching profile from local JSON data, and displays it as a clean interactive profile card.\n\n![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.9%2B-3776AB?logo=python&logoColor=white)\n![Tkinter](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FUI-Tkinter%20%2B%20ttk-0B6EFD)\n![OpenCV](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FOpenCV-QR%20Detection-5C3EE8?logo=opencv&logoColor=white)\n![Pillow](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FImages-Pillow-2B6CB0)\n![Theme](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTheme-Azure%20ttk%20(MIT)-111827)\n\n\u003Cimg src=\"assets\u002Fdemo_cards\u002Fcardlens_product_showcase_v10.png\" alt=\"CardLens product showcase\" width=\"920\">\n\n\u003C\u002Fdiv>\n\n---\n\n## Overview\n\nCardLens is a Python desktop application that connects a physical card to an interactive digital profile. The idea is that a business card, resume, portfolio should not only contain printed text. By adding a CardLens QR marker, the physical card can open a richer digital profile.\n\n```text\nCard image or webcam frame\n        |\n        v\nOpenCV QR recognition\n        |\n        v\nprofile_id\n        |\n        v\ndata\u002Fprofiles.json\n        |\n        v\nTkinter profile display\n```\n\n## What It Does\n\n- Scans a CardLens QR code from an image file or webcam.\n- Opens the matching profile from `data\u002Fprofiles.json`.\n- Displays profile information in a tabbed Tkinter UI.\n- Lets a user create a new CardLens profile.\n- Generates a QR code for the new profile.\n- Supports an optional About page visual from built-in choices or a custom icon image.\n- Supports an optional showcase image and showcase description.\n- Supports optional extra contact links such as GitHub, Instagram, WhatsApp, WeChat, TikTok, Xiaohongshu, and personal websites.\n- Adds a Contact tab automatically when a profile has more than three contact links.\n- Lets a user save contact details as a `.vcf` vCard.\n- Saves guestbook notes per profile in `data\u002Fguestbook.json`.\n- Lets a user delete saved local profiles.\n- Reveals the main profile content with a small Tkinter `after()` animation.\n\n## Libraries Used\n\nThis project is written in Python. The main libraries and modules used are:\n\n- `tkinter` and `ttk` for the desktop user interface. These are included with standard Python on most installations.\n- `opencv-python` for reading QR codes from image files and webcam frames.\n- `Pillow` for loading, resizing, and displaying images.\n- `qrcode[pil]` for generating new CardLens QR codes.\n- `json` for storing profile data and guestbook notes. This is a built-in Python module.\n- `pathlib` for handling file paths. This is a built-in Python module.\n- `webbrowser` for opening contact links. This is a built-in Python module.\n- Azure ttk theme for the visual style. The theme files are already included in `assets\u002Fazure_ttk_theme\u002F`.\n\nThe external libraries are listed in `requirements.txt`:\n\n```text\nopencv-python>=4.8.0\nPillow>=10.0.0\nqrcode[pil]>=7.4\n```\n\n## Step-by-Step Run Guide\n\nThese steps show how to run CardLens on another laptop.\n\n### 1. Install Python\n\nInstall Python 3.9 or later from:\n\n```text\nhttps:\u002F\u002Fwww.python.org\u002Fdownloads\u002F\n```\n\nDuring installation on Windows, select `Add Python to PATH`.\n\n### 2. Open the project folder\n\nOpen PowerShell or Terminal and move into the CardLens folder:\n\n```bash\ncd CardLens\n```\n\nIf the folder is on the desktop, the command may look like this:\n\n```bash\ncd Desktop\u002FCardLens\n```\n\n### 3. Install the required libraries\n\nRun:\n\n```bash\npip install -r requirements.txt\n```\n\n### 4. Start the program\n\nRun the interactive menu:\n\n```bash\npython main.py\n```\n\nThe menu allows the user to:\n\n- choose an image file\n- use a webcam\n- create a new CardLens profile\n- delete a saved local profile\n- exit the program\n\n### 5. Test with an included demo card image\n\nFrom the menu, choose `Choose Image File`, then select one of these included images:\n\n```bash\nassets\u002Fdemo_cards\u002Fcard_001_qr_front.png\nassets\u002Fdemo_cards\u002Fcard_003_qr_front.png\nassets\u002Fdemo_cards\u002Fcard_004_qr_front.png\n```\n\nThe program should recognize the QR code and open the matching digital profile.\n\n### 6. Optional webcam test\n\nFrom the menu, choose `Use Webcam`.\n\nThe webcam mode works with any camera recognized by the computer as a webcam, such as a laptop camera, USB webcam, or external camera connected through webcam software or a capture card.\n\nPress `Q` or `Esc` to close the webcam window.\n\n### 7. Optional project check\n\nRun this command to check that the main files and demo QR images are working:\n\n```bash\npython run_check.py\n```\n\n## Quick Command Summary\n\nInstall libraries:\n\n```bash\npip install -r requirements.txt\n```\n\nRun the interactive menu:\n\n```bash\npython main.py\n```\n\n## Run Modes\n\nInteractive menu:\n\n```bash\npython main.py\n```\n\nRecognize a card from an image:\n\n```bash\npython main.py --image assets\u002Fdemo_cards\u002Fcard_001_qr_front.png\n```\n\nOther included demo card images:\n\n```bash\npython main.py --image assets\u002Fdemo_cards\u002Fcard_003_qr_front.png\npython main.py --image assets\u002Fdemo_cards\u002Fcard_004_qr_front.png\n```\n\nRecognize a card from webcam:\n\n```bash\npython main.py --webcam\n```\n\nCreate a new CardLens profile:\n\n```bash\npython main.py --create\n```\n\nDelete a saved local profile:\n\n```bash\npython main.py --delete\n```\n\n## Main Features\n\n### QR Recognition\n\nCardLens uses OpenCV's `QRCodeDetector` to read a profile ID from a QR code on the card. The payload must be a CardLens ID such as `CARDLENS:card_001` or `card_001`, so ordinary website QR codes are not treated as profile IDs.\n\n### Profile Creation\n\nCreator mode lets the user enter profile details, choose an optional avatar, choose an optional About page visual, choose an optional showcase image, write an optional showcase description, add optional contact accounts, and generate a new QR code. The QR code can then be added to a self-designed physical business card.\n\nIf a user enters more than three contact links, the creator keeps up to three main links on the Profile tab and places the remaining links on a Contact tab. Each contact field has a Main checkbox so the user can choose which contacts appear first.\n\nFor most social platforms, users can enter short account names instead of full URLs. For example, entering `kinn.meiu` in the Instagram field becomes an Instagram profile link internally, while the UI only shows the platform name. TikTok and Xiaohongshu use URL fields, and the program adds `https:\u002F\u002Fwww.` if the user leaves it out.\n\n### Digital Profile UI\n\nThe recognized profile opens in a Tkinter window using standard `ttk` widgets and the Azure ttk theme. The profile includes:\n\n- Profile tab\n- About tab\n- Optional Showcase tab\n- Optional Contact tab\n- Guestbook tab\n\nThe main profile tab uses a small reveal animation made with Tkinter's `after()` method. This keeps the animation simple and reliable.\n\n### Guestbook\n\nEach profile has its own saved notes. Notes are stored locally in `data\u002Fguestbook.json` and displayed in the Guestbook tab.\n\n### Contact Export\n\nThe Save Contact button exports basic contact details as a `.vcf` file. This can be opened by common contact apps.\n\n## Project Structure\n\n```text\nCardLens\u002F\n+-- main.py\n+-- card_creator.py\n+-- card_recognition.py\n+-- profile_loader.py\n+-- ui_display.py\n+-- window_utils.py\n+-- config.py\n+-- run_check.py\n+-- requirements.txt\n+-- README.md\n+-- data\u002F\n|   +-- profiles.json\n|   +-- guestbook.json\n+-- assets\u002F\n|   +-- azure_ttk_theme\u002F\n|   +-- demo_cards\u002F\n|   +-- qr_codes\u002F\n|   +-- avatars\u002F\n|   +-- about_visuals\u002F\n|   +-- highlights\u002F\n|   +-- icons\u002F\n```\n\n## Technical Highlights\n\n- `Tkinter` and `ttk` for the desktop interface.\n- `OpenCV` for QR code recognition from images and webcam frames.\n- `Pillow` for loading and resizing profile images.\n- `qrcode` for generating profile QR codes.\n- `JSON` for storing profile data and guestbook notes.\n- Object-oriented structure for recognition and UI display classes.\n- Lightweight UI animation with Tkinter `after()`.\n- Basic error handling for missing files, invalid JSON, unknown profile IDs, and webcam cancellation.\n\n## Advanced Concepts Used\n\nThis project applies several programming concepts from COMP9001:\n\n- GUI event handling\n- File input and output\n- JSON data storage\n- Image processing\n- Third-party library integration\n- Functions and classes\n- Simple animation timing with Tkinter `after()`\n- Validation and error handling\n\n## Scope Adjustment\n\nThe original concept described recognizing a predefined physical card. In this submitted prototype, the recognition is implemented through an embedded QR code on the card design.\n\nThis is an intentional scope choice. QR recognition is more reliable for a short classroom demo and allows tutors to test the project using either the included demo image or their own webcam.\n\nFuture versions could replace or extend the QR marker with visual card-art recognition, such as a custom logo marker or ring-code pattern.\n\n## Known Limitations\n\n- QR detection requires a clear and readable QR code.\n- Webcam results depend on camera quality, lighting, and distance.\n- The prototype recognizes the QR marker, not the full printed card artwork.\n- Profiles must exist in `data\u002Fprofiles.json` before they can be opened.\n- Data is stored locally and is not synced online.\n\n## Credits\n\nCardLens application code, profile creation, QR recognition flow, JSON storage, and profile UI logic were implemented for this project.\n\nThis project uses the open-source Azure ttk theme by rdbende under the MIT License. The theme files are stored in `assets\u002Fazure_ttk_theme\u002F`.\n\n## Author\n\nZhiheng Jin  \nCOMP9001 Final Project\n","CardLens 是一个基于 Python 的桌面应用程序，通过识别物理卡片上的二维码来展示相应的数字个人资料。其核心功能包括使用 OpenCV 从图片或摄像头读取二维码，根据二维码中的信息从本地 JSON 文件加载对应的个人资料，并通过 Tkinter 构建的用户界面以清晰且交互性强的方式展示这些资料。此外，它还支持创建新的个人资料、生成二维码、添加多种社交链接等。CardLens 适用于需要将实体名片与丰富的在线个人信息相结合的场景，如商务交流和个人品牌推广，为用户提供了一种便捷的方式来分享和获取更详细的联系信息和个人简介。",2,"2026-06-11 04:02:37","CREATED_QUERY"]