Manager class for 2D pictures in memory. More...

#include <Frame.hpp>

Classes
struct	Area
	An area defining a region of a Frame. More...
class	Plane
	Access to pixel values in a plane. More...
class	RGBPlane
	Access to RGB colour pixel values of a Frame. More...
Public Types
typedef sal3d_frame_vpat	VPAT
	The Virtual Pixel Access Table.
Public Member Functions
	Frame (int width, int height, int dimension, int dataType=8)
	Constructor from size and type.
	Frame (const std::string &fileName)
	Creates a new frame from a file.
	Frame (void data, int width, int height, int dimension, int datatype, std::ptrdiff_t strideX, std::ptrdiff_t strideY, std::ptrdiff_t stridePlane, SAL3DFRAMEDELETER deleter, void userData=0, const int *planeOrder=0)
	Creates a frame from a user pointer.
	Frame (sal3d_frame frame)
	Constructor from a C sal3d_frame.
	Frame (const Frame &frame)
	Copy constructor.
	Frame (const Frame &frame, float ratio)
	Creates a new Frame frame by resizing another Frame.
	Frame (const Frame &frame, const Area &area)
	Creates a new Frame as a subframe of another one.
	~Frame ()
	Destructor.
sal3d_frame	c_frame () const
	Returns the C pointer to a sal3d_frame.
Frame	copy () const
	Create a deep copy of the Frame. This means that the object memory is duplicated. More information about this can be found at Memory management: reference counting.
int	dataType (int plane) const
	Gets the data type of a frame's plane. The data type of a plane is a bitfield composed of the following fields:
int	dimension () const
	Gets the number of planes of the frame.
int	height () const
	Gets the frame's height.
void	transpose ()
	Transpose the frame. This function interchanges the frame dimensions, so the width will become the height and vice versa.
Frame &	operator= (const Frame &rhs)
	Copy assignment operator.
void	saveToFile (const std::string &fileName) const
	Saves the frame to a file.
void	vpa (int plane, char *baseAddress, VPAT vpat) const
	Gets the base address and the virtual pixel access table.
int	width () const
	Gets the frame's width.
sal3d::Frame	scaleDepth (int datatype, double inputMin=0, double inputMax=0) const
	Create a new frame with the desired datatype by rescaling this one.
sal3d::Frame	scaleDepth (int datatype, double inputMin, double inputMax) const
	Create a new frame with the desired datatype by rescaling this one.
sal3d::Frame	scaleDepthToRange (int datatype, double outputMin, double outputMax, double inputMin=0, double inputMax=0) const
	Create a new frame with the desired datatype by rescaling this one.
sal3d::Frame	scaleDepthToRange (int datatype, double inputMin, double inputMax, double outputMin, double outputMax) const
	Create a new frame with the desired datatype by rescaling this one.
template<typename T >
const Plane< T >	plane (int p=0) const
	Gets a const Plane accessor to the Frame plane.
template<typename T >
Plane< T >	plane (int p=0)
	Gets a Plane accessor to the Frame plane.
template<typename T >
const Plane< T >::Row	row (int y, int plane=0) const
	Gets a const Plane::Row accessor to the Frame row.
template<typename T >
Plane< T >::Row	row (int y, int plane=0)
	Gets a Plane::Row accessor to the Frame row.
template<typename T >
const T &	pixel (int x, int y, int plane=0) const
	Gets a const pixel value reference for a Frame plane.
template<typename T >
T &	pixel (int x, int y, int plane=0)
	Gets a pixel value reference for a Frame plane.

Detailed Description

Manager class for 2D pictures in memory.

This class requires linking with acquire.lib (import library for acquire.dll).

Each Frame object contains the information for a 2D picture taken by a normal camera, usually from a FrameGrabber. It manages the memory region containing the pixels, and knows enough information on how that pixel information is distributed in that memory (width, height, bits per pixel, etc.).

