Reading images. More...

Functions
roc_error	roc_read_image (const char file_name, roc_color_space color_space, roc_image image)
	Read an image from a file. More...

roc_error	roc_read_image_w (const wchar_t file_name, roc_color_space color_space, roc_image image)
	Read an image from a wide character file path. More...

roc_error	roc_read_exif (const char jpeg_file_name, roc_string exif)
	Returns `Exif` information of a JPEG file as a JSON object. More...

roc_error	roc_write_image (roc_image image, const char *file_name)
	Write an image to a file. More...

roc_error	roc_decode_image (const uint8_t input_byte_array, size_t len, roc_color_space color_space, roc_image image)
	Decode an image from a buffer. More...

roc_error	roc_encode_image (roc_image image, const char format, int quality, roc_buffer buffer, size_t *buffer_length)
	Encode an image to a buffer. More...

roc_error	roc_convert_nv21 (const uint8_t input_byte_array, size_t width, size_t height, roc_image image)
	Convert an NV21-formatted buffer to a roc_image. More...

roc_error	roc_redact_image (roc_image image, roc_detection detection, bool blur)
	Obfuscate a region in the image. More...

roc_error	roc_render_detection (roc_image image, const roc_detection detection, uint8_t r, uint8_t g, uint8_t b)
	Render a detection bounding box on an image. More...

roc_error	roc_resize_image (roc_image src, roc_image *dst, size_t width, size_t height)
	Resize an image. More...

roc_error	roc_read_ebts (const char file_path, int num_face_images, roc_string ebts, roc_image *images)
	Read in an EBTS transaction file. More...

Detailed Description

Reading images.

Decode a roc_image from a file with roc_read_image or from a buffer with roc_decode_image.

Function Documentation

◆ roc_read_image()

roc_error roc_read_image	(	const char *	file_name,
		roc_color_space	color_space,
		roc_image *	image
	)

Read an image from a file.

Free image after use with roc_free_image. If this function returns an error then roc_image::data will also be set to NULL. For wide character file paths use roc_read_image_w.

Supported Image Formats

Windows bitmaps - *.bmp, *.dib
JPEG files - *.jpeg, *.jpg, *.jpe
JPEG 2000 files - *.jp2
Portable Network Graphics - *.png
WebP - *.webp
Portable image format - *.pbm, *.pgm, *.ppm *.pxm, *.pnm
PFM files - *.pfm
Sun rasters - *.sr, *.ras
TIFF files - *.tiff, *.tif
OpenEXR Image files - *.exr
Radiance HDR - *.hdr, *.pic

Color Space Considerations

roc_represent operates natively on ROC_GRAY8 images, and will automatically convert provided ROC_BGR24 images. When you don't otherwise need color images, as a speed/memory optimization you may read an image file directly into grayscale to eliminate the color space conversion in roc_represent.

Note: A template constructed from an image opened with ROC_GRAY8 may not be binary-identical to a template constructed from the same image opened with ROC_BGR24; this difference will not impact system accuracy.

Orientation

A common unfortunate case is when an image file is originally saved with incorrect orientation information. For such an image rotated 90 degrees in either direction from vertical, or upside down, roc_represent will fail to find any faces in it. If you suspect this is the case with your image, use roc_rotate before roc_represent to try the same image at multiple possible orientations.

Example: roc_image image;
roc_read_image("lenna.jpeg", ROC_BGR24, &image);

Parameters

[in]	file_name	Path to the image file.
[in]	color_space	Desired color space, see Color Space Considerations.
[out]	image	Address to store the decoded image.

Remarks: This function is reentrant.

See also: roc_write_image roc_decode_image roc_read_image_w roc_read_exif

◆ roc_read_image_w()

roc_error roc_read_image_w	(	const wchar_t *	file_name,
		roc_color_space	color_space,
		roc_image *	image
	)

Read an image from a wide character file path.

See roc_read_image for details.

