imgtag

A Python CLI tool that scans a dataset folder for image files, creates matching .txt files, and uses an externally downloaded image-tagging model to write tags for each image.

Project Focus

This project emphasizes a clear and maintainable structure, version management, modular design, and execution within an isolated environment.

Structure

This project uses a src/ layout with multiple top-level packages to clearly separate responsibilities.

Directories

imgtag/
│
├─ src/
│   ├─ imgtag/                 # CLI / application entry
│   │   ├─ __init__.py
│   │   ├─ __main__.py
│   │   └─ main.py
│   │
│   ├─ imgtag_config/          # Configuration and path handling
│   │   ├─ __init__.py
│   │   ├─ paths.py
│   │   └─ settings.py
│   │
│   ├─ imgtag_io/              # File and folder I/O operations
│   │   ├─ __init__.py
│   │   ├─ download.py
│   │   ├─ files.py
│   │   ├─ folders.py
│   │   └─ image.py
│   │
│   ├─ imgtag_model/           # Model handling and inference
│   │   ├─ __init__.py
│   │   ├─ model_download.py
│   │   └─ tagger.py
│   │
│   └─ imgtag_utils/           # Shared utilities (logging)
│       ├─ __init__.py
│       └─ logger.py
│
├─ .venv/                      # Virtual environment (not committed, but recommended before install)
├─ pyproject.toml
├─ README.md
└─ .gitignore

Runtime directories

The following directories are created automatically and are not committed to version control:

• dataset/ – images to be tagged
• models/ – downloaded model files
• logs/ – application logs

Installation

1. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate

2. Install the project:

pip install -e .

Usage

Run the tool from anywhere inside the project directory:

imgtag

Run as a module:

python -m imgtag

Uninstall the project:

pip uninstall imgtag

Model Attribution

This project uses the image tagging model wd-vit-tagger-v3 by SmilingWolf.

The tagging logic (image preprocessing, label handling, and inference flow) is based on the official reference implementation provided by the model author in the Hugging Face Space:

https://huggingface.co/SmilingWolf/wd-vit-tagger-v3