remove.bg - npm Package Compare versions

Comparing version 1.1.0 to 1.2.0

dist/index.d.ts

@@ -1,18 +0,81 @@
-interface RemoveBgOptions {
-    apiKey: string;
+interface RemoveBgApiOptions {
     /**
-     * Output resolution.
-     * "regular" default (up to 0.25 megapixels), which costs 1 credit.
-     * "medium" (up to 1.5 megapixels) costs 3.
-     * "hd" (up to 4 megapixels) costs 5.
-     * "4k" (up to 10 megapixels) costs 8.
+     * Maximum output image resolution:
+     * "preview" / "small" / "regular" (default) = Resize image to 0.25 megapixels (e.g. 625×400 pixels) – 0.25 credits per image,
+     * "full" / "4k" = Use original image resolution, up to 25 megapixels (e.g. 6250x4000) with formats ZIP or JPG, or up to 10 megapixels (e.g. 4000x2500) with PNG – 1 credit per image),
+     * "auto" = Use highest available resolution (based on image size and available credits).
+     * For backwards-compatibility this parameter also accepts the values "medium" (up to 1.5 megapixels) and "hd" (up to 4 megapixels) for 1 credit per image.
+     * Note that 'any' was added for future compatibility-sake.
      */
-    size?: "regular" | "medium" | "hd" | "4k";
+    size?: "preview" | "small" | "regular" | "medium" | "full" | "auto" | "hd" | "4k" | any;
     /**
      * Help the API a little by telling the type of image you want to extract the background from.
      * Defaults to "auto".
+     * Note that 'any' was added for future compatibility-sake.
      */
-    type?: "auto" | "person" | "product";
+    type?: "auto" | "person" | "product" | "car" | any;
+    /**
+     * Result image format: "auto" = Use PNG format if transparent regions exists, otherwise use JPG format (default),
+     * "png" = PNG format with alpha transparency,
+     * "jpg" = JPG format, no transparency,
+     * "zip" = ZIP format, contains color image and alpha matte image, supports transparency.
+     */
+    format?: "auto" | "png" | "jpg" | "zip";
+    /**
+     * Scales the subject relative to the total image size.
+     * Can be any value from "10%" to "100%", or "original" (default).
+     * Scaling the subject implies "position=center" (unless specified otherwise).
+     */
+    scale?: string;
+    /**
+     * Positions the subject within the image canvas.
+     * Can be "original" (default unless "scale" is given),
+     * "center" (default when "scale" is given)
+     * or a value from "0%" to "100%" (both horizontal and vertical) or two values (horizontal, vertical).
+     */
+    position?: string;
+    /**
+     * The file to save to.
+     * Alternatively, you can access the result via the result object's `base64img` property.
+     */
     outputFile?: string;
+    /**
+     * Region of interest: Only contents of this rectangular region can be detected as foreground.
+     * Everything outside is considered background and will be removed.
+     * The rectangle is defined as two x/y coordinates in the format "<x1> <y1> <x2> <y2>".
+     * The coordinates can be in absolute pixels (suffix 'px') or relative to the width/height of the image (suffix '%').
+     * By default, the whole image is the region of interest ("0% 0% 100% 100%").
+     */
+    roi?: string;
+    /**
+     * Whether to crop off all empty regions (default: false).
+     * Note that cropping has no effect on the amount of charged credits.
+     */
+    crop?: boolean;
+    /**
+     * Adds a margin around the cropped subject (default: 0).
+     * Can be an absolute value (e.g. "30px") or relative to the subject size (e.g. "10%").
+     * Can be a single value (all sides), two values (top/bottom and left/right) or four values (top, right, bottom, left).
+     * This parameter only has an effect when "crop=true".
+     * The maximum margin that can be added on each side is 50% of the subject dimensions or 500 pixels.
+     */
+    crop_margin?: string;
+    /**
+     * Adds a solid color background.
+     * Can be a hex color code (e.g. 81d4fa, fff) or a color name (e.g. green).
+     * For semi-transparency, 4-/8-digit hex codes are also supported (e.g. 81d4fa77).
+     * (If this parameter is present, the other bg_ parameters must be empty.)
+     */
+    bg_color?: string;
+    /**
+     * Adds a background image from a URL.
+     * The image is centered and resized to fill the canvas while preserving the aspect ratio,
+     * unless it already has the exact same dimensions as the foreground image.
+     * (If this parameter is present, the other "bg_" parameters must be empty.)
+     */
+    bg_image_url?: string;
 }
+interface RemoveBgOptions extends RemoveBgApiOptions {
+    apiKey: string;
+}
 export interface RemoveBgUrlOptions extends RemoveBgOptions {
@@ -28,7 +91,38 @@ url: string;
 export interface RemoveBgResult {
+    /**
+     * The result image, represented as a base64 encoded string.
+     */
     base64img: string;
+    /**
+     * Amount of credits charged for this call.
+     */
     creditsCharged: number;
-    detectedType: "product" | "person";
+    /**
+     * Detected foreground type.
+     */
+    detectedType: "product" | "person" | "animal" | "car" | "other" | any;
+    /**
+     * Width of the result image..
+     */
     resultWidth: number;
+    /**
+     * Height of the result image.
+     */
     resultHeight: number;
+    /**
+     * Total rate limit in megapixel images.
+     */
+    rateLimit: number;
+    /**
+     * Remaining rate limit for this minute.
+     */
+    rateLimitRemaining: number;
+    /**
+     * Unix timestamp when rate limit will reset.
+     */
+    rateLimitReset: number;
+    /**
+     * Seconds until rate limit will reset (only present if rate limit exceeded).
+     */
+    retryAfter?: number;
 }
@@ -35,0 +129,0 @@ export interface RemoveBgError {

dist/index.js

@@ -17,9 +17,7 @@ "use strict";
     return new Promise((resolve, reject) => {
+        const requestOptions = getRequestOptions(options);
+        requestOptions["image_url"] = options.url;
         getPost(options)
             .header("Content-Type", "application/json")
-            .send({
-            "image_url": options.url,
-            "size": options.size || "regular",
-            "type": options.type || "auto"
-        })
+            .send(requestOptions)
             .end(result => processResult(result, options, resolve, reject));
@@ -32,5 +30,8 @@ });
         return new Promise((resolve, reject) => {
-            getPost(options)
-                .field("size", options.size || "regular")
-                .field("type", options.type || "auto")
+            const request = getPost(options);
+            const requestOptions = getRequestOptions(options);
+            for (let k in requestOptions) {
+                request.field(k, requestOptions[k]);
+            }
+            request
                 .attach("image_file", fs.createReadStream(options.path))
@@ -44,9 +45,7 @@ .end(result => processResult(result, options, resolve, reject));
     return new Promise((resolve, reject) => {
+        const requestOptions = getRequestOptions(options);
+        requestOptions["image_file_b64"] = options.base64img;
         getPost(options)
             .header("Content-Type", "application/json")
-            .send({
-            "image_file_b64": options.base64img,
-            "size": options.size || "regular",
-            "type": options.type || "auto"
-        })
+            .send(requestOptions)
             .end(result => processResult(result, options, resolve, reject));
@@ -56,2 +55,15 @@ });
 exports.removeBackgroundFromImageBase64 = removeBackgroundFromImageBase64;
+function getRequestOptions(options) {
+    return {
+        "size": options.size || "preview",
+        "type": options.type || "auto",
+        "scale": options.scale,
+        "position": options.position,
+        "crop": options.crop === true,
+        "crop_margin": options.crop_margin,
+        "roi": options.roi,
+        "bg_color": options.bg_color,
+        "bg_image_url": options.bg_image_url
+    };
+}
 function getPost(options) {
@@ -74,9 +86,13 @@ return unirest
                 resultWidth: result.headers["x-width"],
-                resultHeight: result.headers["x-height"]
+                resultHeight: result.headers["x-height"],
+                rateLimit: result.headers["x-ratelimit-limit"],
+                rateLimitRemaining: result.headers["x-ratelimit-remaining"],
+                rateLimitReset: result.headers["x-ratelimit-reset"],
+                retryAfter: result.headers["retry-after"]
             });
         }
         else {
-            reject((result.body.errors ? result.body.errors : result.body));
+            reject((result.body && result.body.errors ? result.body.errors : result.body));
         }
     });
 }

