#include "heif.h"

Include dependency graph for heif_regions.h:

Typedefs
typedef struct heif_region_item	heif_region_item
typedef struct heif_region	heif_region

Enumerations
enum	heif_region_type { heif_region_type_point = 0 , heif_region_type_rectangle = 1 , heif_region_type_ellipse = 2 , heif_region_type_polygon = 3 , heif_region_type_referenced_mask = 4 , heif_region_type_inline_mask = 5 , heif_region_type_polyline = 6 }
	Region type. More...

Functions
int	heif_image_handle_get_number_of_region_items (const heif_image_handle *image_handle)
	Get the number of region items that are attached to an image.
int	heif_image_handle_get_list_of_region_item_ids (const heif_image_handle image_handle, heif_item_id region_item_ids_array, int max_count)
	Get the region item identifiers for the region items attached to an image.
heif_error	heif_context_get_region_item (const heif_context context, heif_item_id region_item_id, heif_region_item *out)
	Get the region item.
heif_item_id	heif_region_item_get_id (heif_region_item *region_item)
	Get the item identifier for a region item.
void	heif_region_item_release (heif_region_item *region_item)
	Release a region item.
void	heif_region_item_get_reference_size (heif_region_item , uint32_t out_width, uint32_t *out_height)
	Get the reference size for a region item.
int	heif_region_item_get_number_of_regions (const heif_region_item *region_item)
	Get the number of regions within a region item.
int	heif_region_item_get_list_of_regions (const heif_region_item region_item, heif_region *out_regions_array, int max_count)
	Get the regions that are part of a region item.
void	heif_region_release (const heif_region *region)
	Release a region.
void	heif_region_release_many (const heif_region const regions_array, int num_items)
	Release a list of regions.
enum heif_region_type	heif_region_get_type (const heif_region *region)
	Get the region type for a specified region.
heif_error	heif_region_get_point (const heif_region region, int32_t out_x, int32_t *out_y)
	Get the values for a point region.
heif_error	heif_region_get_point_transformed (const heif_region region, heif_item_id image_id, double out_x, double *out_y)
	Get the transformed values for a point region.
heif_error	heif_region_get_rectangle (const heif_region region, int32_t out_x, int32_t out_y, uint32_t out_width, uint32_t *out_height)
	Get the values for a rectangle region.
heif_error	heif_region_get_rectangle_transformed (const heif_region region, heif_item_id image_id, double out_x, double out_y, double out_width, double *out_height)
	Get the transformed values for a rectangle region.
heif_error	heif_region_get_ellipse (const heif_region region, int32_t out_x, int32_t out_y, uint32_t out_radius_x, uint32_t *out_radius_y)
	Get the values for an ellipse region.
heif_error	heif_region_get_ellipse_transformed (const heif_region region, heif_item_id image_id, double out_x, double out_y, double out_radius_x, double *out_radius_y)
	Get the transformed values for an ellipse region.
int	heif_region_get_polygon_num_points (const heif_region *region)
	Get the number of points in a polygon.
heif_error	heif_region_get_polygon_points (const heif_region region, int32_t out_pts_array)
	Get the points in a polygon region.
heif_error	heif_region_get_polygon_points_transformed (const heif_region region, heif_item_id image_id, double out_pts_array)
	Get the transformed points in a polygon region.
int	heif_region_get_polyline_num_points (const heif_region *region)
	Get the number of points in a polyline.
heif_error	heif_region_get_polyline_points (const heif_region region, int32_t out_pts_array)
	Get the points in a polyline region.
heif_error	heif_region_get_polyline_points_transformed (const heif_region region, heif_item_id image_id, double out_pts_array)
	Get the transformed points in a polyline region.
heif_error	heif_region_get_referenced_mask_ID (const heif_region region, int32_t out_x, int32_t out_y, uint32_t out_width, uint32_t out_height, heif_item_id out_mask_item_id)
	Get a referenced item mask region.
size_t	heif_region_get_inline_mask_data_len (const heif_region *region)
	Get the length of the data in an inline mask region.
heif_error	heif_region_get_inline_mask_data (const heif_region region, int32_t out_x, int32_t out_y, uint32_t out_width, uint32_t out_height, uint8_t out_mask_data)
	Get data for an inline mask region.
heif_error	heif_region_get_mask_image (const heif_region region, int32_t out_x, int32_t out_y, uint32_t out_width, uint32_t out_height, heif_image *out_mask_image)
	Get a mask region image.
