Note

Go to the end to download the full example code.

Demonstration of Image Encoder for 2D spatial data encoding.

This demo showcases the ImageEncoder, which encodes 2D images (grayscale, RGB, RGBA) into hypervectors by binding spatial positions with pixel values. This is particularly useful for:

  • Image classification and recognition

  • Image similarity search

  • Pattern matching

  • Computer vision applications

  • Texture analysis

The encoder supports: - Grayscale images (2D or 3D with 1 channel) - RGB color images (3 channels) - RGBA images with transparency (4 channels) - Automatic pixel normalization - Different VSA models (MAP, FHRR, HRR, BSC)

 23 from holovec import VSA
 24 from holovec.encoders import ImageEncoder, ThermometerEncoder, FractionalPowerEncoder
 25 import numpy as np
 26
 27
 28 def print_section(title):
 29     """Print a section header."""
 30     print(f"\n{'=' * 70}")
 31     print(f"{title}")
 32     print('=' * 70)
 33
 34
 35 def demo_basic_grayscale():
 36     """Demonstrate basic grayscale image encoding."""
 37     print_section("Demo 1: Basic Grayscale Image Encoding")
 38
 39     model = VSA.create('MAP', dim=10000, seed=42)
 40     scalar_enc = ThermometerEncoder(model, min_val=0, max_val=1, n_bins=256, seed=42)
 41     encoder = ImageEncoder(model, scalar_enc, normalize_pixels=True, seed=42)
 42
 43     print(f"\nEncoder: {encoder}")
 44
 45     # Small grayscale image
 46     image = np.array([[100, 150, 200],
 47                       [150, 200, 250],
 48                       [200, 250, 255]], dtype=np.uint8)
 49
 50     hv = encoder.encode(image)
 51
 52     print(f"\nInput image shape: {image.shape}")
 53     print(f"Pixel values range: [{image.min()}, {image.max()}]")
 54     print(f"Encoded hypervector shape: {hv.shape}")
 55     print(f"Input type: {encoder.input_type}")
 56
 57
 58 def demo_rgb_encoding():
 59     """Demonstrate RGB color image encoding."""
 60     print_section("Demo 2: RGB Color Image Encoding")
 61
 62     model = VSA.create('MAP', dim=10000, seed=42)
 63     scalar_enc = ThermometerEncoder(model, min_val=0, max_val=1, n_bins=256, seed=42)
 64     encoder = ImageEncoder(model, scalar_enc, seed=42)
 65
 66     # Create a simple RGB gradient
 67     rgb_image = np.zeros((5, 5, 3), dtype=np.uint8)
 68     rgb_image[:, :, 0] = 255  # Red channel
 69     rgb_image[:, :, 1] = np.linspace(0, 255, 25).reshape(5, 5).astype(np.uint8)  # Green gradient
 70     rgb_image[:, :, 2] = 128  # Blue constant
 71
 72     hv = encoder.encode(rgb_image)
 73
 74     print(f"\nRGB image shape: {rgb_image.shape}")
 75     print(f"Red channel: all {rgb_image[0, 0, 0]}")
 76     print(f"Green channel: gradient 0-255")
 77     print(f"Blue channel: all {rgb_image[0, 0, 2]}")
 78     print(f"\nEncoded hypervector shape: {hv.shape}")
 79     print(f"Input type: {encoder.input_type}")
 80
 81
 82 def demo_image_similarity():
 83     """Demonstrate image similarity analysis."""
 84     print_section("Demo 3: Image Similarity Analysis")
 85
 86     model = VSA.create('MAP', dim=10000, seed=42)
 87     scalar_enc = ThermometerEncoder(model, min_val=0, max_val=1, n_bins=256, seed=42)
 88     encoder = ImageEncoder(model, scalar_enc, seed=42)
 89
 90     # Create three images with varying similarity
 91     img1 = np.ones((5, 5), dtype=np.uint8) * 100
 92     img2 = np.ones((5, 5), dtype=np.uint8) * 105  # Slightly different
 93     img3 = np.ones((5, 5), dtype=np.uint8) * 200  # Very different
 94
 95     hv1 = encoder.encode(img1)
 96     hv2 = encoder.encode(img2)
 97     hv3 = encoder.encode(img3)
 98
 99     sim_1_2 = float(model.similarity(hv1, hv2))
