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 ✅

• 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 ✅

• Formats: SVG
• Capabilities:
  • High-quality rendering via resvg
  • Scalable display without quality loss
  • Metadata extraction
  • ⚠️ Note: Transformations not yet implemented for vector documents

Portable Documents ✅

• Formats: PDF
• Capabilities:
  • First page rendering
  • Basic transformations on rendered page
  • ⚠️ Note: Multi-page navigation not yet implemented

Navigation

Folder Navigation ✅

• 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 ✅

• 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 ✅

• 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 ✅

• 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 ✅

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

Transformations

Image Manipulation ✅

• 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 ✅

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

Panels

• Properties panel ✅:
  • Image metadata display
  • File information
  • Toggle with i key or toolbar button
• Navigation panel (Left sidebar):
  • Toggle with n key or toolbar button
  • ⚠️ Content not yet implemented

Keyboard Shortcuts ✅

Full keyboard-driven workflow:

• Navigation: ← →
• Zoom: + - 1 f
• Pan: Ctrl + ← Ctrl + → Ctrl + ↑ Ctrl + ↓
• Transform: r Shift+r h v
• Panels: i n

Configuration

Persistent Settings ✅

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

Technical Features

Architecture ✅

• 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 ✅

• 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

Multi-page Documents ⏳

• PDF page navigation
• Multi-page TIFF support
• Page thumbnails

Error Handling ⏳

• User-friendly error messages (ShowError/ClearError prepared)
• Graceful handling of corrupted files
• Recovery suggestions

Medium Priority

Vector Document Transformations ⏳

• Rotate SVG files
• Flip SVG files
• Transform preservation on save

Enhanced Navigation

• Thumbnail strip
• Grid view for folder contents
• Quick jump to file

Slideshow Mode

• Auto-advance timer
• Configurable intervals
• Fullscreen support

Low Priority

Advanced Editing

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

Batch Operations

• Bulk transformations
• Format conversion
• Batch export

Metadata Editing

• EXIF data modification
• Comment annotations
• Tag management

Feature Status Legend

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

Contributing

Features marked as "Planned" have their message handlers already prepared in the codebase. Look for:

• OpenPath, RefreshMetadata in src/app/message.rs
• ToggleCropMode, ToggleScaleMode in transformation handlers
• Comments marked with TODO: in document implementations

Pull requests welcome! See CONTRIBUTING.md for guidelines.