# ⚡ useblysh (Python)

**High-performance visual hashing for seamless image loading.** The unified toolkit for Python and JavaScript to turn heavy images into elegant, byte-sized blurs.

[![pypi version](https://img.shields.io/pypi/v/imghash?color=green&style=flat-square)](https://pypi.org/project/imghash)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

---

## 🌟 Why useblysh?

Standard `loading="lazy"` leaves users staring at empty white boxes. **useblysh** eliminates this "broken" feel by encoding your images into tiny strings that can be sent inside your JSON API response.

* **Full-Stack:** Identical hashing logic for Python (Backend) and React (Frontend).
* **Zero Layout Shift:** Reserve image space instantly to prevent page jumping.
* **Performance:** Replace 1MB images with 20-byte strings during the initial load.
  
---

## 🛠️ Installation

### Backend (Python)
```bash
pip install imghash
```

---

## 🚀 Simple Examples

### **Generate Hash (Backend)**
Generate hashes on your server using the Python library.

```python
from PIL import Image
from imghash import encode

# Open an image using Pillow
image = Image.open("path/to/image.jpg")

# Generate the hash
hash = encode(image, components_x=4, components_y=3)
print(f"Generated Hash: {hash}")
```

### **Frontend Compatibility**
The hash generated by this Python module is **fully compatible** with the `useblysh` JS package. You can encode on your backend and decode on your frontend using the React component.

---

## 💡 Use Cases

### 1. Progressive Image Loading
Instead of showing a spinner or a blank box, show a beautiful blurred version of the actual image. This keeps users engaged and makes the site feel faster.

### 2. Social Media Feeds
For infinite scroll feeds (like Instagram or Pinterest), send the `useblysh` string in your initial JSON request. The app can render the entire feed layout with placeholders before a single byte of actual image data is even downloaded.

### 3. SEO & Layout Stability (CLS)
Prevent "layout shift" where content jumps around as images load. `useblysh` reserves the correct aspect ratio and space immediately.

---

## 📖 How it Works

**Blysh** uses a Discrete Cosine Transform (DCT) to extract the most important color frequencies from an image.
1. **Encoding:** The image is downsampled and converted into a set of mathematical factors, then compressed into a **Base83** string.
2. **Decoding:** The frontend takes that string and reconstructs a low-resolution version of the original image, applying a smooth blur filter for an elegant look.

---

**Built with ❤️ for the modern web.**

