pylibheif 1.21.2__cp311-cp311-macosx_14_0_arm64.whl

include/libheif/heif_image_handle.h

@@ -0,0 +1,129 @@
+/*
+ * HEIF codec.
+ * Copyright (c) 2017-2025 Dirk Farin <dirk.farin@gmail.com>
+ *
+ * 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_IMAGE_HANDLE_H
+#define LIBHEIF_HEIF_IMAGE_HANDLE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include <libheif/heif_library.h>
+#include <libheif/heif_image.h>
+
+
+// ========================= heif_image_handle =========================
+
+// An heif_image_handle is a handle to a logical image in the HEIF file.
+// To get the actual pixel data, you have to decode the handle to an heif_image.
+// An heif_image_handle also gives you access to the thumbnails and Exif data
+// associated with an image.
+
+// Once you obtained an heif_image_handle, you can already release the heif_context,
+// since it is internally ref-counted.
+
+// Release image handle.
+LIBHEIF_API
+void heif_image_handle_release(const heif_image_handle*);
+
+// Check whether the given image_handle is the primary image of the file.
+LIBHEIF_API
+int heif_image_handle_is_primary_image(const heif_image_handle* handle);
+
+LIBHEIF_API
+heif_item_id heif_image_handle_get_item_id(const heif_image_handle* handle);
+
+/** Get the image width.
+ *
+ * If 'handle' is invalid (NULL) or if the image size exceeds the range of `int`, 0 is returned.
+ */
+LIBHEIF_API
+int heif_image_handle_get_width(const heif_image_handle* handle);
+
+/** Get the image height.
+ *
+ * If 'handle' is invalid (NULL) or if the image size exceeds the range of `int`, 0 is returned.
+ */
+LIBHEIF_API
+int heif_image_handle_get_height(const heif_image_handle* handle);
+
+LIBHEIF_API
+int heif_image_handle_has_alpha_channel(const heif_image_handle*);
+
+LIBHEIF_API
+int heif_image_handle_is_premultiplied_alpha(const heif_image_handle*);
+
+// Returns -1 on error, e.g. if this information is not present in the image.
+// Only defined for images coded in the YCbCr or monochrome colorspace.
+LIBHEIF_API
+int heif_image_handle_get_luma_bits_per_pixel(const heif_image_handle*);
+
+// Returns -1 on error, e.g. if this information is not present in the image.
+// Only defined for images coded in the YCbCr colorspace.
+LIBHEIF_API
+int heif_image_handle_get_chroma_bits_per_pixel(const heif_image_handle*);
+
+// Return the colorspace that libheif proposes to use for decoding.
+// Usually, these will be either YCbCr or Monochrome, but it may also propose RGB for images
+// encoded with matrix_coefficients=0 or for images coded natively in RGB.
+// It may also return *_undefined if the file misses relevant information to determine this without decoding.
+// These are only proposed values that avoid colorspace conversions as much as possible.
+// You can still request the output in your preferred colorspace, but this may involve an internal conversion.
+LIBHEIF_API
+heif_error heif_image_handle_get_preferred_decoding_colorspace(const heif_image_handle* image_handle,
+                                                               enum heif_colorspace* out_colorspace,
+                                                               enum heif_chroma* out_chroma);
+
+// Get the image width from the 'ispe' box. This is the original image size without
+// any transformations applied to it. Do not use this unless you know exactly what
+// you are doing.
+LIBHEIF_API
+int heif_image_handle_get_ispe_width(const heif_image_handle* handle);
+
+LIBHEIF_API
+int heif_image_handle_get_ispe_height(const heif_image_handle* handle);
+
+// Returns whether the image has 'pixel aspect ratio information' information. If 0 is returned, the output is filled with the 1:1 default.
+LIBHEIF_API
+int heif_image_handle_get_pixel_aspect_ratio(const heif_image_handle*, uint32_t* aspect_h, uint32_t* aspect_v);
+
+
+// This gets the context associated with the image handle.
+// Note that you have to release the returned context with heif_context_free() in any case.
+//
+// This means: when you have several image-handles that originate from the same file and you get the
+// context of each of them, the returned pointer may be different even though it refers to the same
+// logical context. You have to call heif_context_free() on all those context pointers.
+// After you freed a context pointer, you can still use the context through a different pointer that you
+// might have acquired from elsewhere.
+LIBHEIF_API
+heif_context* heif_image_handle_get_context(const heif_image_handle* handle);
+
+LIBHEIF_API
+const char* heif_image_handle_get_gimi_content_id(const heif_image_handle* handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

include/libheif/heif_items.h

@@ -0,0 +1,260 @@
+/*
+ * HEIF codec.
+ * Copyright (c) 2023 Dirk Farin <dirk.farin@gmail.com>
+ *
+ * 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_ITEMS_H
+#define LIBHEIF_HEIF_ITEMS_H
+
+#include "heif_library.h"
+#include "heif_error.h"
+#include "heif_metadata.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/**
+ * Gets the number of items.
+ *
+ * This is not the same as the number of images, since there can be other types of items,
+ * such as metadata.
+ *
+ * @param ctx the file context
+ * @return the number of items
+ */
+LIBHEIF_API
+int heif_context_get_number_of_items(const heif_context* ctx);
+
+/**
+ * Get the item identifiers.
+ *
+ * Fills in the item IDs into the user-supplied array {@code ID_array}, preallocated with {@code count} entries.
+ *
+ * @param ctx the file context
+ * @param ID_array the output array.
+ * @param count the number of items allocated within {@code ID_array}.
+ * @return the total number of IDs filled into the array, which may be less than {@code count}.
+ */
+LIBHEIF_API
+int heif_context_get_list_of_item_IDs(const heif_context* ctx,
+                                      heif_item_id* ID_array,
+                                      int count);
+
+/**
+ * Gets the item type.
+ *
+ * Usually, this is a four character code (e.g. `mime` or `uri `), but it can theoretically be
+ * any 4-byte number. Thus, the type is returned as an integer. You can use {@link heif_fourcc} to map
+ * between the two representations.
+ *
+ * @param ctx the file context
+ * @param item_id the item identifier for the item
+ * @return the item type
+ */
+LIBHEIF_API
+uint32_t heif_item_get_item_type(const heif_context* ctx, heif_item_id item_id);
+
+#define heif_item_type_mime   heif_fourcc('m','i','m','e')
+#define heif_item_type_uri    heif_fourcc('u','r','i',' ')
+
+LIBHEIF_API
+int heif_item_is_item_hidden(const heif_context* ctx, heif_item_id item_id);
+
+
+/**
+ * Gets the MIME content_type for an item.
+ *
+ * Only valid if the item type is `mime`.
+ * If the item does not exist, or if it is not a `mime` item, NULL is returned.
+ *
+ * @param ctx the file context
+ * @param item_id the item identifier for the item
+ * @return the item content_type
+ */
+LIBHEIF_API
+const char* heif_item_get_mime_item_content_type(const heif_context* ctx, heif_item_id item_id);
+
+/**
+ * Gets the content_encoding for a MIME item.
+ *
+ * Only valid if the item type is `mime`.
+ * If the item does not exist, or if it is not a `mime` item, NULL is returned.
+ *
+ * If the item is not encoded, the returned value will be an empty string (not null).
+ *
+ * @param ctx the file context
+ * @param item_id the item identifier for the item
+ * @return the item content_type
+ */
+LIBHEIF_API
+const char* heif_item_get_mime_item_content_encoding(const heif_context* ctx, heif_item_id item_id);
+
+/**
+ * Gets the item_uri_type for an item.
+ *
+ * Only valid if the item type is `uri `.
+ * If the item does not exist, or if it is not a `uri ` item, NULL is returned.
+ *
+ * @param ctx the file context
+ * @param item_id the item identifier for the item
+ * @return the item item_uri_type
+ */
+LIBHEIF_API
+const char* heif_item_get_uri_item_uri_type(const heif_context* ctx, heif_item_id item_id);
+
+LIBHEIF_API
+const char* heif_item_get_item_name(const heif_context* ctx, heif_item_id item_id);
+
+LIBHEIF_API
+heif_error heif_item_set_item_name(heif_context* ctx,
+                                   heif_item_id item,
+                                   const char* item_name);
+
+
+/**
+ * Gets the raw metadata, as stored in the HEIF file.
+ *
+ * Data in a "mime" item with "content_encoding" can be compressed.
+ * When `out_compression_format` is NULL, the decompressed data will be returned.
+ * Otherwise, the compressed data is returned and `out_compression_format` will be filled with the
+ * compression format.
+ * If the compression method is not supported, an error will be returned.
+ *
+ * It is valid to set `out_data` to NULL. In that case, only the `out_data_size` is filled.
+ * Note that it is inefficient to use `out_data=NULL` just to get the size of compressed data.
+ * In general, this should be avoided.
+ *
+ * If there is no data assigned to the item or there is an error, `out_data_size` is set to zero.
+ *
+ * @param ctx the file context
+ * @param item_id the item identifier for the item
+ * @param out_compression_format how the data is compressed. If the pointer is NULL, the decompressed data will be returned.
+ * @param out_data the corresponding raw metadata
+ * @param out_data_size the size of the metadata in bytes
+ * @return whether the call succeeded, or there was an error
+ */
+LIBHEIF_API
+heif_error heif_item_get_item_data(const heif_context* ctx,
+                                   heif_item_id item_id,
+                                   enum heif_metadata_compression* out_compression_format,
+                                   uint8_t** out_data, size_t* out_data_size);
+
+/**
+ * Free the item data.
+ *
+ * This is used to free memory associated with the data returned by
+ * {@link heif_item_get_item_data} in 'out_data' and set the pointer to NULL.
+ *
+ * @param ctx the file context
+ * @param item_data the data to free
+ */
+LIBHEIF_API
+void heif_release_item_data(const heif_context* ctx, uint8_t** item_data);
+
+
+// ------------------------- item language -------------------------
+
+/**
+ * Get the extended language associated with the item.
+ * The item is usually a text item.
+ *
+ * @param context the heif file context containg the item.
+ * @param itemId the identifier for the item
+ * @param out_language output parameter with the item's language. Free with heif_string_release().
+ * @return heif_error_ok on success, or an error value indicating the problem
+ */
+LIBHEIF_API
+heif_error heif_item_get_property_extended_language(const heif_context* context,
+                                                    heif_item_id itemId,
+                                                    char** out_language);
+
+LIBHEIF_API
+heif_error heif_item_set_property_extended_language(heif_context* context,
+                                                    heif_item_id item_id,
+                                                    const char* language, heif_property_id* out_optional_propertyId);
+
+// ------------------------- item references -------------------------
+
+/**
+ * Get the item ids that reference the given item.
+ *
+ * @param ctx the file context.
+ * @param from_item_id the item identifier for the item.
+ * @param index the index of the reference to get.
+ * @param out_reference_type_4cc The 4cc of the reference. (e.g dimg, thmb, cdsc, or auxl)
+ * @param out_references_to the item references. Use {@link heif_release_item_references} to free the memory.
+ * @return the number of items that reference the given item. Returns 0 if the index exceeds the number of references.
+ */
+LIBHEIF_API
+size_t heif_context_get_item_references(const heif_context* ctx,
+                                        heif_item_id from_item_id,
+                                        int index,
+                                        uint32_t* out_reference_type_4cc,
+                                        heif_item_id** out_references_to);
+
+LIBHEIF_API
+void heif_release_item_references(const heif_context* ctx, heif_item_id** references);
+
+LIBHEIF_API
+heif_error heif_context_add_item_reference(heif_context* ctx,
+                                           uint32_t reference_type,
+                                           heif_item_id from_item,
+                                           heif_item_id to_item);
+
+LIBHEIF_API
+heif_error heif_context_add_item_references(heif_context* ctx,
+                                            uint32_t reference_type,
+                                            heif_item_id from_item,
+                                            const heif_item_id* to_item,
+                                            int num_to_items);
+
+// ------------------------- adding new items -------------------------
+
+LIBHEIF_API
+heif_error heif_context_add_item(heif_context* ctx,
+                                 const char* item_type,
+                                 const void* data, int size,
+                                 heif_item_id* out_item_id);
+
+LIBHEIF_API
+heif_error heif_context_add_mime_item(heif_context* ctx,
+                                      const char* content_type,
+                                      enum heif_metadata_compression content_encoding,
+                                      const void* data, int size,
+                                      heif_item_id* out_item_id);
+
+LIBHEIF_API
+heif_error heif_context_add_precompressed_mime_item(heif_context* ctx,
+                                                    const char* content_type,
+                                                    const char* content_encoding,
+                                                    const void* data, int size,
+                                                    heif_item_id* out_item_id);
+
+LIBHEIF_API
+heif_error heif_context_add_uri_item(heif_context* ctx,
+                                     const char* item_uri_type,
+                                     const void* data, int size,
+                                     heif_item_id* out_item_id);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

include/libheif/heif_library.h

@@ -0,0 +1,219 @@
+/*
+ * HEIF codec.
+ * Copyright (c) 2017-2023 Dirk Farin <dirk.farin@gmail.com>
+ *
+ * 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_LIBRARY_H
+#define LIBHEIF_HEIF_LIBRARY_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <stdint.h>
+
+
+// API versions table
+//
+// release    dec.options   enc.options   heif_reader   heif_writer   depth.rep   col.profile
+// ------------------------------------------------------------------------------------------
+//  1.0            1           N/A           N/A           N/A           1           N/A
+//  1.1            1           N/A           N/A            1            1           N/A
+//  1.3            1            1             1             1            1           N/A
+//  1.4            1            1             1             1            1            1
+//  1.7            2            1             1             1            1            1
+//  1.9.2          2            2             1             1            1            1
+//  1.10           2            3             1             1            1            1
+//  1.11           2            4             1             1            1            1
+//  1.13           3            4             1             1            1            1
+//  1.14           3            5             1             1            1            1
+//  1.15           4            5             1             1            1            1
+//  1.16           5            6             1             1            1            1
+//  1.18           5            7             1             1            1            1
+//  1.19           6            7             2             1            1            1
+//  1.20           7            7             2             1            1            1
+
+#if (defined(_WIN32) || defined __CYGWIN__) && !defined(LIBHEIF_STATIC_BUILD)
+#ifdef LIBHEIF_EXPORTS
+#define LIBHEIF_API __declspec(dllexport)
+#else
+#define LIBHEIF_API __declspec(dllimport)
+#endif
+#elif defined(HAVE_VISIBILITY) && HAVE_VISIBILITY
+#ifdef LIBHEIF_EXPORTS
+#define LIBHEIF_API __attribute__((__visibility__("default")))
+#else
+#define LIBHEIF_API
+#endif
+#else
+#define LIBHEIF_API
+#endif
+
+/**
+ * Build a 32 bit integer from a 4-character code.
+ */
+#define heif_fourcc(a, b, c, d) ((uint32_t)((a<<24) | (b<<16) | (c<<8) | d))
+
+#include <libheif/heif_version.h>
+#include <libheif/heif_error.h>
+
+
+/* === version numbers === */
+
+// Version string of linked libheif library.
+LIBHEIF_API const char* heif_get_version(void);
+
+// Numeric version of linked libheif library, encoded as 0xHHMMLL00 = hh.mm.ll, where hh, mm, ll is the decimal representation of HH, MM, LL.
+// For example: 0x02150300 is version 2.21.3
+LIBHEIF_API uint32_t heif_get_version_number(void);
+
+// Numeric part "HH" from above. Returned as a decimal number.
+LIBHEIF_API int heif_get_version_number_major(void);
+// Numeric part "MM" from above. Returned as a decimal number.
+LIBHEIF_API int heif_get_version_number_minor(void);
+// Numeric part "LL" from above. Returned as a decimal number.
+LIBHEIF_API int heif_get_version_number_maintenance(void);
+
+// Helper macros to check for given versions of libheif at compile time.
+#define LIBHEIF_MAKE_VERSION(h, m, l) ((h) << 24 | (m) << 16 | (l) << 8)
+#define LIBHEIF_HAVE_VERSION(h, m, l) (LIBHEIF_NUMERIC_VERSION >= LIBHEIF_MAKE_VERSION(h, m, l))
+
+typedef struct heif_context heif_context;
+typedef struct heif_image_handle heif_image_handle;
+
+typedef uint32_t heif_item_id;
+typedef uint32_t heif_property_id;
+
+/**
+ * Free a string returned by libheif in various API functions.
+ * You may pass NULL.
+ */
+LIBHEIF_API
+void heif_string_release(const char*);
+
+
+// ========================= library initialization ======================
+
+typedef struct heif_init_params
+{
+  int version;
+
+  // currently no parameters
+} heif_init_params;
+
+
+/**
+ * Initialise library.
+ *
+ * You should call heif_init() when you start using libheif and heif_deinit() when you are finished.
+ * These calls are reference counted. Each call to heif_init() should be matched by one call to heif_deinit().
+ *
+ * For backwards compatibility, it is not really necessary to call heif_init(), but some library memory objects
+ * will never be freed if you do not call heif_init()/heif_deinit().
+ *
+ * heif_init() will load the external modules installed in the default plugin path. Thus, you need it when you
+ * want to load external plugins from the default path.
+ * Codec plugins that are compiled into the library directly (selected by the compile-time parameters of libheif)
+ * will be available even without heif_init().
+ *
+ * Make sure that you do not have one part of your program use heif_init()/heif_deinit() and another part that does
+ * not use it as the latter may try to use an uninitialized library. If in doubt, enclose everything with init/deinit.
+ *
+ * You may pass nullptr to get default parameters. Currently, no parameters are supported.
+ */
+LIBHEIF_API
+heif_error heif_init(heif_init_params*);
+
+/**
+ * Deinitialise and clean up library.
+ *
+ * You should call heif_init() when you start using libheif and heif_deinit() when you are finished.
+ * These calls are reference counted. Each call to heif_init() should be matched by one call to heif_deinit().
+ *
+ * Note: heif_deinit() must not be called after exit(), for example in a global C++ object's destructor.
+ * If you do, global variables in libheif might have already been released when heif_deinit() is running,
+ * leading to a crash.
+ *
+ * \sa heif_init()
+ */
+LIBHEIF_API
+void heif_deinit(void);
+
+
+// --- Codec plugins ---
+
+// --- Plugins are currently only supported on Unix platforms.
+
+typedef enum heif_plugin_type
+{
+  heif_plugin_type_encoder,
+  heif_plugin_type_decoder
+} heif_plugin_type;
+
+typedef struct heif_plugin_info
+{
+  int version; // version of this info struct
+  enum heif_plugin_type type;
+  const void* plugin;
+  void* internal_handle; // for internal use only
+} heif_plugin_info;
+
+LIBHEIF_API
+heif_error heif_load_plugin(const char* filename, heif_plugin_info const** out_plugin);
+
+LIBHEIF_API
+heif_error heif_load_plugins(const char* directory,
+                             const heif_plugin_info** out_plugins,
+                             int* out_nPluginsLoaded,
+                             int output_array_size);
+
+LIBHEIF_API
+heif_error heif_unload_plugin(const heif_plugin_info* plugin);
+
+// Get a NULL terminated array of the plugin directories that are searched by libheif.
+// This includes the paths specified in the environment variable LIBHEIF_PLUGIN_PATHS and the built-in path
+// (if not overridden by the environment variable).
+LIBHEIF_API
+const char* const* heif_get_plugin_directories(void);
+
+LIBHEIF_API
+void heif_free_plugin_directories(const char* const*);
+
+
+// --- register plugins
+
+typedef struct heif_decoder_plugin heif_decoder_plugin;
+typedef struct heif_encoder_plugin heif_encoder_plugin;
+
+LIBHEIF_API
+heif_error heif_register_decoder_plugin(const heif_decoder_plugin*);
+
+LIBHEIF_API
+heif_error heif_register_encoder_plugin(const heif_encoder_plugin*);
+
+
+// DEPRECATED. Use heif_register_decoder_plugin(const struct heif_decoder_plugin*) instead.
+LIBHEIF_API
+heif_error heif_register_decoder(heif_context* heif, const heif_decoder_plugin*);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif