Core¶

Frame¶

A frame is one of the many images in an acquisition sequence. They are ordered by index. Frames are generated by the acquisition part of the hardware plugin, injected in the processing graph and recycled when the frame is not used (e.g. saved to file).

A frame is a lightweight object that represents a range of pixels. It can be associated to a memory resource that is reference counted with the frame so that memory is released when it’s not referenced by any frame object. The definition of Resource is broad enough to accommodate with the different usages, either owning the memory buffer for the pixels (Container) or mapping a memory zone allocated by a third party (View).

template <typename Metadata, typename... Views>
class frame
{
public:
    typedef ... const_view_t;
    typedef ... view_t;
    typedef std::ptrdiff_t x_coord_t;
    typedef std::ptrdiff_t y_coord_t;
    typedef point<std::ptrdiff_t> point_t;

    frame() = default;
    frame(frame const& other) = default;

    template <typename View>
    frame(View const& view)

    template <typename View, typename Resource>
    frame(View const& view, Resource resource)

    template <typename... OtherViews>
    frame(frame<Metadata, OtherViews...> const& other)

    frame& operator=(frame const& rhs);

    template <typename... OtherViews>
    frame& operator=(frame<Metadata, OtherViews...> const& rhs)

    std::size_t num_channels()  const;
    point_t     dimensions()    const;
    size_type   size()          const;
    x_coord_t   width()         const;
    y_coord_t   height()        const;
};

For consistency with Boost.GIL image concept, the view can be retrieved with

const const_view_t&   const_view(const Frame&);
const view_t&         view(Frame&);

Tracking the ownership of the resource associated with the frame is handled with a shared_ptr<void>. Internally type erasure is used so that the frame type is not parametrized with the resource. Let’s consider a couple of examples:

// GIL.Image as a resource
// construct a shared image
auto img = std::make_shared<gil::gray8_image_t>(dimensions);
// pass the shared image as frame resource
frame_t frm(gil::view(*img), img);

// RAW data as a resource
// construct an array of pixel
gil::gray8_pixel_t pixels[32 * 32];
// construct a view from the buffer and use the Deleter of the shared_ptr to manage memory
frame_t frm(
    gil::interleaved_view(32, 32, pixels, 32),
    std::shared_ptr<gil::gray8_pixel_t>(pixels, [](auto ptr) { /* do something with the ptr */  }));

// RAW data as a resource
// construct an array of pixel
gil::gray8_pixel_t pixels[32 * 32];
// construct a view from the buffer and use the Deleter of the shared_ptr to manage memory
frame_t frm(
    gil::interleaved_view(32, 32, pixels, 32),
    std::shared_ptr<gil::gray8_pixel_t>(pixels, [](auto ptr) { /* do something with the ptr */  }));

Metadata¶

Metadata are attached to a frame and can be augmented by the processing pipeline.

Typed Metadata¶

frame.metadata

Attributes¶

Attributes are basically annotations or text metadata.

frame.attributes