heif_error	heif_image_handle_add_region_item (heif_image_handle image_handle, uint32_t reference_width, uint32_t reference_height, heif_region_item *out_region_item)
	Add a region item to an image.
heif_error	heif_region_item_add_region_point (heif_region_item region_item, int32_t x, int32_t y, heif_region *out_region)
	Add a point region to the region item.
heif_error	heif_region_item_add_region_rectangle (heif_region_item region_item, int32_t x, int32_t y, uint32_t width, uint32_t height, heif_region *out_region)
	Add a rectangle region to the region item.
heif_error	heif_region_item_add_region_ellipse (heif_region_item region_item, int32_t x, int32_t y, uint32_t radius_x, uint32_t radius_y, heif_region *out_region)
	Add a ellipse region to the region item.
heif_error	heif_region_item_add_region_polygon (heif_region_item region_item, const int32_t pts_array, int nPoints, heif_region **out_region)
	Add a polygon region to the region item.
heif_error	heif_region_item_add_region_polyline (heif_region_item region_item, const int32_t pts_array, int nPoints, heif_region **out_region)
	Add a polyline region to the region item.
heif_error	heif_region_item_add_region_referenced_mask (heif_region_item region_item, int32_t x, int32_t y, uint32_t width, uint32_t height, heif_item_id mask_item_id, heif_region *out_region)
	Add a referenced mask region to the region item.
heif_error	heif_region_item_add_region_inline_mask_data (heif_region_item region_item, int32_t x, int32_t y, uint32_t width, uint32_t height, const uint8_t mask_data, size_t mask_data_len, heif_region **out_region)
	Add an inline mask region to the region item.
heif_error	heif_region_item_add_region_inline_mask (heif_region_item region_item, int32_t x, int32_t y, uint32_t width, uint32_t height, heif_image image, heif_region **out_region)
	Add an inline mask region image to the region item.

Typedef Documentation

◆ heif_region

typedef struct heif_region heif_region

◆ heif_region_item

typedef struct heif_region_item heif_region_item

Enumeration Type Documentation

◆ heif_region_type

enum heif_region_type

Region type.

Each region item will contain zero or more regions, which may have different geometry or mask representations.

Enumerator
heif_region_type_point	Point geometry. The region is represented by a single point.
heif_region_type_rectangle	Rectangle geometry. The region is represented by a top left position, and a size defined by a width and height. All of the interior points and the edge are part of the region.
heif_region_type_ellipse	Ellipse geometry. The region is represented by a centre point, and radii in the X and Y directions. All of the interior points and the edge are part of the region.
heif_region_type_polygon	Polygon geometry. The region is represented by a sequence of points, which is considered implicitly closed. All of the interior points and the edge are part of the region.
heif_region_type_referenced_mask	Reference mask. The region geometry is described by the pixels in another image item, which has a item reference of type mask from the region item to the image item containing the mask. The image item containing the mask is one of: a mask item (see ISO/IEC 23008-12:2022 Section 6.10.2), or a derived image from a mask item an image item in monochrome format (4:0:0 chroma) an image item in colour format with luma and chroma planes (e.g. 4:2:0) If the pixel value is equal to the minimum sample value (e.g. 0 for unsigned integer), the pixel is not part of the region. If the pixel value is equal to the maximum sample value (e.g. 255 for 8 bit unsigned integer), the pixel is part of the region. If the pixel value is between the minimum sample value and maximum sample value, the pixel value represents an (application defined) probability that the pixel is part of the region, where higher pixel values correspond to higher probability values.
heif_region_type_inline_mask	Inline mask. The region geometry is described by a sequence of bits stored in inline in the region, one bit per pixel. If the bit value is 1, the pixel is part of the region. If the bit value is 0, the pixel is not part of the region.
heif_region_type_polyline	Polyline geometry. The region is represented by a sequence of points, which are not considered to form a closed surface. Only the edge is part of the region.

Function Documentation

◆ heif_context_get_region_item()

heif_error heif_context_get_region_item	(	const heif_context *	context,
		heif_item_id	region_item_id,
		heif_region_item **	out )

Get the region item.

Caller is responsible for release of the output heif_region_item with heif_region_item_release().

Parameters

context	the context to get the region item from, usually from a file operation
region_item_id	the identifier for the region item
out	pointer to pointer to the resulting region item

Returns: heif_error_ok on success, or an error value indicating the problem

◆ heif_image_handle_add_region_item()

heif_error heif_image_handle_add_region_item	(	heif_image_handle *	image_handle,
		uint32_t	reference_width,
		uint32_t	reference_height,
		heif_region_item **	out_region_item )

