LucidGrasp v1.2.5

What's new in v1.2.5

• Updates checked on every launch. The daily throttle is gone — the app checks GitHub for a newer release every time it is opened (unless automatic checks are turned off in the Updates menu). Toggling 'Check for Updates Automatically' back on runs a check immediately.
• Menus reorganized. The Help menu is now an Updates menu (Check for Updates, Check Automatically, Latest Release Notes) plus a dedicated Help menu (Report an Issue, Request a Feature, Contact the Developer, View on GitHub, Privacy Policy, Legal Notices, About).
• Report an Issue / Request a Feature open the GitHub New Issue form pre-filled with a template and the installed version baked in.
• Complete legal set. Terms of Use, Privacy Policy (GDPR/CCPA/state-law rights, controller identity, children, transfers), Warranty Disclaimer, Acceptable Use, and a Legal Notices index — all available in-app and in the repository.
• New Contributing, Security, Support, and Changelog pages.

Assets

[x] lucidgrasp-linux-x64.tar.gz (Linux)
[x] LucidGrasp-x86_64.AppImage
[x] LucidGrasp_Setup_x64.exe (Windows installer)
[x] lucidgrasp-macos-1.2.5.dmg (macOS)

LucidGrasp 1.2.4

LucidGrasp 1.2.4

Fixes and improvements:

• Drag-and-drop now applies both a dropped folder (library) and a dropped image (query) in one gesture.
• The status bar no longer claims a search was cancelled when the query image simply could not be read.
• Trashed items are now removed from the on-disk index cache, so they never reappear in later sessions.
• The search shortlist scales with library size (from 256 up to a capped 2048 candidates) so large libraries keep deep variants such as crops and rotations.
• The search progress bar advances monotonically through prefilter and scoring instead of resetting mid-search.
• The update dialog gains Ignore This Version; dead update-checker code was removed.

LucidGrasp 1.2.3

Two buttons on every search result, and a macOS build.

New

Show in folder

Every result can now be opened in the file manager with the image selected, rather than only its folder.

Each platform is asked in its own language for this:

• Linux — org.freedesktop.FileManager1.ShowItems, the freedesktop.org standard for exactly this. It ships inside the file manager, so there is nothing to install: GNOME Files 3.4+ and KDE Dolphin 15.08+ already implement it. D-Bus rather than simulated keystrokes, so it works the same under X11 and Wayland and does not have to guess at a window.
• Windows — Explorer's /select, verb, which only understands a raw command line.
• macOS — open -R, which reveals and scrolls to the file.

Move to trash

Moves the result to the OS recycle bin. It does not delete anything.

Windows Recycle Bin, macOS Trash, and on Linux the freedesktop.org trash specification — gio first, then trash-put for setups without it.

If no trash implementation exists on the system, the button refuses and says so. It never falls back to an unlink, so you are never told a file was deleted when it was in fact destroyed.

Trashing also drops the entry from the in-memory index, so it stops appearing in results immediately. The cache file on disk is deliberately not rewritten: a stale entry costs nothing, because a search skips paths that no longer exist, whereas rewriting the cache on every trash would mean a disk write on a read-only-ish path and a chance to lose the index.

macOS

A .dmg for the first time.

x86_64, which runs natively on Intel and under Rosetta on Apple Silicon, so one build covers both. OpenCV's dylibs are bundled into the app and rebased onto @rpath, so nothing has to be installed first.

Two things to expect on first launch, both normal:

• It is ad-hoc signed, not notarized. Notarization needs Apple credentials, which this release does not have. Gatekeeper will therefore object: right-click the app and choose Open, once. Or xattr -d com.apple.quarantine on the DMG.
• The trash button raises a system prompt the first time, asking permission for osascript to control Finder. That is macOS's automation policy. Any Finder-based route asks for it; refusing it just makes the button report the failure.

Fixes

The self-test failed when run more than once at a time

