Image: pixel buffer, size, stride, format and ownership. More...

#include <SimdView.hpp>

Public Types
enum	Format { None = 0 , Gray8 , Uv16 , Bgr24 , Bgra32 , Int16 , Int32 , Int64 , Float , Double , BayerGrbg , BayerGbrg , BayerRggb , BayerBggr , Hsv24 , Hsl24 , Rgb24 , Rgba32 , Uyvy16 , Argb32 , Lab24 }

enum	Position { TopLeft , TopCenter , TopRight , MiddleLeft , MiddleCenter , MiddleRight , BottomLeft , BottomCenter , BottomRight }

typedef A< uint8_t >	Allocator

Public Member Functions
	View ()

	View (const View &view)

	View (View &&view) noexcept

	View (const cv::Mat &mat)

	View (size_t w, size_t h, ptrdiff_t s, Format f, void *d)

	View (size_t w, size_t h, Format f, void *d=NULL, size_t align=Allocator::Alignment())

	View (const Point< ptrdiff_t > &size, Format f)

	~View ()

	operator cv::Mat () const

void	ToTFTensor (tensorflow::Tensor &tensor, float shift=0, float scale=1) const

void	ToTFTensor (tensorflow::Tensor &tensor, int batchIndex, float shift=0, float scale=0) const

View *	Clone () const

View *	Clone (const Rectangle< ptrdiff_t > &rect) const

View *	Clone (View &buffer) const

View	Copy () const

View	Copy (const Rectangle< ptrdiff_t > &rect) const

View &	operator= (const View &view)

View &	operator= (View &&view)

View &	operator= (const cv::Mat &mat)

View &	Ref ()

void	Recreate (size_t w, size_t h, Format f, void *d=NULL, size_t align=Allocator::Alignment())

void	Recreate (const Point< ptrdiff_t > &size, Format f)

View	Region (ptrdiff_t left, ptrdiff_t top, ptrdiff_t right, ptrdiff_t bottom) const

View	Region (const Point< ptrdiff_t > &topLeft, const Point< ptrdiff_t > &bottomRight) const

View	Region (const Rectangle< ptrdiff_t > &rect) const

View	Region (const Point< ptrdiff_t > &size, Position position) const

View	Flipped () const

Point< ptrdiff_t >	Size () const

size_t	DataSize () const

size_t	Area () const

template<class T >
const T &	At (size_t x, size_t y) const

template<class T >
T &	At (size_t x, size_t y)

template<class T >
const T &	At (const Point< ptrdiff_t > &p) const

template<class T >
T &	At (const Point< ptrdiff_t > &p)

template<class T >
const T *	Row (size_t row) const

template<class T >
T *	Row (size_t row)

size_t	PixelSize () const

size_t	ChannelSize () const

size_t	ChannelCount () const

void	Swap (View &other)

bool	Load (const std::string &path, Format format=None)

bool	Load (const uint8_t *src, size_t size, Format format=None)

bool	Save (const std::string &path, SimdImageFileType type=SimdImageFileUndefined, int quality=100) const

void	Clear ()

uint8_t *	Release (size_t *size=NULL)

bool	Owner () const

void	Capture (bool copy=true)

Static Public Member Functions
static size_t	PixelSize (Format format)

static size_t	ChannelSize (Format format)

static size_t	ChannelCount (Format format)

static int	ToOcv (Format format)

static Format	OcvTo (int type)

Data Fields
const size_t	width
	Width in pixels. A region can be narrower than its parent.

const size_t	height
	Height in pixels. A region can be shorter than its parent.

const ptrdiff_t	stride
	Bytes from one row to the next, including alignment padding. Flipped() makes this negative.

const Format	format
	Pixel format. None is an empty view.

uint8_t *const	data
	Pointer to the first row. Flipped() points it at the last row of the parent buffer.

Detailed Description

template<template< class > class A>
struct Simd::View< A >

Image: pixel buffer, size, stride, format and ownership.

View is the C++ image used by the library. The template argument A is the allocator template of an owned buffer. In-tree code uses Simd::Allocator. TestCheckCpp, ContourDetector, Font, Motion, ShiftDetector and the examples in Simd::Point and Simd::Pyramid all write typedef Simd::View<Simd::Allocator> View. Simd::Frame stores one view in each plane. Simd::Pyramid stores one Gray8 view at each level. The wrappers in SimdLib.hpp pass data, stride, width, height and format through to the C API.

width and height are the size in pixels. stride is the step in bytes from one row to the next. An owned row is aligned, so stride can be larger than width * PixelSize(). data points at the first row. These fields are const. Recreate, Load, Clear, Release, Swap and the assignment operators replace them. Pixels are written through data, At and Row. TestViewVector stores moved views in std::vector<View> and then writes views[i].data[i].

A view either owns its buffer or references another buffer. The destructor, Clear and Recreate free the buffer only when Owner() is true. Owning views come from the allocating constructors, Recreate, Load, Copy, Clone and Capture. Referencing views come from the copy constructor, copy assignment, Region, Flipped, an external pointer and, with SIMD_OPENCV_ENABLE, from cv::Mat. A referencing view stays valid while that buffer stays alive.

