Fixing Changes

Got a review saying the readme is too Ai. So I just wrote a readme from scratch. Cut down the Ai stuff and followed the guide and made this. Also changed the project banner to the terminal preview command cause the reviewer said so.

Final Devlog of v2.0.0 (hopefully)

This is the final devlog that I’ll be posting for v2.0.0 of betterqr. Hopefully you guys will give me some more ideas and features for a future version.

What I did.

Repository Cleanup

• Did a clean full push to the /src and have no uncommited changes.
• Pushed the webiste thats going be hosted on Github Pages.
• Ran some tests.
• Merged the feat/v2.0.0 into main branch.

PyPi Configs

• Changes some paths in links to adjust with the branch merge.
• Modified some automations.

Docs

• Cooked up a release log.
• Did some changes to the README.md and DOCUMENTATION.md

Whats Next?

This what I have been working for around 50 hours. Lets See what happens. Im plannning to maintain this as much as I can.

Grinding

I forgot to devlog so this will be a big one lol. Im currently doing exams so I dont really have alot of time to think through new stuff. I mostly did some bug fixes , optimisation and working on the landing page.

Bug Fixes

• Fixed some bugs related to the PDF output where sometime QR codes overlap and make an error.
• Fixed some bugs related to the command line.
• The frame generation does not work. Im actively working on it but Im not able to fix it yet.

Optimisation

• Have been cutting down extra generation time with unnecssary checks.
• Have imporved alot in the generation time.
• This took the longest.

Docs

• Edited the documentation.md with the new data.
• Edited the readme.md with new stuff.
• Working on a landing page for BetterQR.

I also researched a little bit and asked for peoples opinion on this. Selected around 20 people to test this and give their honest review. Most feedbacks were great. Some requested for features and some found bugs.

Session 5

More Benchmarking

I have benchmarked more and repeatedly to get the accurate data. I used automated and manual tests. I found some people online who were down to help me benchmark it. For now the data isnt fully presentable. Will include in the next devlog or in the readme itself.

New Brand

I have decided on updating our logo. I designed a logo on Canva. I’ll probably use it as the official logo. I went for the purplish theme cause why not. The logo has a futuristic vibe to it ig.

Better Landing Pages.

Im currently working on a landing page for betterQR. The old one is fine but I didnt update it accordingly. So Im going to make a entirely new one. I have been looking for some inspo as well.

Bug Fixing

Did some little bug fixes and code cleanup

The tables does not work on the stardance devlogs, idk why look at the attached image for the formatted table

Benchmarking

This session focuses on benchmarking BetterQR with other popular libraries like segno and qrcode.

How it Compares

This is a rough comparison between BetterQR, qrcode, and segno.

Feature BetterQR qrcode segno Micro QR ✅ M1–M4 ❌ ✅ Kanji Mode ✅ ❌ ✅ Structured Append ✅ ❌ ✅ Logo Embedding ✅ Built-in ❌ (Manual PIL) ❌ (Manual) Module Shapes ✅ 8 Shapes ⚠️ Limited ❌ Gradients ✅ ❌ ❌ Animated GIF ✅ 10 Effects ❌ ❌ Frames & Labels ✅ Built-in ❌ ❌ Structured Data Helpers (WiFi, vCard, …) ✅ ❌ ⚠️ Via plugin

BetterQR’s primary aim is not to aggressively beat other libraries, but to provide a highly capable, reliable, and user-friendly alternative packed with creative options out of the box.

---

Performance Metrics

Payload Performance Benchmarks (2.0.0-rc)

All times are in milliseconds (ms). Lower is better.

| Payload Category | Size / Type | BetterQR | Segno | Standard qrcode | BetterQR Status |

