bbannotate 1.0.0__py3-none-any.whl

bbannotate-1.0.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: bbannotate
+Version: 1.0.0
+Summary: A lightweight bounding box annotation tool for image datasets with YOLO/COCO/Pascal VOC export
+Project-URL: Homepage, https://github.com/seba2390/bbannotate
+Project-URL: Documentation, https://github.com/seba2390/bbannotate#readme
+Project-URL: Repository, https://github.com/seba2390/bbannotate
+Project-URL: Issues, https://github.com/seba2390/bbannotate/issues
+Author: Sebastian Yde Madsen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: annotation,bounding-box,coco,computer-vision,image-annotation,machine-learning,object-detection,pascal-voc,yolo
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiofiles>=23.2.1
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: pillow>=10.2.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="frontend/public/logo.png" alt="Bbannotate Logo" width="400">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/bbannotate/"><img src="https://img.shields.io/pypi/v/bbannotate" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/bbannotate/"><img src="https://img.shields.io/pypi/pyversions/bbannotate" alt="Python versions"></a>
+  <a href="https://github.com/sebastianydemadsen/bbannotate/blob/main/LICENSE"><img src="https://img.shields.io/github/license/sebastianydemadsen/bbannotate" alt="License"></a>
+</p>
+
+A lightweight bounding box annotation tool for image datasets. Built with React/TypeScript frontend and FastAPI backend. Export to YOLO, COCO, Pascal VOC, and more.
+
+## Features
+
+- 🖼️ **Multi-format support** — PNG, JPEG, WebP, BMP
+- 📁 **Project management** — Organize annotations by project
+- 🏷️ **Custom labels** — Define your own class labels
+- ⌨️ **Keyboard shortcuts** — Fast annotation workflow
+- 📤 **Multiple export formats** — YOLO, COCO, Pascal VOC, CreateML, CSV
+- 🔄 **Train/Val/Test split** — Automatic dataset splitting for YOLO export
+
+## Installation
+
+```bash
+pip install bbannotate
+```
+
+### Requirements
+
+- Python 3.12+
+- Node.js (only for frontend development)
+
+## Quick Start
+
+```bash
+# Start the annotation server
+bbannotate start
+
+# Opens http://127.0.0.1:8000 in your browser
+```
+
+### CLI Options
+
+```bash
+bbannotate start [OPTIONS]
+
+Options:
+  -h, --host TEXT        Host to bind the server to [default: 127.0.0.1]
+  -p, --port INTEGER     Port to bind the server to [default: 8000]
+  --no-browser           Don't open browser automatically
+  -r, --reload           Enable auto-reload for development
+  -d, --data-dir PATH    Directory for storing data [default: ./data]
+  --projects-dir PATH    Directory for storing projects [default: ./projects]
+  -v, --version          Show version and exit
+  --help                 Show help and exit
+```
+
+### Other Commands
+
+```bash
+bbannotate info            # Show installation info
+bbannotate build-frontend  # Build frontend assets (development)
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `D` | Draw mode |
+| `S` | Select mode |
+| `Space` | Pan mode |
+| `←` `→` | Navigate images |
+| `1-9` | Select label by index |
+| `Del` / `Backspace` | Delete annotation |
+| `Esc` | Deselect / Cancel |
+
+## Export Formats
+
+| Format | Description |
+|--------|-------------|
+| **YOLO** | ZIP with train/val/test split, `data.yaml`, normalized coordinates |
+| **COCO** | COCO JSON format with categories, images, and annotations |
+| **Pascal VOC** | XML files per image with absolute coordinates |
+| **CreateML** | Apple CreateML JSON format |
+| **CSV** | Simple CSV with image, label, and bbox columns |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `BBANNOTATE_DATA_DIR` | Override default data directory |
+| `BBANNOTATE_PROJECTS_DIR` | Override default projects directory |
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/sebastianydemadsen/bbannotate.git
+cd bbannotate
+make install        # Install with dev dependencies
+make frontend-install  # Install frontend dependencies
+```
+
+### Development Commands
+
+| Command | Description |
+|---------|-------------|
+| `make run` | Start full application (backend + frontend) |
+| `make backend-dev` | Start backend only with auto-reload |
+| `make frontend-dev` | Start frontend dev server |
+| `make stop` | Stop all servers |
+| `make test` | Run tests |
+| `make test-cov` | Run tests with coverage report |
+| `make type-check` | Run pyright type checking |
+| `make format` | Format code with ruff |
+| `make check-all` | Run all checks (lint, type, test) |
+| `make build` | Build package for distribution |
+| `make clean` | Remove build artifacts |
+
+### Project Structure
+
+```
+src/               # Python package (FastAPI backend)
+  api/             # API routes
+  models/          # Pydantic models
+  services/        # Business logic
+  cli.py           # CLI entry point
+frontend/          # React/TypeScript frontend
+  src/
+    components/    # UI components
+    hooks/         # React hooks
+tests/             # Test suite (145 tests)
+```
+
+## License
+
+[MIT](LICENSE)