Parameters

[in]	file_name	Wide character path to the image file.
[in]	color_space	Desired color space, see Color Space Considerations.
[out]	image	Address to store the decoded image.

Remarks: This function is reentrant.

See also: roc_read_image

◆ roc_read_exif()

roc_error roc_read_exif	(	const char *	jpeg_file_name,
		roc_string *	exif
	)

Returns Exif information of a JPEG file as a JSON object.

Please see the easyexif header file for a definition of each key in exif.

Free string after use with roc_free_string, unless this function returns an error in which case exif will not be initialized.

Example: const char *jpeg_file_name = ...;
roc_string exif;
roc_read_exif(jpeg_file_name, &exif);

Parameters

[in]	jpeg_file_name	Path to JPEG file.
[out]	exif	Uninitialized string to contain Exif information as a JSON object.

◆ roc_write_image()

roc_error roc_write_image	(	roc_image	image,
		const char *	file_name
	)

Write an image to a file.

The extension of file_name is used to determine the encoding format, see Supported Image Formats for details.

Example: roc_image image = ...;
const char *file_name = ...;
roc_write_image(image, file_name);

Parameters

image	Image to write.
file_name	Path to the image to.

Remarks: This function is reentrant.

See also: roc_read_image

◆ roc_decode_image()

roc_error roc_decode_image	(	const uint8_t *	input_byte_array,
		size_t	len,
		roc_color_space	color_space,
		roc_image *	image
	)

Decode an image from a buffer.

Free image after use with roc_free_image. If this function returns an error then roc_image::data will also be set to NULL.

See roc_read_image for Supported Image Formats and Color Space Considerations.

Example: size_t len = ...;
const char *data = ...;
roc_image image;
roc_decode_image(len, data, ROC_GRAY8, &image);

Parameters

[in]	input_byte_array	Encoded image buffer.
[in]	len	Length of `input_byte_array`.
[in]	color_space	Desired color space, see Color Space Considerations.
[out]	image	Address to store the decoded image.

Remarks: This function is reentrant.

See also: roc_read_image roc_encode_image

◆ roc_encode_image()

roc_error roc_encode_image	(	roc_image	image,
		const char *	format,
		int	quality,
		roc_buffer *	buffer,
		size_t *	buffer_length
	)

Encode an image to a buffer.

Free buffer after use with roc_free_buffer.

Encoding Quality

For .jpg the valid range for quality is 0 to 100, where higher values are better quality, and the suggested default is 95. For .png the valid range for quality is 0 to 9, where higher values are more compressed, and the suggested default it 3. The quality parameter is ignored for all other formats.

Example: roc_image image = ...;
roc_buffer buffer;
size_t buffer_length;
roc_encode_image(image, ".jpg", 95, &buffer, &buffer_length);

Parameters

[in]	image	Image to encode.
[in]	format	File extension specifying the encoding format, see Supported Image Formats for details. The leading period character in the format is optional.
[in]	quality	Image encoding quality, see Encoding Quality.
[out]	buffer	Encoded image buffer.
[out]	buffer_length	Length of `buffer`.

Remarks: This function is reentrant.

See also: roc_write_image roc_decode_image

◆ roc_convert_nv21()

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

Convert an NV21-formatted buffer to a roc_image.

NV21 is the default format for the Android camera preview.

Parameters

[in]	input_byte_array	NV21 data buffer.
[in]	width	Image width.
[in]	height	Image height.
[out]	image	Output ROC_BGR24 image.

Remarks: This function is thread-safe.

◆ roc_redact_image()

roc_error roc_redact_image	(	roc_image	image,
		roc_detection	detection,
		bool	blur
	)

Obfuscate a region in the image.

This function will set pixels in the specified region of the image to black.

Parameters

[in,out]	image	Image to obfuscate.
[in]	detection	Detection to redact.
[in]	blur	If `true` a guassian blur will be applied instead of setting the pixels to black.