Frame memory management

A Frame object, in general, can be created allocating memory according to given dimensions, can be loaded from a file, or can be used as a wrapper to a memory area containing pixel information (for example, when a FrameGrabber stores the pictures in reachable memory regions). In this latter case, the Frame can be given a destruction callback to let the FrameGrabber know the user will not access that picture anymore. In the former cases the Frame will allocate process memory for the storage of the pixel information, and will free it on the destruction of the last reference to that memory. Check the different Frame constructors for all the options.

The Frame C++ copy operator doesn't reallocate or copy the pixel information. Instead, it maintains reference control to that memory area, and calls the proper callback only when the last Frame referencing the memory is destroyed (see Memory management: reference counting).

Building a Frame from memory

Following is an example of how to build a Frame around a region of memory with the information of an image.

Let's imagine we have a framegrabber configured to acquire grayscale images of 300 per 200 pixels. Each pixel is 16 bits, and each row is aligned to 32 bytes. Let's also imagine that the framegrabber API provides a function to tell the device that the buffer is no longer needed, so the memory region can be used again for another capture.

Before going to the code, let us find the strideY, or pitch of the image (which in this case is not the same as the width due to the alignment).

300 x 2 (bytes per pixel) = 600

600 / 32 = 18.75

Then, the strideY would be 19 * 32 = 608, and the code would be as follows:

 void frameDeleter(void *data, void *user)
 {
     //the following function releases the buffer pointed by *user
     fg_API_release_buffer(user);
 }

 void createFrameFromBuffer(int numBuffer)
 {
     //we get the acquired data pointer from the frame grabber API
     void *data = fg_API_get_buffer_addr(numBuffer);

     sal3d::Frame frame(data,
                     300/*width*/,
                     200/*height*/,
                     1/*dimension: 1 for grayscale*/,
                     16/*datatype: 16 bits unsigned*/,
                     2/*strideX*/,
                     608/*strideY*/,
                     0/*stridePlane, not needed*/,
                     frameDeleter,
                     data);
 }

Accessing the pixel color information

The Frame class knows how the pixel information is stored in memory, and the user should access the pixel colors according to that. The parameters taken into account are the following:

Information encoded in each pixel plane (bits per color component, integer, signed/unsigned, float, ...)
Distribution of the 2D pixels in memory (width, height, strideX, strideY, number of planes)

The library provides easy accessors through C++ templates. The least efficient way is using the Frame::pixel() templated method, and the most efficient way goes through the Frame::Plane or Frame::RGBPlane templated objects.

Internal pixel memory coordinates

The Frame class provides an abstraction for locating each pixel in memory according to its spatial coordinates (horizontal and vertical positions) and color component (plane): Virtual Pixel Access. Each Frame has a VPA table associated with each plane, which allows finding the pointer to any pixel value with a simple addition. The memory can then be accessed according to the data type of the Frame, which can be get through the function dataType().

Following is an example that shows how to get a pixel value from the first component of an image with unsigned 16-bit data.

 // Load a Frame from a file, for example.
 sal3d::Frame f ("mypicture.png");

 char *baseAddr;
 sal3d::Frame::VPAT vpa;
 // Get the pixel data base address and the VPA table
 // for the plane 0 of our frame.
 f.vpa(0, &baseAddr, &vpa);

 // Pixel encoding for the plane 0
 int type = f.dataType(0);
 assert (SAL3D_DATA_TYPE_BPP(type) == 16 &&
         !SAL3D_DATA_TYPE_IS_SIGNED(type) &&
         !SAL3D_DATA_TYPE_IS_FLOAT(type))
 {
     // pixel value at coordinates x=3, y=10 of plane 0
     // (remember x=0, y=0 is the top, left corner)
     uint16_t value = *(reinterpret_cast<uint16_t *>(baseAddr +
                      vpa[3].x + vpa[10].y));
 }

Frames with 3D information

