Master Advanced Image Masking with the schananas/grounded_sam Cognitive Actions

24 Apr 2025
Master Advanced Image Masking with the schananas/grounded_sam Cognitive Actions

In the rapidly evolving field of computer vision, the ability to perform advanced image manipulation is crucial for creating engaging applications. The schananas/grounded_sam API provides powerful Cognitive Actions that leverage cutting-edge models like Grounding DINO and Segment Anything to enable developers to perform intricate image masking based on user prompts. This capability is particularly beneficial for applications such as virtual try-ons, where precise segmentation of clothing or accessories is needed.

Prerequisites

Before integrating the Cognitive Actions into your application, ensure you have the following:

  • API Key: You will need an API key to authenticate your requests to the Cognitive Actions platform.
  • Environment Setup: Make sure your development environment can make HTTP requests to the Cognitive Actions API endpoint.

Authentication typically involves passing your API key in the request headers, allowing you to securely access the services provided.

Cognitive Actions Overview

Perform Advanced Image Masking

The Perform Advanced Image Masking action enables users to create detailed image masks that include or exclude specific items based on the provided keywords. This action is particularly useful for applications that require precise control over which elements are highlighted or obscured in an image.

  • Category: image-segmentation
  • Description: Utilizes Grounding DINO and Segment Anything models to perform advanced image masking based on user prompts, ideal for applications like virtual try-ons where specific clothing or accessories need to be segmented. The operation allows for detailed control over mask inclusion and exclusion.

Input

The input schema for this action is structured as follows:

  • image (string, required): The URL of the image to be processed. Must be in valid URI format.
    • Example: "https://st.mngbcn.com/rcs/pics/static/T5/fotos/outfit/S20/57034757_56-99999999_01.jpg"
  • maskPrompt (string, optional): A comma-separated list of keywords indicating elements to include in the mask. Default is "clothes,shoes".
    • Example: "clothes,shoes"
  • adjustmentFactor (integer, optional): An integer value to adjust the mask size. Negative values erode the mask, while positive values dilate it. Default is 0.
    • Example: -15
  • negativeMaskPrompt (string, optional): A comma-separated list of keywords indicating elements to exclude from the mask. Default is "pants".
    • Example: "pants"

Example Input:

{
  "image": "https://st.mngbcn.com/rcs/pics/static/T5/fotos/outfit/S20/57034757_56-99999999_01.jpg",
  "maskPrompt": "clothes,shoes",
  "adjustmentFactor": -15,
  "negativeMaskPrompt": "pants"
}

Output

The output of this action typically consists of an array of URLs pointing to the masked images generated by the action.

Example Output:

[
  "https://assets.cognitiveactions.com/invocations/32da2453-cfd2-466c-bc76-cc16ab4921ff/a1f7d3ac-9513-404c-8718-888960374314.jpg",
  "https://assets.cognitiveactions.com/invocations/32da2453-cfd2-466c-bc76-cc16ab4921ff/4c725460-2148-4366-99ba-33b1c494e386.jpg",
  "https://assets.cognitiveactions.com/invocations/32da2453-cfd2-466c-bc76-cc16ab4921ff/3bc9a75f-9eee-40c9-b5bd-b2e69fa639ab.jpg",
  "https://assets.cognitiveactions.com/invocations/32da2453-cfd2-466c-bc76-cc16ab4921ff/c22f5304-42b2-4cd1-bcbc-ac1cf2f4426f.jpg"
]

Conceptual Usage Example (Python)

Here’s a conceptual example of how you might call the Perform Advanced Image Masking action using Python:

import requests
import json

# Replace with your Cognitive Actions API key and endpoint
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute" # Hypothetical endpoint

action_id = "e7dd1beb-30fa-4c5c-81f5-75ad8f48983f" # Action ID for Perform Advanced Image Masking

# Construct the input payload based on the action's requirements
payload = {
    "image": "https://st.mngbcn.com/rcs/pics/static/T5/fotos/outfit/S20/57034757_56-99999999_01.jpg",
    "maskPrompt": "clothes,shoes",
    "adjustmentFactor": -15,
    "negativeMaskPrompt": "pants"
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json"
}

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json={"action_id": action_id, "inputs": payload} # Hypothetical structure
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body: {e.response.text}")

This code demonstrates how to structure and send a request to the Cognitive Actions API for the Perform Advanced Image Masking action. It highlights where to place the action ID and how to properly format the input payload.

Conclusion

The schananas/grounded_sam Cognitive Action for advanced image masking allows developers to enhance their applications by providing sophisticated image segmentation capabilities. By leveraging these powerful tools, you can create more engaging and interactive user experiences. Consider exploring additional use cases, such as integrating these features into e-commerce platforms or virtual fitting rooms, to fully harness the potential of image masking technology.

← Back to All Articles