qr 0.5.3 → 0.5.5

package/README.md

@@ -1,12 +1,13 @@
 # paulmillr-qr
 
-Minimal 0-dep QR code generator & reader.
+Minimal 0-dependency QR code generator & reader.
 
 - 🔒 Auditable, 0-dependency
-- 🏞️ Encoding (generating) supports ASCII, term, gif and svg codes
+- 🏎 Fast: [faster](#speed) than all JS implementations
+- 🔍 Reliable: 100MB+ of extensive test vectors ensure correctness
+- 🏞️ Encoding (generating) supports ASCII, term, gif, svg and png codes
 - 📷 Decoding (reading) supports camera feed input, files and non-browser environments
-- 🔍 Extensive tests ensure correctness: 100MB+ of vectors
-- 🪶 14KB (gzipped) for encoding + decoding, 7KB for encoding
+- 🪶 18KB (gzipped) for encoding + decoding, 9KB for encoding
 
 Check out:
 
@@ -52,6 +53,8 @@ const terminalFriendly = encodeQR(txt, 'term'); // 2x larger, all fonts are OK
 const gifBytes = encodeQR(txt, 'gif'); // Uncompressed GIF
 const svgElement = encodeQR(txt, 'svg'); // SVG vector image element
 const array = encodeQR(txt, 'raw'); // 2d array for canvas or other libs
+// import { svgToPng } from 'qr/dom.js';
+// const png = svgToPng(svgElement, 512, 512); // .png, using DOM
 
 // Options
 // Custom error correction level
@@ -135,10 +138,6 @@ function decodeWithExternal() {
   const decoded = decodeQR(parseGIF(gifBytes));
   console.log('decoded(gif)', decoded);
 }
-
-// c) draw gif/svg to browser DOM canvas
-import { svgToPng } from 'qr/dom.js';
-const png = svgToPng(encodeQR('Hello world', 'svg'), 512, 512);
 ```
 
 ### Decoding options
@@ -235,27 +234,29 @@ Future plans:
 
 ## Speed
 
-Benchmarks measured with Apple M2 on MacOS 13 with node.js 19.
+Benchmarks measured with Apple M4 with node.js 25.
 
 ```
-======== encode/ascii ========
-encode/paulmillr x 2,995 ops/sec @ 333μs/op
-encode/qrcode-generator x 6,029 ops/sec @ 165μs/op ± 1.39% (min: 142μs, max: 2ms)
-encode/nuintun x 3,647 ops/sec @ 274μs/op
-======== encode/gif ========
-encode/paulmillr x 2,967 ops/sec @ 337μs/op
-encode/qrcode-generator x 3,486 ops/sec @ 286μs/op
-encode/nuintun x 3,643 ops/sec @ 274μs/op
-======== encode: big ========
-encode/paulmillr x 156 ops/sec @ 6ms/op
-encode/qrcode-generator x 200 ops/sec @ 4ms/op
-encode/nuintun x 223 ops/sec @ 4ms/op
-======== decode ========
-decode/paulmillr x 154 ops/sec @ 6ms/op ± 1.29% (min: 6ms, max: 18ms)
-decode/jsqr x 52 ops/sec @ 18ms/op
-decode/nuintun x 51 ops/sec @ 19ms/op
-decode/instascan x 158 ops/sec @ 6ms/op ± 9.06% (min: 3ms, max: 144ms)======== Decoding quality ========
-blurred(45):  paulmillr-qr=12 (26.66%) jsqr=13 (28.88%) nuintun=13 (28.88%) instascan=11 (24.44%)
+# encode format=ascii
+@paulmillr/qr x 9,050 ops/sec @ 110μs/op
+qrcode-generator x 4,543 ops/sec @ 220μs/op
+nuintun x 3,413 ops/sec @ 292μs/op
+
+# encode format=gif
+@paulmillr/qr x 8,439 ops/sec @ 118μs/op
+qrcode-generator x 2,909 ops/sec @ 343μs/op
+nuintun x 3,470 ops/sec @ 288μs/op
+
+# encode of large qr
+@paulmillr/qr x 334 ops/sec @ 2ms/op
+qrcode-generator x 174 ops/sec @ 5ms/op
+nuintun x 221 ops/sec @ 4ms/op
+
+# decode
+@paulmillr/qr x 662 ops/sec @ 1ms/op
+jsqr x 50 ops/sec @ 19ms/op
+nuintun x 49 ops/sec @ 20ms/op
+instascan x 128 ops/sec @ 7ms/op ± 31.44% (4ms..166ms)
 ```
 
 ## License

package/decode.d.ts

@@ -27,7 +27,21 @@ import { Bitmap } from './index.ts';
 export type FinderPoints = [Pattern, Pattern, Point, Pattern];
 /**
  * Convert to grayscale. The function is the most expensive part of decoding:
- * it takes up to 90% of time. TODO: check gamma correction / sqr.
+ * it takes up to 90% of time.
+ *
+ * Binarization pipeline:
+ * 1. Convert RGB/RGBA image to one luma byte per pixel.
+ * 2. Split the image into 8x8 blocks and collect per-block mean/min/max.
+ * 3. Build a 5x5 neighborhood mean over those block means.
+ * 4. Turn each 8x8 block into bitmap bits using a local cut derived from:
+ *    - the neighborhood mean,
+ *    - the current block statistics,
+ *    - a cheap whole-image color-spread estimate,
+ *    - and, on risky scenes, a local variance field over block means.
+ *
+ * Instead of producing "best looking" thresholding: we produce a
+ * bitmap where finder patterns survive perspective / blur / highlights while
+ * keeping false dark regions low enough for downstream finder selection.
  */
 declare function toBitmap(img: Image): Bitmap;
 type Pattern = Point & {
@@ -43,7 +57,7 @@ declare function detect(b: Bitmap): {
     bits: Bitmap;
     points: FinderPoints;
 };
-declare function decodeBitmap(b: Bitmap, decoder?: (bytes: Uint8Array) => string): string;
+declare function decodeBitmap(b: Bitmap, decoder?: (bytes: Uint8Array, eci: number) => string): string;
 export type DecodeOpts = {
     cropToSquare?: boolean;
     textDecoder?: (bytes: Uint8Array) => string;

package/decode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["src/decode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;EAeE;AACF;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAiC,KAAK,EAAQ,KAAK,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,MAAM,EAAS,MAAM,YAAY,CAAC;AAgB3C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AA2B9D;;;GAGG;AACH,iBAAS,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAwEpC;AAGD,KAAK,OAAO,GAAG,KAAK,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA6I7D,iBAAS,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;CACb,CA8HA;AAoHD,iBAAS,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;CACtB,CAkDA;AA4JD,iBAAS,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAoB,GAAG,MAAM,CAgF7F;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;IAC5C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAChD,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CACtC,CAAC;AAsBF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM,CA8BlE;AAED,eAAe,QAAQ,CAAC;AAGxB,eAAO,MAAM,MAAM,EAAE;IACnB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CAMvB,CAAC"}
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["src/decode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;EAeE;AACF;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAiC,KAAK,EAAQ,KAAK,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,MAAM,EAAS,MAAM,YAAY,CAAC;AA6B3C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAoC9D;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CA2TpC;AAGD,KAAK,OAAO,GAAG,KAAK,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA8K7D,iBAAS,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;CACb,CA8HA;AAoHD,iBAAS,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;CACtB,CA6DA;AAqLD,iBAAS,YAAY,CACnB,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,KAAK,MAAsB,GAClE,MAAM,CAuFR;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;IAC5C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAChD,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CACtC,CAAC;AAsBF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM,CA2BlE;AAED,eAAe,QAAQ,CAAC;AAGxB,eAAO,MAAM,MAAM,EAAE;IACnB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CAMvB,CAAC"}