# ImageRepo

A self-hosted image and video gallery application designed for organizing and viewing media collections. Originally built for managing Patreon content archives, it features automatic importing, tagging, duplicate detection, and a responsive dark-themed UI.

## Features

- **Gallery View** - Browse images in a paginated grid with thumbnail previews
- **Showcase View** - Randomized masonry layout for discovery
- **Image Modal** - Full-size viewing with zoom, pan, and keyboard navigation
- **Video Support** - Playback for video files with thumbnail generation
- **Tagging System** - Organize images with tags (artist, character, series, rating, archive, user-defined)
- **Tag Autocomplete** - Quick tag entry with search suggestions
- **Automatic Importing** - Scans `/import` directory on schedule or manual trigger
- **Archive Extraction** - Supports ZIP, RAR, 7z and other archive formats
- **Duplicate Detection** - Perceptual hash (pHash) comparison to skip similar images
- **Import Filters** - Skip images by dimensions or transparency percentage
- **Bulk Deletion** - Delete images by tag or filter criteria
- **Artist Organization** - Auto-tags images based on folder structure
- **Dark Theme** - Easy on the eyes for extended browsing

## Quick Start

### Docker Compose

```yaml
services:
  imagerepo:
    image: git.fabledsword.com/bvandeusen/imagerepo:latest
    ports:
      - "5000:5000"
    volumes:
      - ./imagerepo/db:/db           # SQLite database storage
      - ./imagerepo/images:/images   # Imported images and thumbnails
      - ./your-media:/import         # Source directory to import from
    environment:
      - THUMBS_VERBOSE=1
      - THUMBS_LOG_EVERY=50
```

Then visit `http://localhost:5000` in your browser.

## Volumes

| Path | Description |
|------|-------------|
| `/db` | Database storage (SQLite by default) |
| `/images` | Where imported images and thumbnails are stored |
| `/import` | Source directory the importer scans for new media |

## Environment Variables

### Database Configuration

By default, ImageRepo uses SQLite. Set `DB_TYPE=postgresql` to use PostgreSQL instead.

| Variable | Default | Description |
|----------|---------|-------------|
| `DB_TYPE` | `sqlite` | Database type: `sqlite` or `postgresql` |
| `DB_NAME` | `app.db` | Database name (SQLite filename or PostgreSQL database) |
| `DB_USER` | `imagerepo` | PostgreSQL username |
| `DB_PASS` | `postgres` | PostgreSQL password |
| `DB_HOST` | `postgres` | PostgreSQL host |
| `DB_PORT` | `5432` | PostgreSQL port |

### Import Settings

These can also be configured via the Settings page in the UI.

| Variable | Default | Description |
|----------|---------|-------------|
| `IMPORT_MIN_WIDTH` | `0` | Minimum image width in pixels (0 = no minimum) |
| `IMPORT_MIN_HEIGHT` | `0` | Minimum image height in pixels (0 = no minimum) |
| `IMPORT_SKIP_TRANSPARENT` | `false` | Skip mostly-transparent images (PNG/GIF/WebP) |
| `IMPORT_TRANSPARENCY_THRESHOLD` | `0.9` | Transparency % threshold (0.0-1.0) for skipping |
| `IMPORT_PHASH_THRESHOLD` | `2` | Duplicate detection sensitivity (0=disabled, 1=strict, 2=normal, 5=loose, 10=very loose) |

### Thumbnail Generation

| Variable | Default | Description |
|----------|---------|-------------|
| `THUMBS_VERBOSE` | `0` | Enable verbose logging (`1`, `true`, or `yes`) |
| `THUMBS_LOG_EVERY` | `50` | Log progress every N thumbnails |
| `THUMBS_BATCH_SIZE` | `500` | Process thumbnails in batches of N |
| `THUMBS_FFMPEG_TIMEOUT` | `60` | Timeout in seconds for video thumbnail extraction |

### Archive Extraction