Some cameras encode special 3D information useful to the SAL3D library into the pictures they provide (for example, with the pixel color of additional rows or columns). The Frame objects do not store any specific information for such pictures.

A user which wants to take 3D information from a Frame (as described in Acquisition Overview) will probably have a special function provided by the camera manufacturer which, given a Frame, will directly provide a Profile. The user may also write his own functions for such purpose, implementing algorithms described in the camera operator manuals.

Constructor & Destructor Documentation

sal3d::Frame::Frame	(	int	width,
		int	height,
		int	dimension,
		int	dataType = `8`
	)		`[inline]`

Constructor from size and type.

Creates a new, unitialized frame of the desired size. Each of the specified planes has data of the specified dataType.

Parameters:

[in]	width	The new frame's width.
[in]	height	The new frame's height.
[in]	dimension	The number of planes to create. This value must be greater than 0.
[in]	dataType	The type of data the frame will contain. There are some helper macros in sal3d_def.h to ease the use of datatypes.

Exceptions:

sal3d::Error On error

References dataType().

Referenced by copy(), scaleDepth(), and scaleDepthToRange().

sal3d::Frame::Frame ( const std::string & fileName ) [inline, explicit]

Creates a new frame from a file.

Parameters:

[in] fileName The name of the file to load.

Exceptions:

sal3d::Error On error

sal3d::Frame::Frame	(	void *	data,
		int	width,
		int	height,
		int	dimension,
		int	datatype,
		std::ptrdiff_t	strideX,
		std::ptrdiff_t	strideY,
		std::ptrdiff_t	stridePlane,
		SAL3DFRAMEDELETER	deleter,
		void *	userData = `0`,
		const int *	planeOrder = `0`
	)		`[inline]`

Creates a frame from a user pointer.

Creates a new Frame object around a block of memory. The Frame object then gets the ownership of the block of memory. That means that you mustn't free this memory block by yourself. The Frame will call a deleter function when the memory is no longer needed (i.e., when the frame gets deleted.)

An example of how to use this constructor can be found in Building a Frame from memory.

Parameters:

[in]	data	Pointer to the data block where the image is stored.
[in]	width	The width of the Frame.
[in]	height	The height of the Frame.
[in]	dimension	The number of planes the Frame has.
[in]	datatype	The data type of each plane.
[in]	strideX	The distance in bytes between two horizontal pixels of the same plane. If for example you have a 8-bit monochrome frame, this value is normally 1. For RGB interleaved frames this value would be 3, whereas for a RGB planar frame again it would be 1.
[in]	strideY	The distance in bytes between two vertical pixels of the same plabe. Remember that sometimes the frame is aligned so this value does not necessarily be width().
[in]	stridePlane	The distance in bytes between two planes of the same frame. For RGB interleaved frames this should be 1, whereas for RGB planar frames this should be `height` * `strideY`.
[in]	deleter	Pointer to a callback function that will be called when the Frame object is deleted.
[in]	userData	Pointer that will be passed to the `deleter` callback.
[in]	planeOrder	An array in which you may specify a nonstandard ordering of the planes for the created frame. If it is NULL, then the standard ordering (0, 1, ..., n) will be used for n-planar frames. If an array is passed here, the array must have `dimension` values. This might be useful, for example, in cases where a source provides a BGR frame, instead of RGB. In this case you may simple change the plane order by passing the array (2, 1, 0) to this function.

Exceptions:

sal3d::Error On error

sal3d::Frame::Frame ( sal3d_frame frame ) [inline, explicit]

Constructor from a C sal3d_frame.

Creates a C++ Frame object that holds a C sal3d_frame. The new C++ Frame object will get the ownership of the C frame, so that means you should not call sal3d_frame_release() on this frame, otherwise it would be called twice for this frame.

Parameters:

[in] frame The C sal3d_frame to use to create this object.

sal3d::Frame::Frame ( const Frame & frame ) [inline]