Add a region item to an image.

The region item is a collection of regions (point, polyline, polygon, rectangle, ellipse or mask) along with a reference size (width and height) that forms the coordinate basis for the regions.

The concept is to add the region item, then add one or more regions to the region item.

Parameters

image_handle	the image to attach the region item to.
reference_width	the width of the reference size.
reference_height	the height of the reference size.
out_region_item	the resulting region item

Returns: heif_error_ok on success, or an error indicating the problem on failure

◆ heif_image_handle_get_list_of_region_item_ids()

int heif_image_handle_get_list_of_region_item_ids	(	const heif_image_handle *	image_handle,
		heif_item_id *	region_item_ids_array,
		int	max_count )

Get the region item identifiers for the region items attached to an image.

Possible usage (in C++):

int numRegionItems = heif_image_handle_get_number_of_region_items(handle);
if (numRegionItems > 0) {
    std::vector<heif_item_id> region_item_ids(numRegionItems);
    heif_image_handle_get_list_of_region_item_ids(handle, region_item_ids.data(), numRegionItems);
    // use region item ids
}

Parameters

image_handle	the image handle for the parent image to query
region_item_ids_array	array to put the item identifiers into
max_count	the maximum number of region identifiers

Returns: the number of region item identifiers that were returned.

◆ heif_image_handle_get_number_of_region_items()

int heif_image_handle_get_number_of_region_items ( const heif_image_handle * image_handle )

Get the number of region items that are attached to an image.

Parameters

image_handle the image handle for the image to query.

Returns: the number of region items, which can be zero.

◆ heif_region_get_ellipse()

heif_error heif_region_get_ellipse	(	const heif_region *	region,
		int32_t *	out_x,
		int32_t *	out_y,
		uint32_t *	out_radius_x,
		uint32_t *	out_radius_y )

Get the values for an ellipse region.

This returns the values in the reference coordinate space (from the parent region item). The ellipse is represented by a centre position, and a size defined by radii in the X and Y directions. All of the interior points and the edge are part of the region.

Parameters

region	the region to query, which must be of type heif_region_type_ellipse.
out_x	the X coordinate for the centre point, where 0 is the left-most column.
out_y	the Y coordinate for the centre point, where 0 is the top-most row.
out_radius_x	the radius value in the X direction.
out_radius_y	the radius value in the Y direction

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_ellipse_transformed() for a version in pixels after all transformative properties have been applied.

◆ heif_region_get_ellipse_transformed()

heif_error heif_region_get_ellipse_transformed	(	const heif_region *	region,
		heif_item_id	image_id,
		double *	out_x,
		double *	out_y,
		double *	out_radius_x,
		double *	out_radius_y )

Get the transformed values for an ellipse region.

This returns the coordinates in pixels after all transformative properties have been applied. The ellipse is represented by a centre position, and a size defined by radii in the X and Y directions. All of the interior points and the edge are part of the region.

Parameters

region	the region to query, which must be of type heif_region_type_ellipse.
image_id	the identifier for the image to transform / scale the region to
out_x	the X coordinate for the centre point, where 0 is the left-most column.
out_y	the Y coordinate for the centre point, where 0 is the top-most row.
out_radius_x	the radius value in the X direction.
out_radius_y	the radius value in the Y direction

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_ellipse() for a version that returns the values in the reference coordinate space.

◆ heif_region_get_inline_mask_data()

heif_error heif_region_get_inline_mask_data	(	const heif_region *	region,
		int32_t *	out_x,
		int32_t *	out_y,
		uint32_t *	out_width,
		uint32_t *	out_height,
		uint8_t *	out_mask_data )

Get data for an inline mask region.

This returns the values in the reference coordinate space (from the parent region item). The mask location is represented by a top left corner position, and a size defined by a width and height.

The mask is held as inline data on the region, one bit per pixel, most significant bit first pixel, no padding. If the bit value is 1, the corresponding pixel is part of the region. If the bit value is 0, the corresponding pixel is not part of the region.

Possible usage (in C++):

long unsigned int data_len = heif_region_get_inline_mask_data_len(region);
int32_t x, y;
uint32_t width, height;
std::vector<uint8_t> mask_data(data_len);
err = heif_region_get_inline_mask(region, &x, &y, &width, &height, mask_data.data());

Parameters

region	the region to query, which must be of type heif_region_type_inline_mask.
out_x	the X coordinate for the top left corner, where 0 is the left-most column.
out_y	the Y coordinate for the top left corner, where 0 is the top-most row.
out_width	the width of the mask region
out_height	the height of the mask region
out_mask_data	the location to return the mask data