| Variable | Default | Description |
|----------|---------|-------------|
| `ARCHIVE_TMPDIR` | System temp | Directory for extracting archives |
| `ARCHIVE_MIN_FREE_GB` | `0` | Minimum free disk space (GB) required to start extraction (0 = disabled) |
| `ARCHIVE_NUM_WIDTH` | `4` | Zero-padding width for archive sequence numbers in tags |

### Other

| Variable | Default | Description |
|----------|---------|-------------|
| `PIL_MAX_IMAGE_PIXELS` | `178956970` | Maximum image size Pillow will process (guards against decompression bombs) |

## Import Behavior

The importer runs:
- Automatically every 8 hours
- Manually via the "Trigger Image Import" button in Settings

### Folder Structure

The importer uses the folder structure to auto-tag images:

```
/import/
├── ArtistName/           # Tagged as "artist:ArtistName"
│   ├── image1.png
│   ├── image2.jpg
│   └── archive.zip       # Extracted, contents tagged with "archive:archive"
├── AnotherArtist/
│   └── subfolder/
│       └── image3.png    # Still tagged as "artist:AnotherArtist"
```

- Top-level folders become `artist:FolderName` tags
- Archives (ZIP, RAR, 7z, etc.) are extracted and their contents tagged with `archive:filename`
- Nested subfolders inherit the top-level artist tag

### Supported Formats

**Images:** PNG, JPG, JPEG, GIF, WebP, BMP, TIFF
**Videos:** MP4, WebM, MKV, AVI, MOV
**Archives:** ZIP, RAR, 7z, and others supported by `unar`/`7z`

## Settings Page

The Settings page (`/settings`) provides:

### Admin Actions
- **Trigger Image Import** - Manually start an import scan
- **Regenerate Thumbnails** - Rebuild all thumbnails
- **Reset Image Database** - Clear all image records (files remain on disk)

### Import Filters
Configure filtering rules that apply during import:
- Minimum dimensions
- Transparency filtering
- Duplicate detection sensitivity

### Delete Images by Tag
Bulk delete all images associated with a specific tag (e.g., remove an entire artist's collection).

### Clean Up Existing Images
Scan and selectively delete images that match filter criteria (transparency or dimensions).

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/random-images` | GET | Get random images for showcase |
| `/api/tags/search` | GET | Search tags for autocomplete |
| `/api/import-settings` | GET/POST | Read/write import filter settings |
| `/api/import-stats` | GET | Get last import statistics |
| `/api/filter-scan` | GET | Scan images matching filter criteria |
| `/api/filter-delete` | POST | Delete selected images |
| `/api/delete-by-tag` | POST | Delete all images with a tag |
| `/image/<id>/tags` | GET | List tags for an image |
| `/image/<id>/tags/add` | POST | Add a tag to an image |
| `/image/<id>/tags/remove` | POST | Remove a tag from an image |

## Keyboard Shortcuts

In the image modal:
- **Arrow Left/Right** - Previous/Next image
- **Escape** - Close modal
- **Click image** - Toggle zoom
- **Drag** (when zoomed) - Pan around image

## PostgreSQL Setup

To use PostgreSQL instead of SQLite:

```yaml
services:
  imagerepo:
    image: git.fabledsword.com/bvandeusen/imagerepo:latest
    ports:
      - "5000:5000"
    environment:
      - DB_TYPE=postgresql
      - DB_HOST=postgres
      - DB_USER=imagerepo
      - DB_PASS=your_secure_password
      - DB_NAME=imagerepo
    volumes:
      - ./imagerepo/images:/images
      - ./your-media:/import
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=imagerepo
      - POSTGRES_PASSWORD=your_secure_password
      - POSTGRES_DB=imagerepo
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
```

## Development

### Local Setup

```bash
# Clone the repository
git clone https://git.fabledsword.com/bvandeusen/imagerepo.git
cd imagerepo

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Run with Flask dev server
flask run
```

### Docker Build

```bash
docker build -t imagerepo .
docker run -p 5000:5000 -v ./images:/images -v ./import:/import imagerepo
```

## License

This is a personal project. Use at your own discretion.