Copy constructor.

Parameters:

[in] frame The frame to copy from.

sal3d::Frame::Frame	(	const Frame &	frame,
		float	ratio
	)		`[inline]`

Creates a new Frame frame by resizing another Frame.

This constructor creates a new Frame that is ratio times the size of the provided frame parameter. To achieve this, only the VPA table is recalculated for the new Frame and there is no memory copy involved. This means that the operation is very fast, but has the drawback that no interpolation is used, so the resulting image quality is not optimal.

Parameters:

[in]	frame	The source frame to copy from.
[in]	ratio	The increase ratio. A ratio bigger than 1.0f means a bigger frame will be created, and vice versa. If a ratio < 0.f is given, 1.f will be used instead.

Exceptions:

sal3d::Error On error

References c_frame().

sal3d::Frame::Frame	(	const Frame &	frame,
		const Area &	area
	)		`[inline]`

Creates a new Frame as a subframe of another one.

Creates a new frame which is actually a "map" of another frame's area, i.e., there is no memory copy involved, thus this is a fast operation.

It is mandatory that area's first point (x0, y0) be inside frame's boundaries, otherwise this function throws an error. If the second point (x1, y1) lies outside frame's boundaries, then it is clipped to fit inside.

Parameters:

frame	The frame to create the subframe from.
area	The chosen area to map to the new subframe.

Exceptions:

sal3d::Error On error

References c_frame(), sal3d::Frame::Area::x0, sal3d::Frame::Area::x1, sal3d::Frame::Area::y0, and sal3d::Frame::Area::y1.

Member Function Documentation

sal3d_frame sal3d::Frame::c_frame ( ) const [inline]

Returns the C pointer to a sal3d_frame.

Warning:: Never ever call sal3d_frame_relese() with the pointer returned by this function or the application will fail.

Returns:: The pointer to sal3d's C interface.

Referenced by sal3d::PeakFinderH::calibrate(), sal3d::LensDistortion::calibrateCubic(), sal3d::LensDistortion::calibrateDotsCubic(), sal3d::COP::COP(), Frame(), sal3d::COP::glPaintColourPoints(), sal3d::COP::glPaintColourPolygons(), sal3d::PeakFinder::operator()(), sal3d::PeakFinderH::operator()(), sal3d::RangeMap::RangeMap(), scaleDepth(), and scaleDepthToRange().

Frame sal3d::Frame::copy ( ) const [inline]

Create a deep copy of the Frame. This means that the object memory is duplicated. More information about this can be found at Memory management: reference counting.

This is specially useful, for example, with Frames built around memory owned by a frame grabber, since usually this memory is blocked to the frame grabber until the user releases it. It can also be useful if the user wants to release the frame grabber driver while keeping a captured picture in memory.

Returns:: A new frame, with the picture in user allocated memory.

Exceptions:

sal3d::Error On error

References Frame().

int sal3d::Frame::dataType ( int plane ) const [inline]

Gets the data type of a frame's plane. The data type of a plane is a bitfield composed of the following fields:

                 0 1 2 3 4 5 6 7 8 9 10 11  30 31
                +-+-+-+-+-+-+-+-+-+-+-+-+...+-+-+
                | bits/pixel    |S|F| Reserved  |
                +-+-+-+-+-+-+-+-+-+-+-+-+...+-+-+
               
                S = Signed
                F = Float (only valid for >= 32 bits/pixel)

To ease the construction and checking of data types, the macros SAL3D_SIGNED_DATA_TYPE(), SAL3D_FLOAT_DATA_TYPE(), SAL3D_DATA_TYPE_IS_SIGNED(), and SAL3D_DATA_TYPE_IS_FLOAT() are provided in the sal3d_def.h header.

Parameters:

[in] plane The plane to get the data type from. It must be in the range 0 to dimension() - 1.

Exceptions:

sal3d::Error On error