The copy constructor and the copy assignment share the pixel buffer and leave the destination non-owning. TestCheckCpp does View sv; sv = vs; and View cp = sv. Copy assignment over a view that already owns its buffer frees that buffer and then executes assert(0). A build that defines NDEBUG omits the assert, and the view still becomes a reference of the assigned image. Replace an owning view with Recreate, Simd::Copy, Swap or move assignment. Move construction and move assignment transfer ownership and leave the source empty. TestViewMove does b = std::move(a). TestViewVector push_back of a temporary view relies on the move, so the vector owns the buffer. The move operations require SIMD_CPP_2011_ENABLE.

Copy() and Clone() duplicate pixels. Copy() returns an owning view by value. Clone() returns a heap view that the caller deletes. Capture() turns a referencing view into an owner. TestCheckCpp calls cp.Capture() after copying sv, so cp keeps its own pixels. ImageLoader::Release calls Release() and returns the decoded buffer from SimdImageLoadFromFile. The caller frees that pointer with SimdFree.

Region returns a referencing view of the half-open rectangle [left, right) x [top, bottom), clipped to the image. The sub-view keeps the parent stride and format. ShiftDetector estimates motion from background.Region(region). Simd::CopyFrame copies the four bands around an interior rectangle with Region. ContourDetector::Detect runs on src.Region(_roi). Font::Draw measures the text and draws into canvas.Region(Measure(text), position). A function that takes View& cannot bind a temporary, so the destination is passed through Ref(). Simd::Copy and Simd::Fill in CopyFrame, AlphaBlending into bkg.Region(rect).Ref(), and ImageMatcher wrapping a hash buffer as View(main, main, main, View::Gray8, hash->main).Ref() all do this.

Flipped() returns a referencing view whose stride is the negation of this stride and whose data points at the last row. Row 0 of that view is the last row of this view. Frame::Flipped assigns planes[i] = planes[i].Flipped().

At<T> and Row<T> address pixels. T is the pixel type of the format: uint8_t for Gray8 (detection masks and the shift test), Simd::Pixel::Bgr24 and Simd::Pixel::Bgra32 for color images (the transform and font tests), and float for View::Float (TestSynet). The coordinates must lie inside the view.

EqualSize compares width and height. Compatible also compares format. Simd::Convert requires equal sizes and accepts different formats. TestCheckCpp converts a 6x6 Bgra32 view into a 6x6 Gray8 view. Simd::Copy and the other same-format wrappers require Compatible images and accept different strides.

Format has the same numeric values as SimdPixelFormatType. Gray8 is the format of pyramids, shift detection, contours and forest.jpg loaded as Gray8. Bgr24 and Bgra32 are the formats of OpenCV frames and of drawing. Uv16 is the interleaved chroma plane of an Nv12 frame.

Load and Save wrap SimdImageLoadFromFile, SimdImageLoadFromMemory and SimdImageSaveToFile. The contour and shift-detector examples load forest.jpg as Gray8 and save result.pgm. TestImageIO also decodes a file image from memory.

With SIMD_OPENCV_ENABLE a view and a cv::Mat share one buffer. The cv::Mat constructor reads cols, rows, step[0] and OcvTo(type). operator cv::Mat builds a header over this buffer. CV_8UC3 becomes Bgr24, which is OpenCV's channel order. TestAnyToAny passes views to cv::cvtColor through that conversion. TestCheckCpp assigns a view from a cv::Mat and a cv::Mat from a view.

Using example:

#include "Simd/SimdLib.hpp"
 
int main()
{
    typedef Simd::View<Simd::Allocator> View;
    typedef Simd::Rectangle<ptrdiff_t> Rect;
 
    View image;
    if (!image.Load("../../data/image/forest.jpg", View::Gray8))
        return 1;
 
    View canvas(image.Size(), View::Gray8);
    Simd::Copy(image, canvas);
 
    Rect window(80, 40, 240, 200);
    View crop = canvas.Region(window);
    View patch = crop.Copy();
 
    Simd::Fill(canvas.Region(window).Ref(), 0);
    Simd::Copy(patch, canvas.Region(window).Ref());
 
    uint8_t value = canvas.At<uint8_t>(window.left, window.top);
    canvas.Save("result.pgm");
    return value;
}

OpenCV conversion (define SIMD_OPENCV_ENABLE before including this header):

#include "opencv2/core/core.hpp"
#define SIMD_OPENCV_ENABLE
#include "Simd/SimdView.hpp"
 
int main()
{
    typedef Simd::View<Simd::Allocator> View;
 
    View view(40, 30, View::Bgr24);
    cv::Mat mat(80, 60, CV_8UC3);
 
    View fromMat = mat;
    cv::Mat fromView = view;
    return (int)fromMat.width + fromView.cols;
}

Related Functions.

Member Typedef Documentation

◆ Allocator

typedef A<uint8_t> Allocator

Allocator of an owned buffer. In-tree code passes Simd::Allocator. Alignment() is the default row alignment.

Member Enumeration Documentation

◆ Format

enum Format

Describes pixel format of an image view.

The enumerators have the same values as SimdPixelFormatType. Load, Save and the C wrappers cast Format to that type. PixelSize, ChannelSize and ChannelCount describe the memory layout of each enumerator. Simd::Pixel holds the channel layout of Bgr24, Bgra32, Hsv24, Hsl24, Rgb24 and Rgba32.

