Image data structure and related functions. More...

Data Structures
struct	roc_image
	Common representation for still images and video frames. More...

struct	roc_roi
	Image region of interest to restrict processing. More...

Typedefs
typedef enum roc_color_space	roc_color_space
	Supported image formats.

typedef struct roc_image	roc_image
	Common representation for still images and video frames. More...

typedef struct roc_roi	roc_roi
	Image region of interest to restrict processing. More...

typedef const char *	roc_string
	Represents a string output value that should be freed with roc_free_string after use.

typedef const uint8_t *	roc_buffer
	Represents a buffer output value that should be freed with roc_free_buffer after use.

Enumerations
enum	roc_color_space { ROC_GRAY8, ROC_BGR24 }
	Supported image formats. More...

Functions
roc_roi	roc_roi_get (float x, float y, float width, float height)
	Construct a roc_roi. More...

bool	roc_roi_is_null (roc_roi roi)
	`true` if the area of `roi` is `0`. More...

bool	roc_roi_is_fractional (roc_roi roi)
	Fractional regions of interest are scaled by the image width and height. More...

bool	roc_roi_within (roc_roi test, roc_roi reference, size_t image_width, size_t image_height, float min_overlap)
	Determine if a rectangle is contained within a region of interest. More...

bool	roc_roi_within_set (roc_roi test, const roc_roi include, size_t num_include, const roc_roi exclude, size_t num_exclude, size_t image_width, size_t image_height, float min_overlap)
	Determine if a rectangle satisfies the sets of include and exclude regions of interest. More...

roc_error	roc_new_image (size_t width, size_t height, size_t step, roc_color_space color_space, roc_media_id media_id, roc_camera_id camera_id, roc_time timestamp, const uint8_t input_byte_array, roc_image image)
	Construct a new image. More...

roc_error	roc_copy_image (roc_image src, roc_image *dst)
	Deep copy an image. More...

roc_error	roc_rotate (roc_image *image, int degrees)
	Rotate an image clockwise in intervals of 90 degrees. More...

roc_error	roc_swap_channels (roc_image image)
	Swap red and blue channels to convert between RGB and BGR color spaces. More...

roc_error	roc_bgr2gray (roc_image src, roc_image *dst)
	Convert a color image to grayscale. More...

roc_error	roc_gray2bgr (roc_image src, roc_image *dst)
	Expand a grayscale image to color. More...

roc_error	roc_to_rgba (roc_image src, uint8_t *output_byte_array)
	Copy a roc_image to a pre-allocated `ARGB_8888` buffer. More...

roc_error	roc_from_rgba (const uint8_t input_byte_array, size_t width, size_t height, size_t step, roc_image image)
	Initialize a roc_image from an `ARGB_8888` buffer. More...

roc_error	roc_from_bgra (const uint8_t input_byte_array, size_t width, size_t height, size_t step, roc_image image)
	Initialize a roc_image from a `BGRA_8888` buffer. More...

roc_error	roc_from_yuv (const uint8_t y_in, const uint8_t u_in, const uint8_t v_in, size_t y_row_stride, size_t uv_row_stride, size_t uv_pixel_stride, size_t width, size_t height, roc_image image)
	Initialize a roc_image from a `YUV_420_888` buffer. More...

roc_error	roc_enhance_contrast (const roc_image src, float clip_limit, int num_tiles, roc_image *dst)
	Image contrast enhancement. More...

roc_error	roc_read_ppm (const char file_name, roc_image image)
	Read a PPM or PGM image file. More...

roc_error	roc_write_ppm (const char *file_name, roc_image image)
	Write a PPM or PGM image file. More...

roc_error	roc_free_image (roc_image image)
	Frees the memory previously allocated for a roc_image. More...

roc_error	roc_set_string (const char src, roc_string dst)
	Set a string value. More...

roc_error	roc_free_string (roc_string *str)
	Free a roc_string previously returned by another function. More...

roc_error	roc_free_buffer (roc_buffer *buffer)
	Free a roc_buffer previously returned by another function. More...

Detailed Description

Image data structure and related functions.

Copy an image with roc_copy_image, rotate an image with roc_rotate, and free an image with roc_free_image.

Data Structure Documentation

◆ roc_image

struct roc_image

Common representation for still images and video frames.

Images can be read with roc_read_image or roc_read_frame, and freed with roc_free_image.

