Booru Autotagger for Eagle

Automatically tag your images within the Eagle application using tags generated by the Danbooru Autotagger AI model.

This project consists of two main parts:

1. Booru Image Processor: A standalone desktop application (Windows/Source) that interacts with the Danbooru Autotagger API (via Docker) to analyze your images and save generated tags into .json files (one per image, named identically, e.g., image.png -> image.json).
2. Eagle Plugin: An Eagle extension (.eagleplugin) that reads the .json files generated by the Processor and applies the tags directly to the corresponding images within your Eagle library.

(Optional) Helper Scripts: For users with very large libraries or libraries containing many duplicate filenames or files with special characters, optional Python scripts (imagerenamer.py, eagletagger.py) are provided for a potentially more robust, albeit destructive, renaming and faster bulk-tagging workflow (see Advanced Workflow section).

How it Works

1. Run Processor: Use the Booru Image Processor application to select your image folders. It utilizes Docker to run the AI model, analyzes images, and creates .json metadata files alongside them.
2. Tag in Eagle: Use the Eagle Plugin to read these .json files and automatically add the tags to the images in your Eagle library.

Requirements

• Eagle application (v2.0 or later recommended).
• Docker Desktop (Windows/Mac) or Docker Engine (Linux): Must be installed and running before starting the Booru Image Processor. The processor manages the AI container, but requires your Docker environment to be active.
• Node.js (v16+ recommended): Required only if running the Booru Image Processor from source.
• Python 3: Required only if using the optional helper scripts (imagerenamer.py, eagletagger.py).

Installation

1. Booru Image Processor

Choose one option:

Option A: Executable (Windows)

1. Download the latest Booru-Processor-Setup-X.Y.Z.exe from the Releases page.
2. Run the installer.

Option B: From Source

1. Ensure Node.js and npm are installed.
2. Clone or download this repository.
3. Navigate to the repository's root directory in your terminal.
4. Install dependencies: npm install
5. Start the application: npm start

2. Eagle Plugin

1. Download the BooruTaggerEaglePlugin.eagleplugin file from the eagle-plugin directory in this repository. (Note: Available directly here while awaiting potential review on the official Eagle community plugins page.)
2. Open Eagle.
3. Go to Plugins -> Install Plugin -> Install from File....
4. Select the downloaded .eagleplugin file.
5. Enable the plugin if prompted.

Core Usage Workflow

1. Ensure Docker is Running: Start Docker Desktop or ensure the Docker daemon is active.
2. Run Booru Image Processor:
   • Launch the installed application or run npm start from the source directory.
   • On first launch or if the API isn't detected, the processor will attempt to start a permanent Docker container running the Danbooru Autotagger API on http://localhost:5000. This container stays running in the background for stability.
