0
# Hash Conversion and Serialization
1

2
Functions for converting between hash objects and string representations, enabling hash storage, transmission, and restoration. Supports both single hashes and multi-hashes with compatibility for older formats.
3

4
## Capabilities
5

6
### Single Hash Conversion
7

8
Convert ImageHash objects to and from hexadecimal string representations for storage and transmission.
9

10
```python { .api }
11
def hex_to_hash(hexstr):
12
    """
13
    Convert a stored hash (hex string) back to ImageHash object.
14
    
15
    Assumes hashes are bidimensional arrays with dimensions hash_size * hash_size,
16
    or onedimensional arrays with dimensions binbits * 14.
17
    
18
    Args:
19
        hexstr (str): Hexadecimal string representation of hash
20
    
21
    Returns:
22
        ImageHash: Restored hash object
23
    
24
    Note:
25
        Does not work for hash_size < 2
26
    """
27
```
28

29
**Usage Example:**
30

31
```python
32
from PIL import Image
33
import imagehash
34

35
# Generate a hash
36
original_hash = imagehash.phash(Image.open('image.jpg'))
37
print(f"Original: {original_hash}")
38

39
# Convert to string for storage
40
hash_string = str(original_hash)
41
print(f"String: {hash_string}")
42

43
# Restore from string
44
restored_hash = imagehash.hex_to_hash(hash_string)
45
print(f"Restored: {restored_hash}")
46

47
# Verify they're identical
48
assert restored_hash == original_hash
49
assert str(restored_hash) == hash_string
50
```
51

52
### Flat Hash Conversion
53

54
Specialized conversion for colorhash objects which use flat array representations.
55

56
```python { .api }
57
def hex_to_flathash(hexstr, hashsize):
58
    """
59
    Convert hex string to ImageHash for flat array hashes (colorhash).
60
    
61
    Args:
62
        hexstr (str): Hexadecimal string representation
63
        hashsize (int): Hash size parameter used in original colorhash
64
    
65
    Returns:
66
        ImageHash: Restored hash object for colorhash
67
    """
68
```
69

70
**Usage Example:**
71

72
```python
73
# Generate a color hash
74
original_hash = imagehash.colorhash(Image.open('image.jpg'), binbits=3)
75
hash_string = str(original_hash)
76

77
# Restore colorhash (note: need to specify binbits * 14 as hashsize)
78
hashsize = 3 * 14  # binbits * (2 + 12) - colorhash produces 14 segments
79
restored_hash = imagehash.hex_to_flathash(hash_string, hashsize)
80

81
assert restored_hash == original_hash
82
```
83

84
### Multi-Hash Conversion
85

86
Convert ImageMultiHash objects (used in crop-resistant hashing) to and from string representations.
87

88
```python { .api }
89
def hex_to_multihash(hexstr):
90
    """
91
    Convert a stored multihash (hex string) back to ImageMultiHash object.
92
    
93
    Based on hex_to_hash with same limitations:
94
    - Assumes bidimensional arrays with hash_size * hash_size dimensions
95
    - Does not work for hash_size < 2
96
    
97
    Args:
98
        hexstr (str): Comma-separated hex string representation
99
    
100
    Returns:
101
        ImageMultiHash: Restored multi-hash object
102
    """
103
```
104

105
**Usage Example:**
106

107
```python
108
# Generate crop-resistant hash
109
original_hash = imagehash.crop_resistant_hash(
110
    Image.open('image.jpg'),
111
    min_segment_size=500,
112
    segmentation_image_size=1000
113
)
114

115
# Convert to string
116
hash_string = str(original_hash)
117
print(f"Multi-hash: {hash_string}")  # Comma-separated hashes
118

119
# Restore from string
120
restored_hash = imagehash.hex_to_multihash(hash_string)
121

122
assert restored_hash == original_hash
123
assert str(restored_hash) == hash_string
124
```
125

126
### Legacy Format Support
127

128
Support for hash strings generated by ImageHash versions 3.7 and earlier.
129

130
```python { .api }
131
def old_hex_to_hash(hexstr, hash_size=8):
132
    """
133
    Convert old format hash string to ImageHash object.
134
    
135
    For hashes generated by ImageHash up to version 3.7.
136
    For newer versions, use hex_to_hash instead.
137
    
138
    Args:
139
        hexstr (str): Hexadecimal string in old format
140
        hash_size (int): Hash size used when generating (default: 8)
141
    
142
    Returns:
143
        ImageHash: Restored hash object
144
    
145
    Raises:
146
        ValueError: If hex string size doesn't match expected count
147
    """
148
```
149

150
## String Format Details
151

