go-image-annotator

#+title: Go Image Annotation Tool

A simple web application
to manage, store, and annotate images using bounding boxes
built in [[https://go.dev/][Go]].

* Goals
- Store and organize images in collections
- Annotate images through a simple web interface

* Features
- Simple web frontend to add bounding boxes
- HTTP/REST API to (among other things):
  - Add new annotation labels
  - Ingest images into collections
  - Add bounding box annotations
    
* Usage
** Configuration
This application stores meta and raw-data on a local mount.

In particular, define a path for the SQLite database, e.g.
#+begin_src sh
GOIA_DBPATH=/home/user/.cache/go-image-annotator/db.sqlite
#+end_src

Next, define a path where images will be stored, e.g.
#+begin_src sh
GOIA_ARTEFACTDIR=/home/user/.cache/go-image-annotator/artefacts
#+end_src

** Building
To build the binary, run
#+begin_src sh
go build .
#+end_src

** Ingesting images from a local directory
Aside from the HTTP/REST endpoints, we
provide basic CLI functions to get started quickly.

First, create a new collection that will hold images:

#+begin_src sh
./go-image-annotator create-collection my-new-collection
#+end_src

Next, ingest images by specifying a local directory that contains images you wish to ingest:

#+begin_src sh
./go-image-annotator ingest-dir <path/to/image/directory> my-new-collection
#+end_src

** Run web server

You may then launch the web server on port ~8001~ with:
#+begin_src sh
./go-image-annotator serve -p 8001
#+end_src

* Development dependencies
This application has been tested to build
with ~go~ version ~>= 1.26~.

To (re)-generate the HTTP endpoints, you will need
~oapi-codegen~ version ~>=2.5.1~.

Last, CSS must be generated using ~tailwindcss~ version ~4~.

All other dependencies are bundled in this repository
as javascript files.

Optionally, we provide a [[https://nixos.wiki/wiki/Flakes][Nix Flake]]
that provides a development environment (dev-shell)
with all requirements included.


* Tech Stack
** Frontend
We try to keep this project lightweight, by avoiding
heavy frontend framework. Instead, we make the choice to
generate most content on the server-side, and let
the client be a "thin viewer". In particular,
we rely on [[https://htmx.org/][HTMX]] to generate views on the server and update
the client, and [[https://alpinejs.dev/][Alpine.js]]
for client-side interactivity.

For the annotation client-side widget, we use [[https://annotorious.dev/][Annotatorious]],
which allows to draw and update different kinds of shapes.

Last, we style our pages using [[https://tailwindcss.com/][tailwindcss]].

** Database

For the repository-layer we provide adapters based on [[https://sqlite.org/][SQLite]], which
we choose for its simplicity and speed.

** REST API
This application exposes a number of HTTP endpoints to handle
requests through json payloads. We auto-generate
HTTP controller methods from OpenAPI specs using [[https://github.com/oapi-codegen/oapi-codegen][oapi-codegen]].

* Design Principles
This application is built following the [[https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html][Clean Architecture]],
where use-cases are placed at the center, while dependencies
are places on the outside. In a nutshell, this ensures
clear separation of concern and testability, and
should make this project easy to extend and modify.

Furthermore, we strive to provide an extensive test suite.