Customization: Error Correction (ECC)
Relevant source files
The following files were used as context for generating this wiki page:Error Correction Capability (ECC) is a fundamental feature of QR codes that allows them to be successfully scanned even when parts of the code are damaged, dirty, or obstructed. In QR-Tool, the ECC level is a key customization option, particularly important when adding a logo, as the logo covers a portion of the QR code's data area. A higher ECC level dedicates a larger portion of the QR code to error correction data, making it more robust but also more dense.
The application provides both manual and automatic control over the ECC level. The "Pro" user interface allows users to select a specific level or use an "AUTO" mode that intelligently chooses the best level based on other settings like logo size and color contrast. This ensures a balance between scannability and visual design.
ECC Configuration
The ECC setting is available in the "Pro" (⚡ Chuyên sâu) UI mode. It allows the user to select from five different options, which are managed in the application's state and persisted in localStorage.
Sources: src/App.jsx:343, src/App.jsx:998-1039
ECC Levels
The user can choose one of four standard ECC levels or an automatic mode. Each level corresponds to a certain percentage of data that can be restored.
| Level | Recovery Capacity | Description |
|---|---|---|
L | ~7% | Low. Creates a less dense QR code, suitable for clean environments without logos. |
M | ~15% | Medium. The standard, recommended level for general use. |
Q | ~25% | Quartile. A more durable level, good for when a small logo is used. |
H | ~30% | High. The most durable level, recommended for large logos or when the QR code might get dirty. |
AUTO | Dynamic | Recommended. Automatically selects the best ECC level based on logo size and color contrast. |
The descriptions are derived from the title attributes of the ECC selection buttons in the UI.
Sources: src/App.jsx:1026-1036, README.md
UI Implementation
The ECC selection is rendered as a group of buttons within the "Pro" mode section. The eccMode state variable, initialized from localStorage, tracks the user's selection.
// src/App.jsx:1011-1038
<div className="space-y-2" role="group" aria-labelledby="ecc-label">
{/* ... */}
<div className="flex flex-wrap gap-2">
{['AUTO', 'L', 'M', 'Q', 'H'].map((e) => (
<button
key={e}
className={`px-3 py-2 sm:py-1.5 rounded-lg text-base sm:text-sm font-medium transition-colors ${
eccMode === e
? 'bg-indigo-600 text-white'
: 'bg-slate-200 hover:bg-slate-300 text-slate-700 dark:bg-slate-700/50 dark:hover:bg-slate-700 dark:text-slate-300'
}`}
onClick={() => setEccMode(e)}
title={
e === 'AUTO'
? 'Tự động chọn theo logo/màu'
: e === 'L'
? 'L ~7%: nhẹ, QR thoáng (không logo)'
: e === 'M'
? 'M ~15%: chuẩn khuyên dùng'
: e === 'Q'
? 'Q ~25%: bền'
: 'H ~30%: rất bền (logo/bo góc/bẩn)'
}
>
{e === 'AUTO' ? 'Tự động' : e}
</button>
))}
</div>
{/* ... */}
</div>
Sources: src/App.jsx:1011-1038
Automatic ECC Selection
When eccMode is set to AUTO, the application uses the pickECC helper function to determine the optimal ECC level. This decision is based on the logo size and the color contrast ratio.
Sources: src/App.jsx:434-437, src/utils/qr-helpers.js:235-242
pickECC Logic
The pickECC function follows a clear set of rules to ensure scannability:
- If the mode is not
AUTO(i.e.,L,M,Q, orH), it returns the user's selected mode directly. - If the logo covers 22% or more of the QR code's area (
logoRatio >= 0.22), it forces the ECC level toH(High). - If the color contrast is poor (
contrastOkis false), it also forces the level toHto compensate. - If a logo is present and covers at least 10% of the area (
logoRatio >= 0.1), it selectsQ(Quartile). - If none of the above conditions are met (e.g., no logo and good contrast), it defaults to
M(Medium).
The following diagram illustrates the logic of the pickECC function.
State Calculation and Data Flow
The final ECC level is calculated within a React.useMemo hook in the App component. This ensures the level is re-calculated only when relevant dependencies (eccMode, scale, contrastRatio) change.
The following sequence diagram shows how a user's action flows through the system to update the QR code's ECC level.
Impact on QR Code Generation
The selected ECC level has two primary effects on the final QR code:
-
Rendering: The final
levelis passed directly to theqrcode.reactlibrary (QRCodeCanvasorQRCodeSVG) via theqrPropsobject. The library uses this value to generate the QR code with the appropriate amount of error correction data.
Sources: src/App.jsx:475, src/components/QrPreview.jsx:45-56 -
Size Suggestion: The ECC level is a factor in the
estimateDimensionfunction, which calculates the recommended pixel size for the QR code. A higher ECC level results in a denser, more complex QR code (more modules), which in turn requires a larger pixel size to ensure each module is distinct and scannable.
Sources: src/App.jsx:439-443, src/utils/qr-helpers.js:249-255
Summary
The Error Correction (ECC) customization is a critical feature in QR-Tool that empowers users to create robust and reliable QR codes. The system's "AUTO" mode simplifies the decision-making process by intelligently selecting the appropriate ECC level based on the presence and size of a logo, as well as color contrast. This ensures that even highly customized QR codes maintain a high degree of scannability, which is the ultimate goal of the tool. The implementation correctly balances user control with automated safeguards.