Pixels are stored in row-major order. In other words, pixel layout with respect to decreasing memory spatial locality is channel, column, row. Thus pixel intensity can be retrieved as follows:

uint8_t get_intensity(roc_image image,
                      size_t channel,
                      size_t column,
                      size_t row)
{
    const size_t channels = (image.color_space == ROC_BGR24 ? 3 : 1);
    const size_t index = row*image.step + column*channels + channel;
    return image.data[index];
}

Coordinate (0, 0) corresponds to the top-left corner of the image. Coordinate (width-1, height-1) corresponds to the bottom-right corner of the image.

OpenCV Mat Conversion

Conversion from/to an OpenCV Mat is as follows:

// cv::Mat to roc_image
cv::Mat mat = ...
roc_image image;
image.width = mat.cols();
image.height = mat.rows();
image.step = mat.step;
image.color_space = (mat.channels() == 3 ? ROC_BGR24 : ROC_GRAY8);
image.data = mat.data(); // This is a shallow copy of the data buffer, `mat`
                         // must remain valid as long as `image` is in use.
                         // No need to free `image` separately.
// roc_image to cv::Mat
roc_image image = ...
cv::Mat mat(image.height, image.width,
            image.color_space == ROC_BGR24 ? CV_8UC3 : CV_8UC1, image.data);
// The above is a shallow copy of the data buffer, `image` must remain valid
// as long as `mat` is in use.
// To make a deep copy instead:
mat = mat.clone();

Data Fields
uint8_t *	data	Buffer of pixel intensities.
size_t	width	Column count in pixels.
size_t	height	Row count in pixels.
size_t	step	Bytes per row, including padding.
roc_color_space	color_space	Interpretation of roc_image::data.
roc_media_id	media_id	See roc_media_id.
roc_camera_id	camera_id	See roc_camera_id.
roc_time	timestamp	Timestamp associated with the image, if applicable.

◆ roc_roi

struct roc_roi

Image region of interest to restrict processing.

Regions of interest (ROIs) can be specified as either absolute pixel values or as fractions of the image size. roc_roi_is_fractional determines which convention is used.

Data Fields
float	x	Region of interest horizontal offset (top-left corner).
float	y	Region of interest vertical offset (top-left corner).
float	width	Region of interest width.
float	height	Region of interest height.

Typedef Documentation

◆ roc_image

typedef struct roc_image roc_image

Common representation for still images and video frames.

Images can be read with roc_read_image or roc_read_frame, and freed with roc_free_image.

Pixels are stored in row-major order. In other words, pixel layout with respect to decreasing memory spatial locality is channel, column, row. Thus pixel intensity can be retrieved as follows:

uint8_t get_intensity(roc_image image,
                      size_t channel,
                      size_t column,
                      size_t row)
{
    const size_t channels = (image.color_space == ROC_BGR24 ? 3 : 1);
    const size_t index = row*image.step + column*channels + channel;
    return image.data[index];
}

Coordinate (0, 0) corresponds to the top-left corner of the image. Coordinate (width-1, height-1) corresponds to the bottom-right corner of the image.

OpenCV Mat Conversion

Conversion from/to an OpenCV Mat is as follows:

// cv::Mat to roc_image
cv::Mat mat = ...
roc_image image;
image.width = mat.cols();
image.height = mat.rows();
image.step = mat.step;
image.color_space = (mat.channels() == 3 ? ROC_BGR24 : ROC_GRAY8);
image.data = mat.data(); // This is a shallow copy of the data buffer, `mat`
                         // must remain valid as long as `image` is in use.
                         // No need to free `image` separately.
// roc_image to cv::Mat
roc_image image = ...
cv::Mat mat(image.height, image.width,
            image.color_space == ROC_BGR24 ? CV_8UC3 : CV_8UC1, image.data);
// The above is a shallow copy of the data buffer, `image` must remain valid
// as long as `mat` is in use.
// To make a deep copy instead:
mat = mat.clone();

◆ roc_roi

typedef struct roc_roi roc_roi

Image region of interest to restrict processing.

Regions of interest (ROIs) can be specified as either absolute pixel values or as fractions of the image size. roc_roi_is_fractional determines which convention is used.

Enumeration Type Documentation

◆ roc_color_space

enum roc_color_space

Supported image formats.

Enumerator
ROC_GRAY8	1-channel grayscale, 8-bit depth.
ROC_BGR24	3-channel color (BGR order), 8-bit depth.

Function Documentation