3. Configure Processor:
   • Verify the API Endpoint (usually http://localhost:5000/evaluate).
   • Set your desired Confidence Threshold (0.0 to 1.0, lower values include less confident tags).
   • Click "Browse…" and select the root folder(s) containing images you want to process.
   • Choose "Include subfolders" if necessary.
   • Select the number of API Instances (1 is default, more uses more resources but processes faster).
   • Choose a Processing Mode:
     • Process all images: Re-processes every image.
     • Process only new images: Skips images already successfully processed (checks log file). Recommended for adding tags to new additions.
     • Reprocess only images with missing JSON files: Useful for fixing interrupted runs or inconsistencies.
   • The app may analyze folders and suggest a mode.
4. Start Processing: Click "Process Images".
   • A Json subfolder will be created within each selected image folder (if it doesn't exist).
   • The processor will analyze images and create corresponding .json files in the Json subfolder (e.g., YourFolder/MyImage.png -> YourFolder/Json/MyImage.json).
   • Monitor progress via the progress bar and logs. You can Pause/Resume/Cancel.
5. Tag in Eagle:
   • Once the processor is finished, open Eagle.
   • Ensure the Booru Tagger Eagle Plugin is installed and enabled.
   • The plugin should automatically detect the .json files in the Json subfolders for images already in your Eagle library and apply the tags. (You might need to select images or folders in Eagle depending on the plugin's specific activation method - consult plugin documentation if needed).

Booru Image Processor - Features

• Multi-Folder & Subfolder Support: Process complex directory structures.
• Scalable Processing: Utilize multiple Docker instances (up to 10) for faster tagging on powerful machines.
• Intelligent Modes: Choose to process all, only new, or only missing JSON files.
• Robust Operation: Includes auto-retry for failed requests, connection management, and health checks for API instances.
• Background API Instance: Manages a permanent Docker API container for consistent availability.
• UI Controls: Pause, resume, and cancel ongoing processing jobs.
• Dark Mode: Matches your system theme preference.

Advanced Workflow & Helper Scripts

For very large libraries (>50k images) or libraries with filename issues (duplicates, special characters), the standard workflow might be slow or encounter edge cases. These optional Python scripts offer an alternative approach:

imagerenamer.py

• Purpose: Renames all image files within specified folders (and subfolders) to unique 10-digit numerical names (e.g., 1001371780.jpg). This guarantees unique filenames, preventing conflicts during tagging or import caused by duplicates or invalid characters.
• Usage:
  1. Ensure Python 3 is installed.
  2. Open your terminal/command prompt.
  3. Navigate to the directory containing imagerenamer.py.
  4. Run the script: python imagerenamer.py
  5. Follow the prompts to enter the folder path(s) you want to rename.

⚠️ EXTREME WARNING: Using imagerenamer.py is DESTRUCTIVE AND IRREVERSIBLE. It will permanently rename ALL image files (based on common extensions) in the target folders and their subfolders.

• DO NOT run this on folders containing image files you care about or images whose original filenames you need to preserve.
• BACK UP YOUR FOLDERS before running this script.
• Use this only if you understand the consequences and need to ensure unique filenames for processing.

eagletagger.py

• Purpose: After the Booru Image Processor has generated all the .json files, this script uses the Eagle API to very rapidly add the tags from the JSON files to the corresponding images in your Eagle library. It can be significantly faster than relying solely on the plugin for initial large tagging jobs.
• Usage:
  1. Ensure Python 3 is installed and the requests library is installed (pip install requests).
  2. Ensure the Booru Image Processor has finished generating .json files for the images you want to tag.
  3. Open your terminal/command prompt.
  4. Navigate to the directory containing eagletagger.py.
  5. Run the script: python eagletagger.py
  6. Follow the prompts to enter the folder path(s) containing the Json subfolders. The script will find images in the parent folders and apply tags found in the corresponding Json files.
• Recommendation: If using eagletagger.py, it's best to run the "Process all files" mode first to ensure maximum JSON file coverage for the script to consume. I do also recommend using it predominantly as it does take longer but it ensures all files are added. The other option Smart Search attempts to find the images in a different way vs the Use existing Index as well so I do recommend selecting Use Existing Index 99.99% of the time as if you used my image renamer you should have zero issues with images getting tagged and added unless said image is corrupted.

Troubleshooting

• Processor Error "Docker not available": Ensure Docker Desktop (or Docker Engine on Linux) is installed, running, and accessible to your user account before starting the Booru Image Processor application.
• API Connection Failed (in Processor Log):
  • Verify Docker is running.
  • Check if another process is using port 5000 (or the other ports like 5001, 5002 if using multiple instances).
  • Ensure no firewall is blocking local connections to these ports.
  • Try restarting Docker.
• Tags Not Appearing in Eagle:
  • Ensure the Eagle Plugin is installed and enabled.
  • Verify the .json files were created successfully by the Processor in the correct Json subfolder relative to the images.
  • Ensure the base filename of the image (e.g., MyImage) matches the base filename of the JSON (MyImage.json). Renaming images after generating JSONs will break the link.
  • Restart Eagle after processing completes.

JSON Format Example

The processor saves tags in this format within the Json subfolder (e.g., MyImage.json):

{
  "filename": "MyImage.png",
  "tags": {
    "tag_one": 0.987,
    "tag_two": 0.765,
    "another_tag": 0.543
  }
}

*(Note: The file structure `ImageFolder/Json/ImageName.json` alongside `ImageFolder/ImageName.png` is crucial for the Eagle plugin to find the tags.)*