HEIF-converter

Converter for High Efficiency Image Format(HEIF) to other image format

Available formats

JPEG
PNG
WEBP

Download

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

dependencies {
    def latest_version = "3.0.3"

    // Include everything
    implementation("com.github.lincollincol:heif-converter:$latest_version")

    // Or you can add them individually

    // Main library
    implementation("com.github.lincollincol:heif-converter:heifconverter:$latest_version")

    // Optional DSL + extension library
    implementation("com.github.lincollincol:heif-converter:heifconverter-dsl:$latest_version")

    // Optional OkHttp3 HeifDecoder.ImageLoader for loading URLs
    implementation("com.github.lincollincol:heif-converter:imageloader-okhttp3:$latest_version")
}

Usage

Builder syntax

HeifConverter.useContext(this)
    .fromUrl("https://github.com/nokiatech/heif/raw/gh-pages/content/images/crowd_1440x960.heic")
    .withOutputFormat(HeifConverter.Format.PNG)
    .withOutputQuality(100) // optional - default value = 100. Available range (0 .. 100)
    .saveFileWithName("Image_Converted_Name_2") // optional - default value = uuid random string
    .saveResultImage(true) // optional - default value = true
    .convert {
        println(it[HeifConverter.Key.IMAGE_PATH] as String)
        resultImage.setImageBitmap((it[HeifConverter.Key.BITMAP] as Bitmap))
    }

Note

If your source HEIC file is large (for example 4K), then once it is converted into a Bitmap it could potentially be very very large. Large enough to cause a crash if you pass it directly to an ImageView.

Android 9 and lower

If you are using this and need to support Android API 28 (9 Pie) or lower then by default the GlideDecoder will be used. This is because the default decoder uses the Android 10+ API.

Customizing the conversion

Look at HeifConverter.Options to see all the available options and their defaults. Both the builder and DSL-builder provide methods for changing all of the options.

data class Options(
    val input: Input = None,
    val saveResultImage: Boolean = true, // Save the converting Bitmap to the disk
    val outputQuality: Int = 100, // Quality of the saved image 0-100
    val outputFormat: Format = Format.JPEG,
    val outputFileName: String = UUID.randomUUID().toString(),
    val pathToSaveDirectory: File? = null, // Directory to save the converted bitmap
    val decoder: HeicDecoder? = null, // A custom implementation for decoding a HEIC file
    val urlLoader: HeicDecoder.UrlLoader? = null, // A custom url loader for downloading Input.URL
)

saveResultImage function

Set false, if you need bitmap only without saving.
You can skip this function if you want to save converted image, because it is true by default

saveFileWithName function

Use custom file name.
Skip this function if you don't need custom converted image name, because UUID generate unique name by default.

withOutputQuality function

Use this function if you need custom output quality.
Skip this function if you don't need custom output quality, default quality - 100

withOutputFormat function

Set output image format.
Use values from HeifConverter.Format. (Current available: PNG, JPEG, WEBP).

from (Source)

Convert heic image from sources such file, url, bytes, input stream etc.
You can call this function only one time. If you call this function few times - converter will use last called source.

Convert

Lambda, inside convert method, will return map of Objects. If you want to get result bitmap, you need to get value by library key HeifConverter.Key.BITMAP and cast it to Bitmap
If you need path to converted image - use HeifConverter.Key.IMAGE_PATH key and cast map value to String.

DSL + extension syntax

Note: Make sure you include the heifconverter-dsl dependency!

Unlike the above builder syntax which returns a Map<String, Any?> all of the DSL and extension methods return a HeifConverterResult class:

data class HeifConverterResult(
    val bitmap: Bitmap?, // Null if the decode failed but didn't throw an exception
    val imagePath: String?, // Only non-null if `saveResultImage` was true
)

Which you can get by calling HeifConverter.create then convert:

val inputUrl = "https://github.com/nokiatech/heif/raw/gh-pages/content/images/crowd_1440x960.heic"
val converter = HeifConverter.create(this, inputUrl) {
    saveResultImage(true)
    outputFormat(HeifConverter.Format.PNG)
    outputQuality(50)
    outputName("Image_Converted_Name")
}

// Using Coroutines
val (bitmap, imagePath) = converter.convert()
if (bitmap != null) {
    // do something with bitmap
}

// Using Callback
converter.convert(lifecycleScope /* optional coroutine scope */) { (bitmap, imagePath) ->
    if (bitmap != null) {
        // do something with bitmap
    }
}

There are HeifConverter.create extension functions for each input type. File, InputStream , ByteArray, etc.