Returns: heif_error_ok on success, or an error value indicating the problem on failure

◆ heif_region_get_inline_mask_data_len()

size_t heif_region_get_inline_mask_data_len ( const heif_region * region )

Get the length of the data in an inline mask region.

Parameters

region the region to query, which must be of type heif_region_type_inline_mask.

Returns: the number of bytes in the mask data, or 0 on error.

◆ heif_region_get_mask_image()

heif_error heif_region_get_mask_image	(	const heif_region *	region,
		int32_t *	out_x,
		int32_t *	out_y,
		uint32_t *	out_width,
		uint32_t *	out_height,
		heif_image **	out_mask_image )

Get a mask region image.

This returns the values in the reference coordinate space (from the parent region item). The mask location is represented by a top left corner position, and a size defined by a width and height.

This function works when the passed region is either a heif_region_type_referenced_mask or a heif_region_type_inline_mask. The returned image is a monochrome image where each pixel represents the (scaled) probability of the pixel being part of the mask.

If the region type is an inline mask, which always holds a binary mask, this function converts the binary inline mask to an 8-bit monochrome image with the values '0' and '255'. The pixel value is set to 255 where the pixel is part of the region, and 0 where the pixel is not part of the region.

Parameters

region	the region to query, which must be of type heif_region_type_inline_mask.
out_x	the X coordinate for the top left corner, where 0 is the left-most column.
out_y	the Y coordinate for the top left corner, where 0 is the top-most row.
out_width	the width of the mask region
out_height	the height of the mask region
out_mask_image	the returned mask image

Returns: heif_error_ok on success, or an error value indicating the problem on failure

Note: the caller is responsible for releasing the mask image

◆ heif_region_get_point()

heif_error heif_region_get_point	(	const heif_region *	region,
		int32_t *	out_x,
		int32_t *	out_y )

Get the values for a point region.

This returns the coordinates in the reference coordinate space (from the parent region item).

Parameters

region	the region to query, which must be of type heif_region_type_point.
out_x	the X coordinate, where 0 is the left-most column.
out_y	the Y coordinate, where 0 is the top-most row.

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_point_transformed() for a version in pixels after all transformative properties have been applied.

◆ heif_region_get_point_transformed()

heif_error heif_region_get_point_transformed	(	const heif_region *	region,
		heif_item_id	image_id,
		double *	out_x,
		double *	out_y )

Get the transformed values for a point region.

This returns the coordinates in pixels after all transformative properties have been applied.

Parameters

region	the region to query, which must be of type heif_region_type_point.
image_id	the identifier for the image to transform / scale the region to
out_x	the X coordinate, where 0 is the left-most column.
out_y	the Y coordinate, where 0 is the top-most row.

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_point() for a version that returns the values in the reference coordinate space.

◆ heif_region_get_polygon_num_points()

int heif_region_get_polygon_num_points ( const heif_region * region )

Get the number of points in a polygon.

Parameters

region the region to query, which must be of type heif_region_type_polygon

Returns: the number of points, or -1 on error.

◆ heif_region_get_polygon_points()

heif_error heif_region_get_polygon_points	(	const heif_region *	region,
		int32_t *	out_pts_array )

Get the points in a polygon region.

This returns the values in the reference coordinate space (from the parent region item).

A polygon is a sequence of points that form a closed shape. The first point does not need to be repeated as the last point. All of the interior points and the edge are part of the region. The points are returned as pairs of X,Y coordinates, in the order X₁, Y₁, X₂, Y₂, ..., X_n, Y_n.

Parameters

region	the region to query, which must be of type heif_region_type_polygon
out_pts_array	the array to return the points in, which must have twice as many entries as there are points in the polygon.

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_polygon_points_transformed() for a version in pixels after all transformative properties have been applied.

◆ heif_region_get_polygon_points_transformed()

heif_error heif_region_get_polygon_points_transformed	(	const heif_region *	region,
		heif_item_id	image_id,
		double *	out_pts_array )

Get the transformed points in a polygon region.

This returns the coordinates in pixels after all transformative properties have been applied.

A polygon is a sequence of points that form a closed shape. The first point does not need to be repeated as the last point. All of the interior points and the edge are part of the region. The points are returned as pairs of X,Y coordinates, in the order X₁, Y₁, X₂, Y₂, ..., X_n, Y_n.

Parameters