Enumerator
None	Empty view and the failure format of Load. PixelSize is 0.
Gray8	One 8-bit channel. PixelSize is 1. Pyramid levels, ShiftDetector, ContourDetector, motion masks and forest.jpg loaded as Gray8 use Gray8.
Uv16	Two 8-bit channels, interleaved UV. PixelSize is 2. Frame::Nv12 stores this plane at half resolution.
Bgr24	Three 8-bit channels in B, G, R order. PixelSize is 3. OpenCV frames, drawing and Motion annotation use Bgr24.
Bgra32	Four 8-bit channels in B, G, R, A order. PixelSize is 4. The font example draws on a Bgra32 canvas.
Int16	One signed 16-bit channel. PixelSize is 2. Simd::Int16ToGray reads this format.
Int32	One signed 32-bit channel. PixelSize is 4.
Int64	One signed 64-bit channel. PixelSize is 8. ToOcv has no OpenCV type for Int64.
Float	One 32-bit floating-point channel. PixelSize is 4. TestSynet addresses rows with Row<float>. Synet tests recreate float views with an explicit alignment.
Double	One 64-bit floating-point channel. PixelSize is 8.
BayerGrbg	8-bit Bayer mosaic, 2x2 tile G R / B G. PixelSize is 1.
BayerGbrg	8-bit Bayer mosaic, 2x2 tile G B / R G. PixelSize is 1.
BayerRggb	8-bit Bayer mosaic, 2x2 tile R G / G B. PixelSize is 1.
BayerBggr	8-bit Bayer mosaic, 2x2 tile B G / G R. PixelSize is 1.
Hsv24	Three 8-bit channels in H, S, V order. PixelSize is 3. Simd::BgrToHsv writes this format.
Hsl24	Three 8-bit channels in H, S, L order. PixelSize is 3. Simd::BgrToHsl writes this format.
Rgb24	Three 8-bit channels in R, G, B order. PixelSize is 3.
Rgba32	Four 8-bit channels in R, G, B, A order. PixelSize is 4.
Uyvy16	Packed UYVY422. PixelSize is 2: every four bytes store two pixels as U0, Y0, V0, Y1. Simd::Yuv420pToUyvy422 writes this format.
Argb32	Four 8-bit channels in A, R, G, B order. PixelSize is 4. Simd::AlphaPremultiply treats Argb32 as premultiplied alpha at the first channel.
Lab24	Three 8-bit channels in CIELAB order. PixelSize is 3. Simd::BgrToLab writes this format.

◆ Position

enum Position

Names the place where Region(size, position) puts a window.

The window has the requested size and is then clipped to the image. Font::Draw(canvas, text, position, color) measures the text and uses this placement.

Enumerator
TopLeft	Window origin at (0, 0).
TopCenter	Window centered horizontally and placed at the top.
TopRight	Window placed at the top-right.
MiddleLeft	Window centered vertically and placed at the left.
MiddleCenter	Window centered horizontally and vertically.
MiddleRight	Window centered vertically and placed at the right.
BottomLeft	Window placed at the bottom-left.
BottomCenter	Window centered horizontally and placed at the bottom.
BottomRight	Window placed at the bottom-right.

Constructor & Destructor Documentation

◆ View() [1/7]

SIMD_INLINE View

Creates an empty view.

Width, height and stride are 0, format is None, data is NULL and the view owns nothing. ImageMatcher starts from an empty view and then assigns a Gray8 source or calls Recreate. A failed Load and Clear leave this same state.

◆ View() [2/7]

View ( const View< A > & view )

Creates a view that references another view.

The new view copies width, height, stride, format and data and leaves Owner() false. The source keeps ownership. Destroying the source frees the buffer while this view still points at it. TestCheckCpp uses View cp = sv and then Capture() to obtain an independent buffer. Duplicate pixels with Copy() or Clone().

Parameters

[in] view - an original image view.

◆ View() [3/7]

View ( View< A > && view )

noexcept

Moves a view.

Ownership, geometry and the pixel pointer are transferred with Swap. After the call, view is empty. TestViewMove and std::vector<View>::push_back of a temporary view in TestViewVector use this constructor. Frame can move a temporary view into planes[0].

Parameters

[in] view - a view whose buffer is transferred.

◆ View() [4/7]

SIMD_INLINE View ( const cv::Mat & mat )

Creates a view that references an OpenCV matrix.

Width is mat.cols, height is mat.rows, stride is mat.step[0] and data is mat.data. The format is OcvTo(mat.type()), or None when mat.data is empty. The view does not own the buffer. CV_8UC3 becomes Bgr24. TestCheckCpp assigns sv = cm for a cv::Mat cm.

Note: You have to define SIMD_OPENCV_ENABLE in order to use this functionality.

Parameters

[in] mat - an OpenCV matrix.

◆ View() [5/7]

SIMD_INLINE View	(	size_t	w,
		size_t	h,
		ptrdiff_t	s,
		Format	f,
		void *	d
	)

Creates a view with an explicit stride.

The pointer d is stored as given. This is the constructor used to wrap an external buffer whose row step is already known. ImageMatcher hashes into View(main, main, main, View::Gray8, hash->main). Region and Flipped build their results with this constructor.

When d is NULL and width, height, stride and format are all non-zero, the view allocates height * stride bytes with Allocator::Alignment() and becomes the owner. That allocation uses a positive stride. The stride value itself is not aligned. A zero dimension or format None leaves the view without a buffer.

