/ 
Imager-File-HEIF-0.005
River stage zero No dependents
/ Imager::File::HEIF

NAME

Imager::File::HEIF - read and write HEIF files

SYNOPSIS

use Imager;
# before Imager 1.013 you need to explicitly load this
use Imager::File::HEIF;

my $img = Imager->new;
$img->read(file => "foo.heif")
  or die $img->errstr;

# type won't be necessary if the extension is heif from Imager 1.008
$img->write(file => "foo.heif", type => "heif")
  or die $img->errstr;

DESCRIPTION

Implements .heif file support for Imager.

CLASS METHODS

libversion()
buildversion()
my $lib_version   = Imager::File::HEIF->libversion;
my $build_version = Imager::File::HEIF->buildversion;

Returns the version of libheif, either the version of the library currently being used, or the version that Imager::File::HEIF was built with.

These might differ because the library was updated after Imager::File::HEIF was built.

init()
deinit()
Imager::File::HEIF->init;
Imager::File::HEIF->deinit;

You do not need to call these in normal code.

Initialise or clean up respectively the state of libheif.

These require libheif 1.13.0 or later to have any effect.

Imager::File::HEIF will call these on load and at END time respectively.

In practice libx265 still leaves a lot of memory leaked in my testing.

PATENTS

The h.265 compression libheif uses is covered by patents, if you use this code for commercial purposes you may need to license those patents.

LICENSING

Imager::File::HEIF itself and Imager are licensed under the same terms as Perl itself, and libheif is licensed under the LGPL 3.0.

But libx264, which libheif is typically built to use for encoding, is licensed under the GPL 2.0, and the owners provide a fairly strict interpretation of that license. They also sell commercial licenses.

INSTALLATION

To install Imager::File::HEIF you need Imager installed and you need libheif, libde265 and libx265 and their development files.

Imager::File::HEIF requires at least version 1.9.0 of libheif, but in general you want the very latest version you can get. Imager::File::HEIF has been tested up to version 1.17.3 of libheif.

CONTROLLING COMPRESSION

You can control compression through two tags (implicityly set on the images via write() or write_multi()):

  • heif_lossless - if this is non-zero the image is compressed in "lossless" mode. Note that in both lossy and lossless modes the image is converted from the RGB colorspace to the YCbCr colorspace, which will lose information. If non-zero the heif_quality value is ignored (and irrelevant.) Default: 0 (lossy compression is used.)

  • heif_quality - a value from 0 to 100 representing the quality of lossy compression. Default: 80.

WARNING: from my testing, using the rough measure done by Imager i_img_diff(), lossy at 80 quality turned out closer to the original image than lossless.

RESOURCE USAGE

HEIF processing is fairly resource intensive, and libheif uses multiple decoding threads by default when you read a HEIF image.

With libheif 1.13.0 or later you can set $Imager::File::HEIF::MaxThreads to the maximum number of threads to use. If this is negative or not defined the default is used, which is defined by libheif.

TODO

  • 10-bit/sample and 12-bit/sample images. Based on https://github.com/strukturag/libheif/issues/40 this might not be supported completely yet.

  • reading metadata (any to read?) I think pixel ratios are available. HEIF supports pixel ratios via the PixelAspectRatioBox pasp member of ItemPropertyContainerBox 'ipco' but libheif doesn't appear to support that.

  • writing metadata. We don't seem to have the animation metadata that webp does.

  • reading sub-image data? we can probably skip thumbs (or provide an option to read the thumb rather than the main image), but are there other images to read? Depth images. Low priority.

  • writing sub-image data? thumbnails and depth images. Very low priority.

  • Everything else.

AUTHOR

Tony Cook <tonyc@cpan.org>

SEE ALSO

Imager, Imager::Files.

https://github.com/strukturag/libheif

https://github.com/strukturag/libde265 - x265 decoder

https://www.x265.org/ - x265 encoder