User Guide

New for 0.8.2

• Faster clustering - the app now groups faces even faster and uses less memory (RAM) doing it.
• Hidden people remain hidden - people you hide stay hidden even when they share a group photo with someone else, so that photo no longer shows up under the other people in it. To see those group photos there is now a toggle in the settings, Show hidden people in group photos (see General Settings).
  • If you find that a person is missing photos you know they have, turn that toggle on. The default was left at keeping hidden people hidden because it is the better privacy choice over the long term.
• Older graphics cards fall back to the CPU instead of failing to start the AI, so the app no longer ends up with nothing to show after a scan.
• Resize and maximise like a normal window - drag any edge or corner to resize, double-click the title bar to maximise or restore, and maximising now keeps the Windows taskbar visible instead of covering it.
• A refreshed look - retuned colours in both themes, a curated set of six accent colours, styled dropdown menus, and scrollbars that appear only while you scroll (always visible and thicker, when high contrast is enabled)
• Custom accent colour - pick any colour with a full inbuilt colour picker, including an eyedropper. Newly implemented, so it must first be turned on in Advanced Settings under Custom colours.
• Better colour-vision support - instead of daltonization, the app swaps in specially chosen palettes and adds cues that do not rely on colour, such as the caution mark on red buttons. It can also follow your Windows colour filter automatically.
• Reduce transparency - the blurred, see-through backdrops behind dialogs can be replaced with solid ones; the app follows your Windows transparency setting unless you choose otherwise.

New for 0.8.0 (present in 0.8.2)

• Accessibility options (improved in 0.8.2 and includes an extra option for reduce transparency) increase contrast, bold text, dyslexia-friendly fonts, and colour-blindness assist.
• Export photos into folders - save one person, several people, or everyone into neat per-person folders on your disk. Includes an option (first has to be enabled in Advanced Settings) to use hardlink the organised exported files, which doesn't use any extra storage for the exported photo.
• Reveal a photo in File Explorer - the right-click menu on a photo now opens that photo, already selected, in its source folder.
• Sort, Filter, and Group a person's photos - reorder by name or date, hide certain file types, or split the grid into sections by folder, date, or camera, and other metadata that are available.
• A bigger photo preview with a side panel that shows the photo's details (file name, size, date taken, camera, and more).
• Pin people to the top of the list so your most important people are always easy to find.
• Select several people at once and act on them together (export, pin, or hide).
• Duplicate photos are shown once per person, so a collage or a duplicate file no longer fills the grid with repeats.
• XMP sidecar files - optionally save the face names so other photo apps (like digiKam or Lightroom) can read them.
• A redesigned Settings screen with six clear sections, a new About page, and an improved log with a Normal/Debug detail level.
  • Please don't change to normal before the release of 1.0.0 as debug logs are only slightly larger in size (a few kb) but helps pinpoints a lot of bugs when you submit a bug report.
• A cleaner bottom bar that combines the Settings button, status text, progress bar, and Help button into one row.
• Support for NVIDIA RTX 50-series GPUs for faster grouping on the newest graphics cards.
  • Native GPU support is only available on Nvidia RTX series or equivalent Nvidia datacenter and pro GPU. (for now, will be expanded to support AMD and Intel Arc GPU)
• Faster startup (further improved in 0.8.0) - the app no longer re-calibrates when your source photos have not changed.

First Launch

The first time you open the app, you will see a message that says "No Folders to Scan". This is normal - the app does not yet know where your photos are.

Click the "Take me to settings" button to add your photo folders.

Adding Photo Folders

1. Click the Settings button at the bottom-left of the window.
2. In the list on the left of Settings, click Folders to Scan.
3. Under "Include folders for scanning", click the + Add Folder button.
4. Choose the folder that has your photos in it, and click OK.
5. Repeat for any other photo folders you have.
6. Click Close Settings at the bottom-left.

The app now starts scanning your photos automatically. The very first scan can take a while depending on how many photos you have - this is normal, and it only happens once.

Supported photo types: JPG, JPEG, PNG, BMP, GIF, HEIC, and HEIF.

The Title Bar (top of the window)

At the very top-right of the window there are three small buttons:

