Merge pull request #2 from SDWebImage/feature/encode

Feature: Support JPEG-XL Encoding (HDR/Animated Image as well)

Author: dreampiggy

Example/SDWebImageJPEGXLCoder/SDViewController.m

@@ -9,6 +9,13 @@
 #import "SDViewController.h"
 #import <SDWebImageJPEGXLCoder/SDImageJPEGXLCoder.h>
 #import <SDWebImage/SDWebImage.h>
+#import <libjxl/jxl/encode.h>
+
+static void WriteTempJXLFile(NSData *data, NSString *filename) {
+    NSString *tempOutputPath = [NSTemporaryDirectory() stringByAppendingPathComponent:filename];
+    [data writeToFile:tempOutputPath atomically:YES];
+    NSLog(@"Written encoded JXL to : %@", tempOutputPath);
+}
 
 @interface SDViewController ()
 @property (nonatomic, strong) UIImageView *imageView1;
@@ -34,27 +41,40 @@ - (void)viewDidLoad {
     self.imageView2.contentMode = UIViewContentModeScaleAspectFit;
     [self.view addSubview:self.imageView2];
 
-    NSURL *staticURL = [NSURL URLWithString:@"https://jpegxl.info/logo.jxl"];
-    NSURL *animatedURL = [NSURL URLWithString:@"https://jpegxl.info/anim_jxl_logo.jxl"];
+    NSURL *staticURL = [NSURL URLWithString:@"https://jpegxl.info/images/dice.jxl"];
+    NSURL *animatedURL = [NSURL URLWithString:@"https://jpegxl.info/images/anim-icos.jxl"];
 
     [self.imageView1 sd_setImageWithURL:staticURL placeholderImage:nil options:0 context:nil progress:nil completed:^(UIImage * _Nullable image, NSError * _Nullable error, SDImageCacheType cacheType, NSURL * _Nullable imageURL) {
         if (image) {
             NSLog(@"%@", @"Static JPEG-XL load success");
         }
-        // TODO, JXL encoding
-//        dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
-//            NSUInteger maxFileSize = 4096;
-//            NSData *jxlData = [SDImageJPEGXLCoder.sharedCoder encodedDataWithImage:image format:SDImageFormatJPEGXL options:@{SDImageCoderEncodeMaxFileSize : @(maxFileSize)}];
-//            if (jxlData) {
-//                NSLog(@"%@", @"JPEG-XL encoding success");
-//            }
-//        });
+        // static JXL encoding
+        dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
+            NSUInteger maxFileSize = 4096;
+            NSData *jxlData = [SDImageJPEGXLCoder.sharedCoder encodedDataWithImage:image format:SDImageFormatJPEGXL options:@{SDImageCoderEncodeMaxFileSize : @(maxFileSize)}];
+            if (jxlData) {
+                NSLog(@"Static JPEG-XL encode success, bytes: %lu", (unsigned long)jxlData.length);
+                WriteTempJXLFile(jxlData, imageURL.lastPathComponent);
+            }
+        });
     }];
     [self.imageView2 sd_setImageWithURL:animatedURL placeholderImage:nil completed:^(UIImage * _Nullable image, NSError * _Nullable error, SDImageCacheType cacheType, NSURL * _Nullable imageURL) {
         if (image) {
             NSLog(@"%@", @"Animated JPEG-XL load success");
         }
+        // animated JXL encoding
+        dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
+            NSData *jxlData = [SDImageJPEGXLCoder.sharedCoder encodedDataWithImage:image format:SDImageFormatJPEGXL options:@{
+                SDImageCoderEncodeJXLDistance : @(3.0),
+            }];
+            if (jxlData) {
+                NSLog(@"Animated JPEG-XL encode success, bytes: %lu", (unsigned long)jxlData.length);
+                WriteTempJXLFile(jxlData, imageURL.lastPathComponent);
+            }
+        });
     }];
