Containers

The most important data structure in the Matrox Imaging Library (MIL) is the image buffer. Cameras grab into image buffers, processing functions manipulate image buffers, analysis functions make decisions based on the contents of image buffers. An image buffer is essentially a contiguous block of memory, and some metadata which describes the format of that data (mono8, RGB24, packed, planar, so on and so forth).

With the advent of relatively affordable 3D data acquisition devices, such as the Matrox AltiZ dual-head laser scanner, MIL was going to need greatly expanded 3D processing and analysis functionality. In its simplest form 3D data can be stored in a traditional image buffer, such as a depth map format wherein each pixel value encodes a Z coordinate and the X and Y coordinates are implied by the pixel’s position in the buffer. However, 3D devices often provide significantly more data, in many different formats, potentially requiring a combination of several buffers of different sizes and with different metadata.

Our new data structure was the container, effectively a collection of buffers grouped together with additional metadata.

When I was first assigned this topic, I was told it was a bear trap made of land-mines. Nominally it was fairly simple; a container is just a list of buffers. However, there were myriad details to consider regarding how containers would behave in situations such as:

Because the MIL ecosystem is very large, and every team needed slightly different things, MIL modules did not always use containers in a consistent way. Often, there simply was no codified answer; while MIL would always do something reasonable, nobody could say what behaviour was "correct".

This became a serious problem for the documentation. Skilled technical writers want to provide simple explanations that impart a clear mental model to the user. As the behaviour of containers became more complex and self-contradictory, that became commensurately more difficult. It was clear that we were going to have to get everybody "on the same page" so to speak.

This wasn’t just for our benefit either; MIL provides extremely strong API stability guarantees, so once the behaviour was released we would only change it if absolutely necessary. It was important for the whole product that we get container behavior right.

In collaboration with my editor, I compiled a list of statements about containers based on what we understood. These ranged from basic definitions, to function names, to recommended usage patterns, to expected behaviour in a whole range of situations. We called a meeting with all the stakeholders, including developers and technical management. I led a discussion that covered every single bullet point, editing them as we went along until the room was happy with the result.

This process allowed everybody to clearly express their needs and opinions, and immediately have it reflected as a set of clear and concise statements. Previously, discussions had happened in small groups, focused on one small part of the API at a time. By putting it all down in one place and forcing everybody to confront individual statements in the context of the whole, it became possible to make concrete decisions.

Intense discussions were had, the occasional emotion flew, but when we left that room we had created a single document which clearly expressed what containers were going to be and how they were going to work. There were no significant changes to the design after that point, and what we shipped looked very much like what was described in that document.