qr 0.2.3 → 0.4.0

package/LICENSE

@@ -1,21 +1,203 @@
-The MIT License
-
-Copyright (c) 2010 Brian Celenza
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+   

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Paul Miller (https://paulmillr.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,93 +1,277 @@
-# Node QR #
+# paulmillr-qr
 
-node-qr is a simple NodeJS binding to the libqrencode C library written by Kentaro Fukuchi (http://fukuchi.org/works/qrencode/index.en.html).
+Minimal 0-dep QR code generator & reader.
 
-## Installation ##
+- 🔒 Auditable, 0-dependency
+- 🏞️ Encoding (generating) supports ASCII, term, gif and svg codes
+- 📷 Decoding (reading) supports camera feed input, files and non-browser environments
+- 🔍 Extensive tests ensure correctness: 100MB+ of vectors
+- 🪶 35KB for encoding + decoding, 18KB for encoding (1000 lines of code)
 
-To use node-qr, you will first need to install the libqrencode C library
+Check out:
 
-For Mac OS X (assumed MacPorts installed)
+- [paulmillr.com/apps/qr/](https://paulmillr.com/apps/qr/) - interactive demo
+- [qrBTF.com](https://qrbtf.com/en) - uses the library to generate custom, styled codes
+- [cuer](https://github.com/wevm/cuer) - React component based on the library
+- [metamask-sdk](https://github.com/MetaMask/metamask-sdk/blob/3d0ba19610853ec9259bb1aad459b1eaea799375/packages/sdk/package.json#L56) - is using the library
 
-    port install qrencode
-    
-For Ubuntu Linux
+Why other libraries are less optimal:
 
-    apt-get install qrencode
-    
-Others (see instructions on site)
+- [jsQR](https://github.com/cozmo/jsQR) is dead, [zxing-js](https://github.com/zxing-js/) is [dead](https://github.com/zxing-js/library/commit/b797504c25454db32aa2db410e6502b6db12a401), [qr-scanner](https://github.com/nimiq/qr-scanner/) uses jsQR and doesn't work outside of browser, [qcode-decoder](https://github.com/cirocosta/qcode-decoder) is broken version of jsQR and doesn't work outside of browser, [qrcode](https://github.com/nuintun/qrcode) is fork of jsQR without adoption
+- [instascan](https://github.com/schmich/instascan) is too big: over 1MB+ (it's zxing compiled to js via emscripten)
 
-    http://fukuchi.org/works/qrencode/index.en.html
- 
-   
-Node-qr is available in the Node Package Manager (NPM)
+## Usage
 
-    npm install qr
+A standalone file [qr.js](https://github.com/paulmillr/qr/releases) is also available.
 
-## Usage ##
+> `npm install qr`
 
-Currently node-qr only comes with an encoder. The usage is simple
+> `jsr add jsr:@paulmillr/qr`
 
-    encoder.encode(value, path = null, options = {});
+- [Encoding](#encoding)
+- [Decoding](#decoding)
+  - [Decoding options](#decoding-options)
+  - [Decoding algorithm](#decoding-algorithm)
+  - [Decoding test vectors](#decoding-test-vectors)
+  - [DOM helpers for web apps](#dom-helpers-for-web-apps)
+- [Using with Kotlin](#using-with-kotlin)
+- [Security](#security)
+- [Speed](#speed)
 
-First, require the module
+## Encoding
 
-    var Encoder = require('qr').Encoder;
-    var encoder = new Encoder;
+```ts
+import encodeQR from '@paulmillr/qr';
 
-The following example will encode a given value and emit an 'end' event with PNG data upon completion
+// import decodeQR from '@paulmillr/qr/decode';
+// See separate README section for decoding.
 
-    // add an event listener for the 'end' event
-    // which fires upon encoding completion
-    encoder.on('end', function(png_data){
-        // png_data is an instance of Buffer
-        // do something
-    });
-    encoder.encode('some value');
-    
-Alternatively, you can pass a file path for the PNG data to be saved to
+const txt = 'Hello world';
+const ascii = encodeQR(txt, 'ascii'); // Not all fonts are supported
+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
 
-    encoder.on('end', function(){
-        // if you specify a file path, nothing will be passed to the end listener
-        // do something
-    });
-    encoder.encode('some value', '/tmp/my_qr_file.png');
-    
-If at any time an error occurs, an 'error' event will be emitted
+// Options
+// Custom error correction level
+// low: 7%, medium: 15% (default), quartile: 25%, high: 30%
+const highErrorCorrection = encodeQR(txt, 'gif', { ecc: 'high' });
+// Custom encoding: 'numeric', 'alphanumeric' or 'byte'
+const customEncoding = encodeQR(txt, 'gif', { encoding: 'byte' });
+// Default scale is 2: each block is 2x2 pixels.
+const larger = encodeQR(txt, 'gif', { scale: 4 });
+// All options
+// type QrOpts = {
+//   ecc?: 'low' | 'medium' | 'quartile' | 'high';
+//   encoding?: 'numeric' | 'alphanumeric' | 'byte' | 'kanji' | 'eci';
+//   version?: number; // 1..40, QR code version
+//   mask?: number; // 0..7, mask number
+//   border?: number; // Border size, default 2.
+//   scale?: number; // Scale to this number. Scale=2 -> each block will be 2x2 pixels
+// };
 
-    encoder.on('error', function(err){
-        // err is an instance of Error
-        // do something
-    });
-    
-See the tests in test/qr.js for more ways to use the encoder.
+console.log(ascii);
+> █████████████████████████████████████
+> ██ ▄▄▄▄▄ █  ▀▄▄█ ██▀▄▄▄▄█ ▀█ ▄▄▄▄▄ ██
+> ██ █   █ █▀▄▀▄ ▄▄█▄█ ██▀█▀▀█ █   █ ██
+> ██ █▄▄▄█ ██ ▄▄█▄▀▀ ▀ ██ ▄ ▄█ █▄▄▄█ ██
+> ██▄▄▄▄▄▄▄█ ▀ ▀ █▄▀ ▀ ▀▄█ █ █▄▄▄▄▄▄▄██
+> ██ █  ▀ ▄▄▀▀▀ █▀ ▄   ▀▀▄▀ ▄█ ▀█ ▀▄▄██
+> ██▀▀▀  ▀▄▄██▄▀▀▄█▀ ▀▄█    ▀▀▀ ▄ █▄▄██
+> █████▄▀▀▄▄██ ▀ ▀ ▄▄██▄ ▄▄ ▄ █▀█ █ ███
+> ███   ▄▀▄█▄▄▄█   ▀██▄▄▄▀▀█▄▀ ▄█▀ ████
+> ██▀▀ ▄ ▀▄ ▄▄██▀▄▀▀████▄▄▄ █▄ █  █▀▀██
+> ██▀▀▄ ▄▀▄ ▀▀█▄▀▀▄▄▀▀ █▄▄▀█▀ ▀▄ █▄ ▀██
+> ██▀▄▀██ ▄▄ ▀█▄█▀ ▀ ▀█▄▀▀ █▄▀▀ █  █ ██
+> ███▀█▄▀▄▄ █  █ ██ ██ ▄ █ ▄▄▄ ▄▀▀▄▄ ██
+> ██▄█▄▄▄█▄█ ▄ ▄▀█▀▀ ▄▀ █▀ ▄ ▄▄▄ ▀▄▀▄██
+> ██ ▄▄▄▄▄ █ ▄█▄▀▀ ▀█   █▄█  █▄█ ▀▀▄▀██
+> ██ █   █ █▀ ▄▀█ ██ ▄▄▀██   ▄▄ ▄█   ██
+> ██ █▄▄▄█ █▄  ██▀ ▄▄ ▀█ ▄      ▀▄▄█▀██
+> ██▄▄▄▄▄▄▄█▄███▄█▄█▄▄▄▄█▄█▄████▄▄█████
+> ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+```
 
-While node-qr and libqrencode can encode images up to 4000 characters, this library makes no attempt to automatically set error correction and version options based on the size of the value (yet, anyway). You are responsible for determining what length your values will be and adjusting the options accordingly.
+## Decoding
 
-See [2D QR Code Barcode Generation Guide](http://www.idautomation.com/barcode/qr-code.html#Data_Encoded) for more information on limitations of QR Codes and the devices that read them.
-    
-## Encoder Options ##
+GIF reader is not included in the package (it would take a lot of space).
+Decoding raw bitmap is still possible.
 
-The following options can be passed via the third argument of the encode method, which should be an object
+```js
+import encodeQR from '@paulmillr/qr';
+import decodeQR from '@paulmillr/qr/decode';
+import { Bitmap } from '@paulmillr/qr';
 
-* background_color: self explanatory
-* foreground_color: self explanatory
-* dot_size: specify the size of dot (pixel). (default=3)
-* margin: specify the width of margin. (default=4)
-* level: specify error correction level from L (lowest) to H (highest). (default=L)
-* case_sensitive: ignore case distinctions and use only upper-case characters. (default=true)
-* version: specify the version of the symbol. (default=1)
-* type: type of image to export ('PNG','EPS','SVG','ANSI','ANSI256','ASCII','ASCIIi','UTF8','ANSIUTF8')
+// Scale so it would be 100x100 instead of 25x25
+const opts = { scale: 4 };
 
-For more information around options, see the docs provided for the libqrencoder library [here](http://fukuchi.org/works/qrencode/index.en.html "libqrencoder")
+// a) Decode using raw bitmap, dependency-free
+function decodeRawBitmap() {
+  const bmBits = encodeQR('Hello world', 'raw', opts);
+  const bm = new Bitmap({ width: bmBits[0].length, height: bmBits.length });
+  bm.data = bmBits;
+  const decoded = decodeQR(bm.toImage());
+  console.log('decoded(pixels)', decoded);
+}
+/*
+Output:
+decoded(pixels) Hello world
+decoded(gif) Hello world
+*/
 
-## Feedback/Pull Requests ##
+// b) Decode using external GIF decoder
+import gif from 'omggif'; // npm install omggif@1.0.10
+function parseGIF(image) {
+  const r = new gif.GifReader(image);
+  const data = [];
+  r.decodeAndBlitFrameRGBA(0, data);
+  const { width, height } = r.frameInfo(0);
+  return { width, height, data };
+}
+function decodeWithExternal() {
+  const gifBytes = encodeQR('Hello world', 'gif', opts);
+  const decoded = decodeQR(parseGIF(gifBytes));
+  console.log('decoded(gif)', decoded);
+}
 
-Feedback and pull requests are always welcomed. This is a work-in-progress. Any help is greatly appreciated.
+// c) draw gif/svg to browser DOM canvas
+import { svgToPng } from '@paulmillr/qr/dom';
+const png = svgToPng(encodeQR('Hello world', 'svg'), 512, 512);
+```
 
-## Who's Using node-qr? ##
+### Decoding options
 
-* Rax.io (Rackspace Short URL Service) - http://rax.io
+```ts
+export type Point4 = { x: number; y: number }[];
+export type Image = {
+  height: number;
+  width: number;
+  data: Uint8Array | Uint8ClampedArray | number[];
+};
+export type DecodeOpts = {
+  // By default we assume that image has 4 channel per pixel (RGBA). isRGB: true will force to use only one
+  isRGB?: boolean;
+  // Returns 4 center (3 finder pattern + 1 alignment pattern) points if detected
+  detectFn?: (points: Point4) => void;
+  // Returns RGBA image of detected QR code
+  qrFn?: (img: Image) => void;
+};
+export default function decodeQR(img: Image, opts: DecodeOpts = {});
+```
 
-## Are you using node-qr? ##
+### Decoding algorithm
 
-If you are using Node QR in a production environment, I'd love to know! Send me a PM or email if you don't mind being listed in this readme.
+QR code decoding is challenging; it is essentially a computer vision problem. There are two main scenarios:
+
+- Decoding from files: This can be slow because it needs to handle complicated cases such as blur or rotation.
+- Decoding from a camera feed: This must be fast; even if one frame fails, the next frame can succeed.
+
+The state-of-the-art approach for this, as with other computer vision problems, is using neural networks. However, using them would make the library hard to audit. Additionally, since JavaScript can't access hardware accelerators, it would likely be very slow. We also avoid using WebGL because it is complex and exposes users to fingerprinting.
+
+The implemented reader algorithm is inspired by [ZXing](https://github.com/zxing/zxing):
+
+1. `toBitmap`: Convert the image to a bitmap of black and white segments. This is the slowest part and the most important.
+2. `detect`: Find three finder patterns and one alignment pattern (for versions > 1). This is tricky—they can be rotated and distorted by perspective. A square might appear as a quadrilateral with unknown size. The best we can do is count runs of the same color and select patterns with almost the same ratio of runs.
+3. `transform`: Once patterns have been found, correct the perspective and transform the quadrilateral into a square.
+4. `decodeBitmap`: Execute the encoding in reverse: read information via a zig-zag pattern, de-interleave bytes, correct errors, convert to bits, and finally, read segments from bits to create the string.
+5. **Finished!**
+
+### Decoding test vectors
+
+To test our QR code decoding, we use an excellent dataset
+from [BoofCV](http://boofcv.org/index.php?title=Performance:QrCode). BoofCV decodes 73% of the test cases,
+while ZXing decodes 49%. Our implementation is nearly at parity with ZXing, primarily because ECI (Extended
+Channel Interpretation) support is not yet included. The test vectors are preserved in a Git repository at
+[github.com/paulmillr/qr-code-vectors](https://github.com/paulmillr/qr-code-vectors).
+
+**Note for Testing on iOS Safari:** Accessing the camera on iOS Safari requires HTTPS. This means that the file: protocol or non-encrypted http cannot be used. Ensure your testing environment uses https:.
+
+The QR code specification is available for purchase at [iso.org](https://www.iso.org/standard/62021.html) for 200 CHF.
+
+### DOM helpers for web apps
+
+Check out `dom.ts` for browser-related camera code that would make your apps simpler.
+
+## Using with Kotlin
+
+```kotlin
+@JsModule("@paulmillr/qr")
+@JsNonModule
+external object Qr {
+    @JsName("default")
+    fun encodeQR(text: String, output: String = definedExternally, opts: dynamic = definedExternally): Uint8Array
+}
+
+// then
+val bytes = Qr.encodeQR("text", "gif", js("{ scale: 10 }"))
+val blob = Blob(arrayOf(bytes), BlobPropertyBag("image/gif"))
+val imgSrc = URL.createObjectURL(blob)
+```
+
+## Security
+
+There are multiple ways a single text can be encoded in a QR code, which can lead to potential security implications:
+
+- **Segmentation Differences:** For example, `abc123` can be encoded as:
+  `[{type: 'alphanum', data: 'abc'}, {type: 'num', data: '123'}]` or `[{type: 'alphanum', data: 'abc123'}]`
+- **Mask Selection Algorithms:** Different libraries may use different algorithms for mask selection.
+- **Default Settings:** Variations in error correction levels and how many bits are stored before upgrading versions.
+
+If an adversary can access multiple QR codes generated from a specific library, they may be able to fingerprint the user. This fingerprinting could be used to exfiltrate data from air-gapped systems. In such cases, the adversary would need to create a library-specific exploit.
+
+We mitigate these risks by:
+
+- **Cross-Testing:** We currently cross-test against python-qrcode, which is closer to the specification
+  than some JavaScript implementations.
+- **Single Segment Encoding:** We always use single-segment encoding.
+  While this may not be the most optimal for performance, it reduces the amount of fingerprinting data.
+
+Future plans:
+
+- **Testing Against Multiple Libraries:** To further improve security and reduce fingerprinting, we can
+  cross-test against three to four popular libraries.
+
+## Speed
+
+Benchmarks measured with Apple M2 on MacOS 13 with node.js 19.
+
+```
+======== encode/ascii ========
+encode/paulmillr-qr x 1,794 ops/sec @ 557μs/op
+encode/qrcode-generator x 3,128 ops/sec @ 319μs/op ± 1.12% (min: 293μs, max: 3ms)
+encode/nuintun x 1,872 ops/sec @ 533μs/op
+======== encode/gif ========
+encode/paulmillr-qr x 1,771 ops/sec @ 564μs/op
+encode/qrcode-generator x 1,773 ops/sec @ 563μs/op
+encode/nuintun x 1,883 ops/sec @ 530μs/op
+======== encode: big ========
+encode/paulmillr-qr x 87 ops/sec @ 11ms/op
+encode/qrcode-generator x 124 ops/sec @ 8ms/op
+encode/nuintun x 143 ops/sec @ 6ms/op
+======== decode ========
+decode/paulmillr-qr x 96 ops/sec @ 10ms/op ± 1.39% (min: 9ms, max: 32ms)
+decode/jsqr x 34 ops/sec @ 28ms/op
+decode/nuintun x 35 ops/sec @ 28ms/op
+decode/instascan x 79 ops/sec @ 12ms/op ± 6.73% (min: 9ms, max: 223ms)
+======== Decoding quality ========
+blurred(45):  paulmillr-qr=12 (26.66%) jsqr=13 (28.88%) nuintun=13 (28.88%) instascan=11 (24.44%)
+```
+
+## License
+
+Copyright (c) 2023 Paul Miller (paulmillr.com)
+
+Copyright (c) 2019 ZXing authors
+
+The library @paulmillr/qr is dual-licensed under the Apache 2.0 OR MIT license.
+You can select a license of your choice.
+
+The library contains code inspired by [ZXing](https://github.com/zxing/zxing), which is licensed under Apache 2.0.
+
+The license to the use of the QR Code stipulated by JIS (Japanese Industrial Standards) and the ISO are not necessary.
+The specification for QR Code has been made available for use by any person or organization. (Obtaining QR Code Specification)
+The word “QR Code” is registered trademark of DENSO WAVE INCORPORATED in Japan and other countries.
+To use the word “QR Code” in your publications or web site, etc, please indicate a sentence QR Code is registered trademark of DENSO WAVE INCORPORATED.
+This registered trademark applies only for the word “QR Code”, and not for the QR Code pattern (image).
+(https://www.qrcode.com/en/faq.html)

package/decode.d.ts

@@ -0,0 +1,62 @@
+/*!
+Copyright (c) 2023 Paul Miller (paulmillr.com)
+The library paulmillr-qr is dual-licensed under the Apache 2.0 OR MIT license.
+You can select a license of your choice.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+/**
+ * Methods for decoding (reading) QR code patterns.
+ * @module
+ * @example
+```js
+
+```
+ */
+import type { Image, Point } from './index.js';
+import { Bitmap } from './index.js';
+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.
+ */
+declare function toBitmap(img: Image): Bitmap;
+type Pattern = Point & {
+    moduleSize: number;
+    count: number;
+};
+declare function findFinder(b: Bitmap): {
+    bl: Pattern;
+    tl: Pattern;
+    tr: Pattern;
+};
+declare function detect(b: Bitmap): {
+    bits: Bitmap;
+    points: FinderPoints;
+};
+declare function decodeBitmap(b: Bitmap): string;
+export type DecodeOpts = {
+    cropToSquare?: boolean;
+    pointsOnDetect?: (points: FinderPoints) => void;
+    imageOnBitmap?: (img: Image) => void;
+    imageOnDetect?: (img: Image) => void;
+    imageOnResult?: (img: Image) => void;
+};
+export declare function decodeQR(img: Image, opts?: DecodeOpts): string;
+export default decodeQR;
+export declare const _tests: {
+    toBitmap: typeof toBitmap;
+    decodeBitmap: typeof decodeBitmap;
+    findFinder: typeof findFinder;
+    detect: typeof detect;
+};
+//# sourceMappingURL=decode.d.ts.map