index.d.ts

@@ -1,18 +0,81 @@
-interface RemoveBgOptions {
-    apiKey: string;
+interface RemoveBgApiOptions {
     /**
-     * Output resolution.
-     * "regular" default (up to 0.25 megapixels), which costs 1 credit.
-     * "medium" (up to 1.5 megapixels) costs 3.
-     * "hd" (up to 4 megapixels) costs 5.
-     * "4k" (up to 10 megapixels) costs 8.
+     * Maximum output image resolution:
+     * "preview" / "small" / "regular" (default) = Resize image to 0.25 megapixels (e.g. 625×400 pixels) – 0.25 credits per image,
+     * "full" / "4k" = Use original image resolution, up to 25 megapixels (e.g. 6250x4000) with formats ZIP or JPG, or up to 10 megapixels (e.g. 4000x2500) with PNG – 1 credit per image),
+     * "auto" = Use highest available resolution (based on image size and available credits).
+     * For backwards-compatibility this parameter also accepts the values "medium" (up to 1.5 megapixels) and "hd" (up to 4 megapixels) for 1 credit per image.
+     * Note that 'any' was added for future compatibility-sake.
      */
-    size?: "regular" | "medium" | "hd" | "4k";
+    size?: "preview" | "small" | "regular" | "medium" | "full" | "auto" | "hd" | "4k" | any;
     /**
      * Help the API a little by telling the type of image you want to extract the background from.
      * Defaults to "auto".
+     * Note that 'any' was added for future compatibility-sake.
      */
-    type?: "auto" | "person" | "product";
+    type?: "auto" | "person" | "product" | "car" | any;
+    /**
+     * Result image format: "auto" = Use PNG format if transparent regions exists, otherwise use JPG format (default),
+     * "png" = PNG format with alpha transparency,
+     * "jpg" = JPG format, no transparency,
+     * "zip" = ZIP format, contains color image and alpha matte image, supports transparency.
+     */
+    format?: "auto" | "png" | "jpg" | "zip";
+    /**
+     * Scales the subject relative to the total image size.
+     * Can be any value from "10%" to "100%", or "original" (default).
+     * Scaling the subject implies "position=center" (unless specified otherwise).
+     */
+    scale?: string;
+    /**
+     * Positions the subject within the image canvas.
+     * Can be "original" (default unless "scale" is given),
+     * "center" (default when "scale" is given)
+     * or a value from "0%" to "100%" (both horizontal and vertical) or two values (horizontal, vertical).
+     */
+    position?: string;
+    /**
+     * The file to save to.
+     * Alternatively, you can access the result via the result object's `base64img` property.
+     */
     outputFile?: string;
+    /**
+     * Region of interest: Only contents of this rectangular region can be detected as foreground.
+     * Everything outside is considered background and will be removed.
+     * The rectangle is defined as two x/y coordinates in the format "<x1> <y1> <x2> <y2>".
+     * The coordinates can be in absolute pixels (suffix 'px') or relative to the width/height of the image (suffix '%').
+     * By default, the whole image is the region of interest ("0% 0% 100% 100%").
+     */
+    roi?: string;
+    /**
+     * Whether to crop off all empty regions (default: false).
+     * Note that cropping has no effect on the amount of charged credits.
+     */
+    crop?: boolean;
+    /**
+     * Adds a margin around the cropped subject (default: 0).
+     * Can be an absolute value (e.g. "30px") or relative to the subject size (e.g. "10%").
+     * Can be a single value (all sides), two values (top/bottom and left/right) or four values (top, right, bottom, left).
+     * This parameter only has an effect when "crop=true".
+     * The maximum margin that can be added on each side is 50% of the subject dimensions or 500 pixels.
+     */
+    crop_margin?: string;
+    /**
+     * Adds a solid color background.
+     * Can be a hex color code (e.g. 81d4fa, fff) or a color name (e.g. green).
+     * For semi-transparency, 4-/8-digit hex codes are also supported (e.g. 81d4fa77).
+     * (If this parameter is present, the other bg_ parameters must be empty.)
+     */
+    bg_color?: string;
+    /**
+     * Adds a background image from a URL.
+     * The image is centered and resized to fill the canvas while preserving the aspect ratio,
+     * unless it already has the exact same dimensions as the foreground image.
+     * (If this parameter is present, the other "bg_" parameters must be empty.)
+     */
+    bg_image_url?: string;
 }
+interface RemoveBgOptions extends RemoveBgApiOptions {
+    apiKey: string;
+}
 export interface RemoveBgUrlOptions extends RemoveBgOptions {
@@ -28,7 +91,38 @@ url: string;
 export interface RemoveBgResult {
+    /**
+     * The result image, represented as a base64 encoded string.
+     */
     base64img: string;
+    /**
+     * Amount of credits charged for this call.
+     */
     creditsCharged: number;
-    detectedType: "product" | "person";
+    /**
+     * Detected foreground type.
+     */
+    detectedType: "product" | "person" | "animal" | "car" | "other" | any;
+    /**
+     * Width of the result image..
+     */
     resultWidth: number;
+    /**
+     * Height of the result image.
+     */
     resultHeight: number;
+    /**
+     * Total rate limit in megapixel images.
+     */
+    rateLimit: number;
+    /**
+     * Remaining rate limit for this minute.
+     */
+    rateLimitRemaining: number;
+    /**
+     * Unix timestamp when rate limit will reset.
+     */
+    rateLimitReset: number;
+    /**
+     * Seconds until rate limit will reset (only present if rate limit exceeded).
+     */
+    retryAfter?: number;
 }
@@ -35,0 +129,0 @@ export interface RemoveBgError {

index.js

@@ -17,9 +17,7 @@ "use strict";
     return new Promise((resolve, reject) => {
+        const requestOptions = getRequestOptions(options);
+        requestOptions["image_url"] = options.url;
         getPost(options)
             .header("Content-Type", "application/json")
-            .send({
-            "image_url": options.url,
-            "size": options.size || "regular",
-            "type": options.type || "auto"
-        })
+            .send(requestOptions)
             .end(result => processResult(result, options, resolve, reject));
@@ -32,5 +30,8 @@ });
         return new Promise((resolve, reject) => {
-            getPost(options)
-                .field("size", options.size || "regular")
-                .field("type", options.type || "auto")
+            const request = getPost(options);
+            const requestOptions = getRequestOptions(options);
+            for (let k in requestOptions) {
+                request.field(k, requestOptions[k]);
+            }
+            request
                 .attach("image_file", fs.createReadStream(options.path))
@@ -44,9 +45,7 @@ .end(result => processResult(result, options, resolve, reject));
     return new Promise((resolve, reject) => {
+        const requestOptions = getRequestOptions(options);
+        requestOptions["image_file_b64"] = options.base64img;
         getPost(options)
             .header("Content-Type", "application/json")
-            .send({
-            "image_file_b64": options.base64img,
-            "size": options.size || "regular",
-            "type": options.type || "auto"
-        })
+            .send(requestOptions)
             .end(result => processResult(result, options, resolve, reject));
@@ -56,2 +55,15 @@ });
 exports.removeBackgroundFromImageBase64 = removeBackgroundFromImageBase64;
+function getRequestOptions(options) {
+    return {
+        "size": options.size || "preview",
+        "type": options.type || "auto",
+        "scale": options.scale,
+        "position": options.position,
+        "crop": options.crop === true,
+        "crop_margin": options.crop_margin,
+        "roi": options.roi,
+        "bg_color": options.bg_color,
+        "bg_image_url": options.bg_image_url
+    };
+}
 function getPost(options) {
@@ -74,9 +86,13 @@ return unirest
                 resultWidth: result.headers["x-width"],
-                resultHeight: result.headers["x-height"]
+                resultHeight: result.headers["x-height"],
+                rateLimit: result.headers["x-ratelimit-limit"],
+                rateLimitRemaining: result.headers["x-ratelimit-remaining"],
+                rateLimitReset: result.headers["x-ratelimit-reset"],
+                retryAfter: result.headers["retry-after"]
             });
         }
         else {
-            reject((result.body.errors ? result.body.errors : result.body));
+            reject((result.body && result.body.errors ? result.body.errors : result.body));
         }
     });
 }