◆ roc_roi_get()

roc_roi roc_roi_get	(	float	x,
		float	y,
		float	width,
		float	height
	)

Construct a roc_roi.

Parameters

[in]	x	roc_roi::x.
[in]	y	roc_roi::y.
[in]	width	roc_roi::width.
[in]	height	roc_roi::height.

Remarks: This function is thread-safe.

◆ roc_roi_is_null()

bool roc_roi_is_null ( roc_roi roi )

true if the area of roi is 0.

Parameters

[in] roi ROI to check for NULL.

Remarks: This function is thread-safe.

See also: roc_roi_is_fractional

◆ roc_roi_is_fractional()

bool roc_roi_is_fractional ( roc_roi roi )

Fractional regions of interest are scaled by the image width and height.

A roc_roi is considered fractional if roc_roi::width and roc_roi::height are greater than zero but less than or equal to one. In this case roc_roi::x and roc_roi::width are implicitly scaled by roc_image::width, and roc_roi::y and roc_roi::height are implicitly scaled by roc_image::height.

Parameters

[in] roi ROI to check for fractional size.

Remarks: This function is thread-safe.

See also: roc_roi_is_null

◆ roc_roi_within()

bool roc_roi_within	(	roc_roi	test,
		roc_roi	reference,
		size_t	image_width,
		size_t	image_height,
		float	min_overlap
	)

Determine if a rectangle is contained within a region of interest.

Parameters

[in]	test	Test region of interest.
[in]	reference	Reference region of interest.
[in]	image_width	To be used if `reference` or `test` is roc_roi_is_fractional.
[in]	image_height	To be used if `reference` or `test` is roc_roi_is_fractional.
[in]	min_overlap	Fractional area of `test` that must be contained within `reference`.

Remarks: This function is thread-safe.

See also: roc_roi_within_set

◆ roc_roi_within_set()

bool roc_roi_within_set	(	roc_roi	test,
		const roc_roi *	include,
		size_t	num_include,
		const roc_roi *	exclude,
		size_t	num_exclude,
		size_t	image_width,
		size_t	image_height,
		float	min_overlap
	)

Determine if a rectangle satisfies the sets of include and exclude regions of interest.

Parameters

[in]	test	Test region of interest.
[in]	include	Regions for which `test` must be contained within at least one, or `NULL`.
[in]	num_include	Length of `include`.
[in]	exclude	Regions for which `test` must not be contained within any, or `NULL`.
[in]	num_exclude	Length of `exclude`.
[in]	image_width	To be used if any roc_roi is roc_roi_is_fractional.
[in]	image_height	To be used if any roc_roi is roc_roi_is_fractional.
[in]	min_overlap	Fractional area of `test` that must be contained within `reference`.

Remarks: This function is thread-safe.

See also: roc_roi_within

◆ roc_new_image()

roc_error roc_new_image	(	size_t	width,
		size_t	height,
		size_t	step,
		roc_color_space	color_space,
		roc_media_id	media_id,
		roc_camera_id	camera_id,
		roc_time	timestamp,
		const uint8_t *	input_byte_array,
		roc_image *	image
	)

Construct a new image.

This function initializes a roc_image with the provided parameters and allocates memory for roc_image::data. If the provided input_byte_array is NULL, this function leaves the allocated buffer uninitialized, otherwise it initializes the allocated data buffer by copying input_byte_array.

Free image after use with roc_free_image.

Parameters

[in]	width	See roc_image::width.
[in]	height	See roc_image::height.
[in]	step	See roc_image::step.
[in]	color_space	See roc_image::color_space.
[in]	media_id	See roc_image::media_id.
[in]	camera_id	See roc_image::camera_id.
[in]	timestamp	See roc_image::timestamp.
[in]	input_byte_array	See roc_image::data.
[out]	image	Output image.

Remarks: This function is reentrant.

◆ roc_copy_image()

roc_error roc_copy_image	(	roc_image	src,
		roc_image *	dst
	)

Deep copy an image.

Example: roc_image src = ...;
roc_image dst;
roc_copy_image(src, &dst);

Parameters

[in]	src	Image to copy to `dst`.
[out]	dst	Uninitialized output to hold a copy of `src`.

Remarks: This function is reentrant.

◆ roc_rotate()

roc_error roc_rotate	(	roc_image *	image,
		int	degrees
	)

Rotate an image clockwise in intervals of 90 degrees.

