locallens@community:~$ cat how-it-works.md
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.
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.
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.
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.
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.
Three ways to sort
You pick one rule and it builds the folders to match. This is what you end up with:
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:
One rule, everything
Sort the whole folder by date, place or person. The simple case.
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.
Search, don’t reorganise
Copy only what matches into a new folder. Your library is left exactly as it was.
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.
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.
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.
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.
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.
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.