Detect whether an object in an image is centered

Detect Center transformation allows users to detect whether or not an object in an image is in the center.

This transformation supports png, jpeg, jpg, webp, cr2, nef, rw2, dng, orf, raw, heic, heif, avif, tiff and tif type of files.

The result of Detect Center is a JSON, as shown below:

{
    {
        "data": {
            "output": {
                "is_center": false,
                "distance_x_px": 83,
                "distance_y_px": 19,
                "distance_x_perc": 25,
                "distance_y_perc": 7,
                "original_input_size": "(512, 640, 3)"
            }
        },
        "name": "detect",
        "params": {
            "dist_perc": "10"
        }
    }
}

The JSON keys are explained in the below table:

Property	Description
is_center	The boolean value specifies whether or not an image object is in the center. If the value is true, the image's object is in the center; if the value is false, the image's object is not in the center.
distance_x_px	The distance in pixels between the y-axes drawn from the image's center and the object's center.
distance_y_px	The distance in pixels between the x-axes drawn from the image's center and the object's center.
distance_x_perc	The distance_x_px expressed in percentage is calculated after dividing an image's width in half.
distance_y_perc	The distance_y_px expressed in percentage is calculated after dividing an image's height in half.
original_input_size	A dimension of the input image (height, width, and channel).

note

Instead of getting the output in a traditional CDN URL, you will find the JSON output from the Context API while the CDN URL will return the original image without any modifications.

Original Image

URL

https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/original/images/transformation/water_sprayer.jpeg?v=1744646821354

React

<PixelBinImage
    url="https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/original/images/transformation/water_sprayer.jpeg?v=1744646821354"
/>

JavaScript

import Pixelbin from "@pixelbin/core";

const obj = {
    cloudName: "dummy-cloudname",
    zone: "FIDrmb",
    version: "v2",
    transformations: [],
    filePath: "images/transformation/water_sprayer.jpeg",
    baseUrl: "https://cdn.pixelbin.io",
};

const url = Pixelbin.default.utils.objToUrl(obj);

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/original/images/transformation/water_sprayer.jpeg?v=1744646821354

Node.js

const Pixelbin = require("@pixelbin/admin");

const obj = {
    cloudName: "dummy-cloudname",
    zone: "FIDrmb",
    version: "v2",
    transformations: [],
    filePath: "images/transformation/water_sprayer.jpeg",
    baseUrl: "https://cdn.pixelbin.io",
};

const url = Pixelbin.url.objToUrl(obj);

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/original/images/transformation/water_sprayer.jpeg?v=1744646821354

Python

from pixelbin.utils.url import obj_to_url

obj = {
    "cloudName": "dummy-cloudname",
    "zone": "FIDrmb",
    "version": "v2",
    "transformations": [],
    "filePath": "images/transformation/water_sprayer.jpeg",
    "baseUrl": "https://cdn.pixelbin.io",
}

url = obj_to_url(obj)

# url
# https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/original/images/transformation/water_sprayer.jpeg?v=1744646821354

Golang

package main

import (
 "fmt"
 "github.com/pixelbin-dev/pixelbin-go/v2/sdk/utils/url"
)

func main() {
    obj := map[string]interface{}{
        "cloudName": "dummy-cloudname",
        "zoneSlug": "FIDrmb",
        "version": "v2",
        "transformations": []map[string]interface{}{
            
        },
        "filePath": "images/transformation/water_sprayer.jpeg",
        "baseUrl": "https://cdn.pixelbin.io",
        "options": map[string]interface{}{},
    }

    urlstring, err := url.ObjToUrl(obj)

    if err != nil {
        fmt.Println(err)
    }
}

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/original/images/transformation/water_sprayer.jpeg?v=1744646821354

Kotlin

import com.pixelbin.url.UrlObj
import com.pixelbin.Utils
import com.pixelbin.transformation.TransformationObj

fun main(){
    val obj = UrlObj(
        cloudName = "dummy-cloudname",
        zone = "FIDrmb",
        version = "v2",
        transformation = arrayListOf(
            
        ),
        filePath = "images/transformation/water_sprayer.jpeg",
        baseUrl = "https://cdn.pixelbin.io"
    )

    val url = Utils.objToUrl(obj)
}

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/original/images/transformation/water_sprayer.jpeg?v=1744646821354

C#

using System;
using System.Collections.Generic;
using System.IO;
using Pixelbin.Utils;

namespace ExampleNamespace
{
    class ExampleClass
    {
        static void Main(string[] args)
        {
            UrlObj obj = new UrlObj(
                version: "v2",
                cloudName: "dummy-cloudname",
                filePath: "images/transformation/water_sprayer.jpeg",
                zone: "FIDrmb",
                baseUrl: "https://cdn.pixelbin.io",
                transformations: new List<UrlTransformation>() {
                    
                }
            );

            string url = Url.ObjToUrl(obj);
        }
    }
}

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/original/images/transformation/water_sprayer.jpeg?v=1744646821354

