Pixelbin Core SDK

Pixelbin Core SDK helps you integrate Pixelbin with your Frontend JS Application.

Installation

npm install @pixelbin/core --save

Usage

Setup

// Import the Pixelbin class
import Pixelbin from "@pixelbin/core";

// Create your instance
const pixelbin = new Pixelbin({
    cloudName: "demo",
    zone: "default", // optional
});

Transform and Optimize Images

// Import transformations
import Pixelbin, { transformations } from "@pixelbin/core";

const EraseBg = transformations.EraseBg;
const Basic = transformations.Basic;

// Create a new instance. If you have't (see above for the details)
const pixelbin = new Pixelbin({
    /*...*/
});

// Create EraseBg.bg transformation
let t1 = EraseBg.bg();

// Create resize transformation
const t2 = Basic.resize({ height: 100, width: 100 });

// create a new image
const demoImage = pixelbin.image("path/to/image"); // File Path on Pixelbin

// Add the transformations to the image
demoImage.setTransformation(t1.pipe(t2));

// Get the image url
console.log(demoImage.getUrl());
// output
// https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/erase.bg()~t.resize(h:100,w:100)/path/to/image

Add Pixelbin to HTML

Add the this distributable in a script tag

<script src="pixelbin.v4.1.0.js"></script>

// Pixelbin is available in the browser as `Pixelbin` on the window object
const pixelbin = new Pixelbin({ cloudName: "demo", zone: "default" });

// create an image with the pixelbin object
const image = pixelbin.image("demoImage.jpeg");

// create a transformation
let t = Pixelbin.transformations.Basic.resize({ height: 100, width: 100 });

// add Transformations to the image
image.setTransformation(t);

// get the url
image.getUrl();
// output
// https://cdn.pixelbin.io/v2/demo/default/t.resize(h:100,w:100)/demoImage.jpeg

Upload images to pixelbin

The SDK provides a upload utility to upload images directly from the browser with a presigned url.

upload(file, signedDetails):

| parameter | type | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | file (File) | File to upload to Pixelbin | | signedDetails (Object) | signedDetails can be generated with the Pixelbin Backend SDK @pixelbin/admin. |

returns: Promise

• Resolves with no response on success.
• Rejects with error on failure.

Example :

1. Define an html file input element

<input type="file" id="fileInput" />

2. Generate the presignedUrl with the backend sdk. click here.

3. Use the response object as is with the upload api as shown below.

const fileInput = document.getElementById("fileInput");
// the signed url and fields can be generated and served with @pixelbin/admin

const handleFileInputEvent = function (e) {
    const file = e.target.files[0];
    Pixelbin.upload(file, signedDetails)
        .then(() => console.log("Uploaded Successfully"))
        .catch((err) => console.log("Error while uploading"));
};
fileInput.addEventListener("change", handleFileInputEvent);

Utilities

Pixelbin provides url utilities to construct and deconstruct Pixelbin urls.

urlToObj

Deconstruct a pixelbin url

| Parameter | Description | Example | | --------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | url (string) | A valid Pixelbin URL | https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg | | opts (Object) | Options for the conversion | Default: { isCustomDomain: false } | | opts.isCustomDomain | Indicates if the URL belongs to a custom domain (default: false) |

Returns:

| Property | Description | Example | | ------------------------- | ---------------------------------------------------- | ------------------------------------- | | baseURL (string) | Base path of the URL | https://cdn.pixelbin.io | | filePath (string) | Path to the file on Pixelbin storage | /path/to/image.jpeg | | version (string) | Version of the URL | v2 | | cloudName (string) | Cloud name from the URL | your-cloud-name | | transformations (array) | A list of transformation objects | [{ "plugin": "t", "name": "flip" }] | | zone (string) | Zone slug from the URL | z-slug | | pattern (string) | Transformation pattern extracted from the URL | t.resize(h:100,w:200)~t.flip() | | worker (boolean) | Indicates if the URL is a URL Translation Worker URL | false | | workerPath (string) | Input path to a URL Translation Worker | resize:w200,h400/folder/image.jpeg | | options (Object) | Query parameters added, such as "dpr" and "f_auto" | { dpr: 2.5, f_auto: true} |

Example:

const pixelbinUrl =
    "https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg";

