Anno-Mage: Semi-Automatic Image Annotation With PyTorch Detection Models
Anno-Mage: A Semi Automatic Image Annotation Tool which helps you in annotating images by suggesting you annotations using user-defined labels
At a glance
- What is it?
- Anno-Mage is a Python toolbox that proposes bounding boxes from PyTorch detectors so a human can accept or correct them, and it now ships as a FastAPI plus React web app. The useful part is the output contract: one CSV row per box, plus Pascal VOC XML per image.
- Who is it for?
- Adopt Anno-Mage if you need bounding boxes in CSV or Pascal VOC form and you want a detector to pre-fill them, and if a Python install with PyTorch is acceptable on the annotator's machine. Do not adopt it if your labels are polygons, keypoints or segmentation masks, since the documented output is rectangles only.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 151 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The labelling bottleneck Anno-Mage targets
Drawing boxes by hand is slow, and it is slow in a way that scales with the number of objects per image rather than the number of images. Anno-Mage takes the position that a detector can propose the boxes and a person can accept or fix them. The README describes the tool as a semi-automatic annotation toolbox powered by PyTorch object detection models, and it names open-vocabulary zero-shot detection via OWL-v2 as one of the options. That phrase matters. A zero-shot detector takes the label names you define and looks for those concepts in the image, so a new class does not require a freshly trained model before you can start labelling. The intended user is someone assembling a detection dataset who already knows the class list and wants the first pass done by a model. It is not a general labelling platform for segmentation, and it is not aimed at teams who need multi-annotator review workflows, because nothing in the supplied material describes roles, review queues or inter-annotator agreement.
What the detector proposes and where the boxes go
The mechanism is a proposal loop. You supply labels, the detector runs over an image, and the resulting boxes appear in the interface for a human to confirm or adjust. The README credits PyTorch and Torchvision for the RetinaNet implementation and HuggingFace Transformers for the OWL-v2 zero-shot detection model, so there are at least two model paths rather than one fixed architecture. The output contract is the part worth reading closely. Both interfaces are documented to produce identical output, in two formats. The CSV file at annotations/annotations.csv carries one row per box with the columns image_path,x1,y1,x2,y2,label. Pascal VOC XML is written to annotations/annotations_voc/, one XML file per image. That is a deliberately narrow schema: axis-aligned rectangles with a single label each. There is no field for confidence scores, no field for who annotated the box, and no field for a review state. If your downstream training code expects a score column or a difficult-object flag, you will be adding it yourself. The upside of the narrow schema is that both formats are consumed directly by common detection training pipelines without a conversion step.
Two install paths: PyPI package and web app
The README gives two ways in. The packaged route is pip install anno-mage followed by running anno-mage, and the documentation states the app opens in your browser automatically and saves annotations to ~/.anno-mage/annotations/. The second route runs the web app from source: the backend with cd web/backend && python main.py on port 8000, and the frontend with cd web/frontend && npm install && npm run dev on port 3000. A convenience script at web/start.sh runs both. The repository also documents a build path for maintainers: bash build_release.sh compiles the React frontend, copies the build into anno_mage/static/, and produces wheel and sdist artifacts in dist/. The publishing setup is worth noting because it affects how you track versions. Releases publish to PyPI when a version tag is pushed, for example git tag v2.0.1 followed by git push origin v2.0.1, and the workflow in .github/workflows/release.yml does the rest using PyPI Trusted Publishers rather than stored tokens. The README states that no releases were listed in the material I was given, so I cannot tell you what the current published version is; check the PyPI page before pinning anything.
Where the semi-automatic approach breaks down
The failure mode is silent and it is the one that matters for dataset quality. A detector that proposes boxes is a suggestion engine, and a reviewer who accepts suggestions quickly will accept wrong ones. The output schema gives you no way to tell an accepted suggestion from a hand-drawn box, because there is no provenance column in the CSV and no equivalent field in the VOC XML. If the OWL-v2 path is used with a label vocabulary that does not describe your objects well, the proposals will be plausible-looking boxes on the wrong regions, and the cost of correcting them can exceed the cost of drawing from scratch. There is a second, harder boundary: this tool produces rectangles. If your task needs polygons, keypoints or per-pixel masks, the documented output cannot represent it, and no amount of interface work changes that. I would also treat the browser-opening behaviour of the packaged command as a deployment constraint. It is described as opening the app in your browser automatically, which is convenient on a workstation and awkward on a headless machine where annotators work through a remote session. The material does not describe a documented flag to disable that behaviour.
How it compares with LabelImg and CVAT
The obvious comparison is LabelImg, the long-standing manual bounding box tool that also writes Pascal VOC XML. The difference in approach is that LabelImg has no model in the loop at all: every box is drawn by a person, and the tool's job is to make that drawing fast and the file writing correct. Anno-Mage inserts a detector between the image and the annotator, which changes the cost profile. On a class the detector already handles well, the annotator's job becomes verification rather than creation. On a class it handles badly, the annotator pays for both the proposal and the correction. CVAT sits at the other end: it is a server-based platform with task assignment, multiple annotation types and team-oriented review features. Anno-Mage is a single-user tool with a two-format output, and the README does not describe accounts, task queues or review states. If your bottleneck is coordinating five annotators, CVAT addresses that problem and Anno-Mage does not. If your bottleneck is one person drawing ten thousand boxes, the proposal loop is the relevant feature.
Licence and the cost of keeping it running
The repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That is a permissive licence, and it is compatible with the common practice of vendoring a tool into an internal pipeline. Two things sit outside that licence and you should check them separately. The OWL-v2 model is hosted on HuggingFace, and the README links to google/owlv2-base-patch16-ensemble; the terms attached to that checkpoint are its own, not the repository's, so the licence of the code does not automatically tell you what you may do with the weights. PyTorch and Torchvision carry their own licences as well. On maintenance cost, the release process is automated through GitHub Actions and PyPI Trusted Publishers, so publishing a new version is a tag push, which keeps the maintainer's effort low. What you inherit is the dependency surface: a Python environment with PyTorch, Torchvision and Transformers, plus Node and npm if you run the web app from source. That is a heavier install than a single-purpose desktop tool, and the frontend build step means upgrading from source is not a git pull and a restart. This is a description of the licence terms as stated in the repository, not legal advice; if the model weights are central to your use, have someone check their terms.
Who should adopt it, and what to check first
Adopt Anno-Mage if your target is axis-aligned bounding boxes, your classes are describable in words well enough for a zero-shot detector to find them, and you are willing to run a Python and PyTorch install on the annotator's machine. The two output formats are the strongest argument for it, because they drop into existing detection training code without a conversion script. Do not adopt it if you need polygons, keypoints or masks, if you need several people annotating the same image with a review step, or if you cannot run a GPU or an adequately provisioned CPU where the annotator sits. Before committing, verify three things in this order. First, that the OWL-v2 checkpoint downloads and performs acceptably on a handful of your own images, since a detector that misses your objects turns the tool into a slower drawing program. Second, that the CSV header image_path,x1,y1,x2,y2,label and the VOC directory layout at annotations/annotations_voc/ match what your training loader expects, because a mismatch here is discovered late. Third, that the packaged command's habit of opening the app in your browser fits your setup, or that running web/backend and web/frontend separately on ports 8000 and 3000 does.
Editorial conclusion
Adopt Anno-Mage if you need bounding boxes in CSV or Pascal VOC form and you want a detector to pre-fill them, and if a Python install with PyTorch is acceptable on the annotator's machine. Do not adopt it if your labels are polygons, keypoints or segmentation masks, since the documented output is rectangles only. Verify first that the OWL-v2 checkpoint downloads and runs on your hardware, and that the CSV columns image_path,x1,y1,x2,y2,label match the loader your training code already uses.
Community notes