PHP

<?php
require 'vendor/autoload.php';
use Pixelbin\Utils\Url;

$obj = [
    "cloudName" => "dummy-cloudname",
    "zone" => "FIDrmb",
    "version" => "v2",
    "options" => [],
    "transformations" => [
        
    ],
    "filePath" => "images/transformation/water_sprayer.jpeg",
    "baseUrl" => "https://cdn.pixelbin.io",
];

$url = Url::obj_to_url($obj);

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/original/images/transformation/water_sprayer.jpeg?v=1744646821354
?>

Detect Center

URL

https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect()/images/transformation/water_sprayer.jpeg?v=1744646821354

React

<PixelBinImage
    url="https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect()/images/transformation/water_sprayer.jpeg?v=1744646821354"
/>

JavaScript

import Pixelbin from "@pixelbin/core";

const obj = {
    cloudName: "dummy-cloudname",
    zone: "FIDrmb",
    version: "v2",
    transformations: [{"name":"detect","plugin":"imc"}],
    filePath: "images/transformation/water_sprayer.jpeg",
    baseUrl: "https://cdn.pixelbin.io",
};

const url = Pixelbin.default.utils.objToUrl(obj);

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect()/images/transformation/water_sprayer.jpeg?v=1744646821354

Node.js

const Pixelbin = require("@pixelbin/admin");

const obj = {
    cloudName: "dummy-cloudname",
    zone: "FIDrmb",
    version: "v2",
    transformations: [{"name":"detect","plugin":"imc"}],
    filePath: "images/transformation/water_sprayer.jpeg",
    baseUrl: "https://cdn.pixelbin.io",
};

const url = Pixelbin.url.objToUrl(obj);

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect()/images/transformation/water_sprayer.jpeg?v=1744646821354

Python

from pixelbin.utils.url import obj_to_url

obj = {
    "cloudName": "dummy-cloudname",
    "zone": "FIDrmb",
    "version": "v2",
    "transformations": [{"name":"detect","plugin":"imc"}],
    "filePath": "images/transformation/water_sprayer.jpeg",
    "baseUrl": "https://cdn.pixelbin.io",
}

url = obj_to_url(obj)

# url
# https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect()/images/transformation/water_sprayer.jpeg?v=1744646821354

Golang

package main

import (
 "fmt"
 "github.com/pixelbin-dev/pixelbin-go/v2/sdk/utils/url"
)

func main() {
    obj := map[string]interface{}{
        "cloudName": "dummy-cloudname",
        "zoneSlug": "FIDrmb",
        "version": "v2",
        "transformations": []map[string]interface{}{
            {"plugin": "imc", "name": "detect"},
        },
        "filePath": "images/transformation/water_sprayer.jpeg",
        "baseUrl": "https://cdn.pixelbin.io",
        "options": map[string]interface{}{},
    }

    urlstring, err := url.ObjToUrl(obj)

    if err != nil {
        fmt.Println(err)
    }
}

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect()/images/transformation/water_sprayer.jpeg?v=1744646821354

Kotlin

import com.pixelbin.url.UrlObj
import com.pixelbin.Utils
import com.pixelbin.transformation.TransformationObj

fun main(){
    val obj = UrlObj(
        cloudName = "dummy-cloudname",
        zone = "FIDrmb",
        version = "v2",
        transformation = arrayListOf(
            TransformationObj( plugin = "imc", name = "detect", )
        ),
        filePath = "images/transformation/water_sprayer.jpeg",
        baseUrl = "https://cdn.pixelbin.io"
    )

    val url = Utils.objToUrl(obj)
}

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect()/images/transformation/water_sprayer.jpeg?v=1744646821354

C#

using System;
using System.Collections.Generic;
using System.IO;
using Pixelbin.Utils;

namespace ExampleNamespace
{
    class ExampleClass
    {
        static void Main(string[] args)
        {
            UrlObj obj = new UrlObj(
                version: "v2",
                cloudName: "dummy-cloudname",
                filePath: "images/transformation/water_sprayer.jpeg",
                zone: "FIDrmb",
                baseUrl: "https://cdn.pixelbin.io",
                transformations: new List<UrlTransformation>() {
                    new UrlTransformation(plugin: "imc", name: "detect", )
                }
            );

            string url = Url.ObjToUrl(obj);
        }
    }
}

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect()/images/transformation/water_sprayer.jpeg?v=1744646821354

PHP

<?php
require 'vendor/autoload.php';
use Pixelbin\Utils\Url;