region	the region to query, which must be of type heif_region_type_polygon
image_id	the identifier for the image to transform / scale the region to
out_pts_array	the array to return the points in, which must have twice as many entries as there are points in the polygon.

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_polygon_points() for a version that returns the values in the reference coordinate space.

◆ heif_region_get_polyline_num_points()

int heif_region_get_polyline_num_points ( const heif_region * region )

Get the number of points in a polyline.

Parameters

region the region to query, which must be of type heif_region_type_polyline

Returns: the number of points, or -1 on error.

◆ heif_region_get_polyline_points()

heif_error heif_region_get_polyline_points	(	const heif_region *	region,
		int32_t *	out_pts_array )

Get the points in a polyline region.

This returns the values in the reference coordinate space (from the parent region item).

A polyline is a sequence of points that does not form a closed shape. Even if the polyline is closed, the only points that are part of the region are those that intersect (even minimally) a one-pixel line drawn along the polyline. The points are provided as pairs of X,Y coordinates, in the order X₁, Y₁, X₂, Y₂, ..., X_n, Y_n.

Possible usage (in C++):

int num_polyline_points = heif_region_get_polyline_num_points(region);
if (num_polyline_points > 0) {
    std::vector<int32_t> polyline(num_polyline_points * 2);
    heif_region_get_polyline_points(region, polyline.data());
    // do something with points ...
}

Parameters

region	the region to query, which must be of type heif_region_type_polyline
out_pts_array	the array to return the points in, which must have twice as many entries as there are points in the polyline.

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_polyline_points_transformed() for a version in pixels after all transformative properties have been applied.

◆ heif_region_get_polyline_points_transformed()

heif_error heif_region_get_polyline_points_transformed	(	const heif_region *	region,
		heif_item_id	image_id,
		double *	out_pts_array )

Get the transformed points in a polyline region.

This returns the coordinates in pixels after all transformative properties have been applied.

A polyline is a sequence of points that does not form a closed shape. Even if the polyline is closed, the only points that are part of the region are those that intersect (even minimally) a one-pixel line drawn along the polyline. The points are provided as pairs of X,Y coordinates, in the order X₁, Y₁, X₂, Y₂, ..., X_n, Y_n.

Parameters

region	the region to query, which must be of type heif_region_type_polyline
image_id	the identifier for the image to transform / scale the region to
out_pts_array	the array to return the points in, which must have twice as many entries as there are points in the polyline.

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_polyline_points() for a version that returns the values in the reference coordinate space.

◆ heif_region_get_rectangle()

heif_error heif_region_get_rectangle	(	const heif_region *	region,
		int32_t *	out_x,
		int32_t *	out_y,
		uint32_t *	out_width,
		uint32_t *	out_height )

Get the values for a rectangle region.

This returns the values in the reference coordinate space (from the parent region item). The rectangle is represented by a top left corner position, and a size defined by a width and height. All of the interior points and the edge are part of the region.

Parameters

region	the region to query, which must be of type heif_region_type_rectangle.
out_x	the X coordinate for the top left corner, where 0 is the left-most column.
out_y	the Y coordinate for the top left corner, where 0 is the top-most row.
out_width	the width of the rectangle
out_height	the height of the rectangle

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_rectangle_transformed() for a version in pixels after all transformative properties have been applied.

◆ heif_region_get_rectangle_transformed()

heif_error heif_region_get_rectangle_transformed	(	const heif_region *	region,
		heif_item_id	image_id,
		double *	out_x,
		double *	out_y,
		double *	out_width,
		double *	out_height )

Get the transformed values for a rectangle region.

This returns the coordinates in pixels after all transformative properties have been applied. The rectangle is represented by a top left corner position, and a size defined by a width and height. All of the interior points and the edge are part of the region.

Parameters

region	the region to query, which must be of type heif_region_type_rectangle.
image_id	the identifier for the image to transform / scale the region to
out_x	the X coordinate for the top left corner, where 0 is the left-most column.
out_y	the Y coordinate for the top left corner, where 0 is the top-most row.
out_width	the width of the rectangle
out_height	the height of the rectangle

Returns: heif_error_ok on success, or an error value indicating the problem on failure

See also: heif_region_get_rectangle() for a version that returns the values in the reference coordinate space.

◆ heif_region_get_referenced_mask_ID()

heif_error heif_region_get_referenced_mask_ID	(	const heif_region *	region,
		int32_t *	out_x,
		int32_t *	out_y,
		uint32_t *	out_width,
		uint32_t *	out_height,
		heif_item_id *	out_mask_item_id )