Returns:: The data type of plane.

Referenced by Frame().

int sal3d::Frame::dimension ( ) const [inline]

Gets the number of planes of the frame.

Returns:: The number of planes this frame has.

Exceptions:

sal3d::Error On error

int sal3d::Frame::height ( ) const [inline]

Gets the frame's height.

Returns:: This frame's height.

Exceptions:

sal3d::Error On error

Referenced by sal3d::Frame::Plane< T >::Plane(), and sal3d::PeakFinder::profileLength().

Frame& sal3d::Frame::operator= ( const Frame & rhs ) [inline]

Copy assignment operator.

Parameters:

[in] rhs The frame to copy to this object.

Returns:: A reference to this object.

Exceptions:

sal3d::Error On error

template<typename T >

const T& sal3d::Frame::pixel	(	int	x,
		int	y,
		int	plane = `0`
	)		const `[inline]`

Gets a const pixel value reference for a Frame plane.

Parameters:

x	The X coordinate of the pixel
y	The Y coordinate of the pixel
plane	The plane to get the pixel value from.

References plane(), and vpa().

Referenced by pixel().

template<typename T >

T& sal3d::Frame::pixel	(	int	x,
		int	y,
		int	plane = `0`
	)		`[inline]`

Gets a pixel value reference for a Frame plane.

Parameters:

x	The X coordinate of the pixel
y	The Y coordinate of the pixel
plane	The plane to get the pixel value from.

References pixel(), and plane().

template<typename T >

const Plane<T> sal3d::Frame::plane ( int p = 0 ) const [inline]

Gets a const Plane accessor to the Frame plane.

Parameters:

p	The number of the desired plane.

Referenced by pixel(), plane(), and row().

template<typename T >

Plane<T> sal3d::Frame::plane ( int p = 0 ) [inline]

Gets a Plane accessor to the Frame plane.

Parameters:

p	The number of the desired plane.

References plane().

template<typename T >

const Plane<T>::Row sal3d::Frame::row	(	int	y,
		int	plane = `0`
	)		const `[inline]`

Gets a const Plane::Row accessor to the Frame row.

Parameters:

plane	The plane to get the Plane::Row from.
y	The Y coordinate of the row

References plane(), and vpa().

Referenced by row().

template<typename T >

Plane<T>::Row sal3d::Frame::row	(	int	y,
		int	plane = `0`
	)		`[inline]`

Gets a Plane::Row accessor to the Frame row.

Parameters:

y	The Y coordinate of the row
plane	The plane to get the Plane::Row from.

References plane(), and row().

void sal3d::Frame::saveToFile ( const std::string & fileName ) const [inline]

Saves the frame to a file.

Parameters:

[in] fileName The name of the file to save the frame to.

Exceptions:

sal3d::Error On error

sal3d::Frame sal3d::Frame::scaleDepth	(	int	datatype,
		double *	inputMin = `0`,
		double *	inputMax = `0`
	)		const `[inline]`

Create a new frame with the desired datatype by rescaling this one.

A new sal3d::Frame is created by rescaling the whole range from this frame to the whole range in the output frame. Each pixel is computed following the formula: pixelOut = outputMin + (pixelIn - inputMin) * (outputMax - outputmin) / (inputMax - inputMin). Being outputMin/Max the minimum and maximum values that the specified destination datatype supports. If the inputMin/Max pointers are provided, the function fills them with the values used for the scaling.

Parameters:

[in]	datatype	The sal3d data type for the new Frame.
[out]	inputMin	Pointer to a double that will be filled with the lower limit found in this frame.
[out]	inputMax	Pointer to a double that will be filled with the higher limit found in this frame.

Returns:: The new frame with scaled data.

Exceptions:

sal3d::Error On error

References c_frame(), and Frame().

sal3d::Frame sal3d::Frame::scaleDepth	(	int	datatype,
		double	inputMin,
		double	inputMax
	)		const `[inline]`

