feat: add layer_mode property to overlays and new transformation options

Author: manu4543

lib/imagekitio/helpers/helper.rb

@@ -626,6 +626,10 @@ def safe_get(obj, key)
 
     # Add overlay properties like position, timing, transformations (matching Node.js)
     def add_overlay_properties(parts, overlay)
+      # Add layer_mode property
+      layer_mode = safe_get(overlay, :layer_mode)
+      parts << "lm-#{layer_mode}" if layer_mode
+
       # Add position properties
       position = safe_get(overlay, :position)
       if position

lib/imagekitio/helpers/transformation_utils.rb

@@ -82,6 +82,9 @@ module TransformationUtils
       "unsharp_mask" => "e-usm",
       "unsharpMask" => "e-usm",
       "gradient" => "e-gradient",
+      "color_replace" => "cr",
+      "colorReplace" => "cr",
+      "distort" => "e-distort",
 
       # Other flags & finishing
       "progressive" => "pr",
@@ -109,6 +112,10 @@ module TransformationUtils
       "line_height" => "lh",
       "lineHeight" => "lh",
 
+      # Overlay transformations
+      "layer_mode" => "lm",
+      "layerMode" => "lm",
+
       # Subtitles transformations
       "font_outline" => "fol",
       "fontOutline" => "fol",

test/imagekitio/custom-tests/url-generation/advanced_url_generation_test.rb

@@ -431,6 +431,9 @@ def test_should_generate_the_correct_url_with_many_transformations_including_vid
         sharpen: 10.0,
         unsharp_mask: "2-2-0.8-0.024",
         gradient: "from-red_to-white",
+        # New transformations
+        color_replace: "FF0000_50_0000FF",
+        distort: "p-100_50_200_150_300_250_400_350",
         original: true,
         page: "2_4",
         raw: "h-200,w-300,l-image,i-logo.png,l-end"
@@ -446,7 +449,27 @@ def test_should_generate_the_correct_url_with_many_transformations_including_vid
       )
     )
 
-    expected = "https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,x-10,y-20,xc-30,yc-40,fl-h,o-0.8,z-2,vc-h264,ac-aac,so-5,eo-15,du-10,sr-1440_1080,e-grayscale,e-upscale,e-retouch,e-genvar,e-dropshadow,e-changebg-prompt-car,e-edit-prompt-make it vintage,e-bgremove,e-contrast,e-shadow-bl-15_st-40_x-10_y-N5,e-sharpen-10,e-usm-2-2-0.8-0.024,e-gradient-from-red_to-white,orig-true,pg-2_4,h-200,w-300,l-image,i-logo.png,l-end"
+    expected = "https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,x-10,y-20,xc-30,yc-40,fl-h,o-0.8,z-2,vc-h264,ac-aac,so-5,eo-15,du-10,sr-1440_1080,e-grayscale,e-upscale,e-retouch,e-genvar,e-dropshadow,e-changebg-prompt-car,e-edit-prompt-make it vintage,e-bgremove,e-contrast,e-shadow-bl-15_st-40_x-10_y-N5,e-sharpen-10,e-usm-2-2-0.8-0.024,e-gradient-from-red_to-white,cr-FF0000_50_0000FF,e-distort-p-100_50_200_150_300_250_400_350,orig-true,pg-2_4,h-200,w-300,l-image,i-logo.png,l-end"
+    assert_equal(expected, url)
+  end
+
+  def test_should_generate_the_correct_url_for_radius_with_string_value
+    transformation = [
+      Imagekitio::Models::Transformation.new(
+        radius: "10_20_30_40"
+      )
+    ]
+
+    url = @client.helper.build_url(
+      Imagekitio::Models::SrcOptions.new(
+        src: "/test_path1.jpg",
+        url_endpoint: "https://ik.imagekit.io/test_url_endpoint",
+        transformation_position: :query,
+        transformation: transformation
+      )
+    )
+
+    expected = "https://ik.imagekit.io/test_url_endpoint/test_path1.jpg?tr=r-10_20_30_40"
     assert_equal(expected, url)
   end
 

test/imagekitio/custom-tests/url-generation/overlay_test.rb

@@ -724,6 +724,103 @@ def test_should_properly_encode_overlay_text_when_transformations_are_in_query_p
     assert_equal(expected, url)
   end
 
+  # Layer mode tests
+  def test_should_generate_url_with_image_overlay_and_multiply_layer_mode
+    transformation = [
+      Imagekitio::Models::Transformation.new(
+        overlay: Imagekitio::Models::ImageOverlay.new(
+          input: "overlay.png",
+          layer_mode: :multiply
+        )
+      )
+    ]
+
+    url = @client.helper.build_url(
+      Imagekitio::Models::SrcOptions.new(
+        src: "/base-image.jpg",
+        url_endpoint: "https://ik.imagekit.io/test_url_endpoint",
+        transformation_position: :path,
+        transformation: transformation
+      )
+    )
+
+    expected = "https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-overlay.png,lm-multiply,l-end/base-image.jpg"
+    assert_equal(expected, url)
+  end
+
+  def test_should_generate_url_with_image_overlay_and_displace_layer_mode
+    transformation = [
+      Imagekitio::Models::Transformation.new(
+        overlay: Imagekitio::Models::ImageOverlay.new(
+          input: "displacement-map.png",
+          layer_mode: :displace,
+          position: Imagekitio::Models::OverlayPosition.new(
+            x: "10",
+            y_: "20"
+          )
+        )
+      )
+    ]
+
+    url = @client.helper.build_url(
+      Imagekitio::Models::SrcOptions.new(
+        src: "/base-image.jpg",
+        url_endpoint: "https://ik.imagekit.io/test_url_endpoint",
+        transformation_position: :path,
+        transformation: transformation
+      )
+    )
+
+    expected = "https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-displacement-map.png,lm-displace,lx-10,ly-20,l-end/base-image.jpg"
+    assert_equal(expected, url)
+  end
+
+  def test_should_generate_url_with_image_overlay_and_cutout_layer_mode
+    transformation = [
+      Imagekitio::Models::Transformation.new(
+        overlay: Imagekitio::Models::ImageOverlay.new(
+          input: "mask.png",
+          layer_mode: :cutout
+        )
+      )
+    ]
+
+    url = @client.helper.build_url(
+      Imagekitio::Models::SrcOptions.new(
+        src: "/base-image.jpg",
+        url_endpoint: "https://ik.imagekit.io/test_url_endpoint",
+        transformation_position: :path,
+        transformation: transformation
+      )
+    )
+
+    expected = "https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-mask.png,lm-cutout,l-end/base-image.jpg"
+    assert_equal(expected, url)
+  end
+
+  def test_should_generate_url_with_image_overlay_and_cutter_layer_mode
+    transformation = [
+      Imagekitio::Models::Transformation.new(
+        overlay: Imagekitio::Models::ImageOverlay.new(
+          input: "shape.png",
+          layer_mode: :cutter
+        )
+      )
+    ]
+
+    url = @client.helper.build_url(
+      Imagekitio::Models::SrcOptions.new(
+        src: "/base-image.jpg",
+        url_endpoint: "https://ik.imagekit.io/test_url_endpoint",
+        transformation_position: :path,
+        transformation: transformation
+      )
+    )
+
+    expected = "https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-shape.png,lm-cutter,l-end/base-image.jpg"
+    assert_equal(expected, url)
+  end
+
   # Hash-based API test - verify that plain hashes work for overlays
   def test_should_work_with_plain_hashes_for_text_overlay
     # Using plain hashes for everything including overlay