| :— | :— | :—: | :—: | :—: | :— |
| URL | Tiny / Short | 6.88 | 7.19 | 5.90 | 🟢 Beats Segno / Competitive |
| Medium | Standard | 22.44 | 21.89 | 20.03 | 🟡 Ties Segno (~2.5% diff) |
| Large | V40 / Dense | 106.63 | 98.94 | 98.96 | 🔴 Behind by ~8% |
| Very Large | Max Capacity | 209.00 | 197.00 | 204.00 | 🟡 Highly Competitive (~6% diff) |
| SVG (Large) | Vector | 86.63 | ~0.56 | — | 🟡 Meaningful fix (was 104.66) |
| SVG (Very Large)| Vector | 174.19 | ~1.50 | — | 🟡 Meaningful fix (was 211.84) |

Known Limitations / Project Honesty

To build clear engineering trust, here are the current structural limitations of BetterQR compared to older ecosystem veterans:

• Dependency Overhead: Depends heavily on Pillow for its extensive visual layouts and shapes, unlike segno, which is zero-dependency.
• Large Matrix Vectorization: Pure PNG generation lags behind by ~6-8% on maximum matrix dimensions (like V40) due to mask scoring loops running entirely in pure Python.
• Vector Vectorization Limits: While our SVG generation times dropped significantly in the latest release, pure string-building layout engines like segno still massively outperform us on massive vector layouts.
• Format Boundaries: The legacy EPS writer does not support logo embedding.
• Spec Edge Cases: Kanji mode and Structured Append are fully validated for standard QR codes, but are not yet implemented for Micro QR variants. rMQR (Rectangular Micro QR) is currently unsupported.

---

SES-3

This session focuses on bug fixing , CI/CD improvement and some research about new features.

New Features Research

I realized for the past 2 weeks I have not implemented new features, and only fixed bugs and did improvements. I researched a little and looked into other QR libraries and looked for the stuff that the other libraries lack. I decided on some new features like Kanji Mode, there are few but I wont mention them here. (research time isnt logged cause I forgot but it was like an hour)

Bug Fixing

Did some bug fixing with the logo embedding QR code again. Its the only QR code type that fails the most. This time I guarantee it wont fail again.

CI/CD Improvements

Finally I realized for my test workflows I use pyzbar which is a qr code decoding library. But it does not support microqr decoding. So I had to switch to another libray called zxingcpp which does support what pyzbar has with microqr decoding support as well. I took some help from some people online regarding the tests and they help me make some test scripts. I broke down the main test script into smaller parts so Its easier for me and the readers.

Conclusion

Thats it for this session. Its like 95% completed for shipping and logged 50 hours as well. Just some final new features (mentioned above) and some documentation work and It v2 will be released. Thank you for reading the entire thing. I hope you’ll like it and find BetterQR useful. New features / suggestions / complaints are accepted in the replies via a DM on slack. I need some honest feedback.

Bug Patching (SES-2.1)

This will be my last patch of the day.

Bug

• Styled Micro QR codes render wrong: Both the PNG and SVG renderers assume the standard 3-finder layout when deciding what counts as a “finder square” (for shape/color overrides). Micro QR only has one finder (top-left), so modules near the top-right and bottom-left corners get incorrectly forced into squares / finder-color under custom styling.

This isnt fully fixed, Im having some hard time figuring out whats the main core issue. It is somewhat fixed.

Bug Patching (SES-1)

Ran more tests and got feedback from ~15 people. Made them test the commands and try to find bugs. There were many bugs people were available to find. This is session focuses on fixing some of them

Bugs that were fixed

• Micro QR silently corrupts data near capacity limits: In encoder.py, the capacity check treats every Micro QR data codeword as a full 8 bits — but for M1 and M3 symbols, the last data codeword is only a 4-bit nibble per spec. The checker accepts data that’s 4 bits too big, and the extra bits get silently truncated at render time.
• .logo() crashes every time: core.py builds a logo_info dict with a key "padding", but matrix.py leads logo_info["padding_px"] , instant KeyError the moment anyone calls .logo(...).
• Terminal --terminal-style compact output has padding bugs asymmetric left/right padding and a stray extra row, so piping it anywhere that cares about exact dimensions breaks.

There are some more bugs that will be fixed in the next session.

Mega Lock-In

