v3.2.0

locallens@community:~$ cat how-it-works.md

Basic Understanding of LocalLens

What happens to your photos

You point LocalLens at a folder with a thousand photos in it. Here is every step it takes, in plain English — and where your pictures go while it works.

19photo formats read
0photos sent anywhere
Copyis the default, always
The short version

Five things happen to every photo

Every picture you give it goes down the same short path. Nothing is uploaded, nothing is compressed, and nothing inside the image itself is changed.

1Find themlooks inside everysubfolder you allow2Check the typeJPEG, HEIC, RAWand 16 more3Read the notesthe date and placeyour camera saved4Choose a homeby date, by place,or by who is in it5Put it therecopies it in — youroriginal stays put
The same five steps run whether you hand it fifty photos or fifty thousand. Only step 5 writes anything to disk.
Step one

You decide what it looks at

Before anything happens, it shows you what is actually inside the folder you picked — every subfolder, nested as deeply as they go, with a count of the photos it found.

Untick anything you want left alone. Untick a folder and everything inside it comes off too, so you never have to click through thirty subfolders to exclude one branch.

Photos2023GoaDiwaliScreenshotsWorkMemes2024You untick onefolder. Everythinginside it is leftalone too.
The count at the top updates as you tick, so the number you see is exactly the number of photos the job will touch.
Step three

It reads what your camera already wrote

Every photo carries a small block of notes your camera filled in the moment you pressed the shutter: the date and time, often the GPS position, the camera model. LocalLens reads those notes. It does not look at the picture and guess.

That matters more than it sounds. The file's own date is usually wrong — copying photos off your phone, restoring a backup, or moving them between drives all rewrite it to today. The shutter date does not move. That is the one LocalLens sorts by.

For places, it turns the GPS coordinates into a country, state and city using a map that ships inside the app. No lookup service, no network request, no account.

If the notes are missing

A photo with no shutter date goes to Unknown_Date rather than being guessed at. No GPS means Unknown_Location. Nothing is quietly filed in the wrong place to make the output look tidier than it is.

Step four

Three ways to sort

You pick one rule and it builds the folders to match. This is what you end up with:

BY DATESorted/2024/07-July/08-August/2023/12-December/Unknown_Date/BY LOCATIONSorted/IN/Uttar-Pradesh/Lucknow/Varanasi/JP/Unknown_Location/BY PERSONSorted/Mayank/With Others/Aditi/With Others/Unknown_Faces/No_Faces_Found/
With Others is where a group photo lands — it appears under every enrolled person in it, so both people find it in their own folder.

That is the shape of one rule applied to everything. The same machinery has two other shapes, and they differ in what they leave behind:

STANDARDSorted/2024/07-July/2023/12-December/Unknown_Date/one rule, the whole libraryHYBRIDSorted/Japan-Trip/IMG_0421.jpg2024/07-July/Unknown_Date/matched photos land in bothFIND & GROUPPhotos/IMG_0421.jpgIMG_0455.jpgJapan-Only/IMG_0421.jpgIMG_0455.jpgyour library is not touched
Under Hybrid, the set you pull aside is a copy — the base sort still contains every photo, so a matched picture is in two places on purpose. Nothing is removed from the ordinary folders to make the special one.
Standard

One rule, everything

Sort the whole folder by date, place or person. The simple case.

Hybrid

Pull one set aside

Give one person or one trip a folder of its own, named by you, while everything else still sorts normally underneath it.

Find & Group

Search, don’t reorganise

Copy only what matches into a new folder. Your library is left exactly as it was.

People

Sorting by person works differently

Dates and places are already written into the file. A face is not — so you teach it first, once.

You show it a handful of clear photos of someone and type their name. It finds the face in each one and reduces it to 128 numbers, a kind of fingerprint. The photos you enrolled are not needed again after that.

When you later sort by person, it does the same thing to every photo in your library and compares the numbers. Close enough means it is them.

You show it a few photosIt keeps 128 numbersIt checks every photoMayanklearns oncethe same face always makes similar numberscomparesthe matches are filed under Mayank
Enrolment happens once per person; finding them in a new batch costs nothing extra afterwards. The 128 numbers cannot be turned back into a picture of anyone's face.

How hard should it look?

