friendly-img-hash-js 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +145 -0
  2. package/index.js +14 -0
  3. package/package.json +43 -0
package/README.md ADDED
@@ -0,0 +1,145 @@
1
+ # friendly-friendly-img-hash-js
2
+
3
+ A js implementation of https://docs.rs/img_hash/ which itself is based on the work of http://www.hackerfactor.com/.
4
+
5
+ > **NOTE:** If you want a no dependency, bare bones, and synchronous version of this library then check out https://www.npmjs.com/package/img-hash-js-core.
6
+
7
+ # Installation via NPM
8
+
9
+ ```
10
+ npm install friendly-img-hash-js
11
+ ```
12
+
13
+ # Get started quickly
14
+
15
+ Browser example:
16
+
17
+ ```
18
+ import { hash } from 'friendly-img-hash-js';
19
+
20
+ // Construct a hash!
21
+ const result = hash('https://my-sweet-image-url.png');
22
+ ```
23
+
24
+ Nodejs Example:
25
+
26
+ ```
27
+ import { hash } from 'friendly-img-hash-js';
28
+
29
+ // Construct a hash!
30
+ const result = hash('./some/file/on/disk.png');
31
+
32
+ ```
33
+
34
+ # Detailed examples and options
35
+
36
+ You can see all options, including defaults, inside the file [index.js](https://gitlab.com/kobaj/img-hash-js-core/-/blob/main/index.js). Options can be mixed and matched as much as you like!
37
+
38
+ Different output types.
39
+
40
+ ```
41
+ import { hash, Convert } from 'friendly-img-hash-js';
42
+
43
+ // You can specify the output format as one of the following
44
+ // BigInt -> an integer number like 7930450656421763612n
45
+ // Base64 -> a base64 string like KNCo2Uw3LtY=
46
+ // HexString -> a hex string like 6e0e9edaccc85a1c
47
+ // BitArray -> an array of bits like [0, 0, 1, 1, 0, 1, ...]
48
+
49
+ // Example of how to specify that option
50
+ console.log(
51
+ hash(image {
52
+ output: Convert.options.BigInt
53
+ })
54
+ );
55
+
56
+ ```
57
+
58
+ Different hash algorithms.
59
+
60
+ ```
61
+ import { hash, Hash } from 'friendly-img-hash-js';
62
+
63
+ // All of these come from
64
+ // https://github.com/abonander/img_hash/blob/dbfb37f9251fea8f7efeabbb2267ddb1fcd21ca6/src/alg/mod.rs#L20
65
+
66
+ // You can specify the output format as one of the following
67
+ // Mean -> Simple algorithm, not very resiliant
68
+ // Gradient -> Very effective and efficient algorithm, recommended!
69
+ // VerticalGradient -> Same as gradient, but better for tall images
70
+ // DoubleGradient -> Computationally expensive, but may improve results
71
+
72
+ // Example of how to specify that option
73
+ console.log(
74
+ hash(image, {
75
+ algorithm: Hash.options.Gradient
76
+ })
77
+ );
78
+
79
+ ```
80
+
81
+ Enable Discrete Cosine Transform (DCT)
82
+
83
+ ```
84
+ import { hash, DCT } from 'friendly-img-hash-js';
85
+
86
+ const imageBytes = // get your image bytes following the examples above.
87
+
88
+ // You can specify the output format as one of the following
89
+ // None -> do not enable DCT
90
+ // Type2 -> enable DCT, more computation and slightly more robust results
91
+
92
+ // Example of how to specify that option
93
+ console.log(
94
+ hash(image, {
95
+ dct: {
96
+ algorithm: Dct.options.Type2
97
+ }
98
+ })
99
+ );
100
+
101
+ ```
102
+
103
+ If you want to write your own algorithm, you can for any option. Here is an example of writing a custom hash function (MEDIAN) and a custom output function (BinaryString).
104
+
105
+ ```
106
+ import { hash } from 'friendly-img-hash-js';
107
+
108
+ console.log(
109
+ hash(image, {
110
+ // Dimension is required because of custom algorithm
111
+ dimension: (width, height) => ({ width, height }),
112
+ algorithm: (bytes) => {
113
+ const half = Math.floor(bytes.length / 2);
114
+ const median = [...bytes].sort().at(half);
115
+ return bytes.map((b) => b >= median).map((b) => (b ? 1 : 0));
116
+ },
117
+ output: (hashBits) => hashBits.join(''),
118
+ })
119
+ ); // Outputs "001010011001..."
120
+ ```
121
+
122
+ # Comparing Hashes
123
+
124
+ If you want to then compare two hashes, use something like Hamming distance or Levenshtein distance
125
+
126
+ ```
127
+ import { hash, Convert } from 'friendly-img-hash-js';
128
+ import leven from 'leven';
129
+
130
+ const config = { output: Convert.options.BigInt };
131
+
132
+ const result1 = hash(image1, config);
133
+ const result2 = hash(image2, config);
134
+
135
+ if (leven(result1, result2) <= 12) {
136
+ console.log ('Images are very similar!');
137
+ }
138
+ ```
139
+
140
+ # Alternatives
141
+
142
+ The following may fit your usecases better.
143
+
144
+ * [image-hasher](https://www.npmjs.com/package/img-hasher)
145
+ * [blockhash-core](https://www.npmjs.com/package/blockhash-core)
package/index.js ADDED
@@ -0,0 +1,14 @@
1
+ import { hash as coreHash } from 'img-hash-js-core';
2
+ import JIMP from 'jimp';
3
+
4
+ export {
5
+ Grayscale, Resize, Dct, Hash, Convert,
6
+ } from 'img-hash-js-core';
7
+
8
+ // Hash an image!
9
+ // Input is a string to a url, local file, etc of an image
10
+ // See defaultConfig for options.
11
+ export const hash = async (img, userConfig) => {
12
+ const image = await JIMP.read(img);
13
+ return coreHash(image.bitmap.data, image.bitmap.width, image.bitmap.height, userConfig);
14
+ };
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "friendly-img-hash-js",
3
+ "version": "1.0.0",
4
+ "description": "User friendly algorithms for generating image hashes.",
5
+ "main": "index.js",
6
+ "type": "module",
7
+ "scripts": {
8
+ "test": "mocha index.test.js",
9
+ "lint": "eslint src/** index.js index.test.js --no-error-on-unmatched-pattern",
10
+ "lint:fix": "eslint src/** index.js index.test.js --fix"
11
+ },
12
+ "repository": {
13
+ "type": "git",
14
+ "url": "git+ssh://git@gitlab.com/kobaj/img-hash-js.git"
15
+ },
16
+ "keywords": [
17
+ "hash",
18
+ "image",
19
+ "perceptual",
20
+ "similarity",
21
+ "distance",
22
+ "difference"
23
+ ],
24
+ "author": "Kobaj",
25
+ "license": "MIT",
26
+ "bugs": {
27
+ "url": "https://gitlab.com/kobaj/img-hash-js/issues"
28
+ },
29
+ "homepage": "https://gitlab.com/kobaj/img-hash-js#readme",
30
+ "devDependencies": {
31
+ "chai": "^4.3.7",
32
+ "chai-as-promised": "^7.1.1",
33
+ "eslint": "^8.47.0",
34
+ "eslint-config-airbnb-base": "^15.0.0",
35
+ "eslint-plugin-mocha": "^10.1.0",
36
+ "eslint-plugin-prefer-arrow": "^1.2.3",
37
+ "mocha": "^10.2.0"
38
+ },
39
+ "dependencies": {
40
+ "img-hash-js-core": "^1.0.4",
41
+ "jimp": "^0.22.10"
42
+ }
43
+ }