noctua/docs/features.md

Noctua Features

This document describes the implemented and planned features of Noctua, a modern image viewer for the COSMIC desktop environment.

Current Features

Document Support

Raster Images (Implemented)

• Formats: PNG, JPEG, GIF, BMP, TIFF, WebP, and all formats supported by image-rs
• Capabilities:
  • Full pixel-perfect rendering at 100% zoom
  • Lossless transformations (rotate, flip)
  • Real-time transformation preview
  • EXIF metadata extraction

Vector Graphics (Implemented)

• Formats: SVG
• Rendering: High-quality rendering via resvg library
• Capabilities:
  • Scalable display at any zoom level without quality loss
  • Transformations (rotate, flip)

Portable Documents (Implemented)

• Formats: PDF
• Rendering: Full PDF rendering via poppler library
• Multi-page navigation: Browse through all pages of a document
• Page thumbnails: Left sidebar shows page previews (generated on demand)
• Transformations: Rotate and flip on rendered pages

Navigation

Folder Navigation (Implemented)

• Automatic folder scanning: When opening an image, all supported images in the same folder are indexed
• Quick navigation:
  • Arrow keys (Left/Right) to navigate between images
  • Footer displays current position (e.g., "3 / 42")
  • Seamless transitions between images

File Opening (Implemented)

• Command-line arguments: Open images directly from terminal
• Default directory: Configurable starting location (defaults to XDG Pictures)
• File dialog not yet implemented

View Controls

Zoom (Implemented)

• Mouse wheel: Zoom in/out centered on cursor position
• Keyboard shortcuts:
  • + or = - Zoom in
  • - - Zoom out
  • 1 - Reset to 100% (Actual Size)
  • f - Fit to window
• View modes:
  • Fit: Automatically scales image to fit window while preserving aspect ratio
  • Actual Size: Displays image at 100% (1:1 pixel mapping)
  • Custom: Any zoom level from 10% to 2000%
• Footer display: Real-time zoom percentage or "Fit" indicator

Pan (Implemented)

• Mouse drag: Click and drag to pan around zoomed images
• Keyboard shortcuts: Ctrl + Arrow Keys for precise panning
• Smart boundaries: Pan is automatically limited to image boundaries
• Auto-center: Images smaller than viewport are automatically centered

Bidirectional State Sync (Implemented)

• Mouse interactions update keyboard/button controls
• Keyboard/button controls update mouse interaction state
• No conflicts between input methods

Transformations

Image Manipulation (Implemented)

• Rotate:
  • r - Rotate 90° clockwise
  • Shift + r - Rotate 90° counter-clockwise
  • Toolbar buttons available
• Flip:
  • h - Flip horizontally (mirror)
  • v - Flip vertically
  • Toolbar buttons available
• Lossless operations: All transformations preserve original image quality
• Real-time preview: Changes are immediately visible

User Interface

COSMIC Integration (Implemented)

• Native COSMIC design: Follows COSMIC desktop design language
• Theme support: Automatically adapts to system light/dark theme
• Header toolbar:
  • Left: Navigation controls (Previous/Next) and panel toggle
  • Center: Transformation buttons (Rotate, Flip) - horizontally centered
  • Right: Information panel toggle
• Footer bar:
  • Zoom controls with buttons
  • Current zoom level display
  • Image dimensions
  • Navigation position counter

Panels (Implemented)

• Properties panel:
  • Image metadata display
  • File information
  • Action buttons:
    • Set as Wallpaper (works with COSMIC, GNOME, KDE, XFCE, and tiling WMs)
    • Open With… (planned)
    • Show in Folder (planned)
  • Toggle with i key or toolbar button
• Navigation panel (Left sidebar):
  • Toggle with n key or toolbar button
  • For multi-page documents (PDF): Shows page thumbnails
  • Click to navigate to specific page

Keyboard Shortcuts (Implemented)

Full keyboard-driven workflow:

• Navigation: ← →
• Zoom: + - 1 f
• Pan: Ctrl + ← Ctrl + → Ctrl + ↑ Ctrl + ↓
• Transform: r Shift+r h v
• Panels: i n
• Actions: w (Set as Wallpaper)

Desktop Integration

Wallpaper Support (Implemented)

• Set as Wallpaper: One-click wallpaper setting with cross-desktop compatibility
• Supported desktop environments:
  • COSMIC Desktop (direct config file integration)
  • GNOME (via gsettings)
  • KDE Plasma (via wallpaper crate)
  • XFCE (via wallpaper crate)
  • Tiling window managers (via feh)
• Multiple access methods:
  • Keyboard shortcut: w
  • Icon button in Properties panel
  • Tooltip support for discoverability
• Automatic fallback: Tries multiple methods until one succeeds

Configuration

Persistent Settings (Implemented)

• Panel states: Remembers which panels were open
• Default directory: Customizable starting location
• Settings location: ~/.config/noctua/config.toml

Technical Features

Architecture (Implemented)

• Clean separation: View layer agnostic to document format
• Polymorphic documents: Single DocumentContent interface for all formats
• Efficient rendering: Leverages COSMIC's iced renderer
• Type-safe transformations: Compile-time guarantees for image operations

Performance (Implemented)

• Lazy loading: Images loaded on-demand
• Efficient folder scanning: Fast directory traversal
• Minimal memory footprint: Only active document kept in memory
• Smooth zooming: Hardware-accelerated rendering

Planned Features

High Priority

File Operations

• File dialog integration (OpenPath message prepared)
• Save transformed images
• Copy/Move/Delete operations
• Drag-and-drop support

Medium Priority

Multi-format TIFF Support

• Multi-page TIFF navigation (infrastructure ready)
• Page thumbnails for TIFF (same as PDF)

Metadata Editing

• EXIF data modification
• Comment annotations
• Tag management

Low Priority

Advanced Editing

• Crop tool (message prepared)
• Scale/Resize tool (message prepared)
• Basic color adjustments (brightness, contrast)

Enhanced Navigation

• Grid view for folder contents
• Quick jump to file

Slideshow Mode

• Auto-advance timer
• Configurable intervals
• Fullscreen support

Feature Status Legend

• Implemented: Fully functional and tested
• Planned: Design complete, implementation pending
• Partial: Basic functionality exists, enhancements needed
• In Progress: Currently being developed