• Minimize (the dash) - hides the window. If "Close to tray" is on, the app keeps running in the background.
• Maximize (the square) - makes the window fill the screen while keeping the Windows taskbar visible, or returns it to its previous size. Double-clicking the empty part of the title bar does the same.
• Close (the X) - closes the window. If "Close to tray" is on, this hides the app to the system tray instead of quitting it (see General Settings).

The window can be resized by dragging any edge or corner, just like a regular window, down to a minimum size of 1360 x 768.

The People List (left side)

• This shows every person the app has found.
• Until you rename them, people are listed as "Person 1", "Person 2", and so on.
• Each row shows a small face thumbnail and how many photos that person appears in.
• Click a person to see all of their photos on the right.

At the top of the People list there are two small buttons:

• Sort people (the lines icon) - click it to choose how the list is ordered: by name (A to Z or Z to A) or by number of photos (low to high or high to low).
• Jump to (the grid-of-dots icon) - this appears when you are sorting by name. Click it to get an A-Z list, then click a letter to jump straight to names starting with that letter.

The Photo Area (right side)

When you click a person, their photos appear here as thumbnails. Along the top of this area you will find:

1. The person's name on the left.
2. Filter button - choose which photos to show (see Filtering Photos).
3. Group button - split the photos into sections, for example by date or folder (see Grouping Photos).
4. Size slider - drag it left or right to make the thumbnails smaller or larger.
5. View mode dropdown:

• Show entire photo (default) - thumbnails show the whole picture.
• 
• Zoom to tagged faces - thumbnails zoom in to just this person's face. This is very handy for finding someone in group photos.
• 

6. Sort dropdown - choose the order of the photos (see Sorting Photos).

To work with a single photo:

• Single-click a photo to open a large preview inside the app.
• Double-click a photo to open it in your computer's normal image viewer.
• Right-click a photo (or click its three-dot menu) for more options. The three dot menu appears only on hover.

The Bottom Bar

The bottom of the window is a single row with:

• Settings button (left) - opens the Settings screen.
• Status text (middle) - normally shows something like "Found: 1,234 faces". While the app is busy, it shows what it is doing instead.
• Progress bar - appears only while the app is scanning, exporting, or otherwise working. A Cancel button appears next to it for actions you can stop (such as exporting).
• Help button (right, the "?" icon) - opens a quick tips window.

Viewing Someone's Photos

1. Click a person's name in the left list.
2. All of their photos appear on the right.
3. Single-click any photo for a large preview, or double-click to open it in your normal image viewer.

Renaming a Person

People start with placeholder names like "Person 1". Giving them real names makes everything easier, and the app remembers the name forever.

1. Find the person in the left list.
2. Click the three-dot menu next to their name (or right-click the row).
3. Click Rename.
4. Type the person's real name.
5. Click Confirm.

From now on, every photo of that person is tagged with that name - even after you change settings or add new photos later.

If you type a name that already belongs to someone else, the app asks what you want to do: merge the two people, choose a different name, or go back. This is useful when the same person was accidentally split into two entries - giving them the same name merges them on the next recalibration.

Setting a Cover or Thumbnail (Primary) Photo

The first photo shown for a person is their "cover" photo (also called the primary photo). You can pick a better one:

1. Click the person to show their photos.
2. Find the photo you want as the cover.
3. Right-click it (or use its three-dot menu) and click Make primary photo.

That person's thumbnail in the People list now uses this photo.

Pinning a Person to the Top

Pinning keeps your favourite or most-used people at the top of the list, no matter how the list is sorted.

1. Click the three-dot menu next to a person (or right-click the row).
2. Click Pin.

A small pin icon appears on the right edge of that person's row, and they move to the top. To undo this, open the same menu and click Unpin.

If you pin several people, they all sit at the top together and stay in your chosen sort order among themselves.

Selecting Several People at Once

You can act on more than one person at the same time, the same way you would select multiple files in Windows:

• Ctrl-click a person to add or remove them from your selection.
• Shift-click a person to select everyone between your last click and this one.
• A small bar appears showing how many people are selected, with a Clear button. Pressing Esc also clears the selection.

While two or more people are selected, opening the menu (three dots or right-click) shows group actions:

• Export Selected to Folder - save all the selected people's photos at once.
• Pin / Unpin - shown only when all selected people are in the same state.
• Hide / Unhide - shown only when all selected people are in the same state.

