heif_regions.h

Go to the documentation of this file.

/*
 * HEIF codec.
 * Copyright (c) 2023 Dirk Farin <dirk.farin@gmail.com>
 * Copyright (c) 2023 Brad Hards <bradh@frogmouth.net>
 *
 * This file is part of libheif.
 *
 * libheif is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of
 * the License, or (at your option) any later version.
 *
 * libheif is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with libheif.  If not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef LIBHEIF_HEIF_REGIONS_H
#define LIBHEIF_HEIF_REGIONS_H
 
#include "heif_image_handle.h"
#include "heif_library.h"
#include "heif_error.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
// --- region items and annotations
 
// See ISO/IEC 23008-12:2022 Section 6.10 "Region items and region annotations"
 
typedef struct heif_region_item heif_region_item;

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
};
 
typedef struct heif_region heif_region;

LIBHEIF_API
int heif_image_handle_get_number_of_region_items(const heif_image_handle* image_handle);

LIBHEIF_API
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);

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

LIBHEIF_API
heif_item_id heif_region_item_get_id(heif_region_item* region_item);

LIBHEIF_API
void heif_region_item_release(heif_region_item* region_item);

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

LIBHEIF_API
int heif_region_item_get_number_of_regions(const heif_region_item* region_item);

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

LIBHEIF_API
void heif_region_release(const heif_region* region);

LIBHEIF_API
void heif_region_release_many(const heif_region* const* regions_array, int num_items);

LIBHEIF_API
enum heif_region_type heif_region_get_type(const heif_region* region);
 
// When querying the region geometry, there is a version without and a version with "_transformed" suffix.
// The version without returns the coordinates in the reference coordinate space.
// The version with "_transformed" suffix give the coordinates in pixels after all transformative properties have been applied.

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

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

LIBHEIF_API
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);

LIBHEIF_API
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);

LIBHEIF_API
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);
 

LIBHEIF_API
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);

LIBHEIF_API
int heif_region_get_polygon_num_points(const heif_region* region);

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

LIBHEIF_API
heif_error heif_region_get_polygon_points_transformed(const heif_region* region,
                                                      heif_item_id image_id,
                                                      double* out_pts_array);
LIBHEIF_API
int heif_region_get_polyline_num_points(const heif_region* region);

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

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

LIBHEIF_API
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);

LIBHEIF_API
size_t heif_region_get_inline_mask_data_len(const heif_region* region);
 

LIBHEIF_API
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);

LIBHEIF_API
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);
 
// --- adding region items

LIBHEIF_API
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);

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

LIBHEIF_API
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);

LIBHEIF_API
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);

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

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

LIBHEIF_API
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);
 

LIBHEIF_API
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);

LIBHEIF_API
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);
#ifdef __cplusplus
}
#endif
 
#endif