alfred-py, deep learning utilities packaged as a library and a CLI

The gap it fills is the glue, not the algorithms

alfred-py is presented as a deep learning utility library, and the pitch in the README is about the boring half of the work. The description says it can be called from the terminal via alfred as a tool for deep learning usage, and that it provides utilities to boost daily efficiency: draw a box with a score and a label, add logging to a Python application, convert a model to a TensorRT engine, and so on, with a single import alfred.

That framing matters. It is not a model library and it does not claim to be one. The listed functions are the things you write yourself in every new project: a drawing helper for detection results, a logger, a format converter, a deployment step.

The summary in the README groups the capabilities into five buckets. Visualisation covers boxes, masks and keypoints, including 3D boxes on a point cloud. Command line tools cover viewing annotation data in any of the yolo, voc or coco formats. Deployment covers using alfred to deploy TensorRT models. Deep learning common utilities cover things like torch.device(). And rendering covers rendering 3D models.

The package is on PyPI as alfred-py, with the project description Alfred is a DeepLearning utility library, authored by Lucas Jin, and it is classified as Development Status 4 - Beta with an intended audience of developers and of scientific and engineering work in artificial intelligence and image recognition.

The alfred command exposes the same capabilities

alfred is both a library and a tool, and the README is explicit about that: you can import its APIs or call it directly inside your terminal. After installation you get the alfred command, with a shorter alias a registered alongside it, and the top-level help shows the module structure:

usage: alfred [-h] [--version] {vision,text,scrap,cab,data} ...

positional arguments:
  {vision,text,scrap,cab,data}
    vision              vision related commands.
    text                text related commands.
    scrap               scrap related commands.
    cab                 cabinet related commands.
    data                data related commands.

optional arguments:
  -h, --help            show this help message and exit
  --version, -v         show version info.

Every child module has its own -h as well, so alfred text -h documents the text commands.

The two modules that do the day-to-day work are data and cab. The data module is the annotation toolbox: vocview to show VOC annotations, cocoview for COCO, yoloview for YOLO and txtview for detection labels in text format, plus coco2voc to convert between formats, and evalvoc for evaluation helpers. The cab module is the filing cabinet: count the files of a type in a directory, and split a text file into train and val lists with a ratio.

alfred data cocoview -j annotations/instance_2017.json -i images/
alfred cab count -d ./images -t jpg
alfred cab split -f all.txt -r 0.9,0.1 -n train,val

Those three lines are the pitch in miniature. Look at your data, count your files, split your list.

Vision commands for video work and the optional extras

The vision module handles the media side: extracting a video into images and combining images back into a video.

alfred vision extract -v video.mp4
alfred vision 2video -d images/

That pair is small but it is the kind of thing that otherwise becomes a ffmpeg incantation copied between repositories.

The install requirements are laid out plainly. lxml, pycocotools and opencv-python are all marked optional, and the package metadata expresses that as extras named coco for pycocotools and vision for opencv-python and lxml. The base dependency list is a long tail of small utilities: colorama, natsort, requests, regex, funcy, pascal-voc-writer, markdown, future, deprecated, loguru, pyquaternion, jsons, gtrending, xdg, portalocker and rich. A few of those names explain themselves: pascal-voc-writer writes VOC annotation files, pyquaternion handles the rotations that 3D boxes need, portalocker guards file access, and rich and loguru cover terminal output and logging.

The Windows note is worth keeping if you are on that platform, since pycocotools has no straightforward wheel for every environment. The README gives the source install from the cocoapi repository with pip install and the git URL, and notes that pycocotools is a dependency because the pycoco API is needed.

The base install is one command:

pip install alfred-py

3D visualisation is where the library is most distinctive

The update history shows where the effort went over three years, and the 3D work is the part that is hardest to replace.

In December 2021 alfred added keypoint visualisation, and the README states that almost all datasets supported in mmpose were also supported by alfred. The API is a single function:

from alfred.vis.image.pose import vis_pose_result

# preds are poses, which is (Bs, 17, 3) for coco body
vis_pose_result(ori_image, preds, radius=5, thickness=2, show=True)