Remarks: This function is reentrant.

◆ roc_render_detection()

roc_error roc_render_detection	(	roc_image	image,
		const roc_detection	detection,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

Render a detection bounding box on an image.

This function will render the object/face detection on the provided image.

Parameters

[in]	image	Image to modify.
[in]	detection	Detection bounding box to display.
[in]	r	Bounding box color R channel (0-255).
[in]	g	Bounding box color G channel (0-255).
[in]	b	Bounding box color B channel (0-255).

Remarks: This function is reentrant.

◆ roc_resize_image()

roc_error roc_resize_image	(	roc_image	src,
		roc_image *	dst,
		size_t	width,
		size_t	height
	)

Resize an image.

Parameters

[in]	src	Input image.
[out]	dst	Output image.
[in]	width	Output image width.
[in]	height	Output image height.

Remarks: This function is reentrant.

◆ roc_read_ebts()

roc_error roc_read_ebts	(	const char *	file_path,
		int	num_face_images,
		roc_string *	ebts,
		roc_image *	images
	)

Read in an EBTS transaction file.

Reads in an EBTS v11.0 transaction file. Processes Type 2 and Type 10 records, and stores metadata information in a json string. Each Type 10 record has its image data returned in a buffer of roc_image.

EBTS JSON String

The returned EBTS data string is a Java Script Object Notation (JSON) object which may contain the following keys if found in the supplied EBTS transaction file:

Key	Definition
`FIRSTNAME`	Subject's first name.
`LASTNAME`	Subject's last name.
`DOB`	Subject's date of birth.
`GENDER`	Subject's gender.
`RACE`	Subject's race.
`AGE`	Subject's age.
`IMAGE`	Image Metadata JSON String for each Type 10 Record.

Image Metadata JSON String

The image metadata for each Type 10 record may contain the following keys:

Key	Definition
`PHOTO` CAPTURE DATE	Date photo was captured in yyyyMMdd format.
`POSE`	Image subject's pose.
`TYPE`	Image type.
`SMT` CLASSIFICATION	Scars, marks, tattoos image classification.

Example: const char *ebts_file_name = ...;
int num_face_images = 10;
roc_string ebts;
roc_image *images;
// pre-allocate image resources...
images = (roc_image*)malloc(num_face_images * sizeof(roc_image));
if (!images)
roc_ensure("Failed to allocate!");
roc_ensure(roc_read_ebts(ebts_file_name, num_face_images, &ebts, images));
// use ebts json string...
printf(ebts);
for (int index = 0; index < num_face_images; index++) {
if (!images[index].data)
break;
// use each image...
roc_ensure(roc_write_image(images[index], ...));
// free image resources...
roc_ensure(roc_free_image(images[index]));
}
// free pre-allocated resources...
free(images);
// free string resources...
roc_ensure(roc_free_string(&ebts));

Parameters

[in]	file_path	Path to the EBTS file.
[in]	num_face_images	The desired number of face images to return from the EBTS file in `images`. Faces found in the EBTS file after `num_face_images` will be ignored. If fewer than `num_face_images` are found, the remaining entries in `images` will have their roc_image::data pointer set to `NULL`.
[out]	ebts	Uninitialized roc_string to contain EBTS information as a JSON object. User is responsible for freeing this string after use with roc_free_string.
[out]	images	Pre-allocated array to hold roc_image.

Remarks: This function is reentrant.

Functions

Detailed Description

Function Documentation

◆ roc_read_image()

Supported Image Formats

Color Space Considerations

Orientation

◆ roc_read_image_w()

◆ roc_read_exif()

◆ roc_write_image()

◆ roc_decode_image()

◆ roc_encode_image()

Encoding Quality

◆ roc_convert_nv21()

◆ roc_redact_image()

◆ roc_render_detection()

◆ roc_resize_image()

◆ roc_read_ebts()

EBTS JSON String

Image Metadata JSON String