bbannotate-1.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+src/__init__.py,sha256=Eg75iuRICqJS9qBThEk9OQ4l7sDRagmKrjuc4tGCVns,117
+src/cli.py,sha256=q2u1j1Q4A1F1yMAWPzNmnw053CKqxxnHVGzhUGSJKzI,7533
+src/main.py,sha256=M2yuPRxkRDYCwNw7jPBwDm6R-Egk6EFbdUeh3W3YHss,2346
+src/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/api/__init__.py,sha256=rin7NuwATcUVSpd-oncHr4VPxCj2je9kPpsjMdwQAJ0,99
+src/api/routes.py,sha256=iLliNvNMXFFpm5SxCQ5fj-txaWurIGy-kuchx9v-mYM,11085
+src/models/__init__.py,sha256=V3IlbnQ_PWn43HCKlOi-IRTmNj1GX7iA79ZbCns_yts,368
+src/models/annotations.py,sha256=NiCBjmejQbgoMKkDiNqFZBKK6-QggcU1ikXwXFoQWgc,1951
+src/services/__init__.py,sha256=jDAHHd3p_fYdT3Txzakd2I0fxwEQ6irMQ1nNELhuIEY,207
+src/services/annotation_service.py,sha256=_OiUlm42LXIMrcbTVjGWZPOovhppUJMX3v8rZuq6WVU,10495
+src/services/export_service.py,sha256=-NhO6jCQtOpIgFL3cVDk86KQSQBBiogN3jVpESJQVac,17180
+src/services/project_service.py,sha256=6l2mih32z5_tqLj8orF5szNhuEJYkboNeUwNqDEs9iA,7125
+src/frontend_dist/index.html,sha256=opKxjiCx3PXtHQsAsn7iQ3zkOUMr-fTgZ_l85E4X7cc,733
+src/frontend_dist/logo.png,sha256=hiuri3y0lYBsavGECeXh8VPVJvhA8nOlHCDeTSfqk8s,198758
+src/frontend_dist/assets/index-DFfgJzXo.css,sha256=v9Ez3rvpb4mWv3JtVFrke3ubOwyOfCBSl0vbIbekCC0,20719
+src/frontend_dist/assets/index-DezlWFbC.js,sha256=S8frLZGZ7cm5ugjS7bLjPrJBRGeoJnx1lDyPQVBRQg4,518021
+bbannotate-1.0.0.dist-info/METADATA,sha256=r7SrH-rMJ-TJKqHcWm11Hy-ee3QbeNevgzAA9Pj6zqM,6046
+bbannotate-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+bbannotate-1.0.0.dist-info/entry_points.txt,sha256=nu0u4lG6-pWhDUmquxeusVDJzhsWQOUczupOWmKH01c,44
+bbannotate-1.0.0.dist-info/licenses/LICENSE,sha256=rkJbDOYRrUX8k3S55pPiEquJXZGh07KvD01F1sBBppw,1077
+bbannotate-1.0.0.dist-info/RECORD,,

bbannotate-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bbannotate-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bbannotate = src.cli:main

bbannotate-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Yde Madsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/__init__.py

@@ -0,0 +1,4 @@
+"""Bbannotate - Bounding box annotation tool for image datasets."""
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

src/api/__init__.py

@@ -0,0 +1,5 @@
+"""API routes for the annotation tool."""
+
+from src.api.routes import router
+
+__all__ = ["router"]

src/api/routes.py

