Add example script

Author: halcy

README.md

@@ -25,9 +25,29 @@ This library contains a pure-python implementation of the blurhash algorithm, cl
 $ pip3 install blurhash
 ```
 
-It exports only two functions, "encode" and "decode". The usage is as follows:
+It exports five functions:
+* "encode" and "decode" do the actual en- and decoding of blurhash functions
+* "components" returns the number of components x- and y components of a blurhash
+* "srgb_to_linear" and "linear_to_srgb" are colour space conversion helpers
+
+Have a look at example.py for a recommendation for how to use all of these working together.
+
+Documentation for each function:
 
 ```python
+blurhash.encode(image, components_x = 4, components_y = 4, linear = False):
+"""
+Calculates the blurhash for an image using the given x and y component counts.
+
+Image should be a 3-dimensional array, with the first dimension being y, the second
+being x, and the third being the three rgb components that are assumed to be 0-255 
+srgb integers (incidentally, this is the format you will get from a PIL RGB image).
+
+You can also pass in already linear data - to do this, set linear to True. This is
+useful if you want to encode a version of your image resized to a smaller size (which
+you should ideally do in linear colour).
+"""
+
 blurhash.decode(blurhash, width, height, punch = 1.0, linear = False)
 """
 Decodes the given blurhash to an image of the specified size.
@@ -44,16 +64,13 @@ to a relatively small size and then scale the result up, as it
 basically looks the same anyways.
 """
 
-blurhash.encode(image, components_x = 4, components_y = 4, linear = False):
+blurhash.srgb_to_linear(value):
 """
-Calculates the blurhash for an image using the given x and y component counts.
-
-Image should be a 3-dimensional array, with the first dimension being y, the second
-being x, and the third being the three rgb components that are assumed to be 0-255 
-srgb integers (incidentally, this is the format you will get from a PIL RGB image).
-
-You can also pass in already linear data - to do this, set linear to True. This is
-useful if you want to encode a version of your image resized to a smaller size (which
-you should ideally do in linear colour).
+srgb 0-255 integer to linear 0.0-1.0 floating point conversion.
+"""
+    
+blurhash.linear_to_srgb(value):
+"""
+linear 0.0-1.0 floating point to srgb 0-255 integer conversion.
 """
 ```

example.py

@@ -0,0 +1,93 @@
+"""
+Example "proper" blurhash usage
+"""
+
+import numpy as np
+import PIL.Image
+import blurhash
+
+# Input/output file names
+input_image = "tests/cool_cat.jpg"
+output_image = "example_out.png"
+
+# How many components do we want, maximum and minimum?
+target_components = 4
+min_components = 2
+
+# Which maximum size should we work at for blurhash calculations?
+work_size = 64
+
+# What's the final intended output size?
+out_size = (320, 180)
+
+"""
+Part 1: Encode
+"""
+# Load the image and store sizes (useful for decoding later, and likely part of your
+# metadata objects anyways)
+image = PIL.Image.open(input_image).convert("RGB")
+image_size = (image.width, image.height)
+print("Read image " + input_image + "({} x {})".format(image_size[0], image_size[1]))
+
+# Convert to linear and thumbnail
+image_linear = np.vectorize(blurhash.srgb_to_linear)(np.array(image))
+image_linear_thumb = []
+for i in range(3):
+    channel_linear = PIL.Image.fromarray(image_linear[:,:,i].astype("float32"), mode = 'F')
+    channel_linear.thumbnail((work_size, work_size))
+    image_linear_thumb.append(np.array(channel_linear))
+image_linear_thumb = np.transpose(np.array(image_linear_thumb), (1, 2, 0))
+print("Encoder working at size: {} x {}".format(image_linear_thumb.shape[1], image_linear_thumb.shape[0]))
+
+# Figure out a good component count
+components_x = int(max(min_components, min(target_components, round(image_linear_thumb.shape[1] / (work_size / target_components)))))
+components_y = int(max(min_components, min(target_components, round(image_linear_thumb.shape[0] / (work_size / target_components)))))
+print("Using component counts: {} x {}".format(components_x, components_y))
+
+# Create blurhash
+blur_hash = blurhash.encode(image_linear_thumb, components_x, components_y, linear = True)
+print("Blur hash of image: " + blur_hash)
+
+"""
+Part 2: Decode
+"""
+# Figure out what size to decode to
+decode_components_x, decode_components_y = blurhash.components(blur_hash)
+decode_size_x = decode_components_x * (work_size // target_components)
+decode_size_y = decode_components_y * (work_size // target_components)
+print("Decoder working at size {} x {}".format(decode_size_x, decode_size_y))
+
+# Decode
+decoded_image = np.array(blurhash.decode(blur_hash, decode_size_x, decode_size_y, linear = True))
+
+# Scale so that we have the right size to fill out_size without letter/pillarboxing
+# while matching original images aspect ratio.
+fill_x_size_y = out_size[0] * (image_size[0] / image_size[1])
+fill_y_size_x = out_size[1] * (image_size[1] / image_size[0])
+scale_target_size = list(out_size)
+if fill_x_size_y / out_size[1] < fill_y_size_x / out_size[0]:
+    scale_target_size[0] = max(scale_target_size[0], int(fill_y_size_x))
+else:
+    scale_target_size[1] = max(scale_target_size[1], int(fill_x_size_y))
+
+# Scale (ideally, your UI layer should take care of this in some kind of efficient way)
+print("Scaling to target size: {} x {}".format(scale_target_size[0], scale_target_size[1]))
+decoded_image_large = []
+for i in range(3):
+    channel_linear = PIL.Image.fromarray(decoded_image[:,:,i].astype("float32"), mode = 'F')
+    decoded_image_large.append(np.array(channel_linear.resize(scale_target_size, PIL.Image.BILINEAR)))
+decoded_image_large = np.transpose(np.array(decoded_image_large), (1, 2, 0))
+
+# Convert to srgb PIL image
+decoded_image_out = np.vectorize(blurhash.linear_to_srgb)(np.array(decoded_image_large))
+decoded_image_out = PIL.Image.fromarray(np.array(decoded_image_out).astype('uint8'))
+
+# Crop to final size and write
+decoded_image_out = decoded_image_out.crop((
+    (decoded_image_out.width - out_size[0]) / 2,
+    (decoded_image_out.height - out_size[1]) / 2,
+    (decoded_image_out.width + out_size[0]) / 2,
+    (decoded_image_out.height + out_size[1]) / 2,
+))
+decoded_image_out.save(output_image)
+print("Wrote final result to " + str(output_image))