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.v6.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.
options (Object)	Additional options for fine-tuning the upload process. Default: { chunkSize: 1 * 1024 * 1024, maxRetries: 2, concurrency: 3 }
chunkSize (Number)	Size of each chunk to upload. Default is 1 megabyte. Recommended chunk size for 3g network - upto 5kb, 4g network - 500kb to 1MB, 5g network - 1MB to 2MB
maxRetries (Number)	Maximum number of retries if an upload fails. Default is 2 retries.
concurrency (Number)	Number of concurrent chunk upload tasks. Default is 3 concurrent chunk uploads.

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, {
        chunkSize: 2 * 1024 * 1024,
        maxRetries: 1,
        concurrency: 2,
    })
        .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

1. detect

Usage Example

const t = detect({});

2. Artifact

1. remove

Usage Example

const t = remove({});

3. AWSRekognitionPlugin

1. detectLabels

Supported Configuration

parameter	type	defaults
maximumLabels	integer	5
minimumConfidence	integer	55

Usage Example

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

2. moderation

Supported Configuration

parameter	type	defaults
minimumConfidence	integer	55

Usage Example

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

4. BackgroundGenerator

1. bg

Supported Configuration

parameter	type	defaults
backgroundPrompt	custom	YSBmb3Jlc3QgZnVsbCBvZiBvYWsgdHJlZXMsd2l0aCBicmlnaHQgbGlnaHRzLCBzdW4gYW5kIGEgbG90IG9mIG1hZ2ljLCB1bHRyYSByZWFsaXN0aWMsIDhr
backgroundImage	file	``
focus	enum : Product , Background	Product
negativePrompt	custom	``
seed	integer	123

Usage Example

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

5. EraseBG

1. bg

Supported Configuration

parameter	type	defaults
industryType	enum : general , ecommerce , car , human	general
addShadow	boolean	false
refine	boolean	true

Usage Example

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

6. GoogleVisionPlugin

1. detectLabels

Supported Configuration

parameter	type	defaults
maximumLabels	integer	5

Usage Example

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

7. ImageCentering

1. detect

Supported Configuration

parameter	type	defaults
distancePercentage	integer	10

Usage Example

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

8. IntelligentCrop

1. crop

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

1. detect

Usage Example

const t = detect({});

10. NSFWDetection

1. detect

Supported Configuration

parameter	type	defaults
minimumConfidence	float	0.5

Usage Example

const t = detect({
    minimumConfidence: 0.5,
});

11. NumberPlateDetection

1. detect

Usage Example

const t = detect({});

12. ObjectDetection

1. detect

Usage Example

const t = detect({});

13. CheckObjectSize

1. detect

Supported Configuration

parameter	type	defaults
objectThresholdPercent	integer	50

Usage Example

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

14. TextDetectionandRecognition

1. extract

Supported Configuration

parameter	type	defaults
detectOnly	boolean	false

Usage Example

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

15. PdfWatermarkRemoval

1. remove

Usage Example

const t = remove({});

16. ProductTagging

1. tag

Usage Example

const t = tag({});

17. CheckProductVisibility

1. detect

Usage Example

const t = detect({});

18. Basic

1. resize

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

2. compress

Supported Configuration

parameter	type	defaults
quality	integer	80

Usage Example

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

3. extend

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

4. extract

Supported Configuration

parameter	type	defaults
top	integer	10
left	integer	10
height	integer	50
width	integer	20
boundingBox	bbox

Usage Example

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

5. trim

Supported Configuration

parameter	type	defaults
threshold	integer	10

Usage Example

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

6. rotate

Supported Configuration

parameter	type	defaults
angle	integer	0
background	color	000000

Usage Example

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

7. flip

Usage Example

const t = flip({});

8. flop

Usage Example

const t = flop({});

9. sharpen

Supported Configuration

parameter	type	defaults
sigma	float	1.5

Usage Example

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

10. median

Supported Configuration

parameter	type	defaults
size	integer	3

Usage Example

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

11. blur

Supported Configuration

parameter	type	defaults
sigma	float	0.3
dpr	float	1

Usage Example

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

12. flatten

Supported Configuration

parameter	type	defaults
background	color	000000

Usage Example

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

13. negate

Usage Example

const t = negate({});

14. normalise

Usage Example

const t = normalise({});

15. linear

Supported Configuration

parameter	type	defaults
a	integer	1
b	integer	0

Usage Example

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

16. modulate

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

17. grey

Usage Example

const t = grey({});

18. tint

Supported Configuration

parameter	type	defaults
color	color	000000

Usage Example

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

19. toFormat

Supported Configuration

parameter	type	defaults
format	enum : jpeg , png , webp , tiff , avif , bmp , heif	jpeg
quality	integer	75

Usage Example

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

20. density

Supported Configuration

parameter	type	defaults
density	integer	300

Usage Example

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

21. merge

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

1. gen

Supported Configuration

parameter	type	defaults
backgroundImage	file
backgroundColor	color	ffffff
shadowAngle	float	120
shadowIntensity	float	0.5

Usage Example

const t = gen({
    backgroundImage: null,
    backgroundColor: "ffffff",
    shadowAngle: 120,
    shadowIntensity: 0.5,
});

20. SuperResolution

1. upscale

Supported Configuration

parameter	type	defaults
type	enum : 2x , 4x	2x
enhanceFace	boolean	false
model	enum : Picasso , Flash	Picasso
enhanceQuality	boolean	false

Usage Example

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

21. ViewDetection

1. detect

Usage Example

const t = detect({});

22. WatermarkRemoval

1. remove

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

23. WatermarkDetection

1. detect

Supported Configuration

parameter	type	defaults
detectText	boolean	false

Usage Example

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