Image Organizer How It Works

How It Works

RulZ is written in Python with a Qt (PySide6) interface. All the "AI" runs locally using small pre-trained models through OpenCV, so no internet connection or graphics card is needed.

The pipeline

For every photo, in the background:

1. Decode the image (honoring camera rotation) and save a thumbnail.
2. Find faces with YuNet, which also gives five landmarks (both eyes, nose tip, mouth corners).
3. Fingerprint each face with SFace: a list of 128 numbers that is similar for the same person and different for different people.
4. Expression: the aligned face is classified by the FER+ model.
5. Head direction is calculated from the five landmarks (no extra model): how far the nose sits to one side of the eyes gives left/right, its height between the eyes and mouth gives up/down, and the tilt of the eye line gives head tilt.
6. Body pose: around each face, MediaPipe BlazePose finds the person and 33 body points. Sitting, standing and lying down are decided from the angles at the hips and knees plus where the knees sit relative to the hips. A pose is only given when an ankle is clearly visible.
7. Everything is stored in a local SQLite database.

Grouping faces into people

• A new face is compared with every known person (their average face, and their single closest face). If it is close enough, and clearly closer to one person than to any other, it joins them.
• Remaining new faces that are close to each other form new groups.
• Faces you assigned by hand are never moved, and a face you rejected from someone is never offered to them again.

Why some things are "estimated"

These are small, fast models running on your own PC rather than large cloud models, so they trade some accuracy for privacy and speed. See Search and Filters for the main limits.

Where things live

Part	Source file
Face detection, fingerprints, expression	rulz/faces.py
Head direction, search words	rulz/attributes.py, rulz/search.py
Body pose	rulz/body.py
Grouping	rulz/clustering.py
Scanning, thumbnails	rulz/scanner.py, rulz/imaging.py
Database	rulz/db.py
Interface	rulz/ui/

Models

Model	Purpose	License
YuNet	Face detection	MIT
SFace	Face fingerprints	Apache 2.0
FER+	Expressions	MIT
MediaPipe BlazePose (detector and landmarks)	Body pose	Apache 2.0

Details and sources are in models/README.md.

Building from source

You need Windows and Python 3.10 or newer.

git clone https://github.com/speedyrulz/RulZ-AI-Tools-Suite/tree/main/apps/RulZ-Image-Organizer
cd RulZ-Image-Organizer
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe run.py

To make the packaged app:

powershell -ExecutionPolicy Bypass -File .\build.ps1

This downloads any missing models and builds dist\RulZ Image Organizer\RulZ Image Organizer.exe with PyInstaller. Double-clicking Launch RulZ Image Organizer.bat starts the built app, or the source version if it hasn't been built.

License

Source code: MIT License. The RulZ name and logo are not covered by it; see LOGO-NOTICE.md. The models keep their own licenses.