Finding a face is not one operation — it is a series of increasingly expensive attempts. LocalLens tries the cheap ones first and stops the moment it finds a face, so an ordinary, well-lit photo never pays for the slow methods. The three modes choose how far down the list it is allowed to go.

Each photo stops at the first step that finds a face — most stop at step one.Quick lookmost photos end hereLook closersmall or distant facesTry it sidewaysphotos saved rotatedDeep scanslow, and the last resortFastBalancedAccurate
Balanced is the default. It adds the sideways attempt, which rescues photos your phone saved rotated — a surprisingly common reason a face gets missed. Accurate adds a much slower scan for faces that are small, turned away, or badly lit.
The part people ask about first

Nothing leaves your computer

There is no upload step, because there is nowhere to upload to. The photos are already on your machine, the faces you trained live on your machine, and even the map used to turn GPS into a place name is bundled inside the app.

YOUR COMPUTERYour photosnever copied off the diskLocal Lensruns entirely offlineThe faces you enrolled128 numbers, not picturesA world map, bundled inGPS to city, no lookupThe internetphotos · names · placesnever cross this linechecks for a new versionand for board replies
Two things do go out: a version check, so the app can tell you an update exists, and from the release after 3.1.0 a check for replies to your posts on this site's board. Neither carries anything about your photos. That is the complete list.
Step five

Built so you cannot lose a photo

The last step writes to your disk, which is the only step that could ever hurt. It is the one with the most safeguards on it.

  • Copy is the default. Your originals stay where they are. Moving is opt-in and has to be chosen deliberately.
  • Nothing is overwritten. If two photos would land on the same name, the second is renamed rather than replacing the first.
  • Cancel puts it back. Stop a move halfway through and every file already moved is returned to where it came from, in reverse order.
  • It checks there is room. Moving between drives measures the photos against the free space first, and refuses the job rather than filling the disk.
  • Skipped stays skipped. Folders you unticked are never read, never copied and never deleted — even while the rest of the source folder is being cleaned up.
  • Every job writes a log of what went where, saved alongside your sorted photos.
In short

The whole thing, start to finish

You point LocalLens at a folder. It walks everything inside, including subfolders, and shows you the tree — untick any folder to skip it, and its subfolders come along. It picks up only real photo files: JPEG, PNG, HEIC from an iPhone, RAW from a camera, and a dozen more.

Then it reads what the camera wrote into each photo. Sorting by date uses the moment the shutter fired, not the file's date, which is usually wrong after a backup. Sorting by place turns the GPS position into a country, state and city using a map that ships inside the app, so nothing about your photos ever leaves your machine.

Sorting by person works differently: you first show it a few clear photos of someone and give them a name. It learns that face once, then goes through your library looking for them. Fast checks each photo quickly, Balanced also tries photos that were saved sideways, and Accurate adds a slower scan for faces that are small, turned away or in poor light. Photos it has already examined are remembered, so a second run is much quicker.

Finally it builds the folders and copies your photos in — copy by default, move only if you ask. It never overwrites: a name clash gets renamed. And if you cancel a move halfway through, it puts everything back.

Go deeperInside the Pipeline →

The same journey with the engineering shown: the detection ladder pass by pass, the encoding cache, the write path, and the measured numbers behind each decision.

← home·press ← → for the next section, or ? for every key
© LocalLens · AGPL-3.0net: idle←→ sectionsstars — · forks — · visits —

locallens@community:~$ keys

Jump to a section

press g, then the letter

gpPost
gaAnnouncement
gbBlog
gwHow it workswalkthrough
giPipelineinside the engine
gcContact
ghHome

Move around

no prefix — just press it

←Previous sectionwraps around
→Next sectionwraps around
↑Scroll up
↓Scroll down
PgUpScroll up a screen
PgDnScroll down a screen
HomeTop of the page
EndBottom of the page
TabNext link or controlShift+Tab goes back

The command line

the prompt in the header

/Focus the command linefrom anywhere
TabAccept the suggestionthe dim text after the cursor
→Accept the suggestionfrom the end of the line
EnterRun what you typed
↑Previous commandwhile the prompt has focus
↓Next commandwhile the prompt has focus
EscClear and leave the prompt
?Open this listor type keys

Nothing here needs a mouse. Type help at the prompt for the command list.