# Payas Imager — Documentation

> Privacy-first image viewer · Slideshow · HEIC support · Zoom · Pan · No server · Open Source  
> Developer: **Saman Wijesinghe** · License: MIT

---

## Table of Contents

1. [Project Overview](#1-project-overview)
2. [Quick Start](#2-quick-start)
3. [Interface Layout](#3-interface-layout)
4. [Toolbar Reference](#4-toolbar-reference)
5. [Supported Formats](#5-supported-formats)
6. [Viewing Controls](#6-viewing-controls)
7. [Image Transforms](#7-image-transforms)
8. [Presentation Mode](#8-presentation-mode)
9. [Export & Copy](#9-export--copy)
10. [Sidebar Panels](#10-sidebar-panels)
11. [Context Menu](#11-context-menu)
12. [Keyboard Shortcuts](#12-keyboard-shortcuts)
13. [Settings Reference](#13-settings-reference)
14. [Storage & Data](#14-storage--data)
15. [Architecture & Code Structure](#15-architecture--code-structure)
16. [JavaScript API Reference](#16-javascript-api-reference)
17. [License](#17-license)

---

## 1. Project Overview

**Payas Imager** is a fully client-side image viewer that runs entirely in your browser — no server, no account, no build step. Open `payas-imager.html` directly. Load single images, batches, or entire folders. View, zoom, pan, rotate, and present images in a full-screen slideshow. HEIC/HEIF files are converted in-browser via **heic2any**.

### Key Facts

| Property | Value |
|---|---|
| Entry point | `payas-imager.html` |
| Stack | HTML5 · CSS3 · Vanilla JS (ES2022) |
| Dependencies | Bootstrap 5.3.3 · Font Awesome 6.5.2 · heic2any 0.0.4 · Google Fonts |
| Storage | `localStorage` (theme + settings) |
| Image formats | JPEG · PNG · GIF · BMP · TIFF · WebP · SVG · ICO · AVIF · HEIC · HEIF |
| Export | Download · Copy to clipboard · Print |
| Themes | Light · Dark |
| Responsive | Yes — mobile overlay sidebar |

### Design Language

Payas Imager follows the **Payas design system** shared across all Payas web tools. Same colour tokens, typography, and component patterns.

---

## 2. Quick Start

No build or server required. Open the file directly:

```bash
# Option 1 — open directly
xdg-open payas-imager.html          # Linux
open payas-imager.html              # macOS
start payas-imager.html             # Windows

# Option 2 — serve locally
python3 -m http.server 8080
# Then visit http://localhost:8080/payas-imager.html
```

**Load images** by clicking **Open Image**, **Open Folder**, or **drag and drop** files onto the canvas. Each image opens as a tab.

---

## 3. Interface Layout

```
┌─ Title Bar ──────────────────────────────────────────────────┐
│ [Logo] [☰] [Open Image] [Open Folder] [Copy][Save][Print]    │
│         [Settings] [🌙]                                      │
├─ Tab Bar ────────────────────────────────────────────────────┤
│ [image-1.jpg ✕] [photo.png ✕] [graphic.svg ✕] …             │
├─ Toolbar ────────────────────────────────────────────────────┤
│ [Zoom−][n%][Zoom+][Fit][1:1][2×] | [⛶ Fullscreen] [⚙]       │
│ [◁ Rotate L][▷ Rotate R][↔ Flip H][↕ Flip V] | [1/n]        │
├─ Body ───────────────────────────────────────────────────────┤
│  Sidebar (Image List / Info)  │  Canvas Area (image display) │
├─ Status Bar ─────────────────────────────────────────────────┤
│ 1920×1080 · 2.4 MB · 16:9 · 100%                            │
└──────────────────────────────────────────────────────────────┘
```

### Title Bar

| Control | Shortcut | Action |
|---|---|---|
| Sidebar toggle (☰) | — | Show / hide the sidebar |
| Open Image | `Ctrl+O` | Open single or multiple image files |
| Open Folder | `Ctrl+Shift+O` | Open an entire folder of images |
| Copy | `Ctrl+C` | Copy current image to clipboard |
| Save | `Ctrl+S` | Download current image |
| Print | `Ctrl+P` | Print current image |
| Settings | — | Open the settings panel |
| Theme toggle (🌙) | — | Switch light / dark mode |

---

## 4. Toolbar Reference

### Zoom Controls

| Button | Shortcut | Description |
|---|---|---|
| Zoom Out | `−` or `_` | Decrease zoom by one step |
| Zoom % display | — | Current zoom level; editable input |
| Zoom In | `+` or `=` | Increase zoom by one step |
| Fit to Window | `F` | Zoom to fit the canvas area |
| 100% (1:1) | `1` | Set zoom to 100% actual size |
| 200% | `2` | Set zoom to 200% |
| Fullscreen | `F11` | Toggle browser fullscreen |

### Transform Controls

| Button | Shortcut | Description |
|---|---|---|
| Rotate Left | `L` | Rotate image 90° counter-clockwise |
| Rotate Right | `R` | Rotate image 90° clockwise |
| Flip Horizontal | `H` | Mirror image left/right |
| Flip Vertical | `V` | Mirror image top/bottom |

### Navigation

The toolbar also shows a position counter (e.g. `3 / 12`) indicating the current image index out of total loaded images. Use `←` / `→` to navigate.

---

## 5. Supported Formats

| Format | Extension(s) | Notes |
|---|---|---|
| JPEG | `.jpg`, `.jpeg` | Natively supported |
| PNG | `.png` | Natively supported |
| GIF | `.gif` | Animated GIFs play automatically |
| BMP | `.bmp` | Natively supported |
| TIFF | `.tiff`, `.tif` | Support varies by browser |
| WebP | `.webp` | Natively supported in modern browsers |
| SVG | `.svg` | Rendered as vector; scales losslessly |
| ICO | `.ico` | Natively supported |
| AVIF | `.avif` | Supported in Chrome/Firefox/Safari |
| HEIC / HEIF | `.heic`, `.heif` | Converted to JPEG in-browser via heic2any |

### HEIC / HEIF Conversion

HEIC and HEIF files (commonly produced by iPhones) are automatically converted to JPEG using **heic2any** when loaded. The conversion runs entirely in the browser — no file is sent to a server. The converted JPEG is used for display and export.

---

## 6. Viewing Controls

### Zoom

| Method | Action |
|---|---|
| Toolbar buttons | Step zoom in/out |
| Mouse wheel | Smooth scroll-zoom centred on cursor |
| Zoom input | Type an exact percentage and press Enter |
| `F` key | Fit image to the canvas area |
| `1` key | Jump to 100% |
| `2` key | Jump to 200% |

Zoom sensitivity can be configured in Settings (Slow / Normal / Fast / Very Fast).  
Optional **smooth zoom animation** can be toggled in Settings.

### Pan

| Method | Action |
|---|---|
| Click + drag | Pan the image in any direction |
| `↑` `↓` `←` `→` | Nudge the image 40 px per key press |

### Image Navigation

| Shortcut | Action |
|---|---|
| `←` | Previous image |
| `→` | Next image |
| Click tab | Switch to a specific image |

### Background

The canvas background is configurable (Settings):

| Option | Description |
|---|---|
| Checkerboard | Shows transparency as a grey-white grid |
| White | Solid white background |
| Black | Solid black background |
| Grey | Neutral mid-grey |
| Dark | Matches the dark-theme surface colour |

### Image Rendering

| Option | CSS value | Use case |
|---|---|---|
| Auto | `auto` | Default browser decision |
| Crisp Edges | `crisp-edges` | Pixel art and sharp graphics |
| Pixelated | `pixelated` | Retro / low-res images |
| Smooth | `smooth` | Anti-aliased high-res photos |

---

## 7. Image Transforms

Transforms are **non-destructive view-only** operations — the original file is unchanged.

| Transform | Shortcut | Description |
|---|---|---|
| Rotate Left | `L` | −90° rotation |
| Rotate Right | `R` | +90° rotation |
| Flip Horizontal | `H` | Mirror on vertical axis |
| Flip Vertical | `V` | Mirror on horizontal axis |

Transform state is maintained per image during the session. Switching to another image and back preserves the applied rotation/flip. Transforms are applied with CSS `transform` and animated smoothly when smooth zoom is enabled.

---

## 8. Presentation Mode

Press `P` or click the presentation button to enter full-screen slideshow mode.

### Presentation UI

```
┌── Presentation Overlay (black) ────────────────────────────────┐
│ [▶ Slideshow] [Image Name]             [n / total]  [Exit ✕]   │  ← top bar
│                                                                  │
│          ◀             [ Image ]            ▶                   │  ← navigation
│                                                                  │
│  [⏯][◀][▶]  [Interval▼]  [Transition▼]  [Zoom−][%][Zoom+]     │  ← bottom bar
│  [── thumbnail strip ──────────────────────────────────────────]│  ← thumbnails
└────────────────────────────────────────────────────────────────-┘
```

### Slideshow Controls

| Control | Description |
|---|---|
| Play/Pause button | Start or pause automatic slideshow |
| Interval dropdown | Time between slides: 2 s · 3 s · 5 s · 8 s · 10 s |
| Transition dropdown | Effect between slides: Fade · Slide · None |
| ◀ / ▶ arrows | Manual previous / next |
| Thumbnail strip | Click any thumbnail to jump directly to it |
| Progress bar | Shows position within the image set |
| `Space` | Pause / resume slideshow |
| `←` / `→` | Previous / next image |
| `Esc` or double-click | Exit presentation mode |

---

## 9. Export & Copy

| Action | Shortcut | Description |
|---|---|---|
| Download / Save | `Ctrl+S` | Download the current image with its original filename |
| Copy to clipboard | `Ctrl+C` | Copy the image as a blob to the system clipboard via Canvas API |
| Print | `Ctrl+P` | Open the browser print dialog; UI chrome is hidden by print stylesheet |

> HEIC/HEIF files are exported as JPEG (the converted version).

---

## 10. Sidebar Panels

Toggle the sidebar with the ☰ button in the title bar. On mobile it overlays the canvas.

### Image List

A scrollable list of all loaded images with:
- Thumbnail preview (generated at load time)
- Filename
- Image dimensions (W × H px)
- File size (formatted)

Click any entry to switch to that image.

### Info Panel

Displays metadata for the currently displayed image:

| Field | Description |
|---|---|
| Width / Height | Pixel dimensions |
| Aspect ratio | Reduced fraction (e.g. 16:9) |
| File size | Formatted (B / KB / MB) |
| Format | File extension / codec |
| Colour space | If detectable by the browser |

Press `I` to toggle the info panel.

---

## 11. Context Menu

Right-click anywhere on the canvas to open the context menu:

| Item | Shortcut | Action |
|---|---|---|
| Open Image | `Ctrl+O` | Open file picker |
| Open Folder | `Ctrl+Shift+O` | Open folder picker |
| Close Image | `Delete` | Remove current image from the list |
| Copy to Clipboard | `Ctrl+C` | Copy image to clipboard |
| Save / Download | `Ctrl+S` | Download image |
| Print | `Ctrl+P` | Print image |

---

## 12. Keyboard Shortcuts

| Shortcut | Action |
|---|---|
| `Ctrl+O` | Open image file(s) |
| `Ctrl+Shift+O` | Open folder |
| `Ctrl+C` | Copy image to clipboard |
| `Ctrl+S` | Download / save image |
| `Ctrl+P` | Print image |
| `+` or `=` | Zoom in |
| `−` or `_` | Zoom out |
| `F` | Fit image to window |
| `1` | 100% zoom |
| `2` | 200% zoom |
| `L` | Rotate left (−90°) |
| `R` | Rotate right (+90°) |
| `H` | Flip horizontal |
| `V` | Flip vertical |
| `S` | Toggle slideshow in presentation mode |
| `P` | Enter presentation mode |
| `I` | Toggle info panel |
| `←` | Previous image |
| `→` | Next image |
| `↑` `↓` `←` `→` | Pan image (40 px per press) |
| `Delete` / `Backspace` | Close / remove current image |
| `F11` | Toggle fullscreen |
| `Esc` | Exit presentation mode |

---

## 13. Settings Reference

Open via **Settings** in the title bar.

### Appearance

| Setting | Options | Default |
|---|---|---|
| Theme | Light / Dark | Light |
| Canvas background | Checkerboard · Black · White · Grey · Dark | Checkerboard |
| Image rendering | Auto · Crisp Edges · Pixelated · Smooth | Auto |

### Zoom

| Setting | Options | Default |
|---|---|---|
| Default zoom on open | Fit / 100% / 50% / 200% | Fit |
| Zoom sensitivity | Slow · Normal · Fast · Very Fast | Normal |
| Smooth zoom animation | Toggle on/off | On |

### Slideshow

| Setting | Options | Default |
|---|---|---|
| Slideshow interval | 2 s · 3 s · 5 s · 8 s · 10 s | 3 s |

---

## 14. Storage & Data

### localStorage Keys

| Key | Contents |
|---|---|
| `pi-theme` | `"light"` or `"dark"` |
| `pi-settings` | JSON object of all user settings |

### Settings Object (`pi-settings`)

```json
{
  "defaultZoom":    "fit",
  "zoomSensitivity": 1.1,
  "smoothZoom":     true,
  "background":     "checker",
  "rendering":      "auto",
  "slideshowInterval": 3000
}
```

> The image list is **not persisted** between sessions. Files must be re-opened each time.

---

## 15. Architecture & Code Structure

Payas Imager is a **single HTML file** — no bundler, no framework, no server.

```
payas-imager.html
├── <style>          CSS custom properties, layout, toolbar, canvas, presentation overlay
├── <body>
│   ├── Title Bar    Open, folder, copy, save, print, settings, theme
│   ├── Tab Bar      Per-image tabs with close buttons
│   ├── Toolbar      Zoom, transform, fullscreen, nav counter
│   ├── Body Row
│   │   ├── Sidebar  Image list (thumbnails) · Info panel
│   │   └── Canvas   Image display with pan/zoom; drop-zone overlay
│   ├── Status Bar   Dimensions · size · aspect ratio · zoom %
│   └── Presentation Full-screen overlay with slideshow controls
└── <script>         All application logic (vanilla JS)
    ├── File handling    triggerOpen, triggerOpenFolder, addImages, loadFile
    ├── HEIC             heic2any conversion on load
    ├── Display          switchImage, fitImage, actualSize, zoomStep
    ├── Pan & transform  applyTransform, rotate, flip, arrow-key pan
    ├── Thumbnails       renderImageList (sidebar), renderThumbStrip (presentation)
    ├── Navigation       navigate, switchImage
    ├── Presentation     openPresentMode, closePresentMode, toggleSlideshow, presentNavigate
    ├── Export           saveImage, copyImage (Canvas API), printImage
    ├── Context menu     showContextMenu, hideContextMenu
    ├── Fullscreen       toggleFullscreen
    ├── Info panel       updateStatus, updateInfoPanel
    ├── Settings         loadSettings, saveSettings, applyBg, applyRendering
    └── Theme            setTheme
```

---

## 16. JavaScript API Reference

All functions are in global scope within the single HTML file.

### File Handling

```js
triggerOpen()              // Open OS file picker for images
triggerOpenFolder()        // Open OS folder picker
addImages(files)           // Process FileList; convert HEIC if needed; add to image array
closeImage(idx)            // Remove image at index; switch to adjacent image
```

### Display & Navigation

```js
switchImage(idx)           // Load image at index into canvas; update UI
navigate(dir)              // dir: -1 (prev) or +1 (next)
fitImage()                 // Zoom to fit the canvas; update status bar
fitImageSilent()           // Fit without triggering status bar update (used on resize)
actualSize()               // Set zoom to 100%
zoomStep(dir)              // dir: +1 (in) or -1 (out); uses zoomSensitivity setting
```

### Transform

```js
rotate(deg)                // Apply ±90° rotation to current image
flip(dir)                  // dir: 'h' (horizontal) or 'v' (vertical)
applyTransform(animate)    // Write CSS transform; animate=true for smooth transition
```

### Presentation Mode

```js
openPresentMode()          // Enter full-screen slideshow overlay
closePresentMode()         // Exit presentation overlay
toggleSlideshow()          // Start / pause auto-advance slideshow
presentNavigate(dir)       // -1 (prev) or +1 (next) within presentation
renderThumbStrip()         // Rebuild thumbnail strip in presentation footer
```

### Export

```js
saveImage()                // Trigger download of current image blob
copyImage()                // Draw image to off-screen Canvas; copy blob to clipboard
printImage()               // Open browser print dialog with image-only print CSS
```

### Sidebar & Info

```js
renderImageList()          // Rebuild sidebar image list with thumbnails
updateStatus()             // Refresh status bar with current image metadata
updateInfoPanel()          // Refresh sidebar info panel for current image
```

### Settings & Theme

```js
loadSettings()             // Read pi-theme and pi-settings from localStorage
saveSettings()             // Write current settings to localStorage
applyBg()                  // Apply canvas background setting
applyRendering()           // Apply CSS image-rendering setting
setTheme(dark)             // true = dark, false = light
```

---

## 17. License

MIT License

Copyright © Saman Wijesinghe

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.