Picca Detailed User Manual

This manual covers setup, everyday workflows, advanced tools, and troubleshooting. Use the searchable index to jump directly to any feature.

Quick Start

  1. Launch picca.exe.
  2. On first run, choose your main photo folder in the setup dialog.
  3. Wait for the initial index to complete.
  4. Browse photos in the center grid, then use tags/search in the right panel.
Tip: Picca stores catalog data in a local .catalogue-data folder near your library root.

Interface Layout

  • Left: Folder and album navigation.
  • Center: Photo grid and full-screen photo viewer.
  • Right: Search query, tag tools, tag cloud, selection tags, and caption editor.
  • Top: App toolbar, thumbnail size controls, map/slideshow quick actions.

Library Setup & Folders

Main library folder

  • First-run setup asks you to select the main photo folder.
  • Picca indexes this folder recursively.

Extra folders

  • Use the folder sidebar action to add additional folders into the same catalog.
  • Right-click a folder for contextual actions (scan, auto-tag, vision, remove).

Indexing & Sync

  • Indexing tracks files by path, size, modified time, and hash so it can resume safely.
  • Use File → Sync photos folder to refresh catalog state after external file changes.
  • A running sync can be canceled using the sync status action.

Search, Tags, and Captioning

Boolean query search

  • Use queries like sunset AND beach OR portrait NOT night.
  • Search updates the visible grid to matching photos.

Tag filtering and editing

  • Filter tags by tag type in the tag cloud panel.
  • Select photos, enter tag names, then choose Add, Remove, or Replace.
  • Right-click tags for quick actions (search, edit tag, edit tag type, apply to folder).

Captions

  • Select one or more photos, edit the caption field, and save.
  • Captions are searchable and can be generated by AI tools.

Albums

  • Create an album from the Albums tab.
  • Right-click an album to rename or delete it.
  • Right-click photos to add or remove them from albums.
  • Albums are virtual organization only; originals remain in their folders.

Photo Viewer & Slideshow

  • Open viewer by double-clicking a thumbnail or using photo context menu.
  • Use Previous/Next or arrow keys for navigation.
  • Rotate images with left/right rotate controls.
  • Start slideshow from viewer or top bar button.

Slideshow controls

  • Esc exits slideshow mode and returns to normal UI.
  • Use the top-left exit button for mouse-based exit.

Face Detection & Naming

  • Run face detection from folder/photo context actions.
  • Review face suggestions in the face panel.
  • Confirm accepted names or reject false detections.
  • Use Accept all named to apply all currently named suggestions in bulk.
  • Face tags are stored as searchable face:PersonName tags.

Map and Geotagging

  • Open map with the Map button or menu action.
  • Filter map photos by All, Located, and No location.
  • Search places by city/town/address in the map search box.
  • Assign location by selecting photos then clicking map, or dragging thumbnails onto map.
  • Exit map with the Exit map button.

How Picca decides a photo’s location

A photo can appear on the map from more than one source:

  1. EXIF GPS — coordinates already stored in the photo file.
  2. Place-class image tags — if a photo has no GPS, Picca uses place tags (tag type place, a Place label, a place: prefix, or names such as place:Paris) to predict a location. It looks up those place names and drops a pin on the map.
  3. Manual pin — you click the map or drag a thumbnail onto it.

When you open Map, Picca also reads GPS and place tags in the background for photos that still have no location. Thumbnails with a location from a place name show a “Location from place name” badge. Manual pins are not overwritten by later EXIF or place-tag lookups.

Tip: Tagging a photo as a place (for example place:Cornwall or a Place-type tag “Italy”) can put it on the map even when the camera never wrote GPS.

AI Features

  • Auto-tagging can generate descriptive tags for selected scope.
  • Vision actions can run on a folder or a single photo from context menus.
  • Prompt rules are editable via Edit → AI prompt rules.
  • Face recognition and vision processing are local-first.

Backup, Import, Export

  • File → Back up database creates a backup of catalog metadata.
  • File → Import database backup restores previous catalog state.
  • Photo context menu includes Export photo.
  • Edit → Copy selected paths copies filesystem paths to clipboard.
  • Help → Open logs opens diagnostic logs for support.

Troubleshooting

Photos not appearing

  • Run sync from the File menu.
  • Check selected folder/album filters and query filters.

Face detection unavailable

  • Wait for model download to finish (first-run setup can take time).
  • GPU is optional; Picca falls back to CPU mode automatically.

Map issues

  • Confirm internet access for tile/place services.
  • Verify photos contain GPS data or manually geotag in map mode.

HEIC support

  • HEIC decoding can vary by system codecs and image variants.