PAZ: one perception library with three levels of API

The pitch: perception without the model boilerplate

PAZ stands for Perception for Autonomous Systems and describes itself as a hierarchical perception library in Python. The scope is wide: the repository's own topic list covers emotion recognition, face recognition, instance segmentation, keypoint estimation, object detection, pose estimation and semantic segmentation, and the example gallery matches that, with directories for human pose estimation in 2D and 3D, hand pose estimation, head pose estimation, semantic segmentation, object detection, eigenfaces, prototypical networks and more. The value proposition is that these tasks usually each mean writing the same scaffolding: load an image, preprocess it, run a graph, post-process the outputs, draw boxes. PAZ packages that so a first prediction is a few lines, and the same library also holds the model definitions and layers for the cases where the default pipeline does not fit your data.

The high-level API is a pipeline object you call on an image

The top of the three API levels is what most users will touch. It is described as easy out-of-the-box prediction, and the pattern is that you instantiate a pipeline and hand it a NumPy array image. Here is the object detection example from the project overview.

from paz.applications import SSD512COCO

detect = SSD512COCO()

# apply directly to an image (numpy-array)
inferences = detect(image)

The inference result is returned as a structured object rather than raw tensors, and the overview notes that several such pipelines are already implemented, with the naming convention pointing at the model family and the training data. The application class name carries both, so you can see at a glance what you are loading. This is the layer where a robotics team can get a detector working, or a research team can get a baseline number, without touching a graph definition.

Mid-level and low-level APIs drop you into the model

Below the pipelines sit the mid-level and low-level APIs, and this is where the hierarchical idea earns its name. The mid-level layer is where you work with a model's structure: loading weights, changing the inputs the network expects, reusing a backbone, or swapping in a different head, while still taking advantage of the training and evaluation code that comes with the model. The low-level layer is the raw building blocks, the layers and modules you compose yourself. The practical reason to have all three is that a working pipeline is often the thing you want on day one and the thing you have to dismantle on day ten, when your camera input does not match the training distribution or your latency budget forbids the full network. PAZ lets you start at the top and move down without changing libraries.

Three dependencies, and one install command

PAZ has only three dependencies, according to the project: TensorFlow 2.0, OpenCV and NumPy. The setup file confirms the same three, listing opencv-python, tensorflow and numpy in install_requires, with the distribution published on PyPI under the name pypaz and the package metadata taken from the version attribute in the paz module itself. Installing it is a single command.

pip install pypaz --user

The package is classified for science and research use and for image recognition, and it ships with the MIT licence. Because TensorFlow is a dependency rather than an optional extra, installing PAZ brings the model framework with it, which is convenient for a fresh environment and a decision point in an existing one where a different TensorFlow version is already pinned.

Every model can be re-trained, and one example is not finished

The project states that all models can be re-trained with your own data, with a single exception: Mask-RCNN, which is being worked on in a separate branch, and the gallery links to that branch for the mask_rcnn example, marked as in-progress. The same pattern shows in the example directories, where some tasks have dedicated folders, such as action_scores, efficientdet, efficientpose, fine-tuning_object_detection, hand_detection, images_synthesis and structure_from_motion, while others appear only as gallery entries pointing into the tree. A separate branch for the unfinished work is a reasonable arrangement, but it does mean the master branch is not the whole project, and anyone evaluating the library's coverage should look at both.

The example gallery is the documentation of what works

The gallery in the project overview is unusual in a good way: it links to real-time demos and training scripts rather than to screenshots alone, so you can see a running system and the code that produced it. The set is broad. There is probabilistic 2D keypoints, 6D head-pose estimation, object detection, an emotion classifier, 2D keypoint estimation, semantic segmentation, hand pose estimation, 2D human pose estimation, 3D keypoint discovery, hand closure detection, 6D pose estimation through pix2pose, implicit orientation learning, spatial transformer networks as attention, a Haar cascade detector, eigenfaces, prototypical networks, 3D human pose estimation and MAML. The presence of MAML and prototypical networks, both few-shot learning methods, next to classical cascade detection tells you the library is not limited to one era of computer vision.

The release cadence is the weak point

Here is the fact that should shape an adoption decision. The tagged releases are paz 0.2.6 on 2025-02-03, paz 0.2.5 on 2023-07-13 and paz 0.2.4 on 2023-06-10, and there is a long gap between 0.2.4 and 0.2.5 followed by a much shorter one to 0.2.6. The last push to the repository was on 2026-10-12, so the working tree has seen a lot of work that no release reflects. A version of 0.2.x also signals an API that has not yet promised itself stability. None of this means the code is unmaintained in the sense of abandoned, but it does mean that pip install pypaz --user gives you something noticeably older than the repository, and that a project depending on PAZ should pin a version deliberately rather than track the branch.

Where PAZ is the wrong tool

Three boundaries make PAZ the wrong choice for a particular job. First, the TensorFlow 2.0 pin. The project names TensorFlow 2.0 as its model framework, and that is the version whose APIs have shifted the most, so a modern environment with a different TensorFlow installed will not simply work, and a team that standardised on another framework gains nothing from PAZ. Second, a production service that needs a support contract, a security process or a predictable release stream will find the release history thin, as described above. Third, a project that needs only one task well will probably get further with a focused, maintained implementation of that task than with a perception library that carries implementations of twenty. The value of PAZ is breadth and the ability to open the model up, and if you do not need either, the dependency is larger than the job.

Editorial conclusion

PAZ fits a research engineer who wants a working baseline for a perception task in minutes and the option to open the model up afterwards, since the same repository serves the one-line pipeline and the raw layers, and every model can be re-trained with your own data. It does not fit a production service that needs a maintained, current dependency, because the newest tagged release is paz 0.2.6 from 2025-02-03 while the last push to the repository was on 2026-10-12, so the tree moves faster than the releases, and because the library pins TensorFlow 2.0 as its model framework, which is the version whose APIs have moved on most. Before you build on it, read the mask_rcnn branch separately from the master examples, since the Mask-RCNN example is marked in-progress, check that pip install pypaz --user resolves against the TensorFlow version you already run, and plan to pin an exact paz version rather than tracking master.

Frequently asked questions

Official sources

1. License: MIT
2. oarriaga/paz on GitHub
3. Project website
4. README
5. Releases