@@ -0,0 +1,339 @@
+"""FastAPI routes for the annotation API."""
+
+import os
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile
+from fastapi.responses import FileResponse
+
+from src.models.annotations import (
+    Annotation,
+    AnnotationCreate,
+    AnnotationUpdate,
+    ImageInfo,
+    ProjectInfo,
+)
+from src.services.annotation_service import AnnotationService
+from src.services.export_service import ExportService
+from src.services.project_service import Project, ProjectCreate, ProjectService
+
+router = APIRouter()
+
+
+def get_projects_dir() -> Path:
+    """Get the projects directory from environment or default."""
+    env_path = os.environ.get("BBANNOTATE_PROJECTS_DIR")
+    if env_path:
+        return Path(env_path)
+    return Path.cwd() / "projects"
+
+
+def get_data_dir() -> Path:
+    """Get the data directory from environment or default."""
+    env_path = os.environ.get("BBANNOTATE_DATA_DIR")
+    if env_path:
+        return Path(env_path)
+    return Path.cwd() / "data"
+
+
+# Default directories (use functions for dynamic resolution)
+PROJECTS_DIR = get_projects_dir()
+DATA_DIR = get_data_dir()  # Legacy fallback
+
+# Global state for current project
+_current_project_id: str | None = None
+
+
+def get_project_service() -> ProjectService:
+    """Dependency for project service."""
+    return ProjectService(get_projects_dir())
+
+
+def get_annotation_service() -> AnnotationService:
+    """Dependency for annotation service - uses current project's data directory."""
+    global _current_project_id
+    if _current_project_id:
+        project_service = ProjectService(get_projects_dir())
+        data_dir = project_service.get_project_data_dir(_current_project_id)
+        if data_dir:
+            return AnnotationService(data_dir)
+    # Fallback to legacy data directory
+    return AnnotationService(get_data_dir())
+
+
+def get_export_service(
+    annotation_service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> ExportService:
+    """Dependency for export service."""
+    return ExportService(annotation_service)
+
+
+# Project management endpoints
+@router.get("/projects", response_model=list[Project])
+def list_projects(
+    service: Annotated[ProjectService, Depends(get_project_service)],
+) -> list[Project]:
+    """List all projects, sorted by last opened."""
+    return service.list_projects()
+
+
+@router.post("/projects", response_model=Project)
+def create_project(
+    create: ProjectCreate,
+    service: Annotated[ProjectService, Depends(get_project_service)],
+) -> Project:
+    """Create a new project."""
+    return service.create_project(create)
+
+
+@router.get("/projects/current", response_model=Project | None)
+def get_current_project(
+    service: Annotated[ProjectService, Depends(get_project_service)],
+) -> Project | None:
+    """Get the currently active project."""
+    global _current_project_id
+    if not _current_project_id:
+        return None
+    return service.get_project(_current_project_id)
+
+
+@router.post("/projects/{project_id}/open", response_model=Project)
+def open_project(
+    project_id: str,
+    service: Annotated[ProjectService, Depends(get_project_service)],
+) -> Project:
+    """Open a project (set as current and update last_opened)."""
+    global _current_project_id
+    project = service.open_project(project_id)
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    _current_project_id = project_id
+    return project
+
+
+@router.post("/projects/close")
+def close_project() -> dict[str, bool]:
+    """Close the current project."""
+    global _current_project_id
+    _current_project_id = None
+    return {"success": True}
+
+
+@router.delete("/projects/{project_id}")
+def delete_project(
+    project_id: str,
+    service: Annotated[ProjectService, Depends(get_project_service)],
+) -> dict[str, bool]:
+    """Delete a project and all its data."""
+    global _current_project_id
+    success = service.delete_project(project_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Project not found")
+    if _current_project_id == project_id:
+        _current_project_id = None
+    return {"success": True}
+
+
+# Project endpoints (existing)
+@router.get("/project", response_model=ProjectInfo)
+def get_project_info(
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> ProjectInfo:
+    """Get project statistics and label information."""
+    return service.get_project_info()
+
+
+# Image endpoints
+@router.get("/images", response_model=list[str])
+def list_images(
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> list[str]:
+    """List all images in the project."""
+    return service.list_images()
+
+
+@router.post("/images", response_model=ImageInfo)
+async def upload_image(
+    file: Annotated[UploadFile, File(...)],
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> ImageInfo:
+    """Upload a new image."""
+    if not file.filename:
+        raise HTTPException(status_code=400, detail="Filename is required")
+
+    content = await file.read()
+    try:
+        return service.upload_image(file.filename, content)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+
+@router.get("/images/{filename}")
+def get_image(
+    filename: str,
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> FileResponse:
+    """Get an image file."""
+    path = service.get_image_path(filename)
+    if path is None:
+        raise HTTPException(status_code=404, detail="Image not found")
+    return FileResponse(path)
+
+
+@router.delete("/images/{filename}")
+def delete_image(
+    filename: str,
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> dict[str, bool]:
+    """Delete an image and its annotations."""
+    success = service.delete_image(filename)
+    if not success:
+        raise HTTPException(status_code=404, detail="Image not found")
+    return {"success": True}
+
+
+# Annotation endpoints
+@router.get("/images/{filename}/annotations", response_model=list[Annotation])
+def get_annotations(
+    filename: str,
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> list[Annotation]:
+    """Get all annotations for an image."""
+    return service.get_annotations(filename)
+
+
+@router.post("/images/{filename}/annotations", response_model=Annotation)
+def add_annotation(
+    filename: str,
+    annotation: AnnotationCreate,
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> Annotation:
+    """Add a new annotation to an image."""
+    try:
+        return service.add_annotation(filename, annotation)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+
+
+@router.put("/images/{filename}/annotations/{annotation_id}", response_model=Annotation)
+def update_annotation(
+    filename: str,
+    annotation_id: str,
+    update: AnnotationUpdate,
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> Annotation:
+    """Update an existing annotation."""
+    result = service.update_annotation(filename, annotation_id, update)
+    if result is None:
+        raise HTTPException(status_code=404, detail="Annotation not found")
+    return result
+
+
+@router.delete("/images/{filename}/annotations/{annotation_id}")
+def delete_annotation(
+    filename: str,
+    annotation_id: str,
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> dict[str, bool]:
+    """Delete an annotation."""
+    success = service.delete_annotation(filename, annotation_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Annotation not found")
+    return {"success": True}
+
+
+@router.delete("/images/{filename}/annotations")
+def clear_annotations(
+    filename: str,
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> dict[str, int]:
+    """Clear all annotations for an image."""
+    count = service.clear_annotations(filename)
+    return {"deleted": count}
+
+
+@router.post("/images/{filename}/annotations/copy-from/{source_filename}")
+def copy_annotations(
+    filename: str,
+    source_filename: str,
+    service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> dict[str, int]:
+    """Copy annotations from another image."""
+    count = service.copy_annotations(source_filename, filename)
+    return {"copied": count}
+
+
+# Export endpoints
+@router.post("/export/yolo")
+def export_yolo(
+    export_service: Annotated[ExportService, Depends(get_export_service)],
+    train_split: Annotated[float, Query(ge=0.1, le=0.98)] = 0.7,
+    val_split: Annotated[float, Query(ge=0.01, le=0.5)] = 0.2,
+    test_split: Annotated[float, Query(ge=0.0, le=0.5)] = 0.1,
+) -> FileResponse:
+    """Export annotations in YOLO format as a ZIP file."""
+    zip_path = export_service.export_yolo_zip(train_split, val_split, test_split)
+    return FileResponse(
+        zip_path,
+        media_type="application/zip",
+        filename="yolo_dataset.zip",
+    )
+
+
+@router.post("/export/coco")
+def export_coco(
+    export_service: Annotated[ExportService, Depends(get_export_service)],
+    annotation_service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> FileResponse:
+    """Export annotations in COCO JSON format."""
+    output_path = annotation_service.data_dir / "coco_annotations.json"
+    export_service.export_coco(output_path)
+    return FileResponse(
+        output_path,
+        media_type="application/json",
+        filename="coco_annotations.json",
+    )
+
+
+@router.post("/export/pascal-voc")
+def export_pascal_voc(
+    export_service: Annotated[ExportService, Depends(get_export_service)],
+) -> FileResponse:
+    """Export annotations in Pascal VOC XML format as a ZIP file."""
+    zip_path = export_service.export_pascal_voc_zip()
+    return FileResponse(
+        zip_path,
+        media_type="application/zip",
+        filename="pascal_voc_dataset.zip",
+    )
+
+
+@router.post("/export/createml")
+def export_createml(
+    export_service: Annotated[ExportService, Depends(get_export_service)],
+    annotation_service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> FileResponse:
+    """Export annotations in Apple CreateML JSON format."""
+    output_path = annotation_service.data_dir / "createml_annotations.json"
+    export_service.export_createml(output_path)
+    return FileResponse(
+        output_path,
+        media_type="application/json",
+        filename="createml_annotations.json",
+    )
+
+
+@router.post("/export/csv")
+def export_csv(
+    export_service: Annotated[ExportService, Depends(get_export_service)],
+    annotation_service: Annotated[AnnotationService, Depends(get_annotation_service)],
+) -> FileResponse:
+    """Export annotations in CSV format."""
+    output_path = annotation_service.data_dir / "annotations.csv"
+    export_service.export_csv(output_path)
+    return FileResponse(
+        output_path,
+        media_type="text/csv",
+        filename="annotations.csv",
+    )