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).

Switching catalogues

  • File → Open a different catalogue… opens another .catalogue-data folder (or its parent) without moving photo files.
  • File → New empty catalogue… creates a fresh database in a folder you choose.
  • File → Show current catalogue folder reveals the catalogue you are using now.
  • The previous catalogue is left as it is, so you can open it again later.

Supported Formats

Picca indexes these stills and video types. Files stay in your folders; nothing is imported into a proprietary library.

Standard stills

  • JPEG — .jpg, .jpeg
  • PNG — .png
  • GIF — .gif
  • WebP — .webp
  • BMP — .bmp
  • TIFF — .tif, .tiff
  • HEIC / HEIF — .heic, .heif, .hif

Video

  • MP4 / M4V — .mp4, .m4v
  • QuickTime — .mov
  • AVI — .avi
  • MPEG — .mpg, .mpeg, .mpe, .m2v
  • AVCHD / MPEG-TS — .m2ts, .mts
  • Matroska — .mkv
  • WebM — .webm

Video clips are indexed alongside stills. Thumbnails come from Windows; playback uses the codecs already on your PC. Look-alike search skips videos.

HEIC/HEIF decoding uses Windows Imaging Component. If photos do not open, install HEIF Image Extensions from the Microsoft Store. iPhone stills often also need HEVC Video Extensions.

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.

Similar & Duplicate Images

Find similar images

Look-alike search finds stills that look like a chosen photo — the same scene, a burst, a reprint — not files with identical contents. Videos are skipped. Tags, faces, and search are not changed.

  • Right-click a still photo and choose Find similar photos.
  • If that folder has no look-alike index yet, Picca offers to build one for the folder and its subfolders. You can also right-click a folder and choose Build look-alike index.
  • First use downloads DINOv2 Small once (about 85 MB, Apache 2.0) into this catalogue. After that the model stays on this PC.
  • Matches are ranked in the grid by visual similarity. For identical file copies, use find duplicate images instead.

Find duplicate images

  • Right-click a folder and choose Find duplicate images (identical files).
  • Groups are files with the same contents — identical copies, not near-matches.
  • Show a group in the catalogue, or remove a copy from the catalogue. Files stay on disk until you delete them yourself.

Share on Local Network

Picca can serve a browse-only HTML page on this PC so phones and other computers on the same Wi‑Fi can look through the catalogue. Photos are not uploaded to the internet. Guests cannot tag or change files.

  • Choose File → Share on local network…. A small HTML server starts on this PC (port 8787 by default).
  • Scan the QR code on the share window, or type the LAN address (or the computer-name address) into a browser on another device on the same Wi‑Fi.
  • Guests can browse folders, thumbnails, full images, and slideshows. Phones get a mobile layout of the same page.
  • Closing the share window does not stop the server. Use Stop sharing in that window.
  • Tick Keep sharing after Picca closes so the page stays available after you quit the app. Untick it if sharing should stop when Picca closes.
  • Tick Start when Windows starts to start the share server again at Windows sign-in after a reboot. Untick it to stop those automatic restarts.
  • If a phone cannot connect, allow Picca through Windows Firewall for private networks.

Batch Renaming

  • Select one or more photos or videos, then rename from the photo context menu.
  • Enter a file-name stem. A single file uses that name; a batch is numbered uniquely in the folder.
  • The original extension is kept. The catalogue, search index, and thumbnails stay in sync.

Tag Node Network

  • Open the tag network with the Nodes toolbar button or File → Tag network….
  • Nodes are tags; larger nodes appear on more photos. Lines join tags that share photos.
  • Scope to the current folder or the entire library, and filter which tag types are shown.
  • Drag to pan, right-drag to rotate, wheel to zoom. Click a tag to search it in the catalogue.

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

  • Optional on-device tagging and captions use Moondream (first use downloads the local model into this catalogue).
  • Vision actions can run on a folder or a single photo from context menus.
  • Prompt rules are editable via Edit → Customise AI tagging prompt….
  • Face recognition and vision processing run on your PC.

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.
  • Confirm the file type is in supported formats. Other extensions are ignored.

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

  • Picca opens .heic, .heif and .hif through Windows Imaging Component.
  • If HEIC files do not decode, install HEIF Image Extensions from the Microsoft Store. iPhone stills often also need HEVC Video Extensions (the free OEM version is fine).
  • Decoding can still vary by codec version and image variant.

Phone cannot open the LAN share

  • Stay on the same Wi‑Fi as the PC running Picca.
  • Confirm sharing is still running — closing the share window does not stop it, but Stop sharing does. If you quit Picca, sharing continues only when Keep sharing after Picca closes is ticked.
  • Allow Picca through Windows Firewall for private networks.

Video clips

  • Thumbnails and playback depend on Windows codecs already installed on your PC.
  • Look-alike search skips videos.