heif‐enc Command Line Tool

The heif-enc command line tool is an example application for converting images to HEIF files. It can read JPEG, PNG, TIFF, and Y4M images and it writes all variants of HEIF like HEIC, AVIF, or JPEG-2000 and ISO23001-17 uncompressed content.

The basic syntax is:

heif-enc input.jpg -o output.heic

To switch between different encoding formats use the following command line switches:

switch	compression format	suffix
(default)	H.265 (HEVC)	.heic
-A / --avif	AV1	.avif
--vvc	H.266 (VVC)	.vvic
--jpeg	JPEG
--jpeg2000	JPEG-2000	.hej2
--htj2k	HT-JPEG-2000
-U / --uncompressed	ISO 23001-17

Alternatively, heif-enc also sets the compression format when it recognizes the suffix of your output filename.

Despite its name, the 'uncompressed' codec can use lossless compression. You can specify the compression algorithm with --unci-compression METHOD, where METHOD is either deflate, zlib, or brotli (support for these formats may vary depending on how the libheif build was configured).

Encoding Tiled Images

If you want to encode a high-resolution tiled image, heif-enc expects each tile image in a separate input image with filenames that contain two numbers to denote the tile row and column position. For example: tile-2-3.jpg or image-002-003.jpg.

To switch heif-enc into tile input mode, use the option -T / --tiled-input and specify one tile image as input. heif-enc will scan the directory to search for images with the same name pattern. It will detect the number range for the row and column position. This means that the position numbers may start from 0 or 1 (or any other number). It will also detect whether to use leading zeros for the numbers.

Usually, heif-enc expects that the first number is the vertical position and the second number the horizontal position. If you want to swap these, use --tiled-input-x-y.

The generated tiled image will have a size which is the sum of all the tile widths and heights. However, the input image might have some padding add the right and bottom border. In that case, you can overwrite the total image size with --tiled-image-width # and --tiled-image-height #.

Tiling Modes

You can choose between three different tiling modes:

• grid: this is the default method with the best decoder compatibility. However, it has the largest overhead and the maximum size is limited to 65535 tiles.
• tili: this is a more efficient tiling format with only little overhead and allowing practically unlimited number of tiles.
• unci: this uses the internal tiling support of the ISO 23001-17 (uncompressed) image codec. It can only be used in connection of that codec. Like tili, it has little overhead and supports larger image sizes.

Multi-Resolution Pyramids

heif-enc can also encode a multi-resolution pyramid stack of images. In this case, you just have to specify the input images for each resolution layer on the command line and provide the option --add-pyramid-group.

This also works with tiled images in each pyramid layer. An example command line would be:

heif-enc --tiled-input layer1-001-001.jpg layer2-01-01.jpg layer3-01-01.jpg -o output.heic --add-pyramid-group

The input layer images can be specified in any order, heif-enc will take care to sort them by size and add them in the correct order to the pyramid group.