Hiding a Person

If someone appears in your photos but you do not want to see them in the list:

1. Click the three-dot menu next to their name (or right-click the row).
2. Click Hide person.

They disappear from the list. To bring hidden people back, turn on Show hidden person in General Settings. Hidden people then reappear with "(hidden)" after their name, and you can Unhide them from their menu.

Since 0.8.2, hiding someone also takes them out of everyone else's photos. A group photo that includes a hidden person is no longer shown under the other people in it, and it is left out of their exports as well. Hiding a person is meant to keep that person out of sight, and leaving their group photos on show elsewhere works against that, so this is how the app behaves by default. If you would rather keep those group photos visible, turn on Show hidden people in group photos in General Settings; the hidden person's own entry stays hidden either way.

Previewing a Photo (the big view)

Single-click any thumbnail to open the large preview (also called the lightbox). The preview fills the screen and has two parts:

• The photo on the left.
• A "Details" panel on the right that lists information about the photo, such as the file name and path, the image size, the file size, the date it was taken, and the camera that took it. Only the details that the photo actually contains are shown.

Controls in the preview:

• Left and right arrows (on screen, or the Left/Right keys on your keyboard) - move to the previous or next photo.
• The counter at the bottom shows which photo you are on (for example "3 of 50").
• The open-in-app button at the bottom-right (the blue arrow-out-of-a-box icon) - opens the photo in your computer's normal image viewer.
• The X at the top-left, or the Esc key - closes the preview.

If face tags are turned on, you will also see the person's name marked on the photo, which helps you spot them in a group shot. You can turn this on or off with "Show face tags in full screen image previews" in General Settings.

Sorting Photos

Use the Sort dropdown at the top-right of the photo area to reorder a person's photos. The choices are grouped:

• Names: File name (A-Z or Z-A), or File path + name (A-Z or Z-A).
• Dates: Date taken, Date modified, or Date created - each newest-first or oldest-first.
• Size: Larger first or Smaller first.

Date and Size options only appear when enough of the person's photos actually carry that information (at least half). Photos that are missing a date always sit at the bottom - the app never makes up a date it does not have.

Filtering Photos

Click the Filter button at the top of the photo area to narrow down what is shown:

• File type - tick or untick boxes (for example JPG, PNG, HEIC) to show only certain kinds of file.
• Path contains - type some text to show only photos whose folder or file name contains that text.
• Clear filters - removes all filters and shows everything again.

A filter only affects the person you are currently viewing.

Grouping Photos

Click the Group button to split the grid into labelled sections. Pick one of:

• Folders - one section per folder the photos live in.
• Date taken, Date modified, or Date created - by Days, Weeks, Months, or Years.
• Others - Camera make/model.
• No grouping - returns to a single, flat grid.

Each section has a heading you can click to fold it open or closed. As with sorting, date and camera options only appear when enough photos carry that information, and anything without a value goes into a "No Data Available" section at the bottom.

Hiding Individual Photos

To hide one photo without hiding the whole person:

1. Right-click the photo (or use its three-dot menu).
2. Click Hide photo.

To see hidden photos again, turn on Show hidden photos in General Settings. Hidden photos then appear with diagonal lines across them, and you can Unhide them from the same menu.

Removing or Moving a Photo (Remove/Transfer Tag)

Sometimes the app puts a photo with the wrong person, or you simply want to move it to someone else. You can fix this by hand, one photo at a time.

1. Right-click the thumbnail in the grid (or click its three-dot menu).
2. Click Remove/Transfer Tag.
3. A window titled "Transfer Face To..." opens.

The window lists every person you have named - whether they are currently hidden or not. (Unnamed people such as "Person 1" and the "Unmatched Faces" group never appear here, since you can only move a photo to a real, named person.) If the list is long, scroll down to find the right person.

Your two choices are:

• Remove from this person (the red option at the top) - takes the photo out of this person's group. It is not deleted; it is sent back to Unmatched Faces. Use this when a photo was matched to the wrong person and there is no one to move it to.
• Transfer to [Name] - moves the photo into that person's group instead. Click the name you want.

Click Cancel to close the window without changing anything.

