dcosnet
/
marten
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
marten/QUICKSTART.md

11 KiB
Raw Permalink Blame History

marten — Quickstart

A 5-minute guide to get marten running and showing you photos.

build from source

# Prerequisites (Arch)
sudo pacman -S --needed rust gtk3 wayland-protocols libx11 libxcb fontconfig

# Build
git clone http://git.dcos.net/dcosnet/marten.git
cd marten
cargo run --release

The first build takes ~5 minutes (lots of GUI dependencies to compile). Subsequent builds are incremental and fast.

2. Open a folder

When marten starts, you'll see a dark window with "No image — press O to open a folder" in the center.

Press O (the letter, not the number zero).

Pick a folder that has some images in it. Marten will scan it, filter out unsupported extensions, sort lexicographically, and show the first image.

The top thumbnail strip will populate over the next few seconds as thumbnails decode in the background.

3. Navigate

Action How
Next photo → arrow key, or L, or scroll wheel down
Previous photo ← arrow key, or H, or scroll wheel up
First photo G (uppercase — vim convention)
Last photo g (lowercase)
Random photo in this folder z, or click the shuffle button in the toolbar
Random photo in folder tree Shift+Z
Jump to specific image click its thumbnail in the top strip

The scroll wheel works anywhere in the image area — you do not need to position the cursor over the image. This is the ristretto-style behavior marten was designed around.

Whenever the current image changes (scroll, arrow key, random jump, or thumbnail click), the top thumbnail strip auto-scrolls to keep the current entry centered — like a video editor's playhead on a timeline.

4. Zoom and pan

Action How
Fit to window 0 (zero), or click the fit icon in the bottom toolbar
100% (actual size) 1, or click the 1:1 icon
Zoom in +, or Ctrl+↑, or click +
Zoom out -, or Ctrl+↓, or click −
Pan when zoomed scroll wheel, or drag the scrollbars

In fit-to-window mode (default), the scroll wheel navigates between photos. In any zoom mode (100% or custom), the scroll wheel pans the image. This prevents accidental navigation while you are trying to look at a zoomed detail.

Each zoom step multiplies the factor by 1.1 (zoom in) or divides by 1.1 (zoom out), producing smooth, graceful changes that do not overshoot.

5. Rotate

Action How
Rotate 90° clockwise R, or click the rotate-CW icon, or right-click → Rotate 90° CW
Rotate 90° counter-clockwise Shift+R, or click the rotate-CCW icon, or right-click → Rotate 90° CCW

Rotation is non-destructive — the original file is never modified. The pixel buffer is rotated in memory and the image is re-rendered. Switching to another photo resets rotation to 0°.

6. Right-click menu

Right-click anywhere in the image area. You will get a gpicview-style menu with 12 actions:

  • Open With… — launches xdg-open to hand the file to your system's default image handler.
  • Copy Path — copies the absolute file path to the clipboard.
  • Copy Image — copies the actual pixel data to the clipboard (so you can paste into GIMP, Krita, etc.).
  • Copy to Pictures — copies the file to ~/Pictures/. If a file with the same name already exists there, marten appends _1, _2, etc.
  • Rotate 90° CW / CCW — same as the toolbar buttons.
  • Set as Wallpaper — tries gsettings (GNOME) first, falls back to feh for standalone window managers.
  • Move to Trash — sends the file to the system trash via the trash crate. Removes it from the navigator and loads the next image.
  • Delete Permanently — std::fs::remove_file(). Bypasses trash entirely. Use with care.
  • Properties — opens the EXIF properties panel (see step 7).
  • Export folder as video… — opens the video export dialog (see step 8).
  • About marten — opens the About dialog.

7. Random navigation, sidebar, slideshow, EXIF panel

Random navigation is new in v0.4.0; the sidebar, slideshow, and EXIF panel arrived in v0.3.0 and are grouped here for browsing-mode reference.

Random navigation (z and Shift+Z)

Press z to jump to a random image in the current folder. Press Shift+Z to jump to a random image anywhere in the current folder's parent tree — marten walks the parent directory recursively, collects every supported image across all subfolders, and picks one at random. If the chosen image lives in a different subfolder, marten switches to that folder automatically. Both actions are step-aware: subsequent arrow/scroll navigation continues sequentially from the new position.

Click the shuffle button in the bottom toolbar (between Next and Fit) for the same effect as pressing z.

Folder tree sidebar (Tab)

Press Tab to slide in a 240px left panel. It lists the sibling folders of your current location — every child of the parent directory that contains at least one supported image — each with an image count. Click any entry to switch folders. Press Tab again to dismiss. The sidebar hides automatically in fullscreen.

Slideshow mode (s)

Press s to start an automatic slideshow. Marten advances to the next photo every three seconds via an iced::time::every subscription. Press s again or Escape to stop. A toast confirms the start and stop of the slideshow.

EXIF properties panel (i)

Press i (or right-click → Properties) to open a modal with the full file metadata:

  • Filename, path, dimensions, format, file size
  • Camera make and model
  • Lens model
  • ISO, aperture (f-number), shutter speed, focal length
  • Timestamp
  • GPS coordinates
  • Orientation flag

