feat: improve pipeline

- add types
- update documents

Author: zhzLuke96

README.md

@@ -94,6 +94,27 @@ const { images, parameters } = await new Pipeline(client)
 
 > For details about extensions, refer to the **Processor Usage** section.
 
+### img2img (or inpainting) with pipeline
+```ts
+const input_image = fs.readFileSync("./input_image.jpg").toString("base64");
+const input_mask = fs.readFileSync("./input_mask.jpg").toString("base64");
+const { images, parameters } = await new Pipeline(client)
+  .model("sdxl.safetensors")
+  .prompt("A beautiful sunset over the mountains")
+  .negative("Low quality, blurry")
+  .sampler("DPM++ 2M")
+  .scheduler("exponential")
+  .size(1024, 768)
+  .steps(35)
+  .cfg(5)
+  .images(input_image)
+  // 👇 inpainting params 👇
+  // .inpainting(InpaintFill.original)
+  // .mask(input_mask)
+  .use(/* extension */)
+  .run();
+```
+
 ## API Usage
 
 ### Documentation

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stable-canvas/sd-webui-a1111-client",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "API client for AUTOMATIC1111/stable-diffusion-webui for Node.js and Browser.",
   "source": "src/main.ts",
   "main": "dist/main.umd.js",

src/pipeline/Pipeline.ts

@@ -1,15 +1,15 @@
-import type {
-  SDWebUIA1111Client,
-  StableDiffusionProcessingImg2Img,
-  StableDiffusionProcessingTxt2Img,
-} from "../client";
+import type { SDWebUIA1111Client } from "../client";
 import { ExtensionScript } from "../extensions";
 import { not } from "../misc";
+import {
+  InpaintFill,
+  Img2imgProcessParams,
+  Txt2imgProcessParams,
+} from "../process";
 import { SDProcessor } from "../process/SDProcessor";
 import { SamplerName, SchedulerName } from "./types";
 
-type RequestBody = StableDiffusionProcessingTxt2Img &
-  StableDiffusionProcessingImg2Img;
+type RequestBody = Img2imgProcessParams & Txt2imgProcessParams;
 type BodyKey = keyof RequestBody;
 type BodyValue<K extends BodyKey> = NonNullable<RequestBody[K]>;
 
@@ -91,62 +91,126 @@ export class Pipeline {
   }
 
   // **** 拓展参数 ****
+
+  /**
+   * Sets the text prompt for image generation.
+   * @param {BodyValue<"prompt">} text - The prompt text.
+   * @returns {this} The pipeline instance.
+   */
   prompt(text: BodyValue<"prompt">) {
     this._write("prompt", text);
     return this;
   }
 
+  /**
+   * Sets the negative prompt to avoid undesired features in the image.
+   * @param {BodyValue<"negative_prompt">} text - The negative prompt text.
+   * @returns {this} The pipeline instance.
+   */
   negative(text: BodyValue<"negative_prompt">) {
     this._write("negative_prompt", text);
     return this;
   }
 
+  /**
+   * Sets the seed value for deterministic image generation.
+   * @param {BodyValue<"seed">} seed - The seed value.
+   * @returns {this} The pipeline instance.
+   */
   seed(seed: BodyValue<"seed">) {
     this._write("seed", seed);
     return this;
   }
 
+  /**
+   * Sets the subseed value for variations in deterministic generation.
+   * @param {BodyValue<"subseed">} seed - The subseed value.
+   * @returns {this} The pipeline instance.
+   */
   subseed(seed: BodyValue<"subseed">) {
     this._write("subseed", seed);
     return this;
   }
 
+  /**
+   * Sets the sampler method used for generating images.
+   * @param {SamplerName} name - The sampler name.
+   * @returns {this} The pipeline instance.
+   */
   sampler(name: SamplerName) {
     this._write("sampler_name", name);
     return this;
   }
 
+  /**
+   * Sets the scheduler method for image generation.
+   * @param {SchedulerName} name - The scheduler name.
+   * @returns {this} The pipeline instance.
+   */
   scheduler(name: SchedulerName) {
     this._write("scheduler", name);
     return this;
   }
 
+  /**
+   * Sets the batch size for image generation.
+   * @param {BodyValue<"batch_size">} size - The batch size.
+   * @returns {this} The pipeline instance.
+   */
   batch(size: BodyValue<"batch_size">) {
     this._write("batch_size", size);
     return this;
   }
 