If this person appears in the same photo more than once (or you picked several photos), the options show a count, such as "Transfer to Anagha (3 photos)", and the action applies to all of them at once - but only for this person. Other people in the same photo are left alone.

This makes future results better. These manual corrections are remembered. The next time the app recalibrates (for example after you change the threshold or add new photos), it treats your choices as a strong hint about who is who, so its automatic grouping becomes more accurate over time. In short, every time you fix a photo by hand, you are also teaching the app.

Finding a Photo on Your Computer (Open in File Explorer)

Want to know exactly where a photo lives on your disk? You can jump straight to it.

1. Right-click the thumbnail in the grid (or click its three-dot menu).
2. Click Open in File Explorer.

Windows File Explorer opens to the folder that holds the photo, with that photo already highlighted, so you can see its location, copy it, or work with it elsewhere. Your original photo is not changed in any way.

This option appears for one photo at a time (it is not shown when you have several photos selected, since it points to a single file).

About Duplicate Photos

Each person's grid shows one tile per photo file. If the same person appears more than once in a single picture (for example a collage), or if you have the exact same file saved in two places, the app shows it just once for that person instead of repeating it. The photo still appears for every different person who is in it.

Export One Person

1. Click the three-dot menu next to a person (or right-click the row).
2. Click Export photos....
3. Choose where to save them.

Export Selected or All People

1. Open Settings and click Export Photos.
2. You will see a searchable list of people. Tick the ones you want (use the Search people box to find someone quickly, or Select all / Clear).
3. Click Export Selected to save the ticked people, or scroll down and click Export All Named People to save everyone who has a real name.
4. Choose where to save them.

You can also export several people at once straight from the People list using multi-select.

The export list follows your visibility settings: hidden or unnamed people do not appear, and a person's hidden photos are only included when "Show hidden photos" is on. Photos that include a hidden person are also left out of the other people's exports, unless "Show hidden people in group photos" is on.

While exporting, the progress bar at the bottom shows how far along it is, with a Cancel button. When it finishes, a summary appears with an Open Folder shortcut.

Copy or Hardlink (ADVANCED)

DO NOT USE IF YOU ARE NOT SURE

In the Export Photos screen there is a dropdown that chooses how files are saved:

• Copy (default) - makes normal, independent duplicate files. This works to any drive and is the safe choice for most people.
• Hardlink - saves space by pointing to the same data as your original, but only works when the destination is on the same drive as your photos (it falls back to Copy across drives). Because a hardlink shares its data with the original, editing the copy in another app would also change the original. Hardlink is off by default; you turn it on in Advanced Settings.

General Settings

Threshold

• Controls how similar two faces must be to count as the same person.
• Lower values (around 30-40%) are more relaxed and may group different people together.
• Higher values (around 50-60%) are stricter and may split one person into several entries.
• Default: 50%.
• After changing it, click Recalibrate to regroup all faces. This is fast and does not rescan your photos.
• A good starting point is 45-50%; adjust based on what you see.

Show single unmatched images

• When ON, the app shows a group called "Unmatched Faces" for faces that do not match anyone else (often screenshots, memes, or one-off pictures).
• When OFF, those single faces are hidden.
• Default: OFF.

Hide persons with less than [N] photos

• When the toggle on the right is on, people with fewer than the number you set are hidden from the list.
• Useful for removing people who only appear once or twice.
• Default: OFF (set to 2 when turned on).

Show face tags in full screen image previews

• When ON, the large photo preview marks each person's name on the picture, so you can see who is who in group photos.
• Default: ON.

Show photo details in full screen image previews

• When ON, the large photo preview includes a side panel listing the photo's details (file name and path, image size, file size, date taken, camera, and so on). When OFF, the preview shows just the photo, using the full width.
• Default: ON.

Close to tray

• When ON, clicking the X hides the app to the system tray instead of quitting. To fully quit, right-click the tray icon and choose Quit.
• Default: ON.

Show hidden person

• When ON, people you previously hid reappear in the list with "(hidden)" after their name, so you can unhide them.
• Default: OFF.

Show hidden people in group photos

• Photos that include a hidden person are normally removed from everyone else's photos and exports. When ON, those photos are shown again, while the hidden person's own entry stays hidden.
• Turn this on if a person looks like they are missing photos you know they appear in (see Troubleshooting).
• Default: OFF.