Parameters

[in]	w	- width in pixels.
[in]	h	- height in pixels.
[in]	s	- stride in bytes. May be larger than the row payload, and is negative for a view produced by Flipped().
[in]	f	- pixel format.
[in]	d	- external pixel buffer. NULL allocates an owned buffer when the geometry is non-empty.

◆ View() [6/7]

SIMD_INLINE View	(	size_t	w,
		size_t	h,
		Format	f,
		void *	d = `NULL`,
		size_t	align = `Allocator::Alignment()`
	)

Creates a view and aligns its rows.

Calls Recreate(w, h, f, d, align). The stride is Allocator::Align(width * PixelSize(f), align). View image(320, 240, View::Gray8) and the 128x96 Bgr24 source in TestImageResize use this constructor with a NULL buffer, so the view owns the pixels. A non-NULL d is aligned upward and is not owned. The bytes before the aligned address and a full height * stride block must fit in the caller buffer.

Parameters

[in]	w	- width in pixels.
[in]	h	- height in pixels.
[in]	f	- pixel format.
[in]	d	- external pixel buffer. NULL allocates an owned buffer. The default is NULL.
[in]	align	- row and pointer alignment in bytes. The default is Allocator::Alignment().

◆ View() [7/7]

SIMD_INLINE View	(	const Point< ptrdiff_t > &	size,
		Format	f
	)

Creates an owned view of the given size and format.

Calls Recreate(size.x, size.y, f) with the default alignment. size.x is the width and size.y is the height. The pyramid example allocates View dst(image.Size(), View::Gray8) this way. The buffer is uninitialized.

Parameters

[in]	size	- width in `x` and height in `y`.
[in]	f	- pixel format.

◆ ~View()

SIMD_INLINE ~View

Destroys the view.

Frees data with Allocator::Free when Owner() is true. A referencing view does not free the buffer.

Member Function Documentation

◆ operator cv::Mat()

SIMD_INLINE operator cv::Mat

Creates an OpenCV header that references this image.

The matrix is cv::Mat(height, width, ToOcv(format), data, stride). It does not own the buffer. TestAnyToAny passes (cv::Mat)src and (cv::Mat)(dst.Ref()) to cv::cvtColor. TestCheckCpp assigns cm = sv.

Note: You have to define SIMD_OPENCV_ENABLE in order to use this functionality.

Returns: an OpenCV matrix header over this buffer.

◆ ToTFTensor() [1/2]

SIMD_INLINE void ToTFTensor	(	tensorflow::Tensor &	tensor,
		float	shift = `0`,
		float	scale = `1`
	)		const

Writes this image into a rank-3 float tensor.

The tensor is indexed (row, col, channel). Bgr24 writes three channels. Bgra32 writes blue, green and red and skips alpha. Gray8 writes one channel, reading the first byte of each row for every column. The stored value is (sample + shift) * scale. Any other format leaves the tensor unchanged. The view buffer is not shared with the tensor.

Note: You have to define SIMD_TENSORFLOW_ENABLE in order to use this functionality.

Parameters

[out]	tensor	- destination tensor of rank 3.
[in]	shift	- value added to each sample. The default is 0.
[in]	scale	- value multiplied after the shift. The default is 1.

◆ ToTFTensor() [2/2]

SIMD_INLINE void ToTFTensor	(	tensorflow::Tensor &	tensor,
		int	batchIndex,
		float	shift = `0`,
		float	scale = `0`
	)		const

Writes this image into one batch of a rank-4 float tensor.

The tensor is indexed (batchIndex, row, col, channel). The channel layout is the same as for the rank-3 overload. The default scale of this overload is 0.

Note: You have to define SIMD_TENSORFLOW_ENABLE in order to use this functionality.

Parameters

[out]	tensor	- destination tensor of rank 4.
[in]	batchIndex	- batch coordinate written by this call.
[in]	shift	- value added to each sample. The default is 0.
[in]	scale	- value multiplied after the shift. The default is 0.

◆ Clone() [1/3]

SIMD_INLINE View< A > * Clone

Duplicates this image on the heap.

Allocates an owned view of the same width, height and format and copies width * PixelSize() bytes of each row. Row padding is not copied. The caller deletes the returned view.

Returns: a heap view that owns the copied pixels.

◆ Clone() [2/3]

SIMD_INLINE View< A > * Clone ( const Rectangle< ptrdiff_t > & rect ) const

Duplicates a rectangular region on the heap.

Equivalent to Region(rect).Clone(). The rectangle is half-open and clipped by Region.

Parameters

[in] rect - a rectangle which bounds the region.

Returns: a heap view that owns the copied region.

◆ Clone() [3/3]

SIMD_INLINE View< A > * Clone ( View< A > & buffer ) const

Copies this image into buffer and returns a view of that storage.

When buffer is narrower or shorter than this view, buffer.Recreate(width, height, format) replaces it. The returned view is a non-owning header over buffer.data with the aligned stride of this width, which can differ from buffer.stride. Each row of width * PixelSize() bytes is copied into that header. The caller deletes the view object. The pixels remain in buffer.

Parameters

[in,out] buffer - storage for the copy. Recreated when it is too small.

Returns: a heap view that references buffer.

◆ Copy() [1/2]

SIMD_INLINE View< A > Copy

Duplicates this image by value.