+    
+    [self testHDREncoding];
 }
 
 - (void)viewWillLayoutSubviews {
@@ -63,6 +83,36 @@ - (void)viewWillLayoutSubviews {
     self.imageView2.frame = CGRectMake(0, self.view.bounds.size.height / 2, self.view.bounds.size.width, self.view.bounds.size.height / 2);
 }
 
+- (void)testHDREncoding {
+    // Test JXL Encode
+    NSURL *HDRURL = [NSURL URLWithString:@"https://ncdn.camarts.cn/iso-hdr-demo.jxl"];
+    NSURLSessionTask *task = [NSURLSession.sharedSession dataTaskWithURL:HDRURL completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
+        UIImage *image = [UIImage imageWithData:data];
+        [self encodeJXLWithImage:image];
+    }];
+    [task resume];
+}
+
+- (void)encodeJXLWithImage:(UIImage *)image {
+    NSCParameterAssert(image);
+    NSDictionary *frameSetting = @{
+        @(JXL_ENC_FRAME_SETTING_EFFORT) : @(7),
+//        @(JXL_ENC_FRAME_SETTING_BROTLI_EFFORT) : @(11)
+    };
+    // fastest encoding speed but largest compressed size, you can adjust options here
+    NSData *data = [SDImageJPEGXLCoder.sharedCoder encodedDataWithImage:image format:SDImageFormatJPEGXL options:@{
+//        SDImageCoderEncodeCompressionQuality : @0.68,
+        SDImageCoderEncodeJXLDistance : @(1.0),
+        SDImageCoderEncodeJXLFrameSetting : frameSetting,
+    }];
+    NSCParameterAssert(data);
+    WriteTempJXLFile(data, @"iso-hdr-demo.jxl");
+    
+    CIImage *ciimage = [CIImage imageWithData:data];
+    NSString *desc = [ciimage description];
+    NSLog(@"Re-decoded JXL CIImage description: %@", desc);
+}
+
 - (void)didReceiveMemoryWarning {
     [super didReceiveMemoryWarning];
     // Dispose of any resources that can be recreated.

README.md

@@ -15,8 +15,8 @@ This coder supports the HDR/SDR decoding, as well as JPEG-XL aniamted image.
 ## Notes
 
 1. This coder supports animation via UIImageView/NSImageView, no SDAnimatedImageView currently (Because the current coder API need codec supports non-sequential frame decoding, but libjxl does not have. Will remove this limit in SDWebImage 6.0)
-2. This coder does not supports JPEG-XL encoding (Because I have no time :))
-3. Apple's ImageIO supports JPEGXL decoding from iOS 17/tvOS 17/watchOS 10/macOS 14 (via: [WWDC2023](https://developer.apple.com/videos/play/wwdc2023/10122/)), so SDWebImage on those platform can also decode JPEGXL images using `SDImageIOCoder` (but no animated JPEG-XL support)
+2. Apple's ImageIO supports JPEGXL decoding from iOS 17/tvOS 17/watchOS 10/macOS 14 (via: [WWDC2023](https://developer.apple.com/videos/play/wwdc2023/10122/)), so SDWebImage on those platform can also decode JPEGXL images using `SDImageIOCoder` (but no animated JPEG-XL support)
+3. From v0.2.0, this coder support JXL encoding, including HDR, static JXL, animated JXL encoding as well (a huge work...)
 
 ## Requirements
 
@@ -102,6 +102,102 @@ imageView.sd_setImage(with: JPEGXLURL)
 
 Note: You can also test animated JPEG-XL on UIImageView/NSImageView and WebImage (via SwiftUI port)
 
+### Decoding
+
++ Objective-C
+
+```objective-c
+// JPEGXL image decoding
+NSData *JPEGXLData;
+UIImage *image = [[SDImageJPEGXLCoder sharedCoder] decodedImageWithData:JPEGXLData options:nil];
+```
+
++ Swift
+
+```swift
+// JPEGXL image decoding
+let JPEGXLData: Data
+let image = SDImageJPEGXLCoder.shared.decodedImage(with: data, options: nil)
+```
+
+### Encoding
+
++ Objective-c
+
+```objective-c
+// JPEGXL image encoding
+UIImage *image;
+NSData *JPEGXLData = [[SDImageJPEGXLCoder sharedCoder] encodedDataWithImage:image format:SDImageFormatJPEGXL options:nil];
+// Encode Quality
+NSData *lossyJPEGXLData = [[SDImageJPEGXLCoder sharedCoder] encodedDataWithImage:image format:SDImageFormatJPEGXL options:@{SDImageCoderEncodeCompressionQuality : @(0.1)}]; // [0, 1] compression quality
+```
+
++ Swift
+
+```swift
+// JPEGXL image encoding
+let image: UIImage
+let JPEGXLData = SDImageJPEGXLCoder.shared.encodedData(with: image, format: .jpegxl, options: nil)
+// Encode Quality
+let lossyJPEGXLData = SDImageJPEGXLCoder.shared.encodedData(with: image, format: .jpegxl, options: [.encodeCompressionQuality: 0.1]) // [0, 1] compression quality
+```
+
+### Animated JPEG-XL Encoding
+
++ Objective-c
+
+```objective-c
+// Animated encoding
+NSMutableArray<SDImageFrames *> *frames = [NSMutableArray array];
+for (size_t i = 0; i < images.count; i++) {
+    SDImageFrame *frame = [SDImageFrame frameWithImage:images[i] duration:0.1];
+    [frames appendObject:frame];
+}
+NSData *animatedData = [[SDImageJPEGXLCoder sharedCoder] encodedDataWithFrames:frames loopCount:0 format:SDImageFormatJPEGXL options:nil];
+```
+
++ Swift
+
+```swift
+// Animated encoding
+var frames: [SDImageFrame] = []
+for i in 0..<images.count {
+    let frame = SDImageFrame(image: images[i], duration: 0.1)
+    frames.append(frame)
+}
+let animatedData = SDImageJPEGXLCoder.shared.encodedData(with: frames, loopCount: 0, format: .jpegxl, options: nil)
+```
+
+### Advanced jxl codec options
+
+For advanced user who want detailed control like `cjxl` command line tool, you can pass the underlying encode options in 
+
++ Objective-C
+
+```objective-c
+NSDictionary *frameSetting = @{
+    @(JXL_ENC_FRAME_SETTING_EFFORT) : @(10),
+    @(JXL_ENC_FRAME_SETTING_BROTLI_EFFORT) : @(11)
+};
+NSData *data = [SDImageJPEGXLCoder.sharedCoder encodedDataWithImage:image format:SDImageFormatJPEGXL options:@{
+    SDImageCoderEncodeJXLDistance : @(3.0), // jxl -distance
+    SDImageCoderEncodeJXLFrameSetting : frameSetting, // jxl -effort
+}];
+```
+
++ Swift
+
+```swift
+let frameSetting = [
+    JXL_ENC_FRAME_SETTING_EFFORT.rawValue : 10,
+    JXL_ENC_FRAME_SETTING_BROTLI_EFFORT.rawValue : 11
+]
+let data = SDImageJPEGXLCoder.shared.encodedData(with: image, format: .jpegxl, options: [
+    .encodeJXLDistance : 3.0, // jxl -distance
+    .encodeJXLFrameSetting : frameSetting, // jxl -effort
+]);
+```
+
 ## Example
 
 To run the example project, clone the repo, and run `pod install` from the root directory first. Then open `SDWebImageJPEGXLCoder.xcworkspace`.

