libheif
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
28 extern "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 
35 struct heif_region_item;
36 
44 {
51 
60 
69 
78 
104 
114 
122 };
123 
124 struct heif_region;
125 
133 int heif_image_handle_get_number_of_region_items(const struct heif_image_handle* image_handle);
134 
154 int 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 
169 struct 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 
180 heif_item_id heif_region_item_get_id(struct heif_region_item* region_item);
181 
190 void heif_region_item_release(struct heif_region_item* region_item);
191 
203 void heif_region_item_get_reference_size(struct heif_region_item*, uint32_t* out_width, uint32_t* out_height);
204 
212 int heif_region_item_get_number_of_regions(const struct heif_region_item* region_item);
213 
237 int 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 
251 void heif_region_release(const struct heif_region* region);
252 
264 void heif_region_release_many(const struct heif_region* const* regions_array, int num_items);
265 
273 enum 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 
292 struct heif_error heif_region_get_point(const struct heif_region* region, int32_t* out_x, int32_t* out_y);
293 
308 struct heif_error heif_region_get_point_transformed(const struct heif_region* region, heif_item_id image_id, double* out_x, double* out_y);
309 
328 struct 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 
351 struct 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 
374 struct 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 
398 struct 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 
410 int heif_region_get_polygon_num_points(const struct heif_region* region);
411 
431 struct heif_error heif_region_get_polygon_points(const struct heif_region* region,
432  int32_t* out_pts_array);
433 
454 struct heif_error heif_region_get_polygon_points_transformed(const struct heif_region* region,
455  heif_item_id image_id,
456  double* out_pts_array);
464 int heif_region_get_polyline_num_points(const struct heif_region* region);
465 
495 struct heif_error heif_region_get_polyline_points(const struct heif_region* region,
496  int32_t* out_pts_array);
497 
518 struct 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 
557 struct 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 
569 size_t heif_region_get_inline_mask_data_len(const struct heif_region* region);
570 
571 
602 struct 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 
635 struct 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 
657 struct 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 
673 struct 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 
691 struct 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 
710 struct 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 
733 struct 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 
756 struct 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 
797 struct 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 
826 struct 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 
857 struct 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:364
#define LIBHEIF_API
Definition: heif.h:71
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
LIBHEIF_API 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.
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_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:349