image is rotated in-place. degrees must be evenly divisible by 90. A negative value indicates a counter-clockwise rotation.

Example: roc_image image = ...;
roc_rotate(&image, 90);

Parameters

[in,out]	image	Image to rotate.
[in]	degrees	Degrees to rotate `image` clockwise.

Remarks: This function is reentrant.

◆ roc_swap_channels()

roc_error roc_swap_channels ( roc_image image )

Swap red and blue channels to convert between RGB and BGR color spaces.

Parameters

[in,out] image Image to swap channels in-place.

Remarks: This function is thread-safe.

◆ roc_bgr2gray()

roc_error roc_bgr2gray	(	roc_image	src,
		roc_image *	dst
	)

Convert a color image to grayscale.

Converts an image from ROC_BGR24 to ROC_GRAY8. Free dst after use with roc_free_image.

Example: roc_image src = ...;
roc_image dst;
roc_bgr2gray(src, &dst);

Parameters

[in]	src	Input color image.
[out]	dst	Output grayscale image.

Remarks: This function is reentrant.

◆ roc_gray2bgr()

roc_error roc_gray2bgr	(	roc_image	src,
		roc_image *	dst
	)

Expand a grayscale image to color.

Converts an image from ROC_GRAY8 to ROC_BGR24. The grayscale channel is copied int the red, green and blue channels of dst. Free dst after use with roc_free_image.

Example: roc_image src = ...;
roc_image dst;
roc_gray2bgr(src, &dst);

Parameters

[in]	src	Input grayscale image.
[out]	dst	Output color image.

Remarks: This function is reentrant.

◆ roc_to_rgba()

roc_error roc_to_rgba	(	roc_image	src,
		uint8_t *	output_byte_array
	)

Copy a roc_image to a pre-allocated ARGB_8888 buffer.

ARGB_8888 is the common format for the Android Bitmap class. Despite the name, the true byte order is RGBA.

Parameters

[in]	src	Input image to copy of type ROC_BGR24.
[out]	output_byte_array	Output pre-allocated `ARGB_8888` data buffer of length `4` * roc_image::width * roc_image::height bytes.

Remarks: This function is reentrant.

See also: roc_from_rgba

◆ roc_from_rgba()

roc_error roc_from_rgba	(	const uint8_t *	input_byte_array,
		size_t	width,
		size_t	height,
		size_t	step,
		roc_image *	image
	)

Initialize a roc_image from an ARGB_8888 buffer.

Free image after use with roc_free_image.

Example: const uint8_t *input_byte_array = ...
size_t width = ...
size_t height = ...
size_t step = ...
roc_image image;
roc_from_rgba(input_byte_array, width, height, step, &image);

Parameters

[in]	input_byte_array	`ARGB_8888` buffer.
[in]	width	Width of the `input_byte_array` image.
[in]	height	Height of the `input_byte_array` image.
[in]	step	Step of the `input_byte_array` image.
[out]	image	Uninitialized output image to construct.

Remarks: This function is reentrant.

See also: roc_to_rgba roc_from_yuv roc_from_bgra

◆ roc_from_bgra()

roc_error roc_from_bgra	(	const uint8_t *	input_byte_array,
		size_t	width,
		size_t	height,
		size_t	step,
		roc_image *	image
	)

Initialize a roc_image from a BGRA_8888 buffer.

Free image after use with roc_free_image.

Example: const uint8_t *input_byte_array = ...
size_t width = ...
size_t height = ...
size_t step = ...
roc_image image;
roc_from_rgba(input_byte_array, width, height, step, &image);

Parameters

[in]	input_byte_array	`BGRA_8888` buffer.
[in]	width	Width of the `input_byte_array` image.
[in]	height	Height of the `input_byte_array` image.
[in]	step	Step of the `input_byte_array` image.
[out]	image	Uninitialized output image to construct.

Remarks: This function is reentrant.

See also: roc_from_rgba

◆ roc_from_yuv()

roc_error roc_from_yuv	(	const uint8_t *	y_in,
		const uint8_t *	u_in,
		const uint8_t *	v_in,
		size_t	y_row_stride,
		size_t	uv_row_stride,
		size_t	uv_pixel_stride,
		size_t	width,
		size_t	height,
		roc_image *	image
	)

Initialize a roc_image from a YUV_420_888 buffer.

YUV_420_888 is the common raw camera format for the Android Image class.

Free image after use with roc_free_image.

Parameters

