useblysh 1.0.2

High-performance visual hashing for seamless image loading. Encode images into tiny strings and decode into beautiful, fast-loading blurs

⚡ 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.

---

🌟 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)

pip install useblysh

---

🚀 Simple Examples

1. Generate Hash (Python)

Generate hashes on your server using the Python library.

from PIL import Image
from useblysh import encode

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

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

2. Frontend Decoding (React)

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.

import { ImageHash } from 'useblysh'; 
 
<ImageHash 
  hash={storedHash}        // The short string from your Python backend
  src={imageUrl}          // The real high-quality image URL 
  className="w-full h-64 rounded-xl" 
/>

---

💡 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.