In January 2022 came a Mesh3D visualizer server based on Open3D, which turns 3D model inspection into a client-server thing:

from alfred.vis.mesh3d.o3dsocket import VisOpen3DSocket

def main():
    server = VisOpen3DSocket()
    while True:
        server.update()

You set up a client, send 3D keypoints to the server, and they are visualised out. The server loop is a blocking update call, which is the simplest thing that could work and also the thing you have to design around.

In April 2023 the 3D keypoints visualiser was updated so Human3DM keypoints can be visualised in real time, with the result generated from MotionBert and a reference to examples/demo_o3d_server.py.

For detection work there is 3D box drawing on point clouds, and the examples directory holds the specific scripts: draw_3d_box_on_image.py, draw_3d_pointcloud.py, projection_cal.py, alfred_show_box_gt.py, vis_coco.py, demo_o3d.py, demo_p3d.py, demo_show_mesh.py, pykitti_test.py and a chatbot.py.

Packaging was modernised, but the metadata still lags

The most recent entry in the updates list is dated 2024.08.02 and covers version 3.1.1: COCO to VOC conversion was added, syntax errors were fixed, pyproject.toml was added for modern packaging, and a __version__ was added to the package. The packaging migration is visible in the repository: there is a pyproject.toml alongside setup.py and setup.cfg, plus a MANIFEST.in and a PKG-INFO, and release helper scripts on both platforms in bumpversion.bat, upload_pypi.bat and upload_pypi.sh.

The build backend declaration is worth noting because it is not the modern default. The build-system section requires setuptools>=45 and wheel, and names setuptools.backends._legacy:_Backend as the backend, which keeps the legacy setup.py path working while the metadata moves to pyproject.toml.

Two pieces of metadata are out of step with reality. The requires-python field says >=3.6 and the classifiers run from 3.6 up to 3.10, which is a floor that predates several years of Python releases. And the licence is inconsistent: the licence field on the repository says GPL-3.0, while pyproject.toml declares license as Apache-2.0 and setup.py carries the Apache 2.0 licence header. For a package you intend to depend on, that discrepancy is the first thing to settle with the author, because the answer decides whether you can vendor it into a closed-source codebase.

The development extras are the usual set, pytest, pytest-cov, black, isort, flake8 and mypy, and there is a tests/ directory in the repository, along with a .gitignore and an examples/README.md.

When a maintained dataset library is the better answer

The alternative to alfred-py for the annotation half of the job is to depend directly on the library that owns the format. pycocotools is already an optional dependency of alfred itself for the COCO API, and for VOC, YOLO and KITTI there are format-specific readers that are maintained alongside the datasets themselves.

The difference in approach is ownership. A format library owns the format: it stays correct when the format changes, it is the reference implementation, and its maintainers care about the specification rather than about convenience helpers. alfred-py owns the convenience: it gives you a viewer for four formats, a converter between some of them, a split command, and drawing helpers, in one import.

The trade-off is that convenience libraries drift. When a dataset adds a field or changes a convention, the format library gets updated and the wrapper does not, and the wrapper then quietly does the wrong thing. That is a real risk for a package whose updates list shows the last change in August 2024, with the last push to the repository on 2026-08-02.

So the sensible split is to use alfred for the parts that are genuinely yours to write: visualisation helpers, the 3D keypoint and mesh tooling, the CLI conveniences and the logging wrapper. And to use the format libraries directly for anything where correctness against a specification matters, since alfred already depends on pycocotools for that reason.

Editorial conclusion

alfred-py suits a deep learning engineer who wants quick annotation viewers, format conversion and 2D and 3D visualisation without writing that glue for every project, and who is happy with a single-package dependency. It does not suit a team that wants a maintained dataset toolkit or a deploy pipeline, since it wraps rather than replaces them. Before you depend on it, check the licence discrepancy, because the repository is filed as GPL-3.0 while the package metadata declares Apache-2.0, and confirm your Python version is one the classifiers cover, since the metadata still claims support from 3.6.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. lucasjinreal/alfred on GitHub
4. README
5. Releases