const obj = Pixelbin.utils.urlToObj(pixelbinUrl);
// obj
// {
//     "cloudName": "your-cloud-name",
//     "zone": "z-slug",
//     "version": "v2",
//     "transformations": [
//         {
//             "plugin": "t",
//             "name": "resize",
//             "values": [
//                 {
//                     "key": "h",
//                     "value": "100"
//                 },
//                 {
//                     "key": "w",
//                     "value": "200"
//                 }
//             ]
//         },
//         {
//             "plugin": "t",
//             "name": "flip",
//         }
//     ],
//     "filePath": "path/to/image.jpeg",
//     "baseUrl": "https://cdn.pixelbin.io",
//     "wrkr": false,
//     "workerPath": "",
//     "options": {}
// }

const customDomainUrl =
    "https://xyz.designify.media/v2/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg";

const obj = Pixelbin.utils.urlToObj(customDomainUrl, { isCustomDomain: true });
// obj
// {
//     "zone": "z-slug",
//     "version": "v2",
//     "transformations": [
//         {
//             "plugin": "t",
//             "name": "resize",
//             "values": [
//                 {
//                     "key": "h",
//                     "value": "100"
//                 },
//                 {
//                     "key": "w",
//                     "value": "200"
//                 }
//             ]
//         },
//         {
//             "plugin": "t",
//             "name": "flip",
//         }
//     ],
//     "filePath": "path/to/image.jpeg",
//     "baseUrl": "https://xyz.designify.media",
//     "wrkr": false,
//     "workerPath": "",
//     "options": {}
// }

const workerUrl =
    "https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/wrkr/resize:h100,w:200/folder/image.jpeg";

const obj = Pixelbin.utils.urlToObj(pixelbinUrl);
// obj
// {
//     "cloudName": "your-cloud-name",
//     "zone": "z-slug",
//     "version": "v2",
//     "transformations": [],
//     "filePath": "",
//     "worker": true,
//     "workerPath": "resize:h100,w:200/folder/image.jpeg",
//     "baseUrl": "https://cdn.pixelbin.io"
//     "options": {}
// }

objToUrl

Converts the extracted url obj to a Pixelbin url.

| Property | Description | Example | | -------------------------- | ---------------------------------------------------- | ------------------------------------- | | cloudName (string) | The cloudname extracted from the URL | your-cloud-name | | zone (string) | 6 character zone slug | z-slug | | version (string) | CDN API version | v2 | | transformations (array) | Extracted transformations from the URL | [{ "plugin": "t", "name": "flip" }] | | filePath (string) | Path to the file on Pixelbin storage | /path/to/image.jpeg | | baseUrl (string) | Base URL | https://cdn.pixelbin.io/ | | isCustomDomain (boolean) | Indicates if the URL is for a custom domain | false | | worker (boolean) | Indicates if the URL is a URL Translation Worker URL | false | | workerPath (string) | Input path to a URL Translation Worker | resize:w200,h400/folder/image.jpeg | | options (Object) | Query parameters added, such as "dpr" and "f_auto" | { "dpr": "2", "f_auto": "true" } |

const obj = {
    cloudName: "your-cloud-name",
    zone: "z-slug",
    version: "v2",
    transformations: [
        {
            plugin: "t",
            name: "resize",
            values: [
                {
                    key: "h",
                    value: "100",
                },
                {
                    key: "w",
                    value: "200",
                },
            ],
        },
        {
            plugin: "t",
            name: "flip",
        },
    ],
    filePath: "path/to/image.jpeg",
    baseUrl: "https://cdn.pixelbin.io",
};
const url = Pixelbin.utils.objToUrl(obj); // obj is as shown above
// url
// https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg

Usage with custom domain

const obj = {
    zone: "z-slug",
    version: "v2",
    transformations: [
        {
            plugin: "t",
            name: "resize",
            values: [
                {
                    key: "h",
                    value: "100",
                },
                {
                    key: "w",
                    value: "200",
                },
            ],
        },
        {
            plugin: "t",
            name: "flip",
        },
    ],
    filePath: "path/to/image.jpeg",
    baseUrl: "https://xyz.designify.media",
    isCustomDomain: true,
};
const url = Pixelbin.utils.objToUrl(obj); // obj is as shown above
// url
// https://xyz.designify.media/v2/z-slug/t.resize(h:100,w:200)~t.flip()/path/to/image.jpeg