Create a new frame with the desired datatype by rescaling this one.

A new sal3d::Frame is created by rescaling the desired range from this frame to the whole range in the output frame. Each pixel is computed following the formula: pixelOut = outputMin + (pixelIn - inputMin) * (outputMax - outputmin) / (inputMax - inputMin). Being outputMin/Max the minimum and maximum values that the specified destination datatype supports.

Parameters:

[in]	datatype	The sal3d data type for the new Frame.
[in]	inputMin	The lower limit of the input range which will be used to compute the scaling.
[in]	inputMax	The higher limit of the input range which will be used to compute the scaling.

Returns:: The new frame with scaled data.

Exceptions:

sal3d::Error On error

References c_frame(), and Frame().

sal3d::Frame sal3d::Frame::scaleDepthToRange	(	int	datatype,
		double	outputMin,
		double	outputMax,
		double *	inputMin = `0`,
		double *	inputMax = `0`
	)		const `[inline]`

Create a new frame with the desired datatype by rescaling this one.

A new sal3d::Frame is created by rescaling the whole range from this frame to the desired range in the output frame. Each pixel is computed following the formula: pixelOut = outputMin + (pixelIn - inputMin) * (outputMax - outputmin) / (inputMax - inputMin). If the inputMin/Max pointers are provided, the function fills them with the values used for the scaling.

Parameters:

[in]	datatype	The sal3d data type for the new Frame.
[in]	outputMin	The minimum value that the resulting frame will have.
[in]	outputMax	The maximum value that the resulting frame will have.
[out]	inputMin	Pointer to a double that will be filled with the lower limit found in this frame.
[out]	inputMax	Pointer to a double that will be filled with the higher limit found in this frame.

Returns:: The new frame with scaled data.

Exceptions:

sal3d::Error On error

References c_frame(), and Frame().

sal3d::Frame sal3d::Frame::scaleDepthToRange	(	int	datatype,
		double	inputMin,
		double	inputMax,
		double	outputMin,
		double	outputMax
	)		const `[inline]`

Create a new frame with the desired datatype by rescaling this one.

A new sal3d::Frame is created by rescaling the desired range from this frame to the desired range in the output frame. Each pixel is computed following the formula: pixelOut = outputMin + (pixelIn - inputMin) * (outputMax - outputmin) / (inputMax - inputMin).

Parameters:

[in]	datatype	The sal3d data type for the new Frame.
[in]	inputMin	The lower limit of the input range which will be used to compute the scaling.
[in]	inputMax	The higher limit of the input range which will be used to compute the scaling.
[in]	outputMin	The minimum value that the resulting frame will have.
[in]	outputMax	The maximum value that the resulting frame will have.

Returns:: The new frame with scaled data.

Exceptions:

sal3d::Error On error

References c_frame(), and Frame().

void sal3d::Frame::transpose ( ) [inline]

Transpose the frame. This function interchanges the frame dimensions, so the width will become the height and vice versa.

This function does not perform any operation on the pixel data memory, it only modifies the VPA table, so it should be fast.

Exceptions:

sal3d::Error On error

void sal3d::Frame::vpa	(	int	plane,
		char **	baseAddress,
		VPAT *	vpat
	)		const `[inline]`

Gets the base address and the virtual pixel access table.

The Frame's data can then be accessed as is explained in Accessing the pixel color information.

Parameters:

[in]	plane	The plane from which to get the base address and the virtual pixel access table from.
[out]	baseAddress	The address of a pointer that will store the address to the memory holding the pixel data.
[out]	vpat	The address of a VPAT to be filled.

Exceptions:

sal3d::Error On error

Referenced by pixel(), sal3d::Frame::Plane< T >::Plane(), sal3d::Frame::RGBPlane< T >::RGBPlane(), and row().

int sal3d::Frame::width ( ) const [inline]

Gets the frame's width.