[in]	y_in	Y channel buffer.
[in]	u_in	U channel buffer.
[in]	v_in	V channel buffer.
[in]	y_row_stride	Y channel row stride.
[in]	uv_row_stride	U and V channel row stride.
[in]	uv_pixel_stride	U and V channel pixel stride.
[in]	width	Image width.
[in]	height	Image height.
[out]	image	Uninitialized output image to construct.

Remarks: This function is reentrant.

See also: roc_from_rgba

◆ roc_enhance_contrast()

roc_error roc_enhance_contrast	(	const roc_image	src,
		float	clip_limit,
		int	num_tiles,
		roc_image *	dst
	)

Image contrast enhancement.

This function can be used to pre-process a low-contrast image to reduce missed detections.

Free dst after use with roc_free_image.

Example: roc_image src = ...;
roc_image dst;
roc_enhance_contrast(src, 2.f, 8, &dst);

Parameters

[in]	src	Input low-contrast image.
[in]	clip_limit	Adaptive histogram equalization contrast limit. For more information please reference Contrast Limited AHE.
[in]	num_tiles	Partition the image into this many horizontal and vertical tiles.
[out]	dst	Uninitialized output contrast-enhanced image.

See also: ROC_ENHANCE_CONTRAST

Remarks: This function is reentrant.

◆ roc_read_ppm()

roc_error roc_read_ppm	(	const char *	file_name,
		roc_image *	image
	)

Read a PPM or PGM image file.

Free image after use with roc_free_image.

Example: roc_image image;
roc_embedded_read_ppm("lenna.ppm", &image);

Parameters

[in]	file_name	Path to the image file.
[out]	image	Address to store the decoded image.

Remarks: This function is reentrant.

See also: roc_read_image

◆ roc_write_ppm()

roc_error roc_write_ppm	(	const char *	file_name,
		roc_image	image
	)

Write a PPM or PGM image file.

Note: The magic number will be chosen based on the image roc_image::roc_color_space value.

Example: roc_image image = ...;
roc_embedded_write_ppm("lenna.ppm", image);

Parameters

[in]	file_name	Path to the image file.
[in]	image	Image to write.

Remarks: This function is reentrant.

See also: roc_write_image

◆ roc_free_image()

roc_error roc_free_image ( roc_image image )

Frees the memory previously allocated for a roc_image.

Parameters

[in] image Image to free.

Remarks: This function is reentrant.

◆ roc_set_string()

roc_error roc_set_string	(	const char *	src,
		roc_string *	dst
	)

Set a string value.

Note: str must be initialized, if it already has a value call roc_free_string first.

Example: roc_string str = ...;
roc_set_string("Hello World!", &str);

Parameters

[in]	src	roc_string to copy.
[out]	dst	roc_string to set.

Remarks: This function is reentrant.

◆ roc_free_string()

roc_error roc_free_string ( roc_string * str )

Free a roc_string previously returned by another function.

If str is NULL, this function does nothing.

Example: roc_string str = ...;
roc_free_string(&str);

Parameters

[in,out] str roc_string to free.

Remarks: This function is reentrant.

◆ roc_free_buffer()

roc_error roc_free_buffer ( roc_buffer * buffer )

Free a roc_buffer previously returned by another function.

If buffer is NULL, this function does nothing.

Example: roc_buffer buffer = ...;
roc_free_buffer(&buffer);

Parameters

[in,out] buffer roc_buffer to free.

Remarks: This function is reentrant.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ roc_image

OpenCV Mat Conversion

◆ roc_roi

Typedef Documentation

◆ roc_image

OpenCV Mat Conversion

◆ roc_roi

Enumeration Type Documentation

◆ roc_color_space

Function Documentation

◆ roc_roi_get()

◆ roc_roi_is_null()

◆ roc_roi_is_fractional()

◆ roc_roi_within()

◆ roc_roi_within_set()

◆ roc_new_image()

◆ roc_copy_image()

◆ roc_rotate()

◆ roc_swap_channels()

◆ roc_bgr2gray()

◆ roc_gray2bgr()

◆ roc_to_rgba()

◆ roc_from_rgba()

◆ roc_from_bgra()

◆ roc_from_yuv()

◆ roc_enhance_contrast()

◆ roc_read_ppm()

◆ roc_write_ppm()

◆ roc_free_image()

◆ roc_set_string()

◆ roc_free_string()

◆ roc_free_buffer()