Usage with URL Translation Worker

const obj = {
    cloudName: "your-cloud-name",
    zone: "z-slug",
    version: "v2",
    transformations: [],
    filePath: "",
    worker: true,
    workerPath: "resize:h100,w:200/folder/image.jpeg",
    baseUrl: "https://cdn.pixelbin.io",
};
const url = Pixelbin.utils.objToUrl(obj); // obj is as shown above
// url
// https://cdn.pixelbin.io/v2/your-cloud-name/z-slug/wrkr/resize:h100,w:200/folder/image.jpeg

Transformation

A transformation is an operation or a list of operations that can be performed on an image. Please refer list of supported transformations for details.

// import a resize transformation
import Pixelbin, { transformations } from "@pixelbin/core";

const { resize } = transformations.Basic;

// create the resize transformation
const t = resize({ height: 100, width: 100 });

Multiple transformations can be chained by using and on the created transformation object

// import a resize transformation
import Pixelbin, { transformations } from "@pixelbin/core";

const { resize, flip } = transformations.Basic;

// create the basic transformations
const t1 = resize({ height: 100, width: 100 });
const t2 = flip();
const t3 = t1.pipe(t2);

Image

Image class represents an image on Pixelbin.

//To use the url translation worker feature, call image method on the pixelbin object whilst passing `worker` as true;
const image = pixelbin.image("path/to/image", { worker: true });

//To create an Image, call image method on the pixelbin object;
const image = pixelbin.image("path/to/image");

Transformations can be set on an image by using setTransformation on the image object.

image.setTransformation(t);

Note: Transformations won't be applied to the worker URLs generated from the SDK.

To get the url of the image with the applied transformations, use the getUrl on the image object.

image.getUrl();

For a working example, refer here

List of supported transformations

1. DetectBackgroundType

Usage Example

const t = detect({});

2. Artifact

Usage Example

const t = remove({});

3. AWSRekognitionPlugin

Supported Configuration

| parameter | type | defaults | | ----------------- | ------- | -------- | | maximumLabels | integer | 5 | | minimumConfidence | integer | 55 |

Usage Example

const t = detectLabels({
    maximumLabels: 5,
    minimumConfidence: 55,
});

Supported Configuration

| parameter | type | defaults | | ----------------- | ------- | -------- | | minimumConfidence | integer | 55 |

Usage Example

const t = moderation({
    minimumConfidence: 55,
});

4. BackgroundGenerator

Supported Configuration

| parameter | type | defaults | | ------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------ | | backgroundPrompt | custom | cmVhbGlzdGljIGdyZWVuIGdyYXNzLCBsYXduIGZpZWxkIG9mIGdyYXNzLCBibHVlIHNreSB3aXRoIHdoaXRlIGNsb3Vkcw | | backgroundImageForShadow | file | | | focus | enum : `Product` , `Background` | `Product` | | negativePrompt | custom | | | seed | integer | 123 |

Usage Example

const t = bg({
    backgroundPrompt:
        "cmVhbGlzdGljIGdyZWVuIGdyYXNzLCBsYXduIGZpZWxkIG9mIGdyYXNzLCBibHVlIHNreSB3aXRoIHdoaXRlIGNsb3Vkcw",
    backgroundImageForShadow: "",
    focus: "Product",
    negativePrompt: "",
    seed: 123,
});

5. EraseBG

Supported Configuration

| parameter | type | defaults | | ------------ | -------------------------------------- | --------- | | industryType | enum : general , ecommerce , car | general | | addShadow | boolean | false |

Usage Example

const t = bg({
    industryType: "general",
    addShadow: false,
});

6. GoogleVisionPlugin

Supported Configuration

| parameter | type | defaults | | ------------- | ------- | -------- | | maximumLabels | integer | 5 |

Usage Example

const t = detectLabels({
    maximumLabels: 5,
});

7. ImageCentering

Supported Configuration

| parameter | type | defaults | | ------------------ | ------- | -------- | | distancePercentage | integer | 10 |

Usage Example

const t = detect({
    distancePercentage: 10,
});

8. IntelligentCrop

Supported Configuration