Show hidden photos

• When ON, photos you hid reappear with diagonal lines across them, so you can unhide them.
• Default: OFF.

Hide unnamed persons

• When ON, everyone you have not renamed yet is hidden from the list. (It does not hide "Unmatched Faces".)
• Important: the first time you scan, keep this OFF so you can see and name new people.
• Default: OFF.

Rescan frequency for changes in photos

• Controls how often the app checks your folders for new or deleted photos when it starts.
• Options: after every restart; on the first restart each day; on the first restart each week; or manually only.
• If you choose Manually, you will need to use the Rescan For Changes button in "Folders to Scan" yourself.

Themes and Accessibility

Theme

• Choose Dark theme or Light theme for the whole app. In the light theme the title bar picks up your accent colour.

Accent color

• Click any of the coloured circles to set the highlight colour used across the app (buttons, sliders, and so on). Each circle previews the exact shade for your current theme. The set was retuned in 0.8.2 to six colours chosen to stay readable in both themes.
• Until you pick one, the app uses a theme-matched default: green in the light theme, cyan in the dark theme. Picking a circle keeps that colour in both themes.

Custom accent

• Prefer your own colour? The Custom accent well below the circles opens a full colour picker, including an eyedropper for grabbing a colour from anywhere on your screen. Text on coloured buttons automatically switches between black and white so it stays readable whatever you pick.
• This option is newly implemented, so it sits behind a switch: turn on Custom colours in Advanced Settings first. Until then the well is visible but greyed out.

Increase contrast

• Adds stronger borders and higher-contrast colours, making areas that are otherwise separated only by a faint shade of grey easier to tell apart.

Bold fonts

• Makes the app's text heavier and easier to read. Text that is already bold is left as-is.

Dyslexia-friendly font

• Switches the app to a typeface designed to be easier to read with dyslexia. Choose Off, OpenDyslexic, or Atkinson Hyperlegible.

Colour vision

• Helps tell things apart for a chosen type of colour blindness: Protanopia (no red), Deuteranopia (no green), Tritanopia (no blue), or Achromatopsia (no colour). Rather than filtering the screen, the app swaps its accent colours for a palette chosen to stay distinguishable in that mode and leans on cues that do not rely on colour at all, such as the caution mark on red buttons. This also plays nicely with any colour filter you already run in Windows.
• Set to Auto (match Windows), the default, it follows the colour filter chosen in Windows Settings > Accessibility > Colour filters automatically.

Reduce transparency

• Replaces the blurred, see-through backdrop behind dialogs and the photo preview with a solid background, and removes their shadows. Until you change it here, this follows the transparency setting in Windows (Settings > Accessibility > Visual effects).

Folders to Scan

Include folders for scanning

• Add every folder that contains photos you want organised. Subfolders are included automatically.
• Use + Add Folder to add one and - Remove Folder to remove the selected one.
• Note: a network location must be online during each scan; if it is offline, its photos are treated as deleted.

Exclude subfolders from scanning

• Add specific subfolders you want skipped. This takes priority, so a folder added here is never scanned even if it sits inside an included folder.

Wildcard Exclusion

• Skip files or folders whose name matches a pattern. Separate several patterns with commas. Use * as a wildcard:
  • *.gif - skip every GIF file.
  • *thumbnail* - skip anything with "thumbnail" in its name.
  • C:\Photos\Private - skip that exact folder.

Rescan For Changes

• Click this to check your folders right now for new or deleted photos. Use it after you add or remove photos on your computer.

Export Photos

This section lets you export several people or everyone at once. See Exporting Photos into Folders for full steps. In short: tick people in the list (or Select all), choose Copy or Hardlink, and click Export Selected - or use Export All Named People to export everyone with a real name.

Advanced Settings

These are extra options most people will not need to change.

Use system resources dynamically

• When ON, the app eases off your computer when it is minimized to the tray, so it does not slow down your other work. When OFF, it always runs at full speed.
• Default: ON. (To benefit from this, use "Close to tray".)

Show development options

• Shows extra technical information, such as how many faces are tagged for each person, and a "Remove all tags" option in a person's menu. Most people should leave this OFF.
• Default: OFF.

Thumbnail Cache

