add support for generative background replace (#55)

Author: lisa-kuzmina

.gitignore

@@ -14,3 +14,6 @@ pcakage-lock.json
 __DOCS__/JSDocTemplate/examples
 devTools/sanity/results.json
 .DS_Store
+
+# Prettier
+.prettierignore

__TESTS__/unit/actions/Effect.test.ts

@@ -52,6 +52,8 @@ describe('Tests for Transformation Action -- Effect', () => {
       .effect(Effect.generativeRestore())
       .effect(Effect.upscale())
       .effect(Effect.enhance())
+      .effect(Effect.generativeBackgroundReplace().prompt("dog"))
+      .effect(Effect.generativeBackgroundReplace())
       .toString();
 
     const expectedToContain = [
@@ -92,7 +94,9 @@ describe('Tests for Transformation Action -- Effect', () => {
       'e_deshake:16',
       'e_gen_restore',
       'e_upscale',
-      'e_enhance'
+      'e_enhance',
+      'e_gen_background_replace:prompt_dog',
+      'e_gen_background_replace'
     ].join('/');
 
     expect(tx).toBe(`${expectedToContain}`);

__TESTS__/unit/fromJson/effect.fromJson.test.ts

@@ -48,7 +48,9 @@ describe('effect.fromJson', () => {
       { actionType: 'generativeRecolor', prompts: ['something', 'else'], toColor: 'blue', detectMultiple: false },
       { actionType: 'generativeRestore' },
       { actionType: 'upscale' },
-      { actionType: 'enhance' }
+      { actionType: 'enhance' },
+      { actionType: 'generativeBackgroundReplace', prompt: 'dog' },
+      { actionType: 'generativeBackgroundReplace'},
     ]});
 
     expect(transformation.toString().split('/')).toStrictEqual([
@@ -97,7 +99,9 @@ describe('effect.fromJson', () => {
       'e_gen_recolor:prompt_(something;else);to-color_blue',
       'e_gen_restore',
       'e_upscale',
-      'e_enhance'
+      'e_enhance',
+      'e_gen_background_replace:prompt_dog',
+      'e_gen_background_replace'
     ]);
   });
 });

__TESTS__/unit/toJson/effect.toJson.test.ts

@@ -486,6 +486,24 @@ describe('Effect toJson()', () => {
     });
   });
 
