DeepDanbooru Documentation

Follow these steps to create and train a custom tag estimation model:

1. Prepare dataset: Ensure your images and SQLite database follow the required structure.
2. Create project folder: Initialize a new project directory.
3. Prepare tags: Download the latest tags from Danbooru or create a custom tags.txt.
4. Configure project: Update project.json with the correct database_path.
5. Train: Execute the training process.

Commands:

• deepdanbooru create-project [your_project_folder]
• deepdanbooru download-tags [your_project_folder] --username [your_danbooru_account] --api-key [your_danbooru_api_key]
• deepdanbooru train-project [your_project_folder]

You can install DeepDanbooru using pip. Note that tensorflow is not included by default. To include the tensorflow extra package, use the [tensorflow] syntax.

Requirements include Python 3.11 and packages such as Click, numpy, requests, scikit-image, six, tensorflow, and tensorflow-io.

# default installation
pip install .

# with tensorflow package
pip install .[tensorflow]

# or using requirements.txt
pip install -r requirements.txt

DeepDanbooru requires a specific directory structure and a SQLite database for training.

Directory Structure:

• An images/ folder containing sub-folders named after the first two characters of the image filename (e.g., 00/, 01/, ff/).
• A .sqlite file located in the same directory as the images/ folder.
• Image filenames must follow the pattern [md5].[file_ext].

SQLite posts table schema:

• id (INTEGER)
• md5 (TEXT)
• file_ext (TEXT)
• tag_string (TEXT): A space-separated list of tags (e.g., 1girl ahoge long_hair).
• tag_count_general (INTEGER): Used for the minimum_tag_count setting. Images with a value $\ge$ minimum_tag_count are used for training.

A Project is the minimal unit for training. It consists of:

• project.json: Configuration file (must include the correct database_path).
• tags.txt: A newline-separated file containing all tags to be estimated.

If you need to train using specific optional tags (such as rating and score), convert your dataset into a filtered system tag database using the make-training-database command.

deepdanbooru make-training-database [your_dataset_sqlite_path] [your_filtered_sqlite_path]

Use the evaluate command to estimate tags for specific images or entire folders using a trained project.

deepdanbooru evaluate [image_file_path or folder]... --project-path [your_project_folder] --allow-folder

The train_project function initiates the training process for a DeepDanbooru model using configurations defined in a project's project.json file. It supports resuming training from existing checkpoints, handles mixed-precision training, and manages model exports and checkpoints automatically.

To use this, you must provide a project_path (containing the project.json and dataset) and an optional source_model path to resume training from a specific model file.

Use the evaluate_project function to assess a trained model's performance on a target dataset. The function loads a project context, model, and tags from a specified project_path, then iterates through images in a target_path to predict tags. For each image, it prints tags that meet or exceed a specified threshold score.

Parameters:

• project_path: Path to the directory containing the trained project (context, model, and tags).
• target_path: Path to a specific image file or a directory containing images (supports .png, .jpg, .jpeg, .gif).
• threshold: A float value used to filter predicted tags. Only tags with a prediction score greater than or equal to this value will be printed.

The evaluate function allows you to run inference on one or more images using a trained DeepDanbooru model. It predicts tags for the provided images and can optionally save the results as .txt files.

If a project_path is provided, the function will automatically attempt to load both the model and the tags from that project. Otherwise, you must explicitly provide model_path and tags_path.

The download_category_tags function allows for granular downloading of specific tag categories from the Danbooru API.

Supported Categories

• general (index 0)
• artist (index 1)
• copyright (index 3)
• character (index 4)

Parameters

• category: The category string (general, artist, copyright, or character).
• minimum_post_count: Minimum number of posts required for a tag to be included.
• limit: Maximum number of tags to return.
• username: Danbooru username.
• api_key: Danbooru API key.
• page_size: Number of tags to request per API page (default: 1000).
• order: The order to sort the search results (default: "count").