libheif
Loading...
Searching...
No Matches
heif_regions.h
Go to the documentation of this file.
1/*
2 * HEIF codec.
3 * Copyright (c) 2023 Dirk Farin <dirk.farin@gmail.com>
4 * Copyright (c) 2023 Brad Hards <bradh@frogmouth.net>
5 *
6 * This file is part of libheif.
7 *
8 * libheif is free software: you can redistribute it and/or modify
9 * it under the terms of the GNU Lesser General Public License as
10 * published by the Free Software Foundation, either version 3 of
11 * the License, or (at your option) any later version.
12 *
13 * libheif is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with libheif. If not, see <http://www.gnu.org/licenses/>.
20 */
21
22#ifndef LIBHEIF_HEIF_REGIONS_H
23#define LIBHEIF_HEIF_REGIONS_H
24
25#include "heif.h"
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31// --- region items and annotations
32
33// See ISO/IEC 23008-12:2022 Section 6.10 "Region items and region annotations"
34
35struct heif_region_item;
36
123
124struct heif_region;
125
133int heif_image_handle_get_number_of_region_items(const struct heif_image_handle* image_handle);
134
154int heif_image_handle_get_list_of_region_item_ids(const struct heif_image_handle* image_handle,
155 heif_item_id* region_item_ids_array,
156 int max_count);
157
169struct heif_error heif_context_get_region_item(const struct heif_context* context,
170 heif_item_id region_item_id,
171 struct heif_region_item** out);
172
180heif_item_id heif_region_item_get_id(struct heif_region_item* region_item);
181
190void heif_region_item_release(struct heif_region_item* region_item);
191
203void heif_region_item_get_reference_size(struct heif_region_item*, uint32_t* out_width, uint32_t* out_height);
204
212int heif_region_item_get_number_of_regions(const struct heif_region_item* region_item);
213
237int heif_region_item_get_list_of_regions(const struct heif_region_item* region_item,
238 struct heif_region** out_regions_array,
239 int max_count);
240
251void heif_region_release(const struct heif_region* region);
252
264void heif_region_release_many(const struct heif_region* const* regions_array, int num_items);
265
273enum heif_region_type heif_region_get_type(const struct heif_region* region);
274
275// When querying the region geometry, there is a version without and a version with "_transformed" suffix.
276// The version without returns the coordinates in the reference coordinate space.
277// The version with "_transformed" suffix give the coordinates in pixels after all transformative properties have been applied.
278
292struct heif_error heif_region_get_point(const struct heif_region* region, int32_t* out_x, int32_t* out_y);
293
308struct heif_error heif_region_get_point_transformed(const struct heif_region* region, heif_item_id image_id, double* out_x, double* out_y);
309
328struct heif_error heif_region_get_rectangle(const struct heif_region* region,
329 int32_t* out_x, int32_t* out_y,
330 uint32_t* out_width, uint32_t* out_height);
331
351struct heif_error heif_region_get_rectangle_transformed(const struct heif_region* region,
352 heif_item_id image_id,
353 double* out_x, double* out_y,
354 double* out_width, double* out_height);
355
374struct heif_error heif_region_get_ellipse(const struct heif_region* region,
375 int32_t* out_x, int32_t* out_y,
376 uint32_t* out_radius_x, uint32_t* out_radius_y);
377
378
398struct heif_error heif_region_get_ellipse_transformed(const struct heif_region* region,
399 heif_item_id image_id,
400 double* out_x, double* out_y,
401 double* out_radius_x, double* out_radius_y);
402
410int heif_region_get_polygon_num_points(const struct heif_region* region);
411
431struct heif_error heif_region_get_polygon_points(const struct heif_region* region,
432 int32_t* out_pts_array);
433
454struct heif_error heif_region_get_polygon_points_transformed(const struct heif_region* region,
455 heif_item_id image_id,
456 double* out_pts_array);
464int heif_region_get_polyline_num_points(const struct heif_region* region);
465
495struct heif_error heif_region_get_polyline_points(const struct heif_region* region,
496 int32_t* out_pts_array);
497
518struct heif_error heif_region_get_polyline_points_transformed(const struct heif_region* region,
519 heif_item_id image_id,
520 double* out_pts_array);
521
557struct heif_error heif_region_get_referenced_mask_ID(const struct heif_region* region,
558 int32_t* out_x, int32_t* out_y,
559 uint32_t* out_width, uint32_t* out_height,
560 heif_item_id *out_mask_item_id);
561
569size_t heif_region_get_inline_mask_data_len(const struct heif_region* region);
570
571
602struct heif_error heif_region_get_inline_mask_data(const struct heif_region* region,
603 int32_t* out_x, int32_t* out_y,
604 uint32_t* out_width, uint32_t* out_height,
605 uint8_t* out_mask_data);
606
635struct heif_error heif_region_get_mask_image(const struct heif_region* region,
636 int32_t* out_x, int32_t* out_y,
637 uint32_t* out_width, uint32_t* out_height,
638 struct heif_image** out_mask_image);
639
640// --- adding region items
641
657struct heif_error heif_image_handle_add_region_item(struct heif_image_handle* image_handle,
658 uint32_t reference_width, uint32_t reference_height,
659 struct heif_region_item** out_region_item);
660
673struct heif_error heif_region_item_add_region_point(struct heif_region_item* region_item,
674 int32_t x, int32_t y,
675 struct heif_region** out_region);
676
691struct heif_error heif_region_item_add_region_rectangle(struct heif_region_item* region_item,
692 int32_t x, int32_t y,
693 uint32_t width, uint32_t height,
694 struct heif_region** out_region);
695
710struct heif_error heif_region_item_add_region_ellipse(struct heif_region_item* region_item,
711 int32_t x, int32_t y,
712 uint32_t radius_x, uint32_t radius_y,
713 struct heif_region** out_region);
714
733struct heif_error heif_region_item_add_region_polygon(struct heif_region_item* region_item,
734 const int32_t* pts_array, int nPoints,
735 struct heif_region** out_region);
736
756struct heif_error heif_region_item_add_region_polyline(struct heif_region_item* region_item,
757 const int32_t* pts_array, int nPoints,
758 struct heif_region** out_region);
759
760
797struct heif_error heif_region_item_add_region_referenced_mask(struct heif_region_item* region_item,
798 int32_t x, int32_t y,
799 uint32_t width, uint32_t height,
800 heif_item_id mask_item_id,
801 struct heif_region** out_region);
802
803
826struct heif_error heif_region_item_add_region_inline_mask_data(struct heif_region_item* region_item,
827 int32_t x, int32_t y,
828 uint32_t width, uint32_t height,
829 const uint8_t* mask_data,
830 size_t mask_data_len,
831 struct heif_region** out_region);
832
857struct heif_error heif_region_item_add_region_inline_mask(struct heif_region_item* region_item,
858 int32_t x, int32_t y,
859 uint32_t width, uint32_t height,
860 struct heif_image* image,
861 struct heif_region** out_region);
862#ifdef __cplusplus
863}
864#endif
865
866#endif
uint32_t heif_item_id
Definition heif.h:352
#define LIBHEIF_API
Definition heif.h:69
struct heif_error heif_region_get_polyline_points_transformed(const struct heif_region *region, heif_item_id image_id, double *out_pts_array)
Get the transformed points in a polyline region.
struct heif_error heif_region_get_mask_image(const struct heif_region *region, int32_t *out_x, int32_t *out_y, uint32_t *out_width, uint32_t *out_height, struct heif_image **out_mask_image)
Get a mask region image.
struct heif_error heif_region_get_ellipse(const struct 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.
struct heif_error heif_region_get_rectangle(const struct 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.
struct heif_error heif_context_get_region_item(const struct heif_context *context, heif_item_id region_item_id, struct heif_region_item **out)
Get the region item.
struct heif_error heif_region_item_add_region_polyline(struct heif_region_item *region_item, const int32_t *pts_array, int nPoints, struct heif_region **out_region)
Add a polyline region to the region item.
void heif_region_item_get_reference_size(struct heif_region_item *, uint32_t *out_width, uint32_t *out_height)
Get the reference size for a region item.
struct heif_error heif_region_item_add_region_polygon(struct heif_region_item *region_item, const int32_t *pts_array, int nPoints, struct heif_region **out_region)
Add a polygon region to the region item.
struct heif_error heif_region_item_add_region_ellipse(struct heif_region_item *region_item, int32_t x, int32_t y, uint32_t radius_x, uint32_t radius_y, struct heif_region **out_region)
Add a ellipse region to the region item.
struct heif_error heif_region_item_add_region_rectangle(struct heif_region_item *region_item, int32_t x, int32_t y, uint32_t width, uint32_t height, struct heif_region **out_region)
Add a rectangle region to the region item.
struct heif_error heif_region_get_polyline_points(const struct heif_region *region, int32_t *out_pts_array)
Get the points in a polyline region.
struct heif_error heif_region_get_polygon_points_transformed(const struct heif_region *region, heif_item_id image_id, double *out_pts_array)
Get the transformed points in a polygon region.
struct heif_error heif_region_get_rectangle_transformed(const struct 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.
struct heif_error heif_region_get_referenced_mask_ID(const struct 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 struct heif_region *region)
Get the length of the data in an inline mask region.
int heif_region_item_get_number_of_regions(const struct heif_region_item *region_item)
Get the number of regions within a region item.
struct heif_error heif_region_get_point(const struct heif_region *region, int32_t *out_x, int32_t *out_y)
Get the values for a point region.
void heif_region_release_many(const struct heif_region *const *regions_array, int num_items)
Release a list of regions.
void heif_region_item_release(struct heif_region_item *region_item)
Release a region item.
struct heif_error heif_region_get_point_transformed(const struct heif_region *region, heif_item_id image_id, double *out_x, double *out_y)
Get the transformed values for a point region.
struct heif_error heif_region_item_add_region_point(struct heif_region_item *region_item, int32_t x, int32_t y, struct heif_region **out_region)
Add a point region to the region item.
enum heif_region_type heif_region_get_type(const struct heif_region *region)
Get the region type for a specified region.
int heif_region_get_polygon_num_points(const struct heif_region *region)
Get the number of points in a polygon.
struct heif_error heif_image_handle_add_region_item(struct heif_image_handle *image_handle, uint32_t reference_width, uint32_t reference_height, struct heif_region_item **out_region_item)
Add a region item to an image.
void heif_region_release(const struct heif_region *region)
Release a region.
heif_region_type
Region type.
Definition heif_regions.h:44
@ heif_region_type_polygon
Polygon geometry.
Definition heif_regions.h:77
@ heif_region_type_ellipse
Ellipse geometry.
Definition heif_regions.h:68
@ heif_region_type_inline_mask
Inline mask.
Definition heif_regions.h:113
@ heif_region_type_point
Point gemetry.
Definition heif_regions.h:50
@ heif_region_type_polyline
Polyline geometry.
Definition heif_regions.h:121
@ heif_region_type_rectangle
Rectangle geometry.
Definition heif_regions.h:59
@ heif_region_type_referenced_mask
Reference mask.
Definition heif_regions.h:103
struct heif_error heif_region_get_inline_mask_data(const struct 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.
struct heif_error heif_region_item_add_region_inline_mask_data(struct 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, struct heif_region **out_region)
Add an inline mask region to the region item.
struct heif_error heif_region_get_ellipse_transformed(const struct 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.
struct heif_error heif_region_item_add_region_referenced_mask(struct heif_region_item *region_item, int32_t x, int32_t y, uint32_t width, uint32_t height, heif_item_id mask_item_id, struct heif_region **out_region)
Add a referenced mask region to the region item.
struct heif_error heif_region_item_add_region_inline_mask(struct heif_region_item *region_item, int32_t x, int32_t y, uint32_t width, uint32_t height, struct heif_image *image, struct heif_region **out_region)
Add an inline mask region image to the region item.
int heif_region_item_get_list_of_regions(const struct heif_region_item *region_item, struct heif_region **out_regions_array, int max_count)
Get the regions that are part of a region item.
heif_item_id heif_region_item_get_id(struct heif_region_item *region_item)
Get the item identifier for a region item.
int heif_image_handle_get_number_of_region_items(const struct heif_image_handle *image_handle)
Get the number of region items that are attached to an image.
int heif_region_get_polyline_num_points(const struct heif_region *region)
Get the number of points in a polyline.
struct heif_error heif_region_get_polygon_points(const struct heif_region *region, int32_t *out_pts_array)
Get the points in a polygon region.
int heif_image_handle_get_list_of_region_item_ids(const struct 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.
Definition heif.h:337