# QViewer

A fast, lightweight image viewer built with PyQt5 and optimized with Cython. Navigate through multiple images with keyboard shortcuts!

## Features

- 🖼️ View images from local files or URLs
- ⚡ Auto-scaling to fit screen
- 🎨 Frameless window design
- ⌨️ Keyboard navigation (Arrow keys, Space)
- 🔄 Cycle through multiple images
- 📁 Directory scanning (with recursive depth control)
- 📋 Clipboard support
- 🚀 Cython-optimized for performance

## Supported Formats

JPG, JPEG, PNG, GIF, BMP, TIFF, TIF, WEBP, ICO, SVG, HEIC, HEIF, AVIF, JFIF, APNG

## Installation

```bash
pip install qviewer
```

## Usage

### Command Line

```bash
# View single image
qviewer image.jpg

# View multiple images (navigate with arrow keys)
qviewer img1.jpg img2.png img3.gif

# View all images in a directory
qviewer /path/to/images/

# View images in directory (max depth 2 subdirectories)
qviewer -d 2 /path/to/images/

# View only current directory (no subdirectories)
qviewer -d 0 /path/to/images/

# Mix files and directories
qviewer image1.jpg /path/to/more/images/ image2.png

# View image from URL
qviewer https://example.com/image.png

# Load from clipboard
qviewer c
```

### Keyboard Shortcuts

- `Arrow Right` / `Arrow Down` / `Space` - Next image
- `Arrow Left` / `Arrow Up` - Previous image
- `Q` / `Escape` - Quit

### Python API

```python
from qviewer import show, collect_all_images

# View single image
show(['/path/to/image.jpg'])

# View multiple images
images = [
    '/path/to/img1.jpg',
    '/path/to/img2.png',
    'https://example.com/img3.gif'
]
show(images)

# Collect images from directory and view
images = collect_all_images(['/path/to/images'], max_depth=2)
show(images)
```

## Command Line Options

```
usage: qviewer [-h] [-d N] [paths ...]

positional arguments:
  paths              Image file(s), URL(s), or directory path(s)
                     Use "c" to load from clipboard

optional arguments:
  -h, --help         show help message and exit
  -d N, --depth N    Maximum directory recursion depth
                     (default: infinite, 0: current dir only)
```

## Requirements

- Python >= 3.7
- PyQt5 >= 5.15.0
- requests >= 2.25.0
- clipboard >= 0.0.4

## Examples

### Browse vacation photos
```bash
qviewer ~/Pictures/Vacation2024/
```

### Compare multiple screenshots
```bash
qviewer screenshot1.png screenshot2.png screenshot3.png
```

### Review images from multiple directories
```bash
qviewer ~/Downloads/ ~/Pictures/Recent/ -d 1
```

### Quick view from clipboard
```bash
# Copy image URL or path, then:
qviewer c
```

## 👤 Author
        
[Hadi Cahyadi](mailto:cumulus13@gmail.com)
    

[![Buy Me a Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/cumulus13)

[![Donate via Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/cumulus13)
 
[Support me on Patreon](https://www.patreon.com/cumulus13)