A web-based tool for hierarchically annotating images with bounding boxes, compositional descriptions, and color palettes. Intended to be used for a finetune of Anima that supports JSON similar to Ideogram 4, but with hierarchical elements.

• Hierarchical Tree Editor — Drag-and-drop tree structure for organizing image annotations with nested child nodes.
• Bounding Box Overlay — Visual bounding box overlay on loaded images with resizable corner handles. Coordinates are stored in a normalized 0–1000 space.
• Dominant Color Extraction — Automatic extraction of dominant colors from bounding box regions using K-means clustering.
• JSON Editor — Inline JSON editor that stays in sync with the tree view (bidirectional).
• File Loading — Load images (.jpg, .png) and matching .json files by name.
• Mock API Integration — Placeholder backend endpoints for annotation retrieval and model updates (ready for PyTorch integration).
• JSON Export — Download the current annotation tree as a .json file.

• Node.js ≥ 18 (for ES2022 target and bundler module resolution)
• Python ≥ 3.9
• npm (or yarn)

Run the provided setup script for your platform. This will create a Python virtual environment, install all dependencies, and check your Node.js version.

Linux / macOS:

bash scripts/setup.sh

Windows:

scripts\setup.bat

If you prefer to set things up by hand:

# Backend
cd backend
python -m venv .venv

# Activate the venv
# macOS / Linux:
source .venv/bin/activate
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Windows (CMD):
.venv\Scripts\activate.bat

pip install -r requirements.txt

# Frontend
cd ../frontend
npm install

Use the provided run script for your platform:

Linux / macOS:

bash scripts/run.sh

Windows:

scripts\run.bat

This starts both the Vite dev server and FastAPI backend:

• UI at http://localhost:5173
• API at http://localhost:8000

Backend:

cd backend
source .venv/bin/activate   # or .venv\Scripts\activate.bat on Windows
python server.py
# or: uvicorn server:app --host 0.0.0.0 --port 8000 --reload

Frontend:

cd frontend
npm run dev

python scripts/build.py

This compiles TypeScript and bundles the frontend, outputting static files to backend/static/. Then serve the backend:

cd backend
python server.py

1. Load an image — Click "Choose Files" in the Preview panel and select one or more .jpg/.png files (optionally with a matching .json file of the same base name).
2. Edit annotations — Use the Hierarchy panel to add children, bounding boxes, and descriptions. Drag nodes to reorder.
3. Draw bounding boxes — Select a node in the tree, click "+ BBox", then drag the resize handles on the image preview.
4. Edit JSON directly — Switch to the JSON Editor panel, modify the text, and click "Apply JSON → Tree".
5. Annotate with AI — Click "Annotate Image" to send the loaded image to the backend (currently returns mock data).
6. Update model — After annotating, click "Update model" to send the annotation data to the backend.
7. Export — Click "Download JSON" to save the current annotation tree.

This project is licensed under the Apache License 2.0.