Skip to content

Conversation

@shipurjan
Copy link

Add JSON Group Information Export

This PR adds JSON export functionality for group metadata. When using Cullergrader in scripts or automated workflows, you don't always want to copy files to a new folder - sometimes you just need the grouping information so you can process the groups yourself for other purposes (archiving, custom filtering, integration with other tools, etc.).

Like PR #2, this was implemented with help from Claude Code.

Context

This builds on PR #2 (feature/add-cli-support). Review this after #2 is merged, since it extends the CLI with a new flag and adds a corresponding GUI feature.

What's New

Core Functionality

Added exportGroupsJson() method to FileUtils.java that generates a structured JSON file containing group metadata: total counts, thresholds used, and detailed per-group information including photo paths, timestamps, hashes, and similarity metrics. The JSON is pretty-printed using the existing GSON dependency.

Parent directories are created automatically (matching the --output behavior), so paths like export/data/groups.json work without manual directory creation.

CLI Extension

The CLI now accepts a --json / -j flag that can be used three ways:

  • Alone: --input photos --json groups.json (preview mode + metadata)
  • With output: --input photos --output best --json groups.json (files + metadata)
  • Just output: --input photos --output best (files only, existing behavior)

GUI Addition

The File menu now has "Export Group Information (JSON)" below the existing export option. Opens a file chooser with JSON filter, defaults to groups.json, and uses the current threshold values from the spinners. Automatically appends .json extension if missing and validates that groups exist before exporting.

Notes on the JSON Structure

The exported similarity metrics reflect how the grouping algorithm works - each photo's deltaTimeSeconds and similarityPercent are relative to the previous photo in the sequence, not to all photos in the group. This is why you might see different similarity percentages within the same group (the first photo shows similarity to the last photo of the previous group, which is why it started a new group).

@shipurjan shipurjan changed the title Add JSON Group Information Export Add JSON Group Information Export (incremental to PR #2) Dec 14, 2025
* Add preview image RAM caching + RAW files support

* simplify caching logic

* update readme
* add CLI mode

* update README
This reverts commit d968d02, reversing
changes made to b846054.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant