Tutorial: Finding Similar Images

Learning Objectives

In this tutorial, you’ll learn:

How to search for images similar to a reference image
How to control similarity thresholds for more precise results
How to limit the number of results returned
Best practices for implementing similarity searches
How to interpret and use similarity scores

Prerequisites

Before starting this tutorial, please ensure you have:

Completed the Extracting Image Features tutorial
A valid search context ID from previous tutorials
Your Aspose Cloud credentials (Client ID and Client Secret)
A valid access token for the Aspose Cloud API
Multiple images already added to your search context (at least 5-10 for meaningful results)

Understanding Image Similarity Search

Image similarity search is the core functionality of reverse image search. It allows you to:

Select a reference image (either from your search context or a new image)
Find other images that are visually similar
Sort results by similarity score
Filter results based on a minimum similarity threshold

The similarity is calculated based on the visual features extracted from the images, not just their colors or dimensions.

How Similarity Scoring Works

The similarity score is a value between 0 and 100, where:

100: Perfect match (identical images)
90-99: Very high similarity (same image with minor variations)
70-89: High similarity (same subject, different angles or conditions)
50-69: Moderate similarity (similar subjects or compositions)
Below 50: Low similarity (may share some visual elements)

The exact thresholds for what constitutes a “similar” image depend on your specific use case.

Step 1: Obtain an Access Token

First, authenticate with the Aspose Cloud API:

curl -v "https://api.aspose.cloud/oauth2/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"

Save the access token from the response for use in the next step.

Step 2: Find Similar Images

Use the following API call to find images similar to a reference image in your search context:

curl -v "https://api.aspose.cloud/v3/imaging/ai/imageSearch/YOUR_SEARCH_CONTEXT_ID/findSimilar?similarityThreshold=90.0&maxCount=5&imageId=reference_image.jpg" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace the following placeholders:

YOUR_SEARCH_CONTEXT_ID with your actual search context ID
YOUR_ACCESS_TOKEN with the token from Step 1
reference_image.jpg with the ID of an image already in your search context

The query parameters control the search behavior:

similarityThreshold: Minimum similarity score (0-100) for results
maxCount: Maximum number of results to return

Step 3: Interpret the Results

You’ll receive a response like this:

{
  "Results": [
    {
      "ImageId": "similar_image1.jpg",
      "Similarity": 95.8
    },
    {
      "ImageId": "similar_image2.jpg",
      "Similarity": 92.3
    }
  ],
  "Code": 200,
  "Status": "OK"
}

The response includes:

An array of similar images, each with its ID and similarity score
Images sorted in descending order of similarity (most similar first)
Only images meeting the similarity threshold are included

Finding Similar Images Using an External Image

You can also find images similar to one that isn’t yet in your search context:

curl -v "https://api.aspose.cloud/v3/imaging/ai/imageSearch/YOUR_SEARCH_CONTEXT_ID/findSimilar?similarityThreshold=70.0&maxCount=5" \
-X POST \
-T /path/to/your/query_image.jpg \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Notice we’re using a POST request with the image content in the body, rather than specifying an imageId parameter.

Try It Yourself

Now, let’s practice finding similar images:

Obtain an access token using the curl command
Try finding similar images to one already in your search context
Experiment with different similarity thresholds (try 90, 70, and 50)
Upload a new image and find similar images to it
Compare the results and similarity scores

Using SDK Libraries

Java SDK Example (Find Similar to Existing Image)

import com.aspose.imaging.cloud.sdk.api.ImagingApi;
import com.aspose.imaging.cloud.sdk.model.SearchResultsSet;
import com.aspose.imaging.cloud.sdk.model.SearchResult;

public class FindSimilarImagesExample {
    