$obj = [
    "cloudName" => "dummy-cloudname",
    "zone" => "FIDrmb",
    "version" => "v2",
    "options" => [],
    "transformations" => [
        ["plugin" => "imc", "name" => "detect", ],
    ],
    "filePath" => "images/transformation/water_sprayer.jpeg",
    "baseUrl" => "https://cdn.pixelbin.io",
];

$url = Url::obj_to_url($obj);

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect()/images/transformation/water_sprayer.jpeg?v=1744646821354
?>

Context API Response

```json

{ "data": { "output": { "is_center": false, "distance_x_px": 83, "distance_y_px": 19, "distance_x_perc": 25, "distance_y_perc": 7, "original_input_size": "(512, 640, 3)" } }, "name": "detect", "params": { "dist_perc": "10" } }

</TabItem>
</Tabs>

---

The [**Context API Response**
](/context/) tab consists of a JSON response that has an `is_center` property `false`, which states that the object in the image is not in the center. As shown in the below image, point "A" is the center of the image, and point "B" is the center of the object. The `distance_x_px` is 82 px, and the `distance_x_perc` is 25.625%, which is calculated after dividing an image's width in half. The `distance_y_px` is 19 px, and the `distance_y_perc` is 7.421%, which is calculated after dividing an image's height in half. The `original_input_size` is (512,
640,
3), where 512 px is the height of an image,
640 px is the width of an image, and the number of channels in the image is 3.

<Figure src="images/transformation/detect-center-bottle-infographics.png"  />

## Params

### Distance Percentage (`dist_perc`)

Maximum distance percentage from the center of the image, beyond which the image won't be considered to be centered.

The default value is `10`.

<Tabs>
<TabItem value="Original Image" label="Original Image">
    <ImageWithUrl
        src="images/transformation/basic_pink_flower.jpeg"
        alt="A pink flower"
    />
</TabItem>

<TabItem value="dist_perc=10" label="dist_perc=10">
<ImageWithUrl src="images/transformation/basic_pink_flower.jpeg" alt="A pink flower" pattern="imc.detect(dist_perc:10)" />
</TabItem>

<TabItem value="Context API Response (dist_perc=10 (default))" label="Context API Response (dist_perc=10 (default))">

```json

    {
  "data": {
    "output": {
      "is_center": false,
      "distance_x_px": 31,
      "distance_y_px": 33,
      "distance_x_perc": 9,
      "distance_y_perc": 18,
      "original_input_size": "(350, 650, 3)"
    }
  },
  "name": "detect",
  "params": {
    "dist_perc": 10
  }
}

dist_perc=20

URL

https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect(dist_perc:20)/images/transformation/basic_pink_flower.jpeg?v=1744646821354

React

<PixelBinImage
    url="https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect(dist_perc:20)/images/transformation/basic_pink_flower.jpeg?v=1744646821354"
/>

JavaScript

import Pixelbin from "@pixelbin/core";

const obj = {
    cloudName: "dummy-cloudname",
    zone: "FIDrmb",
    version: "v2",
    transformations: [{"name":"detect","plugin":"imc","values":[{"key":"dist_perc","value":"20"}]}],
    filePath: "images/transformation/basic_pink_flower.jpeg",
    baseUrl: "https://cdn.pixelbin.io",
};

const url = Pixelbin.default.utils.objToUrl(obj);

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect(dist_perc:20)/images/transformation/basic_pink_flower.jpeg?v=1744646821354

Node.js

const Pixelbin = require("@pixelbin/admin");

const obj = {
    cloudName: "dummy-cloudname",
    zone: "FIDrmb",
    version: "v2",
    transformations: [{"name":"detect","plugin":"imc","values":[{"key":"dist_perc","value":"20"}]}],
    filePath: "images/transformation/basic_pink_flower.jpeg",
    baseUrl: "https://cdn.pixelbin.io",
};

const url = Pixelbin.url.objToUrl(obj);

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect(dist_perc:20)/images/transformation/basic_pink_flower.jpeg?v=1744646821354

Python

from pixelbin.utils.url import obj_to_url

obj = {
    "cloudName": "dummy-cloudname",
    "zone": "FIDrmb",
    "version": "v2",
    "transformations": [{"name":"detect","plugin":"imc","values":[{"key":"dist_perc","value":"20"}]}],
    "filePath": "images/transformation/basic_pink_flower.jpeg",
    "baseUrl": "https://cdn.pixelbin.io",
}

url = obj_to_url(obj)

# url
# https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect(dist_perc:20)/images/transformation/basic_pink_flower.jpeg?v=1744646821354

Golang

package main

import (
 "fmt"
 "github.com/pixelbin-dev/pixelbin-go/v2/sdk/utils/url"
)