package.json

 {
   "name": "remove.bg",
-  "version": "1.1.0",
-  "description": "A simple wrapper for the remove.bg API",
+  "version": "1.2.0",
+  "description": "A simple but effective wrapper for the remove.bg API",
   "main": "dist/index.js",
@@ -12,3 +12,5 @@ "types": "dist/index.d.ts",
     "test-remove-from-file": "npm run before-test && node examples/removeFromFile.js",
-    "test-remove-from-base64": "npm run before-test && node examples/removeFromBase64.js"
+    "test-remove-from-base64": "npm run before-test && node examples/removeFromBase64.js",
+    "test-remove-from-file-with-crop-and-scale": "npm run before-test && node examples/removeFromFileWithCropAndScale.js",
+    "test-remove-from-file-with-new-background": "npm run before-test && node examples/removeFromFileWithNewBackground.js"
   },
@@ -15,0 +17,0 @@ "repository": {

README.md

@@ -30,14 +30,22 @@ # [remove.bg](https://www.remove.bg) API wrapper for Node.js
 
-Curious how to use `async/await`? That's another reason to check out those examples.
-
 ## API
 The common **input parameters** of all three currently supported `removeBackgroundFrom*` functions are:
 
-| Property | Mandatory | Type | Description |
-| --- | --- | --- | --- |
-| apiKey | Y | `string` | The API key you got from the [remove.bg website](https://www.remove.bg/api). |
-| size | N | `"regular"` / `"medium"` / `"hd"` / `"4k"` | The returned size of the image. The cheaper `"regular"` option is default. |
-| type | N | `"auto"` / `"person"` / `"product"` | Help the API a little by telling the type of image you want to extract the background from. Default `"auto"`. |
-| outputFile | N | `string` | The path to save the returned file to. |
+Only the `apiKey` property is mandatory.
 
+| Property | Type | Description |
+| --- | --- | --- |
+| apiKey | `string` | The API key you got from the [remove.bg website](https://www.remove.bg/api).
+| size | `"preview"` (or `"small"` / `"regular"`) / `"full"` (or `"4k"`) / `"medium"` / `"hd"` / `"auto"` | The returned size of the image. The cheaper `"preview"` option is default, while `"auto"` uses the highest available resolution (based on image size and available credits.
+| type | `"auto"` / `"person"` / `"product"` / `"car"` | Help the API a little by telling the type of image you want to extract the background from. Default `"auto"`.
+| format | `"auto"` / `"png"` / `"jpg"` / `"zip"` | Result image format, the default is `"auto"` which produces a `.png` if transparentcy is detected and `.jpg` otherwise.
+| scale | `string` | Scales the subject relative to the total image size. Can be any value from `"10%"` to `"100%"`, or `"original"` (default). Scaling the subject implies "position=center" (unless specified otherwise).
+| position | `string` | Positions the subject within the image canvas. Can be "original" (default unless "scale" is given), "center" (default when "scale" is given) or a value from "0%" to "100%" (both horizontal and vertical) or two values (horizontal, vertical).
+| crop | `boolean` | Whether to crop off all empty regions (default: `false`). Note that cropping has no effect on the amount of charged credits.
+| crop_margin | `string` | Adds a margin around the cropped subject (default: `0`). Can be an absolute value (e.g. `"30px"`) or relative to the subject size (e.g. `"10%"`). Can be a single value (all sides), two values (top/bottom and left/right) or four values (top, right, bottom, left). This parameter only has an effect when `crop` is `true`.
+| roi | `string` | Region of interest: Only contents of this rectangular region can be detected as foreground. Everything outside is considered background and will be removed. The rectangle is defined as two x/y coordinates in the format `"<x1> <y1> <x2> <y2>"`. The coordinates can be in absolute pixels (suffix 'px') or relative to the width/height of the image (suffix '%'). By default, the whole image is the region of interest (`"0% 0% 100% 100%"`).
+| bg_color | `string` | Adds a solid color background. Can be a hex color code (e.g. `"81d4fa"`, `"fff"`) or a color name (e.g. `"green"`). For semi-transparency, 4-/8-digit hex codes are also supported (e.g. `"81d4fa77"`). (If this parameter is present, the other "bg_" parameters must be empty.)
+| bg_image_url | `string` | Adds a background image from a URL. The image is centered and resized to fill the canvas while preserving the aspect ratio, unless it already has the exact same dimensions as the foreground image. (If this parameter is present, the other "bg_" parameters must be empty.)
+| outputFile | `string` | The path to save the returned file to. Alternatively, you can access the result via the result object's `base64img` property (see below).
+
 And the **output properties** are:
@@ -49,5 +57,9 @@
 | creditsCharged | `number` | Amount of credits charged for this call, based on the output size of the response.
-| detectedType | `string` | Either a `person` or a `product`.
+| detectedType | `string` | Either `person`, `product`, `animal`, `car`, or `other`.
 | resultWidth | `number` | The width of the result image, in pixels.
 | resultHeight | `number` | The height of the result image, in pixels.
+| rateLimit | `number` | Total rate limit in megapixel images.
+| rateLimitRemaining | `number` | Remaining rate limit for this minute.
+| rateLimitReset | `number` | Unix timestamp when rate limit will reset.
+| retryAfter | `number` | Seconds until rate limit will reset (only present if rate limit exceeded).
 
@@ -68,2 +80,3 @@ ### `removeBackgroundFromImageFile`
   type: "auto",
+  scale: "50%",
   outputFile
@@ -78,2 +91,18 @@ }).then((result: RemoveBgResult) => {
 
+Or have a cool `async/await` example to please your inner hipster:
+
+```typescript
+async function myRemoveBgFunction(path: string, outputFile: string) {
+    const result: RemoveBgResult = await removeBackgroundFromImageFile({
+      path,
+      apiKey: "YOUR-API-KEY",
+      size: "regular",
+      type: "person",
+      crop: true,
+      scale: "50%",
+      outputFile
+    });
+}
+```
+
 ### `removeBackgroundFromImageUrl`
@@ -80,0 +109,0 @@ Remove the background from a remote file (URL).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Lines of code

456

increased by93.22%

Number of lines in readme file

151

increased by23.77%

Worsened metrics

Total package byte prevSize

28284

decreased by-89.16%

Number of package files

6

decreased by-14.29%

No dependency changes