• Shows how much space the saved thumbnails use, with a Clear Cache button. Thumbnails make photos load quickly; clearing them is helpful if photos look wrong after being edited outside the app. They rebuild automatically the next time you open a person.

Hardlink export (ADVANCED)

• Turns on the Hardlink option in the Export Photos screen (see Copy or Hardlink). Off by default.

Custom colours (NEW)

• Unlocks the Custom accent picker in Themes and Accessibility. Off by default because the feature is newly implemented and has not been tested in every corner of the app yet, so unusual colour picks may look a little odd in places while it matures. Your picked colour is kept even while this is off and comes back when you turn it on again.

Write XMP sidecar files (ADVANCED)

• Lets the app save the face names into small files next to your photos so other photo apps can read them. See Sharing Names with Other Photo Apps (XMP) below for full details.

About (and the Log)

The About section shows the version and licence information, plus a row of buttons:

• Help - opens a small window with links to the online help and an offline help PDF.
• Report a bug - opens the page where you can report problems.
• Developer, Website, EULA - open the matching web pages.
• Privacy Policy - explains that the app does not collect any data.

Below About is the Log. The log lists what the app has done (scanning, errors, settings changes, and so on). You can:

• Choose Normal or Debug detail from the dropdown. Use Debug only when you are chasing a problem.
• Click Save Log to save it as a text file, which is helpful when reporting a bug.

Note from the developer

Except for the GPU, there is no definitive way for me (the developer) to test the hardware requirements of Felicity across all the different varieties and combinations of hardware. The list above should only be taken as an estimated requirement.

The actual hardware the app was tested on is provided below for transparency.

Test Bench 1

• Processor: AMD Ryzen Threadripper 7960X 24-Cores ~4.2 GHz
• Memory: 128 GB (130570 MB) DDR5 ECC RAM
• OS: Windows 11 Enterprise LTSC 24H2 (Build 26100) (26100.ge_release.240331-1435)
• GPU: NVIDIA GeForce RTX 4090
• GPU driver version: 591.44
• NVIDIA CUDA: 13.1.86 driver
• Network storage: 40 gigabit/s
• Storage: WD BLACK SN850X 4TB WDS400T2X0E-00BCA0 (729,962.6 IOPS) & Seagate 8TB ST8000NM017B-2TJ103 7200RPM HDD (5586.43 IOPS)

Test Bench 2

• Processor: AMD Ryzen Threadripper 3960X 24-Cores ~4.2 GHz
• Memory: 64 GB DDR4 RAM
• OS: Windows 11 Enterprise 23H2 (22631.1.ni_release.220506-1250)
• GPU: NVIDIA GeForce RTX 3060 Ti
• GPU driver version: 560.76
• NVIDIA CUDA: 12.6.65 driver
• Network storage: 40 gigabit/s
• Storage: Samsung 980 PRO 2 TB MZ-V8P2T0 (~320,000 IOPS) & Samsung 850 EVO 1TB MZ-75E (~93,000 IOPS)

sha256 of the installer (setup.exe)

This is the SHA256 hash of the file Felicity-0.8.2.B-Setup.exe I uploaded.

3a92e2d47ee818fd883be9a010c7edbbfc18987ac513b50eb27cdd505d841e8d

How to check

You can check yours if you use 7zip, by right clicking the installer file and going to the 7zip submenu, and selecting SHA-256.

Or otherwise you can use powershell that comes bundled with Windows by using Get-FileHash "C:\path\to\Felicity-0.8.2.B-Setup.exe" -Algorithm SHA256

• Right click the start menu, go to powershell.
• it can show up as command, terminal or cmd, depending on your Windows setup.
• If this is the case, type powershell first.
• It should read something like PS > C:\Users\...

For example, Get-FileHash "C:\users\rev oconner\Downloads\Felicity-0.8.2.B-Setup.exe" -Algorithm SHA256 where "rev oconner" is the username of my Windows computer and I downloaded the file in my default downloads folder.

The same can be done via Get-FileHash "%userprofile%\Downloads\Felicity-0.8.2.B-Setup.exe" -Algorithm SHA256 where '%userprofile%' will auto resolve to your user default downloads folder and the setup file was downloaded to the default downloads folder.

The string (mixture of numbers and line) shown using either method should be an exact match to the one provided above. Although it is case insensitive.