Get a referenced item mask region.

This returns the values in the reference coordinate space (from the parent region item). The mask location is represented by a top left corner position, and a size defined by a width and height. The value of each sample in that mask identifies whether the corresponding pixel is part of the region.

The mask is provided as an image in another item. The image item containing the mask is one of:

a mask item (see ISO/IEC 23008-12:2022 Section 6.10.2), or a derived image from a mask item
an image item in monochrome format (4:0:0 chroma)
an image item in colour format with luma and chroma planes (e.g. 4:2:0)

If the pixel value is equal to the minimum sample value (e.g. 0 for unsigned integer), the pixel is not part of the region. If the pixel value is equal to the maximum sample value (e.g. 255 for 8 bit unsigned integer), the pixel is part of the region. If the pixel value is between the minimum sample value and maximum sample value, the pixel value represents an (application defined) probability that the pixel is part of the region, where higher pixel values correspond to higher probability values.

Parameters

region	the region to query, which must be of type heif_region_type_referenced_mask.
out_x	the X coordinate for the top left corner, where 0 is the left-most column.
out_y	the Y coordinate for the top left corner, where 0 is the top-most row.
out_width	the width of the mask region
out_height	the height of the mask region
out_mask_item_id	the item identifier for the image that provides the mask.

Returns: heif_error_ok on success, or an error value indicating the problem on failure

◆ heif_region_get_type()

enum heif_region_type heif_region_get_type ( const heif_region * region )

Get the region type for a specified region.

Parameters

region the region to query

Returns: the corresponding region type as an enumeration value

◆ heif_region_item_add_region_ellipse()

heif_error heif_region_item_add_region_ellipse	(	heif_region_item *	region_item,
		int32_t	x,
		int32_t	y,
		uint32_t	radius_x,
		uint32_t	radius_y,
		heif_region **	out_region )

Add a ellipse region to the region item.

Parameters

region_item	the region item that holds this ellipse region
x	the x value for the centre of this ellipse region
y	the y value for the centre of this ellipse region
radius_x	the radius of the ellipse in the X (horizontal) direction
radius_y	the radius of the ellipse in the Y (vertical) direction
out_region	pointer to pointer to the returned region (optional, see below)

Returns: heif_error_ok on success, or an error indicating the problem on failure

Note: The out_region parameter is optional, and can be set to NULL if not needed.

◆ heif_region_item_add_region_inline_mask()

heif_error heif_region_item_add_region_inline_mask	(	heif_region_item *	region_item,
		int32_t	x,
		int32_t	y,
		uint32_t	width,
		uint32_t	height,
		heif_image *	image,
		heif_region **	out_region )

Add an inline mask region image to the region item.

The region geometry is described by a top left corner position, and a size defined by a width and height.

The mask data is held as inline data on the region, one bit per pixel. The provided image is converted to inline data, where any pixel with a value >= 0x80 becomes part of the mask region. If the image width is less that the specified width, it is expanded to match the width of the region (zero fill on the right). If the image height is less than the specified height, it is expanded to match the height of the region (zero fill on the bottom). If the image width or height is greater than the width or height (correspondingly) of the region, the image is cropped.

Parameters

region_item	the region item that holds this mask region
x	the x value for the top-left corner of this mask region
y	the y value for the top-left corner of this mask region
width	the width of this mask region
height	the height of this mask region
image	the image to convert to an inline mask
out_region	pointer to pointer to the returned region (optional, see below)

Returns: heif_error_ok on success, or an error value indicating the problem on failure

◆ heif_region_item_add_region_inline_mask_data()

heif_error heif_region_item_add_region_inline_mask_data	(	heif_region_item *	region_item,
		int32_t	x,
		int32_t	y,
		uint32_t	width,
		uint32_t	height,
		const uint8_t *	mask_data,
		size_t	mask_data_len,
		heif_region **	out_region )

Add an inline mask region to the region item.

The region geometry is described by a top left corner position, and a size defined by a width and height.

The mask is held as inline data on the region, one bit per pixel, most significant bit first pixel, no padding. If the bit value is 1, the corresponding pixel is part of the region. If the bit value is 0, the corresponding pixel is not part of the region.

Parameters

region_item	the region item that holds this mask region
x	the x value for the top-left corner of this mask region
y	the y value for the top-left corner of this mask region
width	the width of this mask region
height	the height of this mask region
mask_data	the location to return the mask data
mask_data_len	the length of the mask data, in bytes
out_region	pointer to pointer to the returned region (optional, see below)

