jsqr - npm Package Compare versions

Comparing version 0.2.2 to 1.0.0

package.json

 {
   "name": "jsqr",
-  "version": "0.2.2",
-  "description": "QR code detection, extraction, decoding and parsing written as pure JS port of the ZXing library.",
+  "version": "1.0.0",
+  "description": "A pure javascript QR code reading library that takes in raw images and will locate, extract and parse any QR code found within.",
   "repository": "https://github.com/cozmo/jsQR",
   "main": "./dist/jsQR.js",
+  "types": "./dist/index.d.ts",
   "contributors": [
@@ -19,13 +20,32 @@ {
   "devDependencies": {
-    "mocha": "^2.3.4",
-    "ts-loader": "^0.7.2",
-    "ts-node": "^0.5.4",
-    "typescript": "^1.7.3",
-    "webpack": "^1.12.9"
+    "@types/fs-extra": "^4.0.2",
+    "@types/jest": "^20.0.8",
+    "@types/node": "^8.0.27",
+    "awesome-typescript-loader": "^3.2.3",
+    "fs-extra": "^4.0.1",
+    "jest": "^20.0.4",
+    "ts-jest": "^20.0.14",
+    "ts-node": "^3.3.0",
+    "tslint": "^5.7.0",
+    "typescript": "^2.5.2",
+    "upng-js": "^1.0.1",
+    "webpack": "^3.10.0"
   },
   "scripts": {
-    "build": "node ./node_modules/webpack/bin/webpack.js",
-    "watch": "node ./node_modules/webpack/bin/webpack.js --watch",
-    "test": "node ./node_modules/mocha/bin/mocha --require ts-node/register ./test/test-*.ts"
+    "build": "./node_modules/.bin/webpack",
+    "watch": "./node_modules/.bin/webpack --watch",
+    "test": "./node_modules/.bin/jest",
+    "lint": "tslint --project .",
+    "generate-test-data": "node_modules/.bin/ts-node --project tests/ tests/generate-test-data.ts"
+  },
+  "jest": {
+    "testRegex": ".*test.ts",
+    "moduleFileExtensions": [
+      "ts",
+      "js"
+    ],
+    "transform": {
+      "^.+\\.ts$": "<rootDir>/node_modules/ts-jest/preprocessor.js"
+    }
   }
 }

README.md

@@ -5,24 +5,12 @@ # jsQR
 
-A pure javascript port of the [ZXing](https://github.com/zxing/zxing) QR parsing library.
-This library takes in raw images and will locate, extract and parse any QR codes found within.
-It also exposes methods to do each step of the process individually.
-This allows piecemeal use and custom extension, for example you can use this library to parse pure QR codes (without extracting from an image), or to locate QR codes within an image without parsing them.
+A pure javascript QR code reading library.
+This library takes in raw images and will locate, extract and parse any QR code found within.
 
-[See a demo](https://s3-us-west-2.amazonaws.com/templaedhel/jsQR/features.html)
+[Demo](https://cozmo.github.io/jsQR)
 
-## Motivation
 
-This library was written because there were no javascript QR code parsing libraries that were well maintained and capable of parsing any reasonably complex QR codes.
+## Installation
 
-[See how jsQR compares to other JS QR code decoders](https://s3-us-west-2.amazonaws.com/templaedhel/jsQR/comparison.html)
+### NodeJS
 
-[ZXing](https://github.com/zxing/zxing) is the best QR code library, and had been ported to many languages, but not to Javascript.
-jsQR is a fully featured port of the QR code portions of the zxing library, with the goal of growing into a maintainable and extendable QR parsing library in pure javascript.
-
-## Documentation
-
-### Installation
-
-#### NodeJS
-
 ```
@@ -33,6 +21,12 @@ npm install jsqr --save
 ```javascript
-jsQR = require("jsqr");
+// ES6 import
+import jsQR from "jsqr";
+
+// CommonJS require
+const jsQR = require("jsqr");
+
+jsQR(...);
 ```
 
-#### Browser
+### Browser
 
@@ -43,141 +37,45 @@ Include [`jsQR.js`](./dist/jsQR.js).
 <script src="jsQR.js"></script>
+<script>
+  jsQR(...);
+</script>
 ```
 
-You can also use module loaders such as [requireJS](http://requirejs.org/) or [browserify](http://browserify.org/)
+## Usage
 
-### Usage
+jsQR exports a method that takes in 3 arguments representing the image data you wish to decode.
 
-qrJS exports methods for each step in the QR recognition, extraction and decoding process, as well as a convenience wrapper method.
-
-#### Examples
-
-Using the wrapper method
 ```javascript
-var decoded = jsQR.decodeQRFromImage(data, width, height);
-```
+const code = jsQR(imageData, width, height);
 
-Using the individual methods
-```javascript
-var binarizedImage = binarizeImage(data, width, height);
-var location = locateQRInBinaryImage(binarizedImage);
-if (!location) {
-  return;
+if (code) {
+  console.log("Found QR code", code);
 }
-var rawQR = extractQRFromBinaryImage(binarizedImage, location);
-if (!rawQR) {
-  return;
-}
-
-console.log(decodeQR(rawQR));
 ```
 
-[Working example of parsing a webcam feed](https://s3-us-west-2.amazonaws.com/templaedhel/jsQR/example.html)
+### Arguments
+- `imageData` - An `Uint8ClampedArray` of RGBA pixel values in the form `[r0, g0, b0, a0, r1, g1, b1, a1, ...]`.
+As such the length of this array should be `4 * width * height`.
+This data is in the same form as the [`ImageData`](https://developer.mozilla.org/en-US/docs/Web/API/ImageData) interface, and it's also [commonly](https://www.npmjs.com/package/jpeg-js#decoding-jpegs) [returned](https://github.com/lukeapage/pngjs/blob/master/README.md#property-data) by node modules for reading images.
+- `width` - The width of the image you wish to decode.
+- `height` The height of the image you wish to decode.
 
-### Methods
+### Return value
+If a QR is able to be decoded the library will return an object with the following keys.
 
-#### qrJS.decodeQRFromImage(data, width, height)
+- `binaryData` - `Uint8ClampedArray` - The raw bytes of the QR code.
+- `data` - The string version of the QR code data.
+- `location` - An object with keys describing key points of the QR code. Each key is a point of the form `{x: number, y: number}`.
+Has points for the following locations.
+  - Corners - `topRightCorner`/`topLeftCorner`/`bottomRightCorner`/`bottomLeftCorner`;
+  - Finder patterns - `topRightFinderPattern`/`topLeftFinderPattern`/`bottomLeftFinderPattern`
+  - May also have a point for the `bottomRightAlignmentPattern` assuming one exists and can be located.
 
-`decodeQRFromImage` is a wrapper method for the different steps of the QR decoding process.
-It takes in a RGBA image and returns a string representation of the data encoded within any detected QR codes.
+Because the library is written in [typescript](http://www.typescriptlang.org/) you can also view the [type definitions](./dist/index.d.ts) to understand the API.
 
-##### Arguments
-- `data` - An 1d array of numbers representing an RGBA image in the form `r1, g1, b1, a1, r2, g2, b2, a2,...`. This is the same form as the [`ImageData`](https://developer.mozilla.org/en-US/docs/Web/API/ImageData) type returned by the `.getImageData()` call when reading data from a canvas element.
-- `width` - The width of the image.
-- `height` The height of the image.
-
-`data.length` should always be equal to `width * height * 4`.
-
-#### qrJS.binarizeImage(data, width, height)
-
-Binarizing an image (converting it to an image where pixels are either back or white, not grey) is the first step of the process.
-binarizeImage takes in a RGBA image and returns a [`BitMatrix`](#bitmatrices) representing the binarized form of that image.
-
-##### Arguments
-- `data` - An 1d array of numbers representing an RGBA image in the form `r1, g1, b1, a1, r2, g2, b2, a2,...`. This is the same form as the [`ImageData`](https://developer.mozilla.org/en-US/docs/Web/API/ImageData) type returned by the `.getImageData()` call when reading data from a canvas element.
-- `width` - The width of the image.
-- `height` The height of the image.
-
-`data.length` should always be equal to `width * height * 4`.
-
-#### qrJS.locateQRInBinaryImage(image)
-
-`locateQRInBinaryImage` takes in a [`BitMatrix`](#bitmatrices) representing a binary image (as output by [`binarizeImage`](#qrjsbinarizeimagedata-width-height)) and returns the location of a QR code if one is detected.
-
-##### Arguments
-- `image` - a [`BitMatrix`](#bitmatrices) representing a binary image (as output by [`binarizeImage`](#qrjsbinarizeimagedata-width-height))
-
-##### Returns
-`locateQRInBinaryImage` returns `null` if no QR is found, else it returns an object with the following structure
-
-```javascript
-{
-  bottomLeft: {
-    x: number,
-    y: number
-  },
-  topLeft: {
-    x: number,
-    y: number
-  },
-  topRight: {
-    x: number,
-    y: number
-  }
-}
-```
-The coordinates represent the pixel locations of the QR's corner points.
-
-#### qrJS.extractQRFromBinaryImage(image, location)
-
-`extractQRFromBinaryImage` takes in a [`BitMatrix`](#bitmatrices) representing a binary image (as output by [`binarizeImage`](#qrjsbinarizeimagedata-width-height)) and the location of a QR code. It returns a [`BitMatrix`](#bitmatrices) representing the raw QR code.
-
-##### Arguments
-- `image` - a [`BitMatrix`](#bitmatrices) representing a binary image (as output by [`binarizeImage`](#qrjsbinarizeimagedata-width-height))
-- `location` - The location of a QR code, as returned by [`locateQRInBinaryImage`](#qrjslocateqrinbinaryimageimage)
-
-##### Returns
-`extractQRFromBinaryImage` a [`BitMatrix`](#bitmatrices) representing the extracted QR code. The matrix is size `N` by `N` where `N` is the number of "blocks" along the edge of the QR code.
-
-#### qrJS.decodeQR(qrCode)
-
-`decodeQR` takes in a [`BitMatrix`](#bitmatrices) representing a raw QR code (as output by [`extractQRFromBinaryImage`](#qrjsextractqrfrombinaryimageimage-location)) and returns a string of decoded data. It is the last step in the QR decoding process.
-
-##### Arguments
-- `qrCode` - a [`BitMatrix`](#bitmatrices) representing a raw QR code (as output by [`extractQRFromBinaryImage`](#qrjsextractqrfrombinaryimageimage-location))
-
-#### BitMatrices
-
-Throughout the QR extraction and decoding process data is often represented as a `BitMatrix`.
-BitMatrices are a convenient way to represent and interact with a 2d array of booleans.
-
-##### Properties
-- `width` - The width of the matrix.
-- `height` - The height of the matrix.
-- `data` - The underlying data (represented as a 1d array)
-
-##### Methods
-- `get(x, y)` - Get the bit at specific coordinates.
-- `set(x, y, bit)` - Set the bit at specific coordinates.
-
-#### qrJS.createBitMatrix(data, width)
-`createBitMatrix` is a convenience method for creating bit matrices.
-
-##### Arguments
-- `data` - A 1d array of booleans representing the data represented by the bit matrix.
-- `width` - The width of the matrix (height is inferred by `data.length / width`).
-
-## State of the library
-jsQR was originally written by porting over the ZXing C# library directly to typescript.
-This lead to code that works extremely well, but may not follow best javascript practices.
-
-The next steps (which are ongoing) are to port over any test cases (writing any that don't exist), and refactor each of the modules into more idomatic code.
-The end goal is a pure JS library QR library that is as fully featured as the ZXing library, but maintainable and extendable in it's own right.
-
 ## Contributing
 
 jsQR is written using [typescript](http://www.typescriptlang.org/).
-You can view the development source in the `src` directory.
+You can view the development source in the [`src`](./src) directory.
 
-Currently the library is very untested, but tests are being added as the library is refactored into more maintainable code.
-Tests can be run via
+Tests can be run with
 
@@ -188,2 +86,6 @@ ```
 
+The test suite is several hundred images that can be found in the [test-data/](./test-data/images) folder.
+
+Not all the images can be read. In general changes should hope to increase the number of images that read. However due to the nature of computer vision some changes may cause images that pass to start to fail and visa versa. To update the expected outcomes run `npm run-script generate-test-data`. These outcomes can be evaluated in the context of a PR to determine if a change improves or harms the overall ability of the library to read QR codes.
+
 After testing any changes, you can compile the production version by running
@@ -190,0 +92,0 @@ ```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Number of low quality alerts

1

decreased by-50%

Worsened metrics

Total package byte prevSize

276826

decreased by-42.23%

Dev dependency count

12

increased by140%

Number of package files

4

decreased by-91.3%

Lines of code

9909

decreased by-10.55%

Number of lines in readme file

96

decreased by-50.52%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes