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 along with axios

<script src="pixelbin.v2.0.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 | | -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- | | pixelbinUrl (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 |

Returns:

| 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 | | | filePath | Path to the file on Pixelbin storage | /path/to/image.jpeg | | baseUrl (string) | Base url | https://cdn.pixelbin.io/ |

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"
// }

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 | | | filePath | Path to the file on Pixelbin storage | /path/to/image.jpeg | | baseUrl (string) | Base url | https://cdn.pixelbin.io/ |

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

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 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);

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. 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 |

Usage Example

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

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 |

Usage Example

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

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 | integer | 1 | | flat | integer | 1 | | jagged | integer | 2 |

Usage Example

const t = sharpen({
    sigma: 1,
    flat: 1,
    jagged: 2,
});

Supported Configuration

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

Usage Example

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

Supported Configuration

| parameter | type | defaults | | --------- | ------- | -------- | | sigma | integer | 1 |

Usage Example

const t = blur({
    sigma: 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 | integer | 1 | | saturation | integer | 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 | jpeg |

Usage Example

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

Supported Configuration

| parameter | type | defaults | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | mode | enum : overlay , underlay | overlay | | image | file | `` | | 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 |

Usage Example

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

2. RemoveBG

Usage Example

const t = bg({});

3. EraseBG

Supported Configuration

| parameter | type | defaults | | ------------ | ------------------------------ | --------- | | industryType | enum : general , ecommerce | general |

Usage Example

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

4. SuperResolution

Supported Configuration

| parameter | type | defaults | | --------- | ------------------ | -------- | | type | enum : 2x , 4x | 2x |

Usage Example

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

5. ArtifactRemoval

Usage Example

const t = remove({});

6. WatermarkRemoval

Usage Example

const t = remove({});

7. AWSRekognition

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,
});

8. GoogleVision

Supported Configuration

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

Usage Example

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