Allocates an owned view and copies width * PixelSize() bytes of each row. Row padding is not copied. With SIMD_CPP_2011_ENABLE the returned view can be moved, so the caller keeps the owned buffer. The example above stores a crop with View patch = crop.Copy().

Returns: an owning view with a copy of the pixels.

◆ Copy() [2/2]

SIMD_INLINE View< A > Copy ( const Rectangle< ptrdiff_t > & rect ) const

Duplicates a rectangular region by value.

Equivalent to Region(rect).Copy().

Parameters

[in] rect - a rectangle which bounds the region.

Returns: an owning view with a copy of the region.

◆ operator=() [1/3]

View & operator= ( const View< A > & view )

Makes this view reference another view.

Self-assignment does nothing. Otherwise, when this view owns its buffer, that buffer is freed and assert(0) is executed. A build that defines NDEBUG omits the assert. In either build the destination then copies width, height, stride, format and data and becomes non-owning. TestCheckCpp assigns into a default-constructed view: View sv; sv = vs;. To replace the pixels of an owning view, use Recreate, Simd::Copy, Swap or move assignment.

Parameters

[in] view - an original image view.

Returns: a reference to itself.

◆ operator=() [2/3]

View & operator= ( View< A > && view )

Moves another view into this view.

Swap exchanges both views, including ownership, and then Clear empties the source. An owned buffer previously held by this view is freed. TestViewMove replaces b with std::move(a).

Parameters

[in] view - a view whose buffer is transferred.

Returns: a reference to itself.

◆ operator=() [3/3]

SIMD_INLINE View< A > & operator= ( const cv::Mat & mat )

Makes this view reference an OpenCV matrix.

Equivalent to assigning View(mat). The same ownership rule as copy assignment applies: assigning over an owning view frees its buffer and executes assert(0).

Note: You have to define SIMD_OPENCV_ENABLE in order to use this functionality.

Parameters

[in] mat - an OpenCV matrix.

Returns: a reference to itself.

◆ Ref()

SIMD_INLINE View< A > & Ref

Returns this view so a temporary can bind to View&.

Region, Flipped and a constructor expression are temporaries. Simd::Copy, Simd::Fill, Simd::AlphaBlending and the other output arguments take View&, so the temporary is passed through Ref(). CopyFrame copies each outer band with dst.Region(...).Ref(). TestShift blends into bkg.Region(rect).Ref(). Font::Draw draws into canvas.Region(Measure(text), position).Ref().

#include "Simd/SimdLib.hpp"
 
int main()
{
    typedef Simd::View<Simd::Allocator> View;
    View a(100, 100, View::Gray8);
    View b(100, 100, View::Gray8);
    Simd::Copy(a.Region(20, 20, 80, 80), b.Region(20, 20, 80, 80).Ref());
    return 0;
}

Returns: a reference to itself.

◆ Recreate() [1/2]

SIMD_INLINE void Recreate	(	size_t	w,
		size_t	h,
		Format	f,
		void *	d = `NULL`,
		size_t	align = `Allocator::Alignment()`
	)

Replaces the geometry and the buffer of this view.

An owned buffer is freed first. The stride becomes Allocator::Align(width * PixelSize(f), align). A non-NULL d is aligned upward and is not owned. A NULL d with non-zero height and stride allocates height * stride bytes and the view becomes the owner. The new pixels are uninitialized. Pyramid::Recreate allocates each level with Recreate(size, Gray8). ImageMatcher recreates a Gray8 view before Simd::Convert. Synet tests place a float row in Recreate(count, 1, View::Float, NULL, align).

Parameters

[in]	w	- width in pixels.
[in]	h	- height in pixels.
[in]	f	- pixel format.
[in]	d	- external pixel buffer. NULL allocates an owned buffer. The default is NULL.
[in]	align	- row and pointer alignment in bytes. The default is Allocator::Alignment().

◆ Recreate() [2/2]

SIMD_INLINE void Recreate	(	const Point< ptrdiff_t > &	size,
		Format	f
	)

Replaces this view with an owned image of the given size and format.

Calls Recreate(size.x, size.y, f).

Parameters

[in]	size	- width in `x` and height in `y`.
[in]	f	- pixel format.

◆ Region() [1/4]

SIMD_INLINE View< A > Region	(	ptrdiff_t	left,
		ptrdiff_t	top,
		ptrdiff_t	right,
		ptrdiff_t	bottom
	)		const

Returns a referencing sub-view of a half-open rectangle.

The rectangle is [left, right) x [top, bottom). When data is NULL, or right < left, or bottom < top, the result is an empty view. Otherwise each side is clamped to the image, and the result has width right - left, height bottom - top, the parent stride and format, and data + top * stride + left * PixelSize(). A rectangle that only partly overlaps the image is reduced to the overlap. The result does not own the pixels.

ShiftDetector passes background.Region(region). CopyFrame splits the image into the bands outside an interior rectangle. ContourDetector restricts metrics to src.Region(_roi). An output region is bound with Ref().

Parameters

[in]	left	- left side of the region.
[in]	top	- top side of the region.
[in]	right	- right side of the region. The pixel column `right` is outside the region.
[in]	bottom	- bottom side of the region. The pixel row `bottom` is outside the region.

Returns: a referencing view of the clipped region.

◆ Region() [2/4]

