Tutorial: How to Detect and Visualize Objects in Images

Learning Objectives

In this tutorial, you’ll learn how to:

Detect objects in images and visualize the results
Customize the appearance of object detection boxes
Process images with and without cloud storage
Implement visualization in multiple programming languages
Save and handle the visualized output images

Prerequisites

Before starting this tutorial, ensure you have:

Completed our basic object detection tutorial
An Aspose Cloud account with Client ID and Client Secret
Basic familiarity with REST APIs
A development environment for your preferred language

Introduction

While getting object detection results as JSON is useful for data processing, visualization provides an immediate, intuitive understanding of detected objects. In this tutorial, we’ll use the Aspose.Imaging Cloud API to detect objects and draw bounding boxes directly on the images.

1. Understanding the Visual Bounds API

The /visualbounds method draws detected objects directly on the image. It accepts these parameters:

Parameter	Type	Description
name	string (required)	Image name to process
method	string (optional)	Detection method, currently only “ssd” is supported
threshold	number (optional)	Minimum probability threshold (0-100) for including objects
includeLabel	boolean (optional)	Whether to include object labels in the visualization
includeScore	boolean (optional)	Whether to include object probabilities in the visualization
color	string (optional)	Custom color for bounds (if not specified, different labels get different colors)
folder	string (optional)	Storage folder containing the image
storage	string (optional)	Storage name

2. Getting Started with Authentication

First, obtain a JWT token:

curl -v "https://api.aspose.cloud/connect/token" \
-X POST \
-d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET' \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json"

Store the JWT token for use in subsequent API calls.

3. Visualizing Objects Using Cloud Storage

In this approach, you first upload an image to Cloud Storage, then process it:

Try it yourself: Visualize Objects in a Stored Image

curl -v "https://api.aspose.cloud/v3/imaging/ai/your_image.jpg/visualbounds?method=ssd&threshold=50&includeLabel=true&includeScore=true" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: multipart/form-data" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-o visualized_image.jpg

This will save the visualized image with detection boxes to a file named visualized_image.jpg.

4. Visualizing Objects Directly from Request Body

For more flexibility, you can send the image directly in the request body:

Try it yourself: Visualize Objects from Request Body

curl -v "https://api.aspose.cloud/v3/imaging/ai/visualbounds?method=ssd&threshold=50&includeLabel=true&includeScore=true" \
-X POST \
-T your_image.jpg \
-H "Content-Type: application/json" \
-H "Accept: multipart/form-data" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-o visualized_image.jpg

5. Customizing Visualization

You can customize the appearance of detection boxes using the color parameter:

curl -v "https://api.aspose.cloud/v3/imaging/ai/your_image.jpg/visualbounds?method=ssd&threshold=50&includeLabel=true&includeScore=true&color=red" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: multipart/form-data" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-o visualized_image_red.jpg

This will draw all detection boxes in red, regardless of object type.

6. Implementing Visualization with SDKs

.NET Implementation

// Tutorial Code Example - Object Detection Visualization with Aspose.Imaging Cloud .NET SDK
using Aspose.Imaging.Cloud.Sdk.Api;
using Aspose.Imaging.Cloud.Sdk.Model.Requests;
using System;
using System.IO;

namespace AsposeTutorials
{
    class ObjectVisualizationTutorial
    {
        // Your Client ID and Client Secret
        private const string ClientId = "YOUR_CLIENT_ID";
        private const string ClientSecret = "YOUR_CLIENT_SECRET";