+  it('effect.GenerativeBackgroundReplace', () => {
+    const transformation = new Transformation()
+      .addAction(Effect.generativeBackgroundReplace().prompt('dog'))
+      .addAction(Effect.generativeBackgroundReplace());
+
+    expect(transformation.toJson()).toStrictEqual({
+      actions: [
+        {
+          actionType: 'generativeBackgroundReplace',
+          prompt: 'dog',
+        },
+        {
+          actionType: 'generativeBackgroundReplace',
+        },
+      ]
+    });
+  });
+
   it('effect.GenerativeRecolor', () => {
     const transformation = new Transformation()
       .addAction(Effect.generativeRecolor('something', 'red'))

src/actions/effect.ts

@@ -30,6 +30,7 @@ import { DropShadow } from "./effect/DropShadow.js";
 import { GenerativeRemove } from "./effect/GenerativeRemove.js";
 import { GenerativeReplace } from "./effect/GenerativeReplace.js";
 import { GenerativeRecolor } from "./effect/GenerativeRecolor.js";
+import { GenerativeBackgroundReplace } from "./effect/GenerativeBackgroundReplace.js";
 
 /**
  * @summary action
@@ -460,6 +461,18 @@ function generativeReplace(): GenerativeReplace {
   return new GenerativeReplace();
 }
 
+/**
+ * @summary action
+ * @description Uses generative AI to replace background of your image with something else.
+ *              {@link https://cloudinary.com/documentation/transformation_reference#e_gen_background_replace|Generative Background Replace}
+ *
+ * @memberOf Actions.Effect
+ * @return {Actions.Effect.GenerativeBackgroundReplace}
+ */
+function generativeBackgroundReplace(): GenerativeBackgroundReplace {
+  return new GenerativeBackgroundReplace();
+}
+
 /**
  * @summary action
  * @description Uses generative AI to recolor objects from your image.
@@ -610,6 +623,7 @@ const Effect = {
   dropShadow,
   generativeRemove,
   generativeReplace,
+  generativeBackgroundReplace,
   generativeRecolor,
   generativeRestore,
   upscale,
@@ -637,6 +651,7 @@ export declare type EffectActions =
   | DropShadow
   | GenerativeRemove
   | GenerativeReplace
+  | GenerativeBackgroundReplace
   | GenerativeRecolor;
 
 export {
@@ -677,6 +692,7 @@ export {
   dropShadow,
   generativeRemove,
   generativeReplace,
+  generativeBackgroundReplace,
   generativeRecolor,
   generativeRestore,
   upscale,

src/actions/effect/GenerativeBackgroundReplace.ts

@@ -0,0 +1,46 @@
+import { Action } from "../../internal/Action.js";
+import { Qualifier } from "../../internal/qualifier/Qualifier.js";
+import { IGenerativeBackgroundReplaceModel } from "../../internal/models/IEffectActionModel.js";
+
+/**
+ * @description Uses generative AI to replace background of your image with something else.
+ * @extends SDK.Action
+ * @memberOf Actions.Effect
+ * @see Visit {@link Actions.Effect|Effect} for an example
+ */
+class GenerativeBackgroundReplace extends Action {
+  private _prompt: string;
+
+  constructor() {
+    super();
+    this._actionModel.actionType = "generativeBackgroundReplace";
+  }
+
+  prompt(value: string): GenerativeBackgroundReplace {
+    this._prompt = value;
+    this._actionModel.prompt = value;
+
+    return this;
+  }
+
+  protected prepareQualifiers(): void {
+    if (!this._prompt) {
+      this.addQualifier(new Qualifier("e", "gen_background_replace"));
+    } else {
+      this.addQualifier(
+        new Qualifier("e", `gen_background_replace:prompt_${this._prompt}`)
+      );
+    }
+  }
+
+  static fromJson(
+    actionModel: IGenerativeBackgroundReplaceModel
+  ): GenerativeBackgroundReplace {
+    const { prompt } = actionModel;
+    const result = new this();
+
+    return result.prompt(prompt);
+  }
+}
+
+export { GenerativeBackgroundReplace };

src/internal/fromJson.ts

@@ -69,9 +69,10 @@ import { BorderAction } from "../actions/border.js";
 import { GenerativeRemove } from "../actions/effect/GenerativeRemove.js";
 import { GenerativeReplace } from "../actions/effect/GenerativeReplace.js";
 import { GenerativeRecolor } from "../actions/effect/GenerativeRecolor.js";
-import {ResizeAdvancedAction} from "../actions/resize/ResizeAdvancedAction.js";
-import {BackgroundColor} from "../actions/background/actions/BackgroundColor.js";
-import {ResizeAutoPadAction} from "../actions/resize/ResizeAutoPadAction.js";
+import { ResizeAdvancedAction } from "../actions/resize/ResizeAdvancedAction.js";
+import { BackgroundColor } from "../actions/background/actions/BackgroundColor.js";
+import { ResizeAutoPadAction } from "../actions/resize/ResizeAutoPadAction.js";
+import { GenerativeBackgroundReplace } from "actions/effect/GenerativeBackgroundReplace.js";
 
 const ActionModelMap: Record<string, IHasFromJson> = {
   scale: ResizeScaleAction,
@@ -149,6 +150,7 @@ const ActionModelMap: Record<string, IHasFromJson> = {
   border: BorderAction,
   generativeRemove: GenerativeRemove,
   generativeReplace: GenerativeReplace,
+  generativeBackgroundReplace: GenerativeBackgroundReplace,
   generativeRecolor: GenerativeRecolor,
   generativeRestore: SimpleEffectAction,
   upscale: SimpleEffectAction,

src/internal/models/IEffectActionModel.ts

@@ -135,6 +135,10 @@ interface IGenerativeReplaceModel extends IActionModel {
   detectMultiple?: boolean;
 }
 
+interface IGenerativeBackgroundReplaceModel extends IActionModel {
+  prompt?: string;
+}
+
 interface IBackgroundColorModel extends IActionModel {
   color?: SystemColors | string;
 }
@@ -163,5 +167,6 @@ export {
   IGenerativeRemoveModel,
   IGenerativeReplaceModel,
   IGenerativeRecolorModel,
+  IGenerativeBackgroundReplaceModel,
   IBackgroundColorModel,
 };