+  /**
+   * Sets the number of inference steps.
+   * @param {BodyValue<"steps">} steps - The number of steps.
+   * @returns {this} The pipeline instance.
+   */
   steps(steps: BodyValue<"steps">) {
     this._write("steps", steps);
     return this;
   }
 
+  /**
+   * Sets the classifier-free guidance scale.
+   * @param {BodyValue<"cfg_scale">} scale - The CFG scale value.
+   * @returns {this} The pipeline instance.
+   */
   cfg(scale: BodyValue<"cfg_scale">) {
     this._write("cfg_scale", scale);
     return this;
   }
 
+  /**
+   * Sets the image size.
+   * @param {BodyValue<"width">} width - The image width.
+   * @param {BodyValue<"height">} height - The image height.
+   * @returns {this} The pipeline instance.
+   */
   size(width: BodyValue<"width">, height: BodyValue<"height">) {
     this._write("width", width);
     this._write("height", height);
     return this;
   }
 
+  /**
+   * Enables high-resolution image generation.
+   * @param {BodyValue<"enable_hr">} [enable=true] - Whether to enable high-resolution mode.
+   * @returns {this} The pipeline instance.
+   */
   enableHR(enable: BodyValue<"enable_hr"> = true) {
     this._write("enable_hr", enable);
     return this;
   }
 
