blockhash 1.0.0

A perceptual hashing algorithm for detecting similar images.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# blockhash

[![Crates.io](https://img.shields.io/crates/v/blockhash.svg)](https://crates.io/crates/blockhash)
[![CI status](https://img.shields.io/github/actions/workflow/status/jaehl/blockhash/main.yml)](https://github.com/jaehl/blockhash/actions/workflows/main.yml?query=branch%3Amaster)
[![MIT License](https://img.shields.io/github/license/jaehl/blockhash)](https://github.com/jaehl/blockhash/blob/master/LICENSE)

This is an implementation of the [Blockhash] algorithm for detecting similar images, and can produce 16-, 64-, 144-, and 256-bit
perceptual hashes.

Support for the [`image`] crate is provided by default, but support for any image type can be easily
added.

[Documentation](https://docs.rs/blockhash)

## Usage

```rust
use blockhash::blockhash64;

let img = image::open("images/example.png").unwrap();
let hash = blockhash64(&img);

assert_eq!(hash.to_string(), "c7c48f8989c77e0c");
```

## The Blockhash algorithm

This is a basic outline of how the algorithm works. Note that this explanation uses floating-point
numbers, but the library itself only uses integer operations in order to avoid any rounding errors.

To demonstrate the algorithm, we will calculate the 64-bit hash of the following image:

![](images/example.png)

First we convert it to a grayscale image by taking the average of the red, green, and blue
components:

![](images/example-gray.png)

Then we divide the image into 64 (8×8) blocks and calculate the average brightness for all the
pixels in each block:

![](images/example-blocks.png)

Next, we divide the blocks into 4 horizontal bands and find the median value for each band:

![](images/example-medians.png)

Blocks brighter than the median represent a 1 and blocks darker than the median represent a 0.
This gives us the 64 bits of the hash, read from left to right, top to bottom:

![](images/example-bits.png)

We can represent the hash as a hexadecimal string:

```
c7c48f8989c77e0c
```

## License

This project is licensed under the [MIT license](LICENSE).

[Blockhash]: https://web.archive.org/web/20210827144701/http://blockhash.io/
[`image`]: https://crates.io/crates/image