EXIF is parsed with kamadak-exif. Files without EXIF (PNG, SVG, OpenEXR, screenshots, etc.) still show the file-info rows. Press Escape or click outside the card to dismiss.

8. Export a folder as video

Right-click → Export folder as video… opens a modal that turns the current folder into a .webm slideshow with an audio track of your choice.

  1. The dialog shows the image count and the folder name.
  2. Click Select audio file and pick an audio file (.mp3, .wav, .ogg, .flac, .aac, or .m4a).
  3. Click Select output file and pick a destination .webm path.
  4. Choose a codec: VP9 (libvpx-vp9, broad compatibility, faster encode) or AV1 (libaom-av1, better compression, slower encode).
  5. Set the seconds-per-image duration (default 3.0).
  6. Click Export. ffmpeg runs in a background thread via tokio::task::spawn_blocking; the dialog shows "Exporting…" then "Export complete!" or an error message.

Marten invokes ffmpeg with the concat demuxer and a temporary file list. ffmpeg must be installed and on $PATH — if it is missing, the dialog reports "ffmpeg not found. Install ffmpeg to use video export."

9. Keyboard shortcuts (full list)

Action Default bindings
Next photo → or L
Previous photo ← or H
First photo g
Last photo G
Random photo (same folder) z
Random photo (folder tree) Shift+Z
Zoom in + or Ctrl+↑
Zoom out - or Ctrl+↓
Fit to window 0
Actual size (100%) 1
Rotate CW r
Rotate CCW Shift+R
Toggle sidebar Tab
Toggle slideshow s
Toggle fullscreen F11
Toggle chrome (minimal mode) Shift+F
Open folder o
Copy to Pictures Shift+Home
Delete permanently Shift+Delete
Properties (EXIF panel) i
About marten a
Quit q or Ctrl+Q
Dismiss overlay (menu/modal) Escape

All of these are configurable — see step 10.

10. Customize the keymap

Copy the default keymap to your config directory:

mkdir -p ~/.config/marten
cp config/keymap.toml ~/.config/marten/keymap.toml
$EDITOR ~/.config/marten/keymap.toml

The format is a flat TOML map. Each action takes a list of bindings (you can bind multiple keys to the same action):

next_photo = ["Right", "l", "Space"]
prev_photo = ["Left", "h", "Backspace"]

Modifier syntax: Ctrl+Shift+R, Alt+Tab, Logo+L (logo = Super/Windows/Cmd). Modifiers are case-insensitive; the key name itself is case-sensitive (g and G are different bindings, following vim convention).

Restart marten after editing. Unknown keys are warned about in the console (run with RUST_LOG=info to see warnings) but do not crash.

11. Fullscreen / minimal mode

Press F11 (or Shift+F) to toggle fullscreen. In this mode:

  • The thumbnail strip, sidebar, toolbar, and status bar all hide.
  • The image fills the entire window.
  • A small floating hint at the top-center of the screen ("Press F11 to exit fullscreen") reminds you how to leave.
  • All keyboard shortcuts still work.
  • Right-click still works.

Press F11 or Shift+F again to exit fullscreen.

12. Quit

Press Q or Ctrl+Q. Or close the window normally.

Troubleshooting

"No supported images in that folder" — the folder exists but contains no files with extensions marten recognizes. Check that your files end in .png, .jpg, .jpeg, .gif, .webp, .avif, .bmp, .ico, .cur, .jxl, .tif, .tiff, .svg, .svgz, or .exr.

The window opens but is blank / shows a black screen — your GPU driver may not support Vulkan. Check the console output for wgpu errors. Marten requires a Vulkan-capable GPU; NVIDIA, AMD, and Intel drivers all work.

Anti-list modal appears — you tried to open a .heic, .cr3, .nef, .arw, .psd, .dng, or Apple Live Photo file. Marten deliberately refuses these formats. The modal explains why and suggests an open alternative (e.g. convert HEIC to AVIF).

Thumbnails are slow to load — marten decodes thumbnails on a tokio spawn_blocking thread pool at 72px using nearest-neighbor filtering. For folders with thousands of images, only the current ±15 are cached at any time. If your disk is slow (network mount, spinning rust), the first scroll through a fresh folder may take a moment.

"ffmpeg not found" in the export dialog — video export shells out to ffmpeg. Install it via your distribution package manager (sudo pacman -S ffmpeg on Arch, sudo apt install ffmpeg on Debian, sudo dnf install ffmpeg on Fedora) and ensure the ffmpeg binary is on $PATH.

RUST_LOG=warn marten — shows warnings (malformed keymap, decode errors) in the console. RUST_LOG=info adds informational messages (startup, adapter selection). RUST_LOG=debug is very noisy.

Where to go next

  • README.md — full project overview, format support tiers, license.
  • DECISION.md — architectural decision records (why iced, why dark-only, why the anti-list, etc.).
  • BLOG.md — v0.4.0 release notes and design rationale.
  • config/keymap.toml — the default keymap, fully commented.