+  /**
+   * Configures high-resolution settings.
+   * @param {BodyValue<"hr_scale">} scale - The upscaling factor.
+   * @param {BodyValue<"hr_upscaler">} upscaler - The upscaler algorithm.
+   * @param {BodyValue<"hr_second_pass_steps">} [secondPassSteps] - Additional processing steps.
+   * @returns {this} The pipeline instance.
+   */
   hr(
     scale: BodyValue<"hr_scale">,
     upscaler: BodyValue<"hr_upscaler">,
@@ -161,6 +225,12 @@ export class Pipeline {
     return this;
   }
 
+  /**
+   * Overrides some of the processing settings.
+   * @param {BodyValue<"override_settings">} settings - The settings to override.
+   * @param {boolean} [restore_afterwards=false] - Whether to restore the original settings after processing.
+   * @returns {this} The pipeline instance.
+   */
   override(
     settings: BodyValue<"override_settings">,
     restore_afterwards = false
@@ -173,6 +243,13 @@ export class Pipeline {
     return this;
   }
 
+  /**
+   * Sets the model checkpoint to be used for processing.
+   * @param {string} sd_model_checkpoint - The checkpoint identifier for the model.
+   * @param {boolean} [restore_afterwards=false] - Whether to restore the original model checkpoint after processing.
+   * @returns {this} The pipeline instance.
+   */
+
   model(sd_model_checkpoint: string, restore_afterwards = false) {
     this.override(
       { sd_model_checkpoint: sd_model_checkpoint },
@@ -181,6 +258,13 @@ export class Pipeline {
     return this;
   }
 
+  /**
+   * Sets the script to be used for processing.
+   *
+   * @param {BodyValue<"script_name">} name - The name of the script.
+   * @param {BodyValue<"script_args">} [args] - Optional arguments for the script.
+   * @returns {this} The pipeline instance.
+   */
   script(name: BodyValue<"script_name">, args?: BodyValue<"script_args">) {
     this._write("script_name", name);
     if (args) {
@@ -189,36 +273,78 @@ export class Pipeline {
     return this;
   }
 
+  /**
+   * Controls whether images are saved to disk or not.
+   * @param {BodyValue<"save_images">} [save=true] - Whether to save images.
+   * @returns {this} The pipeline instance.
+   */
   saveImages(save: BodyValue<"save_images"> = true) {
     this._write("save_images", save);
     return this;
   }
 
+  /**
+   * Controls whether generated images are sent back to the client or not.
+   * @param {BodyValue<"send_images">} [send=true] - Whether to send images.
+   * @returns {this} The pipeline instance.
+   */
   sendImages(send: BodyValue<"send_images"> = true) {
     this._write("send_images", send);
     return this;
   }
 
+  /**
+   * Sets the denoising strength for image processing.
+   * @param {BodyValue<"denoising_strength">} value - The denoising strength value.
+   * @returns {this} The pipeline instance.
+   */
+
   strength(value: BodyValue<"denoising_strength">) {
     this._write("denoising_strength", value);
     return this;
   }
 
+  /**
+   * Sets the initial images for image processing.
+   * @param {...BodyValue<"init_images">} images - The initial images.
+   * @returns {this} The pipeline instance.
+   */
   images(...images: BodyValue<"init_images">) {
     this._write("init_images", images);
     return this;
   }
 
+  /**
+   * Sets the resize mode for image processing.
+   * @param {BodyValue<"resize_mode">} mode - The resize mode: 0 to upscale by upscaling_resize amount, 1 to upscale up to upscaling_resize_h x upscaling_resize_w.
+   * @returns {this} The pipeline instance.
+   */
   resizeMode(mode: BodyValue<"resize_mode">) {
     this._write("resize_mode", mode);
     return this;
   }
 
+  /**
+   * Sets the image configuration scale used in image processing.
+   * @param {BodyValue<"image_cfg_scale">} scale - The scale value for image configuration.
+   * @returns {this} The pipeline instance.
+   */
+
   imageCfgScale(scale: BodyValue<"image_cfg_scale">) {
     this._write("image_cfg_scale", scale);
     return this;
   }
 
+  /**
+   * Sets the mask for image processing.
+   * @param {BodyValue<"mask">} mask - The mask image (base64).
+   * @param {Object} [options] - Optional parameters.
+   * @param {BodyValue<"mask_blur_x">} [options.blurX] - The blur value for the mask in the X direction.
+   * @param {BodyValue<"mask_blur_y">} [options.blurY] - The blur value for the mask in the Y direction.
+   * @param {BodyValue<"mask_blur">} [options.blur] - The blur value for the mask.
+   * @param {BodyValue<"mask_round">} [options.round] - Whether to round the mask.
+   * @returns {this} The pipeline instance.
+   */
   mask(
     mask: BodyValue<"mask">,
     {
@@ -231,7 +357,7 @@ export class Pipeline {
       blurY?: BodyValue<"mask_blur_y">;
       blur?: BodyValue<"mask_blur">;
       round?: BodyValue<"mask_round">;
-    }
+    } = {}
   ) {
     this._write("mask", mask);
     if (blurX !== undefined) this._write("mask_blur_x", blurX);
@@ -241,17 +367,28 @@ export class Pipeline {
     return this;
   }
 
+  /**
+   * Configures inpainting settings for image processing.
+   *
+   * @param {BodyValue<"inpainting_fill">} fill - The fill type for inpainting, defaults to original.
+   * @param {Object} [options] - Optional parameters for inpainting.
+   * @param {BodyValue<"inpaint_full_res">} [options.fullRes] - Whether to use full resolution for inpainting.
+   * @param {BodyValue<"inpaint_full_res_padding">} [options.fullResPadding] - Padding to apply when using full resolution.
+   * @param {BodyValue<"inpainting_mask_invert">} [options.maskInvert] - Invert the mask for inpainting.
+   * @returns {this} The pipeline instance.
+   */
+
   inpainting(
-    fill: BodyValue<"inpainting_fill">,
+    fill: BodyValue<"inpainting_fill"> = InpaintFill.original,
     {
       fullRes,
       fullResPadding,
       maskInvert,
     }: {
-      fullRes: BodyValue<"inpaint_full_res">;
+      fullRes?: BodyValue<"inpaint_full_res">;
       fullResPadding?: BodyValue<"inpaint_full_res_padding">;
       maskInvert?: BodyValue<"inpainting_mask_invert">;
-    }
+    } = {}
   ) {
     this._write("inpainting_fill", fill);
     this._write("inpaint_full_res", fullRes);
@@ -262,13 +399,25 @@ export class Pipeline {
     return this;
   }
 
+  /**
+   * Sets the initial noise multiplier.
+   * @param {BodyValue<"initial_noise_multiplier">} value - The initial noise multiplier.
+   * @returns {this} The pipeline instance.
+   */
   initialNoiseMultiplier(value: BodyValue<"initial_noise_multiplier">) {
     this._write("initial_noise_multiplier", value);
     return this;
   }
 
+  /**
+   * Sets the always-on scripts.
+   * @param {BodyValue<"alwayson_scripts">} scripts - The always-on scripts configuration.
+   * @returns {this} The pipeline instance.
+   */
+
   alwaysOnScripts(scripts: BodyValue<"alwayson_scripts">) {
     this._write("alwayson_scripts", scripts);
+
     return this;
   }
 }