SIMD_INLINE View< A > Region	(	const Point< ptrdiff_t > &	topLeft,
		const Point< ptrdiff_t > &	bottomRight
	)		const

Returns a referencing sub-view between two corners.

Calls Region(topLeft.x, topLeft.y, bottomRight.x, bottomRight.y).

Parameters

[in]	topLeft	- top-left corner of the region.
[in]	bottomRight	- bottom-right corner of the region. This corner is outside the region.

Returns: a referencing view of the clipped region.

◆ Region() [3/4]

SIMD_INLINE View< A > Region ( const Rectangle< ptrdiff_t > & rect ) const

Returns a referencing sub-view of a rectangle.

Calls Region(rect.Left(), rect.Top(), rect.Right(), rect.Bottom()). The rectangle uses the same half-open range as Simd::Rectangle. Region(Rectangle<ptrdiff_t>(view.Size())) is the full image. ShiftDetector shifts the rectangle before taking the region: background.Region(region.Shifted(shift)).

Parameters

[in] rect - a rectangle which bounds the region.

Returns: a referencing view of the clipped region.

◆ Region() [4/4]

SIMD_INLINE View< A > Region	(	const Point< ptrdiff_t > &	size,
		Position	position
	)		const

Returns a referencing window placed at a named position.

The window size is size. The position selects one of the nine placements: the horizontal origin is 0, width - size.x, or (width - size.x) / 2, and the vertical origin is 0, height - size.y, or (height - size.y) / 2. A centered span runs from (side - size) / 2 to (side + size) / 2. The resulting rectangle is clipped by Region(left, top, right, bottom), so a window larger than the image is reduced to the image. Font::Draw uses this overload.

Parameters

[in]	size	- width in `x` and height in `y` of the window.
[in]	position	- placement of the window. See Simd::View::Position.

Returns: a referencing view of the clipped window.

◆ Flipped()

SIMD_INLINE View< A > Flipped

Returns a referencing view of this image turned upside down.

For a view with at least one row, the result has the same width, height and format, stride -stride, and data data + (height - 1) * stride. Row y of the result is row height - 1 - y of this view. The result does not own the pixels. Frame::Flipped stores planes[i].Flipped() and toggles Frame::flipped. DataSize() of a flipped view is not the allocation size, because the stride is negative.

Returns: a referencing view with a negative stride.

◆ Size()

SIMD_INLINE Point< ptrdiff_t > Size

Returns the image size as a point.

x is the width and y is the height. ContourDetector::Init and Pyramid take this size. Rectangle<ptrdiff_t>(view.Size()) is the full image, because that rectangle constructor treats the point as the bottom-right corner.

Returns: a point with image width and height.

◆ DataSize()

SIMD_INLINE size_t DataSize

Returns stride * height.

For an owned view created by Recreate or by an allocating constructor this is the number of allocated bytes, including row padding. A region reports the parent stride times the region height, which is larger than the region payload when the parent rows are padded. A flipped view has a negative stride, so this product is not the buffer size.

Returns: stride times height, as size_t.

◆ Area()

SIMD_INLINE size_t Area

Returns the number of pixels, width * height.

Returns: the area of this view in pixels.

◆ At() [1/4]

const T & At	(	size_t	x,
		size_t	y
	)		const

Returns a const pixel at integer coordinates.

The pixel is ((const T*)(data + y * stride))[x]. sizeof(T) is the pixel size: uint8_t for Gray8, Simd::Pixel::Bgr24 for Bgr24, float for Float, and so on. The function asserts x < width and y < height. Coordinates are not clamped.

Parameters

[in]	x	- x coordinate of the pixel.
[in]	y	- y coordinate of the pixel.

Returns: a const reference to the pixel.

◆ At() [2/4]

T & At	(	size_t	x,
		size_t	y
	)

Returns a pixel at integer coordinates.

The address is the same as for the const overload. The transform test assigns At<Simd::Pixel::Bgr24>(x, y) and At<Simd::Pixel::Bgra32>(x, y).

Parameters

[in]	x	- x coordinate of the pixel.
[in]	y	- y coordinate of the pixel.

Returns: a reference to the pixel.

◆ At() [3/4]

const T & At ( const Point< ptrdiff_t > & p ) const

Returns a const pixel at a point.

Calls At<T>(p.x, p.y). Motion reads a neighbour produced by current + Point(-1, 0) this way. A negative coordinate converts to a large size_t and fails the bounds assert.

Parameters

[in] p - coordinates of the pixel.

Returns: a const reference to the pixel.

◆ At() [4/4]

T & At ( const Point< ptrdiff_t > & p )

Returns a pixel at a point.

Calls At<T>(p.x, p.y).

Parameters

[in] p - coordinates of the pixel.

Returns: a reference to the pixel.

◆ Row() [1/2]

const T * Row ( size_t row ) const

Returns a const pointer to the first pixel of a row.

The pointer is (const T*)(data + row * stride). The function asserts row < height. The font test scans Row<uint8_t>. TestSynet takes Row<float> of a Float view. The transform test writes a Uv16 row through Row<uint8_t> at indexes 2 * x and 2 * x + 1. A negative stride walks upward, which is how a flipped view addresses its rows.

Parameters

[in] row - row index.

Returns: a const pointer to the first pixel of the row.

◆ Row() [2/2]

T * Row ( size_t row )

