Image masking is a process of applying a visibility layer to an image. Every pixel that falls outside the mask will become fully transparent and hence invisible. The Optidash Image API enables you to apply an elliptical mask with ease.

Elliptical Masking

To mask your images, simply add a new hash called mask to your request JSON with a shape property set to ellipse. Input image boundaries will be used to describe the area covered by the mask.

{
    "mask": {
        "shape": "ellipse"
    }
}

An example cURL request of using Image Fetch method with an elliptical mask will look like the following:

curl https://api.optidash.ai/1.0/fetch
     --user your-api-key: \
     --header "Content-Type: application/json" \
     --data '{
         "url": "https://www.website.com/image.jpg",
         "mask": {
             "shape": "ellipse"
         }
     }'

Because image boundaries describe the masked area, if you would like to have your output images fit into a perfect circle, you would first need to resize them to square dimensions using, for example, fit mode:

{
    "resize": {
        "mode": "fit"
        "width": 200,
        "height": 200
    },
    "mask": {
        "shape": "ellipse"
    }
}

Mask Background Color

The default background for masked images is white for image formats without the support for alpha-transparency such as JPEG. For image formats which support alpha-transparency such as PNG, a fully transparent background will be used. You can alter this behavior by specifying a background color, which takes a hex-encoded string in RGB, RRGGBB, or RRGGBBAA format. For example, to set the background color to yellow #f8d448:

{
    "mask": {
        "shape": "ellipse",
        "background": "#f8d448"
    }
}