Returns: heif_error_ok on success, or an error value indicating the problem on failure

◆ heif_region_item_add_region_point()

heif_error heif_region_item_add_region_point	(	heif_region_item *	region_item,
		int32_t	x,
		int32_t	y,
		heif_region **	out_region )

Add a point region to the region item.

Parameters

region_item	the region item that holds this point region
x	the x value for the point location
y	the y value for the point location
out_region	pointer to pointer to the returned region (optional, see below)

Returns: heif_error_ok on success, or an error indicating the problem on failure

Note: The out_region parameter is optional, and can be set to NULL if not needed.

◆ heif_region_item_add_region_polygon()

heif_error heif_region_item_add_region_polygon	(	heif_region_item *	region_item,
		const int32_t *	pts_array,
		int	nPoints,
		heif_region **	out_region )

Add a polygon region to the region item.

A polygon is a sequence of points that form a closed shape. The first point does not need to be repeated as the last point. The points are provided as pairs of X,Y coordinates, in the order X₁, Y₁, X₂, Y₂, ..., X_n, Y_n.

Parameters

region_item	the region item that holds this polygon region
pts_array	the array of points in X,Y order (see above)
nPoints	the number of points
out_region	pointer to pointer to the returned region (optional, see below)

Returns: heif_error_ok on success, or an error indicating the problem on failure

Note: nPoints is the number of points, not the number of elements in the array; The out_region parameter is optional, and can be set to NULL if not needed.

◆ heif_region_item_add_region_polyline()

heif_error heif_region_item_add_region_polyline	(	heif_region_item *	region_item,
		const int32_t *	pts_array,
		int	nPoints,
		heif_region **	out_region )

Add a polyline region to the region item.

A polyline is a sequence of points that does not form a closed shape. Even if the polyline is closed, the only points that are part of the region are those that intersect (even minimally) a one-pixel line drawn along the polyline. The points are provided as pairs of X,Y coordinates, in the order X₁, Y₁, X₂, Y₂, ..., X_n, Y_n.

Parameters

region_item	the region item that holds this polyline region
pts_array	the array of points in X,Y order (see above)
nPoints	the number of points
out_region	pointer to pointer to the returned region (optional, see below)

Returns: heif_error_ok on success, or an error indicating the problem on failure

Note: nPoints is the number of points, not the number of elements in the array; The out_region parameter is optional, and can be set to NULL if not needed.

◆ heif_region_item_add_region_rectangle()

heif_error heif_region_item_add_region_rectangle	(	heif_region_item *	region_item,
		int32_t	x,
		int32_t	y,
		uint32_t	width,
		uint32_t	height,
		heif_region **	out_region )

Add a rectangle region to the region item.

Parameters

region_item	the region item that holds this rectangle region
x	the x value for the top-left corner of this rectangle region
y	the y value for the top-left corner of this rectangle region
width	the width of this rectangle region
height	the height of this rectangle region
out_region	pointer to pointer to the returned region (optional, see below)

Returns: heif_error_ok on success, or an error indicating the problem on failure

Note: The out_region parameter is optional, and can be set to NULL if not needed.

◆ heif_region_item_add_region_referenced_mask()

heif_error heif_region_item_add_region_referenced_mask	(	heif_region_item *	region_item,
		int32_t	x,
		int32_t	y,
		uint32_t	width,
		uint32_t	height,
		heif_item_id	mask_item_id,
		heif_region **	out_region )

Add a referenced mask region to the region item.

The region geometry is described by the pixels in another image item, which has a item reference of type mask from the region item to the image item containing the mask.

The image item containing the mask is one of:

a mask item (see ISO/IEC 23008-12:2022 Section 6.10.2), or a derived image from a mask item
an image item in monochrome format (4:0:0 chroma)
an image item in colour format with luma and chroma planes (e.g. 4:2:0)

If the pixel value is equal to the minimum sample value (e.g. 0 for unsigned integer), the pixel is not part of the region. If the pixel value is equal to the maximum sample value (e.g. 255 for 8 bit unsigned integer), the pixel is part of the region. If the pixel value is between the minimum sample value and maximum sample value, the pixel value represents an (application defined) probability that the pixel is part of the region, where higher pixel values correspond to higher probability values.

Parameters

region_item	the region item that holds this mask region
x	the x value for the top-left corner of this mask region
y	the y value for the top-left corner of this mask region
width	the width of this mask region
height	the height of this mask region
mask_item_id	the item identifier for the mask that is referenced
out_region	pointer to pointer to the returned region (optional, see below)

