imghash 1.2.0

Image hashing for Rust
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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

# `imghash` - Image Hashing for Rust

![Crates.io Version](https://img.shields.io/crates/v/imghash)
[![Main](https://github.com/YannickAlex07/imghash-rs/actions/workflows/main.yaml/badge.svg)](https://github.com/YannickAlex07/imghash-rs/actions/workflows/main.yaml)

- [`imghash` - Image Hashing for Rust](#imghash---image-hashing-for-rust)
  - [Usage](#usage)
    - [Quickstart](#quickstart)
    - [Custom Hashers](#custom-hashers)
  - [Python Compatability](#python-compatability)

`imghash` is a crate that allows you to generate different hashes for images. The following hashes can be generated using this crate:

* [Average Hash](./docs/average.md)
* [Difference Hash](./docs/difference.md)
* [Perceptual Hash](./docs/perceptual.md)

## Usage

There are multiple ways how to utilize `imghash` depending on your use case.

### Quickstart

The easy way to use `imghash` is by using the provided utility functions which assume reasonable defaults.

```rust
use imghash::{average_hash, difference_hash, perceptual_hash};

let path = Path::new("path/to/my/image");

let average = average_hash(path);
let difference = difference_hash(path);
let perceptual = perceptual_hash(path);
```

Each of these functions return a `Result<ImageHash, String>`-type. The `ImageHash` object is essentially a container for the encoded bit matrix of the image (learn more [here](./docs/encoding.md)). The `ImageHash` can be encoded into hexadecimal string by calling the encode method:

```rust
let res: String = hash.encode();
```

### Custom Hashers

If you need more flexibility, for example getting a larger bit matrix, you can use a custom Hasher instance.

For each hash type the crate provides a custom hasher, here for the example we will use the `AverageHasher`:

```rust
use imghash::{average::AverageHasher};

let path = Path::new("path/to/my/image");

let hasher = AverageHasher {
  width: 10,
  height: 10,
};

let hash = hasher.hash_from_path(path);
```

Hasher instances also allow you to create hashes for already loaded images:

```rust
let img = ImageReader::open(...);

let hasher = AverageHasher { ..Default::default() };

let hash = hasher.hash_from_img(&img);
```

Each hasher also implements the `Default`-trait, allowing you to create them with their default values:

```rust
let hasher = AverageHasher { ..Default::default() };
```

## Python Compatability

One of the major factors that drove development of this crate was the need to have a hasher implementation that matches the [`imagehash`-package](https://pypi.org/project/ImageHash/) for Python.

A future Python-wrapper for this crate is already on the roadmap, to allow a replacement of the `imagehash`-package.

As of Version 1.2.0 all hashes generated by this crate should match hashes generated by `imagehash` - however it is not guaranteed for any other package or crate. Previous version of this crate (<1.2.0) were **not** generated the same hashes. To make sure you are generating the same hashes, set the color space of the hasher to `REC601`, as this will make sure the same grayscaling as Pillow is used - this is configured as the default.