| parameter | type | defaults | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | requiredWidth | integer | 0 | | requiredHeight | integer | 0 | | paddingPercentage | integer | 0 | | maintainOriginalAspect | boolean | false | | aspectRatio | string | `` | | gravityTowards | enum : object , foreground , face , none | none | | preferredDirection | enum : north_west , north , north_east , west , center , east , south_west , south , south_east | center | | objectType | enum : airplane , apple , backpack , banana , baseball_bat , baseball_glove , bear , bed , bench , bicycle , bird , boat , book , bottle , bowl , broccoli , bus , cake , car , carrot , cat , cell_phone , chair , clock , couch , cow , cup , dining_table , dog , donut , elephant , fire_hydrant , fork , frisbee , giraffe , hair_drier , handbag , horse , hot_dog , keyboard , kite , knife , laptop , microwave , motorcycle , mouse , orange , oven , parking_meter , person , pizza , potted_plant , refrigerator , remote , sandwich , scissors , sheep , sink , skateboard , skis , snowboard , spoon , sports_ball , stop_sign , suitcase , surfboard , teddy_bear , tennis_racket , tie , toaster , toilet , toothbrush , traffic_light , train , truck , tv , umbrella , vase , wine_glass , zebra | person |

Usage Example

const t = crop({
    requiredWidth: 0,
    requiredHeight: 0,
    paddingPercentage: 0,
    maintainOriginalAspect: false,
    aspectRatio: "",
    gravityTowards: "none",
    preferredDirection: "center",
    objectType: "person",
});

9. ObjectCounter

Usage Example

const t = detect({});

10. NumberPlateDetection

Usage Example

const t = detect({});

11. ObjectDetection

Usage Example

const t = detect({});

12. CheckObjectSize

Supported Configuration

| parameter | type | defaults | | ---------------------- | ------- | -------- | | objectThresholdPercent | integer | 50 |

Usage Example

const t = detect({
    objectThresholdPercent: 50,
});

13. TextDetectionandRecognition

Supported Configuration

| parameter | type | defaults | | ---------- | ------- | -------- | | detectOnly | boolean | false |

Usage Example

const t = extract({
    detectOnly: false,
});

14. PdfWatermarkRemoval

Usage Example

const t = remove({});

15. ProductTagging

Usage Example

const t = tag({});

16. CheckProductVisibility

Usage Example

const t = detect({});

17. RemoveBG

Usage Example

const t = bg({});

18. Basic

Supported Configuration

| parameter | type | defaults | | ---------- | ----------------------------------------------------------------------------------------------------------------- | ---------- | | height | integer | 0 | | width | integer | 0 | | fit | enum : cover , contain , fill , inside , outside | cover | | background | color | 000000 | | position | enum : top , bottom , left , right , right_top , right_bottom , left_top , left_bottom , center | center | | algorithm | enum : nearest , cubic , mitchell , lanczos2 , lanczos3 | lanczos3 | | dpr | float | 1 |

Usage Example

const t = resize({
    height: 0,
    width: 0,
    fit: "cover",
    background: "000000",
    position: "center",
    algorithm: "lanczos3",
    dpr: 1,
});

Supported Configuration

| parameter | type | defaults | | --------- | ------- | -------- | | quality | integer | 80 |

Usage Example

const t = compress({
    quality: 80,
});

Supported Configuration

| parameter | type | defaults | | ---------- | ---------------------------------------------------- | ---------- | | top | integer | 10 | | left | integer | 10 | | bottom | integer | 10 | | right | integer | 10 | | background | color | 000000 | | borderType | enum : constant , replicate , reflect , wrap | constant | | dpr | float | 1 |

Usage Example

const t = extend({
    top: 10,
    left: 10,
    bottom: 10,
    right: 10,
    background: "000000",
    borderType: "constant",
    dpr: 1,
});

Supported Configuration

| parameter | type | defaults | | --------- | ------- | -------- | | top | integer | 10 | | left | integer | 10 | | height | integer | 50 | | width | integer | 20 |

Usage Example

const t = extract({
    top: 10,
    left: 10,
    height: 50,
    width: 20,
});

Supported Configuration

| parameter | type | defaults | | --------- | ------- | -------- | | threshold | integer | 10 |

Usage Example

const t = trim({
    threshold: 10,
});

Supported Configuration

| parameter | type | defaults | | ---------- | ------- | -------- | | angle | integer | 0 | | background | color | 000000 |

Usage Example