100     sim_1_3 = float(model.similarity(hv1, hv3))
101
102     print("\nImage 1: uniform intensity 100")
103     print("Image 2: uniform intensity 105 (slightly different)")
104     print("Image 3: uniform intensity 200 (very different)")
105
106     print(f"\nSimilarity (img1 vs img2): {sim_1_2:.3f}")
107     print(f"Similarity (img1 vs img3): {sim_1_3:.3f}")
108
109     print("\nKey insight:")
110     print("  Images with similar pixel values have higher similarity")
111
112
113 def demo_pattern_recognition():
114     """Demonstrate pattern recognition in images."""
115     print_section("Demo 4: Simple Pattern Recognition")
116
117     model = VSA.create('MAP', dim=10000, seed=42)
118     scalar_enc = ThermometerEncoder(model, min_val=0, max_val=1, n_bins=256, seed=42)
119     encoder = ImageEncoder(model, scalar_enc, seed=42)
120
121     # Create simple patterns
122     horizontal = np.zeros((7, 7), dtype=np.uint8)
123     horizontal[3, :] = 255  # Horizontal line
124
125     vertical = np.zeros((7, 7), dtype=np.uint8)
126     vertical[:, 3] = 255    # Vertical line
127
128     diagonal = np.zeros((7, 7), dtype=np.uint8)
129     for i in range(7):
130         diagonal[i, i] = 255  # Diagonal line
131
132     hv_h = encoder.encode(horizontal)
133     hv_v = encoder.encode(vertical)
134     hv_d = encoder.encode(diagonal)
135
136     print("\nPattern Library:")
137     print("  - Horizontal line")
138     print("  - Vertical line")
139     print("  - Diagonal line")
140
141     # Test with similar pattern
142     test_horizontal = np.zeros((7, 7), dtype=np.uint8)
143     test_horizontal[3, :] = 200  # Slightly dimmer horizontal line
144     hv_test = encoder.encode(test_horizontal)
145
146     sim_h = float(model.similarity(hv_test, hv_h))
147     sim_v = float(model.similarity(hv_test, hv_v))
148     sim_d = float(model.similarity(hv_test, hv_d))
149
150     print(f"\nTest pattern: Dimmer horizontal line")
151     print(f"  Similarity to horizontal: {sim_h:.3f}")
152     print(f"  Similarity to vertical: {sim_v:.3f}")
153     print(f"  Similarity to diagonal: {sim_d:.3f}")
154
155     best_match = max([("Horizontal", sim_h), ("Vertical", sim_v), ("Diagonal", sim_d)],
156                      key=lambda x: x[1])
157     print(f"\nBest match: {best_match[0]}")
158
159
160 def demo_color_classification():
161     """Demonstrate color-based classification."""
162     print_section("Demo 5: Color-Based Classification")
163
164     model = VSA.create('MAP', dim=10000, seed=42)
165     scalar_enc = ThermometerEncoder(model, min_val=0, max_val=1, n_bins=256, seed=42)
166     encoder = ImageEncoder(model, scalar_enc, seed=42)
167
168     print("\nScenario: Classify images by dominant color\n")
169
170     # Create color prototypes
171     red_img = np.zeros((5, 5, 3), dtype=np.uint8)
172     red_img[:, :, 0] = 200
173
174     green_img = np.zeros((5, 5, 3), dtype=np.uint8)
175     green_img[:, :, 1] = 200
176
177     blue_img = np.zeros((5, 5, 3), dtype=np.uint8)
178     blue_img[:, :, 2] = 200
179
180     # Encode prototypes
181     hv_red = encoder.encode(red_img)
182     hv_green = encoder.encode(green_img)
183     hv_blue = encoder.encode(blue_img)
184
185     color_db = {
186         "Red": hv_red,
187         "Green": hv_green,
188         "Blue": hv_blue
189     }
190
191     print("Color Library:")
192     print("  - Red (R=200, G=0, B=0)")
193     print("  - Green (R=0, G=200, B=0)")
194     print("  - Blue (R=0, G=0, B=200)")
195
196     # Test images
197     test_images = [
198         (np.array([[[180, 0, 0]]], dtype=np.uint8), "Red"),
199         (np.array([[[0, 190, 0]]], dtype=np.uint8), "Green"),
200         (np.array([[[0, 0, 210]]], dtype=np.uint8), "Blue"),
201     ]
202
203     print("\nTest Results:")
204     for test_img, true_color in test_images:
205         hv_test = encoder.encode(test_img)
206
207         # Find best match
208         best_match = None
209         best_sim = -1.0
210         for color_name, color_hv in color_db.items():
211             sim = float(model.similarity(hv_test, color_hv))
212             if sim > best_sim:
213                 best_sim = sim
214                 best_match = color_name
215
216         print(f"\n  Test image: {true_color} variant")
217         print(f"  Classified as: {best_match} (similarity: {best_sim:.3f})")
218         print(f"  Result: {'✓ Correct' if best_match == true_color else '✗ Incorrect'}")
219
220
221 def demo_texture_similarity():
222     """Demonstrate texture similarity."""
223     print_section("Demo 6: Texture Similarity")
224
225     model = VSA.create('MAP', dim=10000, seed=42)
226     scalar_enc = ThermometerEncoder(model, min_val=0, max_val=1, n_bins=256, seed=42)
227     encoder = ImageEncoder(model, scalar_enc, seed=42)
228
229     # Create checkerboard pattern
230     checkerboard = np.zeros((8, 8), dtype=np.uint8)
231     for i in range(8):
232         for j in range(8):
233             if (i + j) % 2 == 0:
234                 checkerboard[i, j] = 255
235
236     # Create striped pattern
237     stripes = np.zeros((8, 8), dtype=np.uint8)
238     stripes[::2, :] = 255
239
240     # Create noise-like pattern
241     np.random.seed(42)
242     noise = np.random.randint(0, 256, (8, 8), dtype=np.uint8)
243
244     hv_checker = encoder.encode(checkerboard)
245     hv_stripes = encoder.encode(stripes)
246     hv_noise = encoder.encode(noise)
247
248     print("\nTexture Patterns:")
249     print("  - Checkerboard (regular alternating)")
250     print("  - Stripes (horizontal lines)")
251     print("  - Noise (random pixels)")
252
253     sim_cs = float(model.similarity(hv_checker, hv_stripes))
254     sim_cn = float(model.similarity(hv_checker, hv_noise))
255     sim_sn = float(model.similarity(hv_stripes, hv_noise))
256
257     print(f"\nSimilarity (checkerboard vs stripes): {sim_cs:.3f}")
258     print(f"Similarity (checkerboard vs noise): {sim_cn:.3f}")
259     print(f"Similarity (stripes vs noise): {sim_sn:.3f}")
260
261     print("\nKey insight:")
262     print("  Different texture patterns produce distinct encodings")
263
264
265 def demo_different_models():
266     """Demonstrate using different VSA models."""
267     print_section("Demo 7: Different VSA Models")
268
269     image = np.ones((5, 5), dtype=np.uint8) * 128
270
271     print("\nEncoding same image with different VSA models:\n")
272
273     # MAP model
274     model_map = VSA.create('MAP', dim=10000, seed=42)
275     scalar_map = ThermometerEncoder(model_map, min_val=0, max_val=1, n_bins=256, seed=42)
276     encoder_map = ImageEncoder(model_map, scalar_map, seed=42)
277     hv_map = encoder_map.encode(image)
278     print(f"MAP model: {hv_map.shape}, dtype={hv_map.dtype}")
279
280     # FHRR model
281     model_fhrr = VSA.create('FHRR', dim=10000, seed=42)
282     scalar_fhrr = FractionalPowerEncoder(model_fhrr, min_val=0, max_val=1, seed=42)
283     encoder_fhrr = ImageEncoder(model_fhrr, scalar_fhrr, seed=42)
284     hv_fhrr = encoder_fhrr.encode(image)
285     print(f"FHRR model: {hv_fhrr.shape}, dtype={hv_fhrr.dtype}")
286
287     print("\nKey insight:")
288     print("  ImageEncoder works with any VSA model using appropriate scalar encoder")
289
290
291 def main():
292     """Run all demos."""
293     print("=" * 70)
294     print("Image Encoder - Comprehensive Demonstration")
295     print("=" * 70)
296     print("\nThe ImageEncoder encodes 2D images (grayscale, RGB, RGBA) into")
297     print("hypervectors by binding spatial positions with pixel values.")
298     print("This is essential for:")
299     print("  - Image classification and recognition")
300     print("  - Image similarity search")
301     print("  - Pattern and texture matching")
302     print("  - Computer vision applications")
303
304     demo_basic_grayscale()
305     demo_rgb_encoding()
306     demo_image_similarity()
307     demo_pattern_recognition()
308     demo_color_classification()
309     demo_texture_similarity()
310     demo_different_models()
311
312     print("\n" + "=" * 70)
313     print("Demo Complete!")
314     print("=" * 70)
315     print("\nNext steps:")
316     print("  - See docs/theory/encoders.md for mathematical details")
317     print("  - Run tests: pytest tests/test_encoders_spatial.py")
318     print("  - Try with your own images!")
319
320
321 if __name__ == '__main__':
322     main()

Gallery generated by Sphinx-Gallery