Returns: heif_error_ok on success, or an error indicating the problem on failure

Note: The out_region parameter is optional, and can be set to NULL if not needed.

◆ heif_region_item_get_id()

heif_item_id heif_region_item_get_id ( heif_region_item * region_item )

Get the item identifier for a region item.

Parameters

region_item the region item to query

Returns: the region item identifier (or 0 if the region_item is null)

◆ heif_region_item_get_list_of_regions()

int heif_region_item_get_list_of_regions	(	const heif_region_item *	region_item,
		heif_region **	out_regions_array,
		int	max_count )

Get the regions that are part of a region item.

Caller is responsible for releasing the returned heif_region objects, using heif_region_release() on each region, or heif_region_release_many() on the returned array.

Possible usage (in C++):

int num_regions = heif_image_handle_get_number_of_regions(region_item);
if (num_regions > 0) {
    std::vector<heif_region*> regions(num_regions);
    int n = heif_region_item_get_list_of_regions(region_item, regions.data(), (int)regions.size());
    // use regions
    heif_region_release_many(regions.data(), n);
}

Parameters

region_item	the region_item to query
out_regions_array	array to put the region pointers into
max_count	the maximum number of regions, which needs to correspond to the size of the out_regions_array

Returns: the number of regions that were returned.

◆ heif_region_item_get_number_of_regions()

int heif_region_item_get_number_of_regions ( const heif_region_item * region_item )

Get the number of regions within a region item.

Parameters

region_item the region item to query.

Returns: the number of regions

◆ heif_region_item_get_reference_size()

void heif_region_item_get_reference_size	(	heif_region_item *	,
		uint32_t *	out_width,
		uint32_t *	out_height )

Get the reference size for a region item.

The reference size specifies the coordinate space used for the region items. When the reference size does not match the image size, the regions need to be scaled to correspond.

Parameters

out_width	the return value for the reference width (before any transformation)
out_height	the return value for the reference height (before any transformation)

◆ heif_region_item_release()

void heif_region_item_release ( heif_region_item * region_item )

Release a region item.

This should be called on items from heif_context_get_region_item().

Parameters

region_item the item to release.

◆ heif_region_release()

void heif_region_release ( const heif_region * region )

Release a region.

This should be called on regions from heif_region_item_get_list_of_regions().

Parameters

region the region to release.

See also: heif_region_release_many() to release the whole list

◆ heif_region_release_many()

void heif_region_release_many	(	const heif_region const	regions_array,
		int	num_items )

Release a list of regions.

This should be called on the list of regions from heif_region_item_get_list_of_regions().

Parameters

regions_array	the regions to release.
num_items	the number of items in the array

See also: heif_region_release() to release a single region

Typedefs

Enumerations

Functions

Typedef Documentation

◆ heif_region

◆ heif_region_item

Enumeration Type Documentation

◆ heif_region_type

Function Documentation

◆ heif_context_get_region_item()

◆ heif_image_handle_add_region_item()

◆ heif_image_handle_get_list_of_region_item_ids()

◆ heif_image_handle_get_number_of_region_items()

◆ heif_region_get_ellipse()

◆ heif_region_get_ellipse_transformed()

◆ heif_region_get_inline_mask_data()

◆ heif_region_get_inline_mask_data_len()

◆ heif_region_get_mask_image()

◆ heif_region_get_point()

◆ heif_region_get_point_transformed()

◆ heif_region_get_polygon_num_points()

◆ heif_region_get_polygon_points()

◆ heif_region_get_polygon_points_transformed()

◆ heif_region_get_polyline_num_points()

◆ heif_region_get_polyline_points()

◆ heif_region_get_polyline_points_transformed()

◆ heif_region_get_rectangle()

◆ heif_region_get_rectangle_transformed()

◆ heif_region_get_referenced_mask_ID()

◆ heif_region_get_type()

◆ heif_region_item_add_region_ellipse()

◆ heif_region_item_add_region_inline_mask()

◆ heif_region_item_add_region_inline_mask_data()

◆ heif_region_item_add_region_point()

◆ heif_region_item_add_region_polygon()

◆ heif_region_item_add_region_polyline()

◆ heif_region_item_add_region_rectangle()

◆ heif_region_item_add_region_referenced_mask()

◆ heif_region_item_get_id()

◆ heif_region_item_get_list_of_regions()

◆ heif_region_item_get_number_of_regions()

◆ heif_region_item_get_reference_size()

◆ heif_region_item_release()

◆ heif_region_release()

◆ heif_region_release_many()