        static void Main(string[] args)
        {
            // Create instance of API
            var imagingApi = new ImagingApi(ClientId, ClientSecret);

            // 1. Example with storage: Process an image from cloud storage
            string imageName = "object_detection_image.jpg";
            string folder = ""; // File is in the root
            string storage = ""; // Use default storage
            string outputFile = "visualized_cloud_image.jpg";
            
            Console.WriteLine("Visualizing objects in stored image...");
            try
            {
                // Object detection visualization parameters
                var request = new GetVisualObjectBoundsRequest(
                    name: imageName,
                    method: "ssd",
                    threshold: 50,
                    includeLabel: true,
                    includeScore: true,
                    color: null, // Using default colors
                    folder: folder,
                    storage: storage
                );

                // Get the resulting image and save it
                var resultStream = imagingApi.GetVisualObjectBounds(request);
                
                using (var fileStream = File.Create(outputFile))
                {
                    resultStream.CopyTo(fileStream);
                }
                
                Console.WriteLine($"Visualized image saved to {outputFile}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }

            // 2. Example without storage: Process an image directly
            string imageFilePath = @"C:\path\to\your\local_image.jpg";
            string directOutputFile = "visualized_local_image.jpg";
            
            Console.WriteLine("\nVisualizing objects in local image...");
            
            try
            {
                using (FileStream fileStream = new FileStream(imageFilePath, FileMode.Open))
                {
                    // Custom color demonstration
                    var request = new CreateVisualObjectBoundsRequest(
                        imageData: fileStream,
                        method: "ssd",
                        threshold: 50,
                        includeLabel: true,
                        includeScore: true,
                        color: "blue", // Set all boxes to blue
                        outPath: null // Not saving to cloud storage
                    );

                    var resultStream = imagingApi.CreateVisualObjectBounds(request);
                    
                    using (var fileStream2 = File.Create(directOutputFile))
                    {
                        resultStream.CopyTo(fileStream2);
                    }
                    
                    Console.WriteLine($"Visualized image saved to {directOutputFile}");
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
            
            // 3. Example saving to cloud storage
            Console.WriteLine("\nSaving visualized image to cloud storage...");
            string outputPath = "visualized_results/output_image.jpg";
            
            try
            {
                using (FileStream fileStream = new FileStream(imageFilePath, FileMode.Open))
                {
                    var request = new CreateVisualObjectBoundsRequest(
                        imageData: fileStream,
                        method: "ssd",
                        threshold: 50,
                        includeLabel: true,
                        includeScore: true,
                        color: null,
                        outPath: outputPath // Specify cloud storage path
                    );

                    // This will save the result to cloud storage
                    imagingApi.CreateVisualObjectBounds(request);
                    
                    Console.WriteLine($"Visualized image saved to cloud storage at {outputPath}");
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
        }
    }
}

Java Implementation

// Tutorial Code Example - Object Detection Visualization with Aspose.Imaging Cloud Java SDK
import com.aspose.imaging.cloud.sdk.api.ImagingApi;
import com.aspose.imaging.cloud.sdk.model.requests.GetVisualObjectBoundsRequest;
import com.aspose.imaging.cloud.sdk.model.requests.CreateVisualObjectBoundsRequest;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.io.OutputStream;

public class ObjectVisualizationTutorial {
    // Your Client ID and Client Secret
    private static final String CLIENT_ID = "YOUR_CLIENT_ID";
    private static final String CLIENT_SECRET = "YOUR_CLIENT_SECRET";

    public static void main(String[] args) {
        try {
            // Create instance of the API
            ImagingApi imagingApi = new ImagingApi(CLIENT_ID, CLIENT_SECRET);

            // 1. Example with storage: Process an image from cloud storage
            String imageName = "object_detection_image.jpg";
            String folder = ""; // File is in the root
            String storage = ""; // Use default storage
            String outputFile = "visualized_cloud_image.jpg";
            
            System.out.println("Visualizing objects in stored image...");
            
            // Object detection visualization parameters
            GetVisualObjectBoundsRequest request = new GetVisualObjectBoundsRequest(
                imageName,     // name
                "ssd",         // method
                50,            // threshold
                true,          // includeLabel
                true,          // includeScore
                null,          // color (null means default colors)
                folder,        // folder
                storage        // storage
            );

            // Get the resulting image and save it
            byte[] resultImage = imagingApi.getVisualObjectBounds(request);
            
            try (OutputStream outStream = new FileOutputStream(outputFile)) {
                outStream.write(resultImage);
            }
            
            System.out.println("Visualized image saved to " + outputFile);

            // 2. Example without storage: Process an image directly
            String imageFilePath = "C:/path/to/your/local_image.jpg";
            String directOutputFile = "visualized_local_image.jpg";
            
            System.out.println("\nVisualizing objects in local image...");
            
            File inputFile = new File(imageFilePath);
            InputStream imageStream = new FileInputStream(inputFile);
            
            // Custom color demonstration
            CreateVisualObjectBoundsRequest directRequest = new CreateVisualObjectBoundsRequest(
                imageStream,    // imageData
                "ssd",          // method
                50,             // threshold
                true,           // includeLabel
                true,           // includeScore
                "red",          // color (all boxes will be red)
                null            // outPath (null means the result will be returned in the response)
            );

            byte[] directResult = imagingApi.createVisualObjectBounds(directRequest);
            
            try (OutputStream outStream = new FileOutputStream(directOutputFile)) {
                outStream.write(directResult);
            }
            
            System.out.println("Visualized image saved to " + directOutputFile);
            
            // 3. Example saving to cloud storage
            System.out.println("\nSaving visualized image to cloud storage...");
            String outputPath = "visualized_results/output_image.jpg";
            
            imageStream = new FileInputStream(inputFile); // Reopen the stream
            
            CreateVisualObjectBoundsRequest cloudSaveRequest = new CreateVisualObjectBoundsRequest(
                imageStream,    // imageData
                "ssd",          // method
                50,             // threshold
                true,           // includeLabel
                true,           // includeScore
                null,           // color (null means default colors)
                outputPath      // outPath (specify cloud storage path)
            );

            // This will save the result to cloud storage
            imagingApi.createVisualObjectBounds(cloudSaveRequest);
            
            System.out.println("Visualized image saved to cloud storage at " + outputPath);
            
        } catch (Exception e) {
            System.out.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

7. Understanding the Visualization Output

The visualization includes:

Bounding boxes around detected objects
Object labels (when includeLabel=true)
Confidence scores (when includeScore=true)
Color-coded boxes based on object type (when color is not specified)

8. Adjusting Detection Sensitivity

You can control which objects appear in the visualization by adjusting the threshold parameter:

Higher values (e.g., 80): Only high-confidence detections will be shown
Lower values (e.g., 30): More objects will be detected, but with potentially more false positives

Try it yourself: Experiment with Different Thresholds

# High threshold - only very confident detections
curl -v "https://api.aspose.cloud/v3/imaging/ai/your_image.jpg/visualbounds?method=ssd&threshold=80&includeLabel=true&includeScore=true" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: multipart/form-data" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-o high_threshold.jpg

# Low threshold - more detections with potential false positives
curl -v "https://api.aspose.cloud/v3/imaging/ai/your_image.jpg/visualbounds?method=ssd&threshold=30&includeLabel=true&includeScore=true" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: multipart/form-data" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-o low_threshold.jpg

Compare the resulting images to see the difference in detection sensitivity.

9. Practical Applications

Object visualization can be used in various applications:

Content moderation: Highlight potentially inappropriate content
Retail analytics: Identify products on shelves
Security systems: Mark detected persons or vehicles
Photo organization: Auto-tag images based on detected objects
Accessibility tools: Describe image content for visually impaired users

10. Common Issues and Troubleshooting

Missing labels or scores: Ensure includeLabel and includeScore are set to true
Poor visualization quality: Try adjusting the threshold or using a better quality input image
Unexpected detection results: Try different object categories or check if your objects are in the supported labels list
Performance issues: Consider resizing large images before processing

What You’ve Learned

In this tutorial, you’ve learned:

How to visualize object detections directly on images
How to customize the appearance of detection visualizations
How to save visualized results locally and to cloud storage
How to implement visualization using .NET and Java SDKs
How to adjust detection sensitivity for better results

Further Practice

To reinforce your learning:

Create a simple web application that uploads images and displays visualized detections
Experiment with detecting and visualizing specific object categories
Build a batch processing tool to visualize objects in multiple images
Try combining object detection with other Aspose.Imaging features

Next Steps

Continue your learning journey with our next tutorial: Understanding Available Object Detection Labels

Helpful Resources

Have questions about this tutorial? We’re here to help! Reach out on our support forum with any questions about implementing object detection visualization in your applications.