Hierarchical Image Annotation Tool with napari

Introduction

This Python-based application allows users to annotate images with hierarchical labels using the napari ecosystem. The tool supports assigning category labels to images based on a predefined hierarchical structure (e.g., Animal → Cat → Abyssinian Cat). Annotations are saved persistently and can be loaded when reopening the application.

Project Goals

• Loads images from a specified directory.
• Allows users to annotate images with hierarchical category labels.
• Saves and loads annotations persistently.

Class Hierarchy

The annotation tool supports the following hierarchical structure:

    Animal
    ├── Cat
    │   ├── Abyssinian cat
    │   ├── Persian cat
    │   └── Siamese cat
    ├── Dog
    │   ├── French bulldog
    │   ├── German Shepherd
    │   └── Labrador Retriever
    ├── Tiger
    └── Bear

Core Functionality

• Image Loading & Navigation:

  • Accept a directory path containing images as a command-line argument.
  • Display the filenames from the directory in a list widget.
  • Navigate between images using the Left Arrow and Right Arrow keys.
  • Display the selected image in the napari viewer.

• Hierarchical Annotation Interface:

  • Use UI elements to guide the user through the hierarchy:
    • Select between "Animal" or "Other".
    • If "Animal" is selected, enable the selection of categories like Cat, Dog, Tiger, Bear.
    • Enable sub_category (breed) selection for Cat (Abyssinian, Persian, Siamese) and Dog (French bulldog, German Shepherd, Labrador Retriever).
    • The interface updates dynamically as the user selects categories or changes their selection.

• Annotation Persistence:

  • Automatically save annotations when navigating away from an image.
  • Implement a "Save" button to allow manual saving of annotations.
  • Store annotation data persistently in the image directory (in a dedicated hidden .json file).
  • Load previously saved annotations when the application is reopened.

Optional Feature

• Add a checkbox to the UI that applies a simple image transformation (Gaussian blur) to the displayed image.
• Unchecking the box should remove the transformation.

Technologies Used

• Language: Python (3.9+)
• Core Library: napari (0.5.X)
• UI Widgets: magicgui, pyQT
• Image Processing: napari's built-in functionality and sckit-image integration for transformations.

Installation & Setup

Requirements

• Python 3.9 or higher
• Dependencies listed in requirements.txt

Installation Steps

1. Clone the repository:

   git clone https://github.com/Eaglemann/Auto1-Task-Python.git

2. Navigate to the project directory:

  cd Auto1-Task-Python

3. Set up a venv and activate it

  python3 -m venv venv
  source venv/bin/activate 

4. Install the dependencies:

  pip3 install -r requirements.txt

5. Run the application with the following command, passing the path to the image directory:

  python3 main.py /path/to/image/directory

6. The application should launch a napari window displaying the images and annotation interface.

Annotation Storage Format

Annotations are saved as a hidden .json file within the image directory. Each annotation file contains the hierarchical label for the image in a human-readable format.

   1   │ {
   2   │     "01.jpg": {
   3   │         "category": "Animal",
   4   │         "sub_category": "Dog",
   5   │         "breed": "French bulldog"
   6   │     },
   7   │     "02.jpg": {
   8   │         "category": "Animal",
   9   │         "sub_category": "Tiger"
  10   │     },
  11   │ }

Code Quality & Structure

• The project strictly follows the Black code style for Python code formatting.
• The application structure follows good practices for separation of concerns, with clear distinctions between UI logic and data handling.