Returns a pointer to the first pixel of a row.

The address is the same as for the const overload.

Parameters

[in] row - row index.

Returns: a pointer to the first pixel of the row.

◆ PixelSize() [1/2]

SIMD_INLINE size_t PixelSize ( Format format )

static

Returns the pixel size in bytes of a format.

The sizes are: 0 for None; 1 for Gray8 and every Bayer format; 2 for Uv16, Int16 and Uyvy16; 3 for Bgr24, Hsv24, Hsl24, Rgb24 and Lab24; 4 for Bgra32, Int32, Float, Rgba32 and Argb32; 8 for Int64 and Double. An unknown format asserts and returns 0. Simd::Copy passes this size to SimdCopy. Font::Draw requires sizeof(color) to equal PixelSize().

Parameters

[in] format - a pixel format.

Returns: the pixel size in bytes.

◆ PixelSize() [2/2]

SIMD_INLINE size_t PixelSize

Returns the pixel size in bytes of this image.

Calls PixelSize(format).

Returns: the pixel size in bytes.

◆ ChannelSize() [1/2]

SIMD_INLINE size_t ChannelSize ( Format format )

static

Returns the channel size in bytes of a format.

The sizes are: 0 for None; 1 for every 8-bit format, including multi-channel 8-bit formats and both Bayer and UYVY; 2 for Int16; 4 for Int32 and Float; 8 for Int64 and Double. An unknown format asserts and returns 0.

Parameters

[in] format - a pixel format.

Returns: the channel size in bytes.

◆ ChannelSize() [2/2]

SIMD_INLINE size_t ChannelSize

Returns the channel size in bytes of this image.

Calls ChannelSize(format).

Returns: the channel size in bytes.

◆ ChannelCount() [1/2]

SIMD_INLINE size_t ChannelCount ( Format format )

static

Returns the number of channels in a format.

The counts are: 0 for None; 1 for Gray8, Int16, Int32, Int64, Float, Double and every Bayer format; 2 for Uv16 and Uyvy16; 3 for Bgr24, Hsv24, Hsl24, Rgb24 and Lab24; 4 for Bgra32, Rgba32 and Argb32. An unknown format asserts and returns 0. Simd::AlphaBlending passes ChannelCount() as the channel count of the color image.

Parameters

[in] format - a pixel format.

Returns: the number of channels.

◆ ChannelCount() [2/2]

SIMD_INLINE size_t ChannelCount

Returns the number of channels in this image.

Calls ChannelCount(format).

Returns: the number of channels.

◆ ToOcv()

SIMD_INLINE int ToOcv ( Format format )

static

Converts a pixel format to an OpenCV matrix type.

Gray8, None and every Bayer format return CV_8UC1. Uv16 and Uyvy16 return CV_8UC2. Bgr24, Hsv24, Hsl24, Rgb24 and Lab24 return CV_8UC3. Bgra32, Rgba32 and Argb32 return CV_8UC4. Int16 returns CV_16SC1, Int32 returns CV_32SC1, Float returns CV_32FC1 and Double returns CV_64FC1. Int64 is not mapped and asserts. The OpenCV type does not record BGR versus RGB or a Bayer pattern. operator cv::Mat uses this mapping.

Note: You have to define SIMD_OPENCV_ENABLE in order to use this functionality.

Parameters

[in] format - a pixel format.

Returns: an OpenCV matrix type.

◆ OcvTo()

SIMD_INLINE View< A >::Format OcvTo ( int type )

static

Converts an OpenCV matrix type to a pixel format.

CV_8UC1 returns Gray8, CV_8UC2 returns Uv16, CV_8UC3 returns Bgr24, CV_8UC4 returns Bgra32, CV_16SC1 returns Int16, CV_32SC1 returns Int32, CV_32FC1 returns Float and CV_64FC1 returns Double. Any other type asserts and returns None. A 3-channel OpenCV matrix therefore becomes Bgr24, including when the caller stored RGB, HSV or Lab bytes. The cv::Mat constructor uses this mapping.

Note: You have to define SIMD_OPENCV_ENABLE in order to use this functionality.

Parameters

[in] type - an OpenCV matrix type.

Returns: a pixel format.

◆ Swap()

SIMD_INLINE void Swap ( View< A > & other )

Exchanges this view with another view.

Width, height, stride, format, data and ownership are swapped. TestCheckCpp calls sv.Swap(vs). The move constructor and move assignment are implemented with Swap. Frame::Swap swaps every plane through this method.

Parameters

[in,out] other - the view to exchange with.

◆ Load() [1/2]

SIMD_INLINE bool Load	(	const std::string &	path,
		Format	format = `None`
	)

Decodes an image from a file into this view.

Clear() runs first, so a previous owned buffer is freed. The file type is detected from the file content. PGM, PPM, PNG, JPEG and BMP are recognized. PGM and PPM comments are not supported, and a PGM or PPM max value other than 255 is rejected. On input, format requests Gray8, Bgr24, Bgra32, Rgb24, Rgba32, or None. None keeps the natural format of the file. A color JPEG such as forest.jpg is Rgb24 unless Gray8 is requested. On success the view owns the decoded buffer and the method returns true. The contour and shift-detector examples load ../../data/image/forest.jpg as Gray8. TestYuvToAny loads a file as Bgr24. On failure the view is empty, format is None and the method returns false.