SDWebImageJPEGXLCoder/Classes/SDImageJPEGXLCoder.h

@@ -19,3 +19,57 @@ static const SDImageFormat SDImageFormatJPEGXL = 17; // JPEG-XL
 @property (nonatomic, class, readonly, nonnull) SDImageJPEGXLCoder *sharedCoder;
 
 @end
+
+#pragma mark - JXL Encode Options
+
+/*
+ * Sets the distance level for lossy compression: target max butteraugli
+ * distance, lower = higher quality. Range: 0 .. 25.
+ * 0.0 = mathematically lossless (however, use @ref JxlEncoderSetFrameLossless
+ * instead to use true lossless, as setting distance to 0 alone is not the only
+ * requirement). 1.0 = visually lossless. Recommended range: 0.5 .. 3.0. Default
+ * value: 1.0.
+ * See more in upstream: https://libjxl.readthedocs.io/en/latest/api_encoder.html#_CPPv426JxlEncoderSetFrameDistanceP23JxlEncoderFrameSettingsf
+ * A NSNumber value. The default value is nil.
+ * @note: When you use both `SDImageCoderEncodeCompressionQuality` and this option, this option will override that one and takes effect.
+ */
+FOUNDATION_EXPORT _Nonnull SDImageCoderOption SDImageCoderEncodeJXLDistance;
+
+/**
+ * Enables lossless encoding.
+ * See more in upstream: https://libjxl.readthedocs.io/en/latest/api_encoder.html#_CPPv426JxlEncoderSetFrameLosslessP23JxlEncoderFrameSettings8JXL_BOOL
+ * A NSNumber value. The default value is NO.
+ */
+FOUNDATION_EXPORT _Nonnull SDImageCoderOption SDImageCoderEncodeJXLLoseless;
+
+/**
+ * Sets the feature level of the JPEG XL codestream. Valid values are 5 and
+ * 10, or -1 (to choose automatically). Using the minimum required level, or
+ * level 5 in most cases, is recommended for compatibility with all decoders.
+ * See more in upstream: https://libjxl.readthedocs.io/en/latest/api_encoder.html#_CPPv428JxlEncoderSetCodestreamLevelP10JxlEncoderi
+ * A NSNumber value. The default value is -1.
+ */
+FOUNDATION_EXPORT _Nonnull SDImageCoderOption SDImageCoderEncodeJXLCodeStreamLevel;
+
+/* Pass extra underlying libjxl encoding frame setting. The Value is a NSDictionary, which each key-value pair use`JxlEncoderFrameSettingId` (NSNumber) as key, and NSNumber as value.
+ * See more in upstream: https://libjxl.readthedocs.io/en/latest/api_encoder.html#_CPPv424JxlEncoderFrameSettingId
+ * If you can not impoort the libjxl header, just pass the raw int number as `JxlEncoderFrameSettingId`
+
+ Objc code:
+ ~~~
+ @{SDImageCoderEncodeJXLFrameSetting: @{@JXL_ENC_FRAME_SETTING_EFFORT: @(11)}
+ ~~~
+ 
+ Swift code:
+ ~~~
+ [.encodeJXLFrameSetting : [JxlEncoderFrameSettingId.JXL_ENC_FRAME_SETTING_EFFORT : 11]
+ ~~~
+*/
+FOUNDATION_EXPORT _Nonnull SDImageCoderOption SDImageCoderEncodeJXLFrameSetting;
+
+/**
+ * Set the thread count for multithreading. 0 means using logical CPU core (hw.logicalcpu) to detect threads (like 8 core on M1 Mac/ 4 core on iPhone 16 Pro)
+ * @warning If you're encoding huge or multiple JXL image at the same time, set this value to 1 to avoid huge CPU usage.
+ * A NSNumber value. Defaults to 0, means logical CPU core count. Set to 1 if you want single-thread encoding.
+ */
+FOUNDATION_EXPORT _Nonnull SDImageCoderOption SDImageCoderEncodeJXLThreadCount;