func main() {
    obj := map[string]interface{}{
        "cloudName": "dummy-cloudname",
        "zoneSlug": "FIDrmb",
        "version": "v2",
        "transformations": []map[string]interface{}{
            {"plugin": "imc", "name": "detect", "values": []map[string]interface{}{ {"key": "dist_perc", "value": "20"},}},
        },
        "filePath": "images/transformation/basic_pink_flower.jpeg",
        "baseUrl": "https://cdn.pixelbin.io",
        "options": map[string]interface{}{},
    }

    urlstring, err := url.ObjToUrl(obj)

    if err != nil {
        fmt.Println(err)
    }
}

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect(dist_perc:20)/images/transformation/basic_pink_flower.jpeg?v=1744646821354

Kotlin

import com.pixelbin.url.UrlObj
import com.pixelbin.Utils
import com.pixelbin.transformation.TransformationObj

fun main(){
    val obj = UrlObj(
        cloudName = "dummy-cloudname",
        zone = "FIDrmb",
        version = "v2",
        transformation = arrayListOf(
            TransformationObj( plugin = "imc", name = "detect", values = hashMapOf( "dist_perc" to "20"), )
        ),
        filePath = "images/transformation/basic_pink_flower.jpeg",
        baseUrl = "https://cdn.pixelbin.io"
    )

    val url = Utils.objToUrl(obj)
}

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect(dist_perc:20)/images/transformation/basic_pink_flower.jpeg?v=1744646821354

C#

using System;
using System.Collections.Generic;
using System.IO;
using Pixelbin.Utils;

namespace ExampleNamespace
{
    class ExampleClass
    {
        static void Main(string[] args)
        {
            UrlObj obj = new UrlObj(
                version: "v2",
                cloudName: "dummy-cloudname",
                filePath: "images/transformation/basic_pink_flower.jpeg",
                zone: "FIDrmb",
                baseUrl: "https://cdn.pixelbin.io",
                transformations: new List<UrlTransformation>() {
                    new UrlTransformation(plugin: "imc", name: "detect", values: new List<Dictionary<string, string>>() { new Dictionary<string, string>() { { "key", "dist_perc" }, { "value", "20" } }} )
                }
            );

            string url = Url.ObjToUrl(obj);
        }
    }
}

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect(dist_perc:20)/images/transformation/basic_pink_flower.jpeg?v=1744646821354

PHP

<?php
require 'vendor/autoload.php';
use Pixelbin\Utils\Url;

$obj = [
    "cloudName" => "dummy-cloudname",
    "zone" => "FIDrmb",
    "version" => "v2",
    "options" => [],
    "transformations" => [
        ["plugin" => "imc", "name" => "detect", "values" => [ [ "key" => "dist_perc", "value" => "20" ], ], ],
    ],
    "filePath" => "images/transformation/basic_pink_flower.jpeg",
    "baseUrl" => "https://cdn.pixelbin.io",
];

$url = Url::obj_to_url($obj);

// url
// https://cdn.pixelbin.io/v2/dummy-cloudname/FIDrmb/imc.detect(dist_perc:20)/images/transformation/basic_pink_flower.jpeg?v=1744646821354
?>

Context API Response (dist_perc=20)

{
    {
        "name": "detect",
        "operation": "Image Centering",
        "identifier": "imc",
        "params": {
            "dist_perc": "20"
        },
        "data": {
            "output": {
                "is_center": true,
                "distance_x_px": 31,
                "distance_y_px": 33,
                "distance_x_perc": 9,
                "distance_y_perc": 18,
                "original_input_size": "(350, 650, 3)"
            }
        }
    }
  }
}

The Context API Response (dist_perc=10 (default)) tab consists of a JSON response that has an is_center property false, which states that the object in the image is not in the center. As shown in the below image, point "A" is the center of the image, and point "B" is the center of the object. The distance_x_px is 31 px, and the distance_x_perc is 9.538%, which is calculated after dividing an image's width in half. The distance_y_px is 32 px, and the distance_y_perc is 18.285%, which is calculated after dividing an image's height in half. In this case, the center of the object is 9.538% (31 px) to the right and 18.285% (32 px) to the top. The dist_perc is 10%, indicating that the object is centered as long as its center does not deviate above 10% from the center of the image.

The horizontal (x) deviation is 9.538% to the right, which is less than the dist_perc of 10%, while the vertical (y) deviation is 18.285% to the right, which is greater than the dist_perc of 10%. Since neither of the percentage values is greater than 18.285%, the is_center property has returned false.

To make the is_center property true in the above image, increase the dist_perc amount above 18.285%.

The Context API Response (dist_perc=20) tab contains a JSON response that is obtained when the dist_perc parameter is set to 20%. In this case, the is_center property is returned as true in the JSON.