noctua/docs/usage.md

Usage Guide

Noctua is a modern image viewer for the COSMIC desktop environment with full keyboard support.

Opening Images

Command Line

Open an image directly from the terminal:

noctua /path/to/image.png

When you open an image, Noctua automatically scans the folder and indexes all supported images for quick navigation.

Supported Formats

• Raster Images: PNG, JPEG, GIF, BMP, TIFF, WebP, and all formats supported by image-rs
• Vector Graphics: SVG (with scalable rendering)
• Portable Documents: PDF (with multi-page navigation and thumbnails)

Keyboard Shortcuts

All keyboard shortcuts are case-insensitive unless otherwise noted.

Navigation

Key	Action	Description
←	Previous image	Navigate to the previous image in the folder
→	Next image	Navigate to the next image in the folder

The footer shows your current position (e.g., "3 / 42").

For multi-page documents (PDF):

• Click thumbnails in the left sidebar to jump to a specific page
• Use ← → to navigate between pages

Zoom and View

Key	Action	Description
+ / =	Zoom in	Increase zoom by 10%
-	Zoom out	Decrease zoom by ~9%
1	Actual size (100%)	Display image at pixel-perfect 1:1 scale
f	Fit to window	Scale image to fit the window while preserving ratio

You can also zoom with the mouse wheel - the zoom centers on your cursor position.

The current zoom level is displayed in the footer (e.g., "150%" or "Fit").

Pan

Pan controls allow you to move around zoomed images:

Key	Action	Description
Ctrl + ←	Pan left	Move view to the left
Ctrl + →	Pan right	Move view to the right
Ctrl + ↑	Pan up	Move view upward
Ctrl + ↓	Pan down	Move view downward
0	Reset pan	Center the image

You can also click and drag with the mouse to pan around zoomed images.

Transformations

Key	Action	Description
h	Flip horizontal	Mirror the image horizontally
v	Flip vertical	Flip the image upside down
r	Rotate clockwise	Rotate 90° clockwise
Shift + r	Rotate counter-clockwise	Rotate 90° counter-clockwise

All transformations are lossless and show in real-time.

Panels and UI

Key	Action	Description
i	Toggle properties	Show/hide the properties panel (metadata)
n	Toggle navigation	Show/hide the navigation sidebar

For multi-page documents (PDF), the navigation sidebar displays page thumbnails. Click on a thumbnail to jump to that page.

Actions

Key	Action	Description
w	Set as wallpaper	Set the current image as desktop wallpaper

Mouse Controls

Zoom

• Mouse wheel up/down: Zoom in/out centered on cursor
• Footer buttons: Click zoom in/out buttons for step-by-step control

Pan

• Click and drag: Pan around zoomed images
• Hold and drag anywhere on the image to move the view

Navigation

• Footer navigation: Use Previous/Next buttons to browse images

Toolbar

The header toolbar provides quick access to common operations:

Left Side

• Navigation toggle: Show/hide the sidebar
• Previous/Next buttons: Navigate between images in the folder

Center (Horizontally Centered)

• Rotate buttons: Rotate clockwise or counter-clockwise
• Flip buttons: Flip horizontally or vertically

Right Side

• Properties toggle: Show/hide the metadata panel

Properties Panel

The properties panel (toggle with i) displays image metadata and provides quick actions:

Action Buttons

Located at the top-right of the properties panel:

• Set as Wallpaper (w key): Set the current image as your desktop wallpaper

  • Works with COSMIC, GNOME, KDE, XFCE, and tiling window managers
  • Automatically detects your desktop environment
  • Falls back to alternative methods if the primary method fails

• Open With (planned): Open the image with another application

• Show in Folder (planned): Open the containing folder in your file manager

Metadata Display

• File Information: Name, format, dimensions, file size, color type
• Camera Information (if available): Camera model, date taken, exposure settings, GPS location

Footer Information

The footer displays useful information:

• Zoom controls: Zoom out, current zoom level, zoom in, fit buttons
• Image dimensions: Width × Height in pixels
• Navigation position: Current image / Total images in folder

For PDFs, it also shows the current page number.

Tips and Tricks

Keyboard-Driven Workflow

Noctua is designed for efficient keyboard use:

1. Open an image from terminal
2. Use ← → to browse through the folder
3. Press r to rotate, h or v to flip
4. Use + - to zoom, Ctrl + arrows to pan
5. Press i to check metadata

Zoom and Pan Together

• Zoom with mouse wheel while hovering over the area you want to examine
• The zoom centers on your cursor, making it easy to focus on details
• Once zoomed, drag with mouse or use Ctrl + arrows to navigate

Bidirectional Controls

Mouse and keyboard work together seamlessly:

• Zoom with keyboard, pan with mouse
• Zoom with mouse wheel, the footer updates automatically
• Pan with keyboard, continue with mouse drag

Configuration

Settings are stored in ~/.config/cosmic/org.codeberg.wfx.Noctua/v1/.

Configurable Options

• Default directory: Set your preferred starting location
• Panel states: Your panel preferences are remembered between sessions

Planned Features

The following features are prepared in code but not yet implemented:

File Operations

• File open dialog
• Save transformed images
• (Copy/Move/)Delete operations

Document Support

• SVG rendering (implemented)

Advanced Editing

• Crop mode (c key prepared)
• Scale/Resize mode (s key prepared)

See features.md for a complete list of planned features.