    public static void main(String[] args) {
        // Get your clientId and clientSecret from https://dashboard.aspose.cloud/
        String clientId = "YOUR_CLIENT_ID";
        String clientSecret = "YOUR_CLIENT_SECRET";
        
        // Create instance of the API
        ImagingApi api = new ImagingApi(clientId, clientSecret);
        
        // Your search context ID from previous operations
        String searchContextId = "YOUR_SEARCH_CONTEXT_ID";
        
        // ID of the reference image in your search context
        String imageId = "reference_image.jpg";
        
        // Search parameters
        Double similarityThreshold = 70.0; // Minimum similarity score (0-100)
        Integer maxCount = 5; // Maximum number of results
        
        try {
            // Find similar images
            SearchResultsSet results = api.findSimilarImages(searchContextId, similarityThreshold, imageId, maxCount, null, null);
            
            // Print the results
            System.out.println("Found " + results.getResults().size() + " similar images:");
            for (SearchResult result : results.getResults()) {
                System.out.println("Image ID: " + result.getImageId() + ", Similarity: " + result.getSimilarity());
            }
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Java SDK Example (Find Similar to New Image)

import com.aspose.imaging.cloud.sdk.api.ImagingApi;
import com.aspose.imaging.cloud.sdk.model.SearchResultsSet;
import com.aspose.imaging.cloud.sdk.model.SearchResult;

import java.io.File;
import java.nio.file.Files;

public class FindSimilarToNewImageExample {
    
    public static void main(String[] args) {
        // Get your clientId and clientSecret from https://dashboard.aspose.cloud/
        String clientId = "YOUR_CLIENT_ID";
        String clientSecret = "YOUR_CLIENT_SECRET";
        
        // Create instance of the API
        ImagingApi api = new ImagingApi(clientId, clientSecret);
        
        // Your search context ID from previous operations
        String searchContextId = "YOUR_SEARCH_CONTEXT_ID";
        
        // Path to your local image file
        String imagePath = "/path/to/your/query_image.jpg";
        
        // Search parameters
        Double similarityThreshold = 70.0; // Minimum similarity score (0-100)
        Integer maxCount = 5; // Maximum number of results
        
        try {
            // Read the image into a byte array
            File imageFile = new File(imagePath);
            byte[] imageData = Files.readAllBytes(imageFile.toPath());
            
            // Find similar images
            SearchResultsSet results = api.findSimilarImages(searchContextId, similarityThreshold, null, maxCount, imageData, null);
            
            // Print the results
            System.out.println("Found " + results.getResults().size() + " similar images:");
            for (SearchResult result : results.getResults()) {
                System.out.println("Image ID: " + result.getImageId() + ", Similarity: " + result.getSimilarity());
            }
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

.NET SDK Example

using Aspose.Imaging.Cloud.Sdk.Api;
using Aspose.Imaging.Cloud.Sdk.Model;
using System;
using System.IO;

namespace AsposeImagingCloudTutorials
{
    class FindSimilarImagesExample
    {
        static void Main(string[] args)
        {
            // Get your clientId and clientSecret from https://dashboard.aspose.cloud/
            string clientId = "YOUR_CLIENT_ID";
            string clientSecret = "YOUR_CLIENT_SECRET";
            
            // Create instance of the API
            ImagingApi api = new ImagingApi(clientId, clientSecret);
            
            // Your search context ID from previous operations
            string searchContextId = "YOUR_SEARCH_CONTEXT_ID";
            
            // ID of the reference image in your search context
            string imageId = "reference_image.jpg";
            
            // Search parameters
            double similarityThreshold = 70.0; // Minimum similarity score (0-100)
            int maxCount = 5; // Maximum number of results
            
            try
            {
                // Find similar images
                SearchResultsSet results = api.FindSimilarImages(searchContextId, similarityThreshold, imageId, maxCount);
                
                // Print the results
                Console.WriteLine("Found " + results.Results.Count + " similar images:");
                foreach (SearchResult result in results.Results)
                {
                    Console.WriteLine("Image ID: " + result.ImageId + ", Similarity: " + result.Similarity);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("Error: " + ex.Message);
            }
        }
    }
}

Real-World Applications of Image Similarity Search

Image similarity search has many practical applications:

Content Deduplication: Identify and remove duplicate or near-duplicate images in large collections.
Visual Product Search: Let users find products by uploading an image of what they’re looking for.
Copyright Infringement Detection: Find unauthorized uses of proprietary images.
Visual Recommendations: Suggest visually similar content to users based on what they’re currently viewing.
Image Organization: Automatically group visually similar images to help organize large collections.

Best Practices for Similarity Searching

Adjust Thresholds Carefully: Start with a higher threshold (80-90) and lower it if you need more results.
Consider Context: Different use cases need different thresholds—product matching might need 90+, while style matching might work better at 70.
Limit Result Count: For performance reasons, limit the maximum results returned to what you actually need.
Index Diverse Images: Make sure your search context contains a diverse set of images for better results.
Pre-process Images: Consider standardizing image sizes and formats before adding them to your search context.

What You’ve Learned

In this tutorial, you’ve learned:

How to find images similar to a reference image in your search context
How to find images similar to a new external image
How to control search parameters like similarity threshold and result count
How to interpret similarity scores
Real-world applications and best practices for image similarity search

Troubleshooting Tips

No Results: If you get no results, try lowering the similarity threshold.
Unexpected Results: Remember that similarity is based on visual features, not semantic meaning.
Performance Issues: Large search contexts may take longer to search; consider optimizing by removing unnecessary images.
Image Quality: Poor quality images may not extract enough features for reliable matching.

Next Steps

Now that you know how to find similar images, you’re ready to move on to the next tutorial in our series:

→ Tutorial: Detecting Duplicate Images

In the next tutorial, you’ll learn how to find duplicate or near-duplicate images in your search context.

Further Practice

To reinforce what you’ve learned:

Create a script that finds similar images at different threshold levels
Try finding similar images to various types of content (people, landscapes, objects)
Create a simple web interface to upload an image and display similar results
Experiment with pre-processing images before searching

Helpful Resources

Have questions about this tutorial? Please feel free to post your questions on our support forum.