--selftest wrote its generated corpus to a fixed path, so two runs would delete each other's images mid-test. Seven of sixteen concurrent runs failed; none did on their own, which is what made it look like a flaky test rather than a real bug. Each run now uses its own directory.

Upgrading

Drop-in replacement on Linux and Windows. The index cache format did not change, so nothing needs reindexing.

Built and self-tested on Linux, Windows and macOS.

LucidGrasp 1.2.2

Bug fixes. Local search, indexing and the cache path.

Fixes

An interrupted save could destroy your index

The index cache was written directly to its final location. If the write was interrupted — a crash, a kill, a full disk — it left a truncated file, and the next launch could not tell "never indexed" from "index destroyed", so it rebuilt from scratch. On a whole-filesystem library that is hours of work thrown away by something that looks like a successful run.

Caches are now written to a temporary file and renamed into place only once complete, so the file on disk is always a usable index.

A miscounted size guard could refuse a valid cache

The check that rejects a corrupt cache header counted more fields than the format actually writes, making its threshold too high. A cache whose entries have very short relative paths could therefore be judged corrupt and silently reindexed on every launch. The threshold is now correct. This could only ever cause an unnecessary rebuild, never a wrong search result.

Documentation

Two claims in the README did not match the code, and are now accurate:

• The 45/35/20 weighting between SSIM, ORB and colour histogram is the inner comparison. The score you see is 80% of that plus 20% from the hash ranking, which was not documented.
• Search time does not grow with library size in the way previously stated. The expensive half of the work is capped at 256 candidates; ranking those is a fast in-memory pass. In practice a whole-filesystem search stays in the low milliseconds.

Upgrading

Drop-in replacement. Existing index caches keep working — the format did not change, so nothing needs reindexing.

Built and self-tested on Linux and Windows.

LucidGrasp 1.2.1 - Search race and score calibration fixes

Bug-fix release.

• Search race fix: the File menu could replace the in-memory index while a search was reading it (heap-use-after-free); menu actions are now gated like the buttons.
• Score calibration: identical keypoint-free images now reach 1.0 instead of topping out at 0.72, so the default 50% threshold behaves the same on every library.
• Deleted files no longer resurface as ghost results; CLI threshold is validated (0-100); progress math overflow fixed; Windows whole-drive scans skip system folders.
• New self-test cases cover the default threshold and score ceiling.

LucidGrasp 1.2.0 - Update checking, OS colours, and a working shortlist

LucidGrasp 1.2.0 - Update checking, OS colours, and a working shortlist

LucidGrasp now tells you when a newer release exists, takes every colour it draws from your operating system, and actually does the two-stage search it has always claimed to do.

---

Update checking

On launch, LucidGrasp asks GitHub for the latest published release and tells you if there is a newer one. The notice has three buttons: open the download page, not now, or never check again. It only reads the release page -- nothing is ever downloaded or installed without you asking.

It checks at most once a day, and you control it fully:

• Help -> Check for Updates Automatically turns the automatic check on and off. This is the way back if you ever press "never" by accident -- the opt-out would otherwise only be reversible by reinstalling.
• Help -> Check for Updates... (Ctrl+U) checks right now, ignoring the daily limit.

If you would rather it never contacted anything at all, turn the toggle off. It reads its state from a settings file under your own user directory, and it does not read anything else and send it anywhere.

A few deliberate details, for the curious:

• The check is throttled on attempts, not successes. GitHub allows 60 requests per hour per IP address, and an IP is shared by everyone behind a single NAT or carrier-grade NAT, so one exhausted office budget otherwise silences every machine in the building. Recording the attempt means a rate-limited GitHub costs one try a day instead of one per launch.
• Every failure is silent. Truncated JSON, an error page served with a 200, a timeout, a corporate proxy that inspects TLS -- all no-ops. A failure is reported only if you asked for that particular check yourself.
• An unreadable version tag is also silent. A tag like v2024.01.15 would otherwise be read as version 2024.1.15 and tell every user to update on every launch, forever.

Colours come from the operating system