const t = rotate({
    angle: 0,
    background: "000000",
});

Usage Example

const t = flip({});

Usage Example

const t = flop({});

Supported Configuration

| parameter | type | defaults | | --------- | ----- | -------- | | sigma | float | 1.5 |

Usage Example

const t = sharpen({
    sigma: 1.5,
});

Supported Configuration

| parameter | type | defaults | | --------- | ------- | -------- | | size | integer | 3 |

Usage Example

const t = median({
    size: 3,
});

Supported Configuration

| parameter | type | defaults | | --------- | ----- | -------- | | sigma | float | 0.3 | | dpr | float | 1 |

Usage Example

const t = blur({
    sigma: 0.3,
    dpr: 1,
});

Supported Configuration

| parameter | type | defaults | | ---------- | ----- | -------- | | background | color | 000000 |

Usage Example

const t = flatten({
    background: "000000",
});

Usage Example

const t = negate({});

Usage Example

const t = normalise({});

Supported Configuration

| parameter | type | defaults | | --------- | ------- | -------- | | a | integer | 1 | | b | integer | 0 |

Usage Example

const t = linear({
    a: 1,
    b: 0,
});

Supported Configuration

| parameter | type | defaults | | ---------- | ------- | -------- | | brightness | float | 1 | | saturation | float | 1 | | hue | integer | 90 |

Usage Example

const t = modulate({
    brightness: 1,
    saturation: 1,
    hue: 90,
});

Usage Example

const t = grey({});

Supported Configuration

| parameter | type | defaults | | --------- | ----- | -------- | | color | color | 000000 |

Usage Example

const t = tint({
    color: "000000",
});

Supported Configuration

| parameter | type | defaults | | --------- | -------------------------------------------------------- | -------- | | format | enum : jpeg , png , webp , tiff , avif , bmp | jpeg |

Usage Example

const t = toFormat({
    format: "jpeg",
});

Supported Configuration

| parameter | type | defaults | | --------- | ------- | -------- | | density | integer | 300 |

Usage Example

const t = density({
    density: 300,
});

Supported Configuration

| parameter | type | defaults | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | mode | enum : overlay , underlay , wrap | overlay | | image | file | | | transformation | custom | | | background | color | 00000000 | | height | integer | 0 | | width | integer | 0 | | top | integer | 0 | | left | integer | 0 | | gravity | enum : northwest , north , northeast , east , center , west , southwest , south , southeast , custom | center | | blend | enum : over , in , out , atop , dest , dest-over , dest-in , dest-out , dest-atop , xor , add , saturate , multiply , screen , overlay , darken , lighten , colour-dodge , color-dodge , colour-burn , color-burn , hard-light , soft-light , difference , exclusion | over | | tile | boolean | false | | listOfBboxes | bboxList | | | listOfPolygons | polygonList | |

Usage Example

const t = merge({
    mode: "overlay",
    image: "",
    transformation: "",
    background: "00000000",
    height: 0,
    width: 0,
    top: 0,
    left: 0,
    gravity: "center",
    blend: "over",
    tile: false,
    listOfBboxes: null,
    listOfPolygons: null,
});

19. SuperResolution

Supported Configuration

| parameter | type | defaults | | ----------- | ------------------ | -------- | | type | enum : 2x , 4x | 2x | | enhanceFace | boolean | false |

Usage Example

const t = upscale({
    type: "2x",
    enhanceFace: false,
});

20. ViewDetection

Usage Example

const t = detect({});

21. WatermarkRemoval

Supported Configuration

| parameter | type | defaults | | ---------- | ------- | ------------- | | removeText | boolean | false | | removeLogo | boolean | false | | box1 | string | 0_0_100_100 | | box2 | string | 0_0_0_0 | | box3 | string | 0_0_0_0 | | box4 | string | 0_0_0_0 | | box5 | string | 0_0_0_0 |

Usage Example

const t = remove({
    removeText: false,
    removeLogo: false,
    box1: "0_0_100_100",
    box2: "0_0_0_0",
    box3: "0_0_0_0",
    box4: "0_0_0_0",
    box5: "0_0_0_0",
});

22. WatermarkDetection

Supported Configuration

| parameter | type | defaults | | ---------- | ------- | -------- | | detectText | boolean | false |

Usage Example

const t = detect({
    detectText: false,
});