If you want to skip the step of creating a HeifConverter instance you can use the HeifConverter.convert extensions instead:

val inputUrl = "https://github.com/nokiatech/heif/raw/gh-pages/content/images/crowd_1440x960.heic"
val result = HeifConverter.convert(context, inputUrl) {
    saveResultImage = true
    outputName = "Image_Converted_Name"
    outputDirectory = File(context.cacheDir)
    outputFormat = HeifConverter.Format.JPEG
}

There are HeifConverter.convert extension functions for each input type. File, InputStream , ByteArray, etc.

You can also pass in a HeifConverter.Options object to each of the DSL extensions:

class SampleClass(context: Context) {
    private val convertOptions = HeifConverter.Options.build {
        saveResultImage = true
        outputQuality(50)
        outputDirectory(context.cacheDir)
    }

    suspend fun convertImage(url: String): Bitmap? {
        val result = HeifConverter.create(context, url, convertOptions).convert()
        return result.bitmap
    }
}

Custom Decoder

If you need to customize the HEIC decoding behaviour you can either subclass HeicDecoder.Default or you can create your own HeicDecoder implementation.

class MyDecoder(context: Context) : HeicDecoder.Default(context) {

    override suspend fun fromFile(file: File): Bitmap? {
        // override the default behaviour
    }
}

Or create your own decoder:

class MyDecoder(context: Context) : HeicDecoder {

    override suspend fun fromFile(file: File): Bitmap? {
        // Decode the HEIC file yourself
    }

    // implement the rest
}

Then set it when constructing HeifConverter:

val file: File = File("sample.heic")
HeifConverter.create(contex)
    .fromFile(file)
    .withCustomDecoder(MyDecoder(context))
    .convert { }

Glide decoder

Alongside HeicDecoder.Default there is also GlideHeicDecoder. Which is useful for decoding HEIC on all versions of Android.

Then set the custom decoder when using HeifConverter:

val file: File = File("sample.heic")
HeifConverter.create(contex)
    .fromFile(file)
    .withCustomDecoder(GlideHeicDecoder(context))
    .convert { result -> /* handle result */ }

Here is an example using the DSL:

val (bitmap, imagePath) = HeifConverter.convert(context, file) {
    customDecoder(GlideHeicDecoder(context))
}

If you only want to use the Glide decoder on Android 9 and lower:

val decoder: HeifConverter.HeicDecoder = HeicDecoder.default(context)

val (bitmap, imagePath) = HeifConverter.convert(context, file) {
    customDecoder = decoder
}

Glide and Hardware Bitmaps

Glide has a concept called Hardware Bitmaps. They have the potential to save memory and be quicker. However support is only on Android 9 and above, so keep that in mind.

To enable them you can do:

val decoder = GlideHeicDecoder(context, useHardwareBitmaps = true)

Custom URL loader

By default when using HeifConverter.Input.URL the HeicDecoder.Default uses HttpURLConnection to open a connection to the URL and return a InputStream that gets passed to the HeicDecoder.

If you want to customize this. For example, adding authentication or other custom headers, you have three options:

Customize [HeicDecoder.UrlLoader.Default].
Implement your own HeicDecoder.UrlLoader.
Import and customize the OkHttpUrlLoader.

Customize Default URL loader

You can override HeicDecoder.UrlLoader.Default.download to perform logging or analytics:

class MyImageLoader : HeicDecoder.UrlLoader.Default() {
    override suspend fun download(url: String): InputStream {
        Log.i("Downloading: $url")
        return super.download(url)
    }
}

Or you can customize the [HttpURLConnection] object like so:

class MyImageLoader(private val auth: AuthRepo) : HeicDecoder.UrlLoader.Default() {
    override fun customizeConnection(connection: HttpUrlConnection) {
        val authToken = auth.getAuthToken()
        connection.setRequestProperty("Authorization", "Bearer $authToken")
    }
}

Then set the custom decoder when using HeifConverter:

HeifConverter.create(contex)
    .fromUrl("https://sample.com/image.heic")
    .withUrlLoader(MyImageLoader())
    .convert { result -> /* handle result */ }

OkHttp3 URL loader

If you prefer to use OkHttp instead you can import and use the urlloader-okhttp3 dependency:

implementation("com.github.lincollincol:HEIF-converter:urlloader-okhttp3:$latest_version")

Then set the custom url loader when using HeifConverter:

HeifConverter.create(contex)
    .fromUrl("https://sample.com/image.heic")
    .withUrlLoader(OkHttpUrlLoader())
    .convert { result -> /* handle result */ }