rubymagick/README.md

# 📸 Rubymagick — Simple Ruby Image Converter & Pixelation Tool

**Rubymagick** is a tiny Ruby/Sinatra web app for converting images (like PNGs) into **JPEGs**, shrinking file sizes, or applying **fun retro effects** such as CRT scanlines and adjustable pixelation.

It’s designed to be lightweight, easy to run locally, and perfect for:

* Compressing PNGs into small JPGs
* Preparing images for websites or blog posts
* Pixelating art or photos (SNES / PS1 / Game Boy style)
* Adding fake CRT scanlines for retro aesthetics
* Quickly batch-converting images through a browser

No account, no cloud upload — just run it on your own machine.

---

## ✨ Features

### ✔️ JPEG Conversion

Upload any image (PNG, JPG, WebP, HEIC, etc.) and convert it into a JPEG with adjustable quality.

### ✔️ Adjustable JPEG Quality Slider

Choose any value from **10–100**. Lower quality = smaller file size.

### ✔️ Pixelation Effect (with slider)

A fully adjustable pixelation slider:

* Factor **2** → subtle pixelation
* Factor **8** → chunky SNES/GBA style
* Factor **12–25** → extreme blocky PS1 / Minecraft look

### ✔️ CRT / Scanline Effect

Simulates a low-resolution CRT display:

* Downscales to fake 480p
* Adds contrast + noise
* Optionally overlays scanlines if `public/scanlines.png` exists

### ✔️ Local, Private, Simple

Everything runs on your machine.
Nothing leaves your computer.

---

## 🛠 Requirements

You need the following gems:

```
sinatra
sinatra-contrib
mini_magick
rackup
puma
```

Install them with:

```bash
gem install sinatra sinatra-contrib mini_magick rackup puma
```

And you must have ImageMagick installed:

### Debian/Ubuntu

```bash
sudo apt install imagemagick
```

### Fedora/Rocky/RHEL

```bash
sudo dnf install imagemagick
```

### Arch

```bash
sudo pacman -S imagemagick
```

---

## 🚀 Running the App

Save the project as `app.rb`, then run:

```bash
bundle exec ruby app.rb
```

Or if you're not using Bundler:

```bash
ruby app.rb
```

A provided `start-server.sh` Bash script is also available

Then visit:

```
http://localhost:4567/
```

---

## 🖼 How to Use

1. Open the web UI.
2. Upload an image (PNG, JPG, WEBP, etc.)
3. Choose your desired JPEG output quality.
4. Select an effect (None, CRT, or Pixelated).
5. If you choose Pixelated → adjust the intensity slider.
6. Click **Convert to .jpg**.
7. Download your JPEG file.

Converted files are stored in:

```
public/output/
```

---

## 🎛 Effects Explained

### 🔸 CRT / Scanline Mode

This effect simulates an old-school CRT monitor:

* Resizes image down to low resolution
* Boosts contrast
* Adds light noise for texture
* If `public/scanlines.png` exists, overlays it

Good for:

* Retro edits
* Vaporwave / synthwave style
* Terminal-style effects

---

### 🔸 Pixelation Mode (Adjustable)

Uses nearest-neighbor downscale → upscale trick.

Formula:

```
small_w = width / factor
small_h = height / factor
```

Then scales back up with no filtering.

Great for:

* Pixel art effects
* Lo-fi game textures
* Retro aesthetic
* Meme-style blur blocks

---

## 📁 Optional: Add Custom Scanlines

Place a PNG named:

```
public/scanlines.png
```

It will be automatically applied when CRT mode is selected.

---

## 🧩 Project Structure

Typical layout:

```
rubymagick/
 ├─ app.rb
 ├─ Gemfile
 ├─ public/
 │    ├─ output/
 │    └─ scanlines.png (optional)
```

Output files go into `public/output/`.

---

## 📝 About This App

Rubymagick is intentionally small and hackable.
It’s perfect as:

* A personal utility
* A learning project for Sinatra
* A way to explore ImageMagick through Ruby
* A lightweight image-prep tool for websites

You can expand it easily with:

* WebP/AVIF export
* Batch uploads
* Color palette reduction (NES/Game Boy)
* VHS distortion effects
* CLI wrapper mode

Just modify the helper functions or add more UI elements.

---