Parameters

[in]	path	- path to the image file.
[in]	format	- requested pixel format. The default is None.

Returns: true when the file was decoded.

◆ Load() [2/2]

SIMD_INLINE bool Load	(	const uint8_t *	src,
		size_t	size,
		Format	format = `None`
	)

Decodes an image from a memory buffer into this view.

The buffer is a file image, not raw pixels. Detection of the file type, the requested formats and the ownership of the result are the same as for Load(path). TestImageIO decodes two encoded buffers and compares the views.

Parameters

[in]	src	- pointer to the encoded file bytes.
[in]	size	- number of bytes in `src`.
[in]	format	- requested pixel format. The default is None.

Returns: true when the buffer was decoded.

◆ Save()

SIMD_INLINE bool Save	(	const std::string &	path,
		SimdImageFileType	type = `SimdImageFileUndefined`,
		int	quality = `100`
	)		const

Encodes this image and writes it to a file.

The view is not changed. type selects the encoder. SimdImageFileUndefined, the default, selects it from the path extension: .pgm, .ppm, .png, .jpg/.jpeg or .bmp. For a JPEG extension, quality 100 is written as quality 85. An unrecognized extension saves Gray8 as binary PGM and any other supported format as binary PPM. The detection and contour examples call Save("result.pgm"). TestDrawing saves draw_line.jpg and rectangles.pgm. TestResize saves a JPEG region with an explicit quality of 85.

Parameters

[in]	path	- path to the output file.
[in]	type	- file format, or SimdImageFileUndefined to infer it from `path`. The default is SimdImageFileUndefined.
[in]	quality	- compression quality for encoders that use it. The default is 100.

Returns: true when the file was written.

◆ Clear()

SIMD_INLINE void Clear

Releases an owned buffer and makes the view empty.

When Owner() is true the buffer is freed. Width, height and stride become 0, format becomes None, data becomes NULL and the view is not an owner. Load calls Clear before decoding. Move assignment calls Clear on the source after Swap.

◆ Release()

SIMD_INLINE uint8_t * Release ( size_t * size = NULL )

Detaches the pixel buffer and makes the view empty.

The buffer is not freed. When size is not NULL, *size receives DataSize() from before the fields are cleared. ImageLoader::Release reads the geometry and then calls Release() so SimdImageLoadFromFile can return the decoded pointer. That pointer was allocated by the Simd allocator and is freed with SimdFree. Release of a referencing view still detaches data; that external pointer is not an allocation to pass to SimdFree.

Parameters

[out] size - optional pointer that receives DataSize() of the detached buffer. May be NULL.

Returns: the detached pixel pointer.

◆ Owner()

SIMD_INLINE bool Owner

Reports whether the destructor will free the buffer.

The allocating constructors, Recreate with a NULL buffer, Load, Copy, Clone(), Capture and a moved-from owner return true. The copy constructor, copy assignment, Region, Flipped, an external pointer and a cv::Mat wrapper return false. Frame::Owner is true only when every used plane is an owner.

Returns: true when this view owns its buffer.

◆ Capture()

SIMD_INLINE void Capture ( bool copy = true )

Makes this view the owner of its pixels.

A view that is already an owner, or whose data is NULL, is left unchanged. Otherwise, when copy is true, the pixels are copied into a new owned buffer and the previous pointer is left with its original owner. TestCheckCpp does this after View cp = sv, and Frame::Capture does it for every plane. When copy is false, the view takes ownership of the current pointer without copying. That pointer must be one Allocator::Free can release.

Parameters

[in] copy - true copies the pixels into a new buffer. False adopts the current pointer. The default is true.

Simd Library Documentation.

Public Types

Public Member Functions

Static Public Member Functions

Data Fields

Detailed Description

Member Typedef Documentation

◆ Allocator

Member Enumeration Documentation

◆ Format

◆ Position

Constructor & Destructor Documentation

◆ View() [1/7]

◆ View() [2/7]

◆ View() [3/7]

◆ View() [4/7]

◆ View() [5/7]

◆ View() [6/7]

◆ View() [7/7]

◆ ~View()

Member Function Documentation

◆ operator cv::Mat()

◆ ToTFTensor() [1/2]

◆ ToTFTensor() [2/2]

◆ Clone() [1/3]

◆ Clone() [2/3]

◆ Clone() [3/3]

◆ Copy() [1/2]

◆ Copy() [2/2]

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ Ref()

◆ Recreate() [1/2]

◆ Recreate() [2/2]

◆ Region() [1/4]

◆ Region() [2/4]

◆ Region() [3/4]

◆ Region() [4/4]

◆ Flipped()

◆ Size()

◆ DataSize()

◆ Area()

◆ At() [1/4]

◆ At() [2/4]

◆ At() [3/4]

◆ At() [4/4]

◆ Row() [1/2]

◆ Row() [2/2]

◆ PixelSize() [1/2]

◆ PixelSize() [2/2]

◆ ChannelSize() [1/2]

◆ ChannelSize() [2/2]

◆ ChannelCount() [1/2]

◆ ChannelCount() [2/2]

◆ ToOcv()

◆ OcvTo()

◆ Swap()

◆ Load() [1/2]

◆ Load() [2/2]

◆ Save()

◆ Clear()

◆ Release()

◆ Owner()

◆ Capture()