The 9 hours was logged in span of the last week. Didn`t get to devlog due to internet outage here in Sri Lanka.

Bugs Fixed

in core.py

• _hex_to_rgb 3-char hex crash:#000, #FFF, #F00 etc. caused invalid literal for int() with base 16: ''. Added expansion of 3-char to 6-char before parsing

• .logo() crash: 'QR' object has no attribute '_version_size'``logo() tried to compute size_px = int(self._version_size * ratio) but _version_size doesn’t exist on the QR object at call time (the matrix hasn’t been built yet). Fixed to compute size_px lazily inside _get_logo_info() from module_count × box_size × ratio.

• logo(border=True) crash: invalid literal for int() with base 16: 'Tr'The _logo_border attribute stores a bool, but was passed directly as border_color to embed_image() which called _hex_to_rgb(True) → _hex_to_rgb("True") → crash. Fixed to pass "#000000" if self._logo_border else None.

• image_ops.py + animation.py — _hex_to_rgb None guard
  Added if not c: return (0, 0, 0) guard so passing None as a color never crashes.

• The _color() validator didn’t strip surrounding shell-added quotes from color strings like “#FF0000”, causing # to be split off the hex digits. Fixed to strip " and ' before processing.

Changes

• Corrected Micro QR capacity table (all 8 version/ECC combos with accurate numeric/alpha/byte limits)
• Fixed logo() parameter docs (border is bool, not int)- Fixed double ```bash` in installation section
• Corrected SMS encoding protocol note (sms: not smsto:)

Docs

• Added a more detailed info about MicroQR codes to README.md and DOCUMENTATION.md- Made a landing site with help of Claude.

Locking in

Bug hunting has started. I have been looking for any bugs in the hidden corners and have found many of them. Like the embedded logo QR codes throw an error , microQR m4 type just crashes everything,etc. I also have used the library in actual code to test as well.

Landing Page

Used my front-end skills to to the best and locked in and designed a good looking website for BetterQR. Looks fine for now. Will do some changes later. Made it a single page website cause easier load for Github Pages.

(v2 is not out, expect it earlier this week)

Prepping for shipping

I initially planned to release this today, but realized something. The embedded logo thing and microqr is now failing on me. and Im lazy to fix this now so I’ll be fixingit tomorrow.

Making a website

So I thought why not make a website. So Im have been working on a small landing website with vanilla html and probably host it on GitHub Pages as well.

Prepping to ship

Doing stuff related to publishing the new version. Im noy going to be going in details cause Im at school

Fixing failed tests

I have ran multiple CI/CD tests and have noted that most animations and data type qr codes fail. I think its mostly from wrong placements.

• CLI Redirect: Redirect data -> output when a helper flag is active.
• SMS Protocol: Use sms: not smsto:.

_write_format_info function bugs

The _write_format_info function as two major bugs.

• Top-Right: uses bit_idx=i in write_bit (which applies 14-i) but should write (fmt >> i) & 1 (vbit). The bit indices are swapped.
• Bottom Left: Only writes 7 rows (missing row size-8) ad uses wrong bit indices.

These are only like 1/4 of the bugs. These were the easiest to document so listed them here.

Testing and Fixing

After running the new CI/CD Tests most pass but some fail. I traced back the issues and fixed half of them.

Some issues I found

1, Micro QR auto-version: _min_version doesn’t enforce mode compatibility (M1=numeric only, M2=no byte, etc.) and uses wrong mode-indicator bit count in the needed formula.
2. WiFi/Geo/SMS/Phone/Email/VCard: The helper objects need to be passed as str() to QR() — the test is likely calling them directly. The __str__ methods need to produce correct strings, and some may have format issues.
3. Animations: GIF decode — need to verify each frame.
4. small_border: border=1 means only 4px quiet zone which may confuse decoders.

(i have been fixing them but not produce a result yet)

CI/CD

Writing the test scripts from scratch cause the last CI/CD pipelines are kind of glitched. Used claude a little this time to structure it.

More Debugging

Trying to fix some bugs, scrolling through stack overlay rn (yes stack overflow and not ai, IM NOT A BOOMER trust)

Fixing time

I have identified all of the bugs (hopefully) and marked everything that has to be fixed.

Fixed Stuff

• Current bit-stream builder in build_matrix writes all bits including the full 8-bit last data CW, then starts ECC. For M1/M3, the correct order is: 10 data CW (80 bits) + 4-bit partial + 6 ECC CW (48 bits). The current code writes all 17 CW as bits sequentially which gives the WRONG bit order.So I fixed the bit placement in build_matrix for M1/M3
• fixed encode_data to use zero padding for Micro QR and handle the M1/M3 last-4-bit rule.

Need to be fixed

• I need to fix _apply_mask to use Micro QR mask conditions (indices 1,4,6,7 of standard) for micro QR, and add a separate _MICRO_MASK_CONDITIONS list.
• Need to fix the _min_version capacity checker, which has the same wrong cc_bits values

Debugging 2

Finding errors in tables.py

As my last devlog I identified that there is some errors in matrix and table files. I started looking through the table data and found some errors.

• bs.append(mode, 4) — always writes a 4-bit mode indicator. But for Micro QR, mode indicators are 1–4 bits depending on the version, not always 4 bits
• The _data_placement_order function skips col 6 (standard QR timing column). For Micro QR, col 0 is the timing column that should be skipped. But since col 0 and row 0 are already marked as reserved via timing pattern placement, the if not reserved[row][c] check already handles it. The col == 6 skip is only needed because in standard QR col 6 is a function column that isn’t individually reserved — but since we now properly reserve col 0 for Micro QR, it’s already handled. The issue is the function always skips col 6, which in Micro QR is a valid data column.
• The Micro QR format info table has duplicate dict keys, so versions M1-M3 silently get clobbered by M4’s values.

I’m still going through the code to find the errors first, Then I’ll start to fix them one-by-one cause I’m tired of fixing one and get another 2 bugs out of nowhere.

Debugging

After introducing CI/CD Integrations and Test Scripts I have noticed all the generated QR codes fail or unreadable. Im currently tracking the issue behind this. And the main assumption is to something with the src/matrix.py or src/tables.py cause thats the main logic behind the validity. So im curretly digging through the code to find the bugs. I have fixed some of them but when i fix one bug two bug appears. 😭

Alot of progress today

CI/CD Intergration.

Implemented few tests that gets triggered during a push / pull request that tests if the generated QR codes are valid and working as intented. Results are sent to a private discord server via a webhook.

ISO Complying

Working on making the generated QR Codes fully compliant with the ISO Standards.
(attached is a fail qr code LOL)

Made some main changes and reorganization.

• Made a separate file for all the helper classes
• Secure algorithm for sensitive data.
• Researched some more stuff

Working for the V2.0.0

I have successfully released the first version of it. So I have been working on adding some more features for the next version.

MicroQR Support

This is one of the most requested feature here. It is little tricky to make it work. But most logic for this has been programmed.

SVG Optimization

Drastically reduced SVG file size by merging modules into a single element.

Security

Added HMAC-SHA256 signing and bitwise XOR obfuscation to protect sensitive QR data.

Safety

Automatically detects low contrast between foreground and background. Includes auto_fix_contrast to force scannable colors.

First Beta Release

I did my first beta release to PyPI and tested out. It worked pretty well. Got some suggestions from Reddit as well.

Writing Documentation , readme.md and improving the repo structure

Wrote the entire documentation , reamd.md , changelog and contribution.md to improve the repo.

First public release

Release the first official version with some improvements.
Currently working on adding microQR codes and security warnings for Crypto qr codes

First version release on pypi, run pip install betterqr to install. Gotta work on the readme and website now

Completed the base qr engine finally after hours of coding and debugging. Now it can generate basic qr codes with texts and links.

Currently worked on the QR code engine that generates the QR code. Also did some CLI work to make it work. Created some GH workflows as well

Currently writing the core for the package. I have added the basic starter classes like the Wifi QR and contact QR