Masking

Image Operations / Image Masking

On this page:
Intro ▾
{{activeSubMenu.text}} ▾

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 invsible. The Pixaven Image API enables you to apply an elliptical mask with ease.

Elliptical Masking

In order 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.pixaven.com/1.0/fetch
     --user your-api-key: \
     --header "Content-Type: application/json" \
     --data '{
         "url": "https://www.website.com/image.jpg",
         "mask": {
             "shape": "ellipse"
         }
     }'
Given the input image 750px × 300px
Apply an ellitical mask
The resulting image is a masked 750px × 300px image on a white background

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"
    }
}
Given the input image 750px × 300px
Resize the image to 200px × 200px with "fit" mode and apply and elliptical mask
The resulting image is 200px × 200px on a white background

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 AARRGGBB format. For example, to set the background color to yellow #f8d448:

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

Code Examples for Image Masking

Below, you'll find examples of how to use the Image Masking from the Pixaven API:

<?php

/**
* Instantiate new `$pix` by calling a constructor
*/

$pix = new Pixaven\Pixaven('your-api-key');


/**
* Provide a publicly available image URL with fetch(string) method
* and apply an elliptical mask on a yellow #f8d448 background
*/

$pix
    ->fetch('https://www.website.com/image.jpg')
    ->mask(array(
        'shape' => 'ellipse',
        'background' => '#f8d448'
    ))
    ->toJSON(function ($error, $meta) {
        if (!empty($error)) {
            throw new Exception($error);
        }

        /**
        * You'll find the full JSON metadata array within the `$meta` variable.
        * Remember to always check if the `success` property is set to `true`.
        */

        if ($meta['success'] == true) {
            print ($meta['output']['url']);
        } else {
            print ($meta['message']);
        }
    });
/**
* Module dependencies
*/

const Pixaven = require("pixaven");


/**
* Instantiate new `pix` by calling a constructor
*/

const pix = new Pixaven("your-api-key");


/**
* Provide a publicly available image URL with fetch(string) method
* and apply an elliptical mask on a yellow #f8d448 background
*/

pix
    .fetch("https://www.website.com/image.jpg")
    .mask({
        shape: "ellipse",
        background: "#f8d448"
    })
    .toJSON((err, meta) => {
        if (err) {
            return console.log(err);
        }

        /**
        * You'll find the full JSON metadata hash within the `meta` variable.
        * Remember to always check if the `success` property is set to `true`.
        */

        if (meta.success) {
            console.log(meta.output.url);
        } else {
            console.log(meta.message);
        }
    });
##
# Require dependencies

require "pixaven"


##
# Instantiate new `pix` by calling a constructor

pix = Pixaven.new("your-api-key")


##
# Provide a publicly available image URL with fetch(string) method
# and apply an elliptical mask on a yellow #f8d448 background

err, meta = pix
    .fetch("https://www.website.com/image.jpg")
    .mask(
        shape: "ellipse",
        background: "#f8d448"
    )
    .to_json

abort(err) if err


##
# You'll find the full JSON metadata hash within the `meta` variable.
# Remember to always check if the `success` property is set to `true`.

if meta["success"]
    puts meta["output"]["url"]
else
    puts meta["message"]
end
package main

import (
    "fmt"
    "github.com/pixaven/pixaven-go"
)

func main() {

    /**
    * Instantiate new `pix` by calling a constructor
    */

    pix, err := pixaven.NewClient("your-api-key")

    if err != nil {
        panic(err)
    }


    /**
    * Provide a publicly available image URL with Fetch(string) method
    * and apply an elliptical mask on a yellow #f8d448 background
    */

    meta, err := pix.
        Fetch("https://www.website.com/image.jpg").
        Mask(pixaven.P{
            "shape": "ellipse",
            "background": "#f8d448"
        }).
        ToJSON()

    if err != nil {
        panic(err)
    }


    /**
    * You'll find the full JSON metadata hash within the `meta` variable.
    * Remember to always check if the `success` property is set to `true`.
    */

    if meta["success"].(map[string]interface{})["success"].(bool) {
        fmt.Println(meta["output"].(map[string]interface{})["url"])
    } else {
        fmt.Println(meta["message"])
    }
}
##
# Import dependencies

from pixaven import pixaven


##
# Instantiate new `client` by calling a constructor

client = pixaven('your-api-key')


##
# Provide a publicly available image URL with fetch(string) method
# and apply an elliptical mask on a yellow #f8d448 background

err, meta = (
    client
        .fetch('https://www.website.com/image.jpg')
        .mask({
            'shape': 'ellipse',
            'background': '#f8d448'
        })
        .toJSON()
)

if err is not None:
    raise StandardError(err)


##
# You'll find the full JSON metadata hash within the `meta` variable.
# Remember to always check if the `success` property is set to `true`.

if meta['success'] is True:
    print (meta['output']['url'])
else:
    print (meta['message'])
package com.pixaven.examples;

/**
* Import dependencies
*/

import static com.pixaven.OperationConfiguration.settings;
import com.pixaven.Pixaven;
import com.pixaven.Fetch;
import com.pixaven.Response;

public class Masking {
    public static void main(String[] args) {

        /**
        * Instantiate new `pix` by calling a constructor
        */

        Pixaven pix = new Pixaven("your-api-key");

        /**
        * Provide a publicly available image URL with fetch(string) method
        * and apply and elliptical mask on a yellow #f8d448 background
        */

        final Fetch fetch = pix.fetch("https://www.website.com/image.jpg");

        fetch.mask(
            settings()
                .set("shape", "ellipse")
                .set("background", "#f8d448")
        );

        final Response response = fetch.toJson();

        /**
        * You'll find the full JSON metadata hash within the `Response#getMetadata()` property.
        * Remember to always check if the `Response#successful` property is set to `true`.
        */

        if (response.isSuccessful()) {
            System.out.println(response.getMetadata().getOutput().get("url"));
        } else {
            System.out.println(response.getMessage());
        }
    }
}

We use both proprietary and third-party cookies to improve your browsing experience and to provide you with a better service. By continuing to use this site you consent our use of cookies as described in our Cookie Policy×