Every surface, accent, border and text colour is now read out of your desktop's palette rather than chosen by hand. LucidGrasp follows your system's light or dark scheme, and follows your accent colour with it -- on both Windows and Linux, with no per-OS styling.

The square button in the top right still switches between light and dark. It is worth pressing even if you agree with your system, because when you disagree with it the app builds the opposite scheme from your palette rather than substituting a generic dark grey.

The file pickers now use your platform's own dialog on Windows, so they carry the system's look, its previews and its shell integration. (On Linux they stay on Qt's, because GTK3's native picker rejects files. That used to be forced on every platform, which is why the pickers were never actually using the OS's dialog.)

Search: the shortlist now works

If you have a large library and searches felt slower than they should have, this is the one to read. The two-stage search -- cheap in-memory ranking first, expensive OpenCV comparison only on the shortlist -- was not capping the shortlist in 1.1. Stage one collected every entry that passed the relaxed bound and stage two decoded and scored all of them, so the design did no work at all.

Per-query cost is now genuinely bounded by the shortlist rather than by your library size, and decoding happens at a bounded size instead of at full resolution.

Also in this release:

• Byte-identical copies are always returned, and never compete with other candidates for a slot in the shortlist.
• If a file changed since it was indexed, its features are refreshed before it is scored, instead of being compared against hashes for pixels that are no longer there.
• The two control panels are now the same height. They were previously laid out ragged.

Fixed

Each of these was a silently wrong answer rather than a crash, which is why they survived as long as they did:

• A user folder named dev, sys or run was silently dropped from a scan, because system-directory skipping matched on the folder's name alone. Skipping is now decided by resolved path. Those losses never reached the error counter, so they were invisible.
• A corrupt or truncated cache could leave the index in a state where its root pointed at a library it no longer described. The cache format has also moved to version 2; existing caches are rebuilt automatically on first launch.
• An exception escaping either background thread called terminate and killed the process. OpenCV throws on malformed input, which is precisely what a whole-filesystem scan of untrusted files will eventually hand it. Both worker threads now report failures instead of vanishing.
• Images were decoded at full resolution and copied into an OpenCV matrix before being shrunk down to the 256 px the comparison actually reads.
• EXIF orientation is now applied consistently on both sides of a comparison.

Verifying your build

--selftest builds a synthetic image corpus, indexes it, and checks that edited and rescaled copies rank above unrelated distractors. It also covers the update checker's version comparison and payload parsing -- offline, with no network access and no display:

./LucidGrasp --selftest

All eight cases pass on both platforms in CI, and the project still builds with zero warnings under -Wall -Wextra.

---

Upgrade notes

No configuration or cache migration is needed. Your existing index is rebuilt once on first launch after upgrading, which takes as long as indexing did. Preferences, if you use the update opt-out, are stored separately and are preserved.

Downloads, as before: lucidgrasp-linux-x64.tar.gz for Linux (Qt6 and OpenCV from your package manager), LucidGrasp_Setup_x64.exe for Windows.

LucidGrasp 1.1.0 - Full OS scan enabled

Fix Windows CI: use Qt 6.5-compatible arch and restore MSVC toolset pin

Qt 6.5 LTS ships only MSVC 2019 (v142) Windows desktop binaries. Requesting
win64_msvc2022_64 made aqtinstall fail with "The packages ['qt_base'] were
not found while parsing XML of package information!", which broke the
Windows release job before it ever reached the build.

- arch: win64_msvc2022_64 -> win64_msvc2019_64
- restore msvc-dev-cmd toolset 14.29, matching the v142 toolset used to
  build both Qt 6.5 msvc2019_64 and the OpenCV 4.10.0 vc16 prebuilts

Verified locally with aqtinstall 3.3.0: list-qt confirms win64_msvc2019_64
exists for all 6.5.x, and install-qt 6.5.3 win64_msvc2019_64 --autodesktop
now completes successfully.

LucidGrasp 1.0 - Pixel Perfect Matching

v1.0.0

Rename project executable from image_search to LucidGrasp