152
### Single Hash Format
153

154
ImageHash objects convert to hexadecimal strings representing the binary hash array:
155

156
```python
157
# Example hash string for 8x8 hash
158
"ffd7918181c9ffff"  # 16 hex characters = 64 bits = 8x8 hash
159
```
160

161
### Multi-Hash Format
162

163
ImageMultiHash objects use comma-separated hash strings:
164

165
```python
166
# Example multi-hash string
167
"ffd7918181c9ffff,7f7f7f7f7f7f7f7f,0f0f0f0f0f0f0f0f"  # 3 segment hashes
168
```
169

170
### Color Hash Format
171

172
Color hashes use flat arrays with different bit arrangements:
173

174
```python
175
# Color hash with binbits=3 has 14 * 3 = 42 bits
176
# Represented as 11 hex characters (44 bits, with 2 padding bits)
177
"7ff3e1c8764"
178
```
179

180
## Practical Storage Examples
181

182
### Database Storage
183

184
```python
185
import sqlite3
186
from PIL import Image
187
import imagehash
188

189
# Setup database
190
conn = sqlite3.connect('image_hashes.db')
191
cursor = conn.cursor()
192
cursor.execute('''
193
    CREATE TABLE IF NOT EXISTS images (
194
        id INTEGER PRIMARY KEY,
195
        filename TEXT,
196
        ahash TEXT,
197
        phash TEXT,
198
        dhash TEXT
199
    )
200
''')
201

202
# Store hashes
203
image = Image.open('photo.jpg')
204
cursor.execute('''
205
    INSERT INTO images (filename, ahash, phash, dhash) 
206
    VALUES (?, ?, ?, ?)
207
''', (
208
    'photo.jpg',
209
    str(imagehash.average_hash(image)),
210
    str(imagehash.phash(image)),
211
    str(imagehash.dhash(image))
212
))
213

214
# Retrieve and restore hashes
215
cursor.execute('SELECT ahash, phash, dhash FROM images WHERE filename = ?', ('photo.jpg',))
216
ahash_str, phash_str, dhash_str = cursor.fetchone()
217

218
restored_ahash = imagehash.hex_to_hash(ahash_str)
219
restored_phash = imagehash.hex_to_hash(phash_str)
220
restored_dhash = imagehash.hex_to_hash(dhash_str)
221
```
222

223
### JSON Serialization
224

225
```python
226
import json
227
import imagehash
228
from PIL import Image
229

230
# Create hash data structure
231
image = Image.open('photo.jpg')
232
hash_data = {
233
    'filename': 'photo.jpg',
234
    'hashes': {
235
        'average': str(imagehash.average_hash(image)),
236
        'perceptual': str(imagehash.phash(image)),
237
        'difference': str(imagehash.dhash(image)),
238
        'crop_resistant': str(imagehash.crop_resistant_hash(image))
239
    }
240
}
241

242
# Save to JSON
243
with open('hashes.json', 'w') as f:
244
    json.dump(hash_data, f)
245

246
# Load and restore hashes
247
with open('hashes.json', 'r') as f:
248
    loaded_data = json.load(f)
249

250
restored_hashes = {
251
    'average': imagehash.hex_to_hash(loaded_data['hashes']['average']),
252
    'perceptual': imagehash.hex_to_hash(loaded_data['hashes']['perceptual']),
253
    'difference': imagehash.hex_to_hash(loaded_data['hashes']['difference']),
254
    'crop_resistant': imagehash.hex_to_multihash(loaded_data['hashes']['crop_resistant'])
255
}
256
```
257

258
## Internal Functions
259

260
### Binary Array to Hex Conversion
261

262
Internal utility function used by ImageHash classes for string conversion.
263

264
```python { .api }
265
def _binary_array_to_hex(arr):
266
    """
267
    Internal function to convert binary array to hexadecimal string.
268
    
269
    Args:
270
        arr (NDArray): Boolean numpy array to convert
271
    
272
    Returns:
273
        str: Hexadecimal string representation
274
    
275
    Note:
276
        This is an internal function not intended for direct use.
277
        Use str(hash_object) instead for hash-to-string conversion.
278
    """
279
```
280

281
## Version Compatibility
282

283
- **Current Format (4.0+)**: Use `hex_to_hash()`, `hex_to_multihash()`, `hex_to_flathash()`
284
- **Legacy Format (≤3.7)**: Use `old_hex_to_hash()` for compatibility
285
- **Breaking Change**: Version 4.0 changed the binary-to-hex implementation due to bugs in earlier versions
286

287
Always specify which version was used to generate stored hashes to ensure correct restoration.