{"id":21879332,"url":"https://github.com/animator/blurhash-numba","last_synced_at":"2025-04-15T03:11:06.571Z","repository":{"id":62560284,"uuid":"298132396","full_name":"animator/blurhash-numba","owner":"animator","description":"Fastest BlurHash implementation for Python using Numba ","archived":false,"fork":false,"pushed_at":"2022-03-03T05:18:19.000Z","size":4150,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-05T06:45:51.511Z","etag":null,"topics":["blurhash","numba","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/animator.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-24T00:59:22.000Z","updated_at":"2024-03-21T18:07:45.000Z","dependencies_parsed_at":"2022-11-03T14:15:26.866Z","dependency_job_id":null,"html_url":"https://github.com/animator/blurhash-numba","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/animator%2Fblurhash-numba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/animator%2Fblurhash-numba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/animator%2Fblurhash-numba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/animator%2Fblurhash-numba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/animator","download_url":"https://codeload.github.com/animator/blurhash-numba/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248997079,"owners_count":21195799,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blurhash","numba","python"],"created_at":"2024-11-28T08:16:00.432Z","updated_at":"2025-04-15T03:11:06.551Z","avatar_url":"https://github.com/animator.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/animator/blurhash-numba/master/media/logo-text.png\" alt=\"Blurhash numba logo\"\u003e\n\u003c/p\u003e\n\n# blurhash-numba : The fastest Python 3 BlurHash implementation *powered by* numba\n[![Build Status](https://travis-ci.com/animator/blurhash-numba.svg?branch=master)](https://travis-ci.com/animator/blurhash-numba)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/blurhash-numba)](https://pypi.org/project/blurhash-numba)\n[![PyPI version](https://badge.fury.io/py/blurhash-numba.svg)](https://pypi.org/project/blurhash-numba)\n[![GitHub](https://img.shields.io/github/license/animator/blurhash-numba)](https://github.com/animator/blurhash-numba/blob/master/LICENSE)\n\n## Check out the Interactive Demo - [Link](https://share.streamlit.io/realworldpython/blurhash-numba-app/main/app.py)\n![Blurhash numba demo](https://raw.githubusercontent.com/animator/blurhash-numba/master/media/blurhash-numba-demo.gif)\n\n## What is BlurHash?\n\nBlurHash is a compact representation of a placeholder for an image.  \n\n\u003cimg src=\"https://raw.githubusercontent.com/animator/blurhash-numba/master/media/WhyBlurHash.png\" width=\"600\"\u003e\n\nBlurHash encoder consumes an image, and provides a short string (only 20-30 characters!) that represents the placeholder for the image. You perform this on the backend of your service, and store the string along with the image. When you send data to any client, you send both the URL to the image, and the BlurHash string. Your client then takes the string, and decodes it into an image that it shows while the real image is loading over the network. The string is short enough that it comfortably fits into whatever data format you use. For instance, it can easily be added as a field in a JSON object.\n\nIn summary:\n\n\u003cimg src=\"https://raw.githubusercontent.com/animator/blurhash-numba/master/media/HowItWorks1.jpg\" width=\"250\"\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003cimg src=\"https://raw.githubusercontent.com/animator/blurhash-numba/master/media/HowItWorks2.jpg\" width=\"250\"\u003e\n\nRead more about the algorithm [here](https://github.com/woltapp/blurhash/blob/master/Algorithm.md).\n\n# Installation\n\nYou can install `blurhash-numba` using pip3\n```\n$ pip3 install blurhash-numba\n```\n\nYou can also optionally install `Pillow` (PIL) along with `blurhash-numba` in case it is not already installed\n```\n$ pip3 install blurhash-numba[pillow]\n```\n\n# Usage\n\n## Encoding \n\nAs `blurhash_numba.encode` accepts the image in the form of a `numpy` array. You can convert an image file using the `Pillow` python library.\n\n```python\nfrom blurhash_numba import encode\nfrom PIL import Image\nimport numpy as np\n\nimage = Image.open(\"256.jpg\")\n```\n\n\n\u003e `image`    \n\u003e \u003cimg src=\"https://raw.githubusercontent.com/animator/blurhash-numba/master/media/256.jpg\" width=\"256\"\u003e\n\n```python\nimage_array = np.array(image.convert(\"RGB\"), dtype=np.float)\nblurhash_code = encode(image_array, x_components = 4, y_components = 3)\n```\n\n\u003e `blurhash_code`    \n\u003e `'LtL#LZR*x]jG.TRkoeayIUofM{R*'`\n\n`y_components` and `x_components` parameters adjust the amount of\nvertical and horizontal AC components in hashed image. Both parameters must\nbe `\u003e= 1` and `\u003c= 9`.\n\n## Decoding\n\n```python\nfrom blurhash_numba import decode\nfrom PIL import Image\nimport numpy as np\n\nblurhash_code = 'LtL#LZR*x]jG.TRkoeayIUofM{R*'\nblur_img = Image.fromarray(np.array(decode(blurhash_code, 256, 256)).astype('uint8'))\n```\n\n\u003e `blur_img`    \n\u003e \u003cimg src=\"https://raw.githubusercontent.com/animator/blurhash-numba/master/media/256-blur.jpg\" width=\"256\"\u003e\n\n# Tests\n\nRun test suite with `pytest` in virtual environment\n```\n$ pytest\n```\n\n# FAQs\n\n## Why should I use blurhash-numba?\n\nThis is the fastest implementation of the BlurHash algorithm (both encoding \u0026 decoding) in Python currently as it uses `numba` to directly convert the Python+NumPy code into fast machine code. It is 30-70x faster than [halcy/blurhash-python](https://github.com/halcy/blurhash-python) and 2-4x faster than [woltapp/blurhash](https://github.com/woltapp/blurhash).\n\n## How do I pick the number of X and Y components?\n\nIt depends a bit on taste. The more components you pick, the more information is retained in the placeholder, but the longer the BlurHash string will be. Also, it doesn't always look good with too many components. We usually go with 4 by 3, which seems to strike a nice balance.\n\nHowever, you should adjust the number of components depending on the aspect ratio of your images. For instance, very wide images should have more X components and fewer Y components.\n\n## What is the `punch` parameter in this implementations?\n\nIt is a parameter that adjusts the contrast on the decoded image. 1 means normal, smaller values will make the effect more subtle, and larger values will make it stronger. This is basically a design parameter, which lets you adjust the look.\n\nTechnically, what it does is scale the AC components up or down.\n\n# Credits\n\nThis project is based on the pure python BlurHash implementation by [halcy/blurhash-python](https://github.com/halcy/blurhash-python).   \nAlso credit goes to the original implementation by [woltapp/blurhash](https://github.com/woltapp/blurhash). \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanimator%2Fblurhash-numba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanimator%2Fblurhash-numba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanimator%2Fblurhash-numba/lists"}