Cupola

A fast, native image viewer, built with the COSMIC desktop environment in mind, but works on all DE's.

Features

• Gallery: This is the default view. It enables the user to brows images as in a grid with quick thumbnail previews.
• Aspect Ratio Preservation: Thumbnails maintain their original aspect ratios without stretching or distortion, displayed with letterboxing/pillarboxing within a consistent grid.
• Centered Thumbnails: All thumbnails are centered within their grid cells with proper padding for different aspect ratios.
• Single Image Modal: Selecting an image from the Gallery will open a popup for the user to view the selected image.
  • The user can zoom and scroll around the zoomed image.
• Fast Loading: Concurrent image decoding with LRU caching.
• Keyboard Navigation: Navigate images without taking your hands off the keyboard.
• Native Desktop Environment Integration: Follows your desktop theme and conventions.
• Accessibility: Screen reader support with image descriptions and keyboard navigation for all thumbnails.

Dependencies

• Rust 2024 Edition installation
• libxkbcommon-dev
• just

Screenshots

Installation

---

From Source

git clone https://codeberg.org/bhh32/cupola.git
cd cupola
sudo just install

Supported Formats

Format	Extension	Works/Needs Testing/Planned
PNG	.png	works
JPEG	.jpg, .jpeg	works
GIF	.gif	works
WebP	.webp	works
BMP	.bmp	works
TIFF	.tif, .tiff	works
ICO	.ico	works
RAW	.raw, .cr2, .cr3, .nef, .arw, .dng, .orf, .rw2	needs testing
HEIC/HEIF	.heic, .heif (requires --features heif)	planned

Usage

# CLI methods

# Just open the viewer to the last directory selected
cupola

# Open the viewer to a directory
cupola ~/Pictures/wallpapers

# Open the viewer to a specific image
cupola ~/Pictures/wallpapers/superman_wallpaper.png

If you have it installed, using the just install command, you use it just like you would any other image viewer application. If it's set as the default for opening images, it will start with an image opened from the file explorer application.

Keyboard Shortcuts

Key	Action
← / →	Previous/Next image
↑ / ↓	Gallery - Focus image above/below currently focused
Ctrl + '=' / Ctrl + '-'	Zoom In/Out (single image modal open)
Ctrl + F	Fit in Window (single image modal) open
Ctrl + 0	Zoom to 100% (single image modal only, not the same as Fit in Window)
ESC	Close Single View Modal
Ctrl + Q or Alt + F4	Close the application

Configuration Files

Settings are stored at the standard XDG config location:

• ~/.config/cosmic/org.codeberg.bhh32.Cupola/

Building for Development

just build # Debug build just build-release # Release build just run # Run in release (can test better) cargo fmt # Format code cargo clippy # Run linter

Roadmap

The goal is to build a fast, private image manager that helps organize photo libraries through tags, locations, and smart detection without shipping photos to someone else's cloud. All ML-based features run locally using embedded models. No cloud AI, no third-party LLMs, nothing leaves your computer.

In Progress

• Set as wallpaper
• Custom Flex Grid Widget
• Theme switching
• Gallery keyboard navigation (arrow keys, Enter to select)
• Fix gallery scrolling to follow focus
• Refine scroll logic (smart scrolling) and fix geometry bugs
• Focus first image on load (without opening modal)
• Visual focus indicator on thumbnails
• Directory watching for external file changes
• Zoom controls with fit-to-window
• Thumbnail caching with configurable sizes
• Modal single-image view with navigation
• Settings page UI
• Slideshow in single view modal (not full implementation)
• Delete image with confirmation
• Copy image to clipboard
• Sort by name, date, size
• Rotate 90/270 degrees
• Flip horizontal/vertical

Core Features

• Slideshow with play/pause and timer controls
• Filename search/filter
• Zoom slider
• Animated GIF playback
• Drag and drop to open folders/images
• Recent folders menu

Editing

• Rotate 90/270 degrees
• Flip horizontal/vertical
• Crop
• Save and Save As

Annotations

• Freehand drawing
• Highlighter
• Arrows and shapes
• Text labels
• Blur/redact regions

Organization

• Manual tagging
• Boolean tag queries (AND/OR/NOT)
• Smart collections (saved filters)
• Duplicate detection (SHA256 + perceptual hash)
• Example-based auto-tagging using local embedded ML (faces, pets, objects)
• Color search by dominant color

Location

• Map view with clustered pins
• Location heat map
• Click-to-filter by map region
• Timeline view

Metadata and Export

• EXIF viewer/editor
• Export presets
• Batch format conversion

Privacy

• GPS metadata viewer
• Strip location data from images
• Privacy audit for sensitive metadata

Completed

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT

Known Bugs/Issues

• Slideshow skips the first image due to starting before single image modal can popup.
• Single image modal blocks the use of the rest of the UI.
• While in gallery, no image selected, using the left and right arrow keys opens the single image modal to cycle the images.
• Deleting an image externally, currently selected or not, while any image is selected doesn't always refresh the directory.
• Keyboard navigation in gallery mode diagnonal navigation and no scrolling.