Tutorial: Working with Image Tags

Learning Objectives

In this tutorial, you’ll learn:

• What image tags are and why they enhance reverse image search
• How to add tags and reference images to your search context
• How to find images using tags
• Best practices for effective image tagging strategies
• How to combine tag-based and visual similarity search

Prerequisites

Before starting this tutorial, please ensure you have:

• Completed the Comparing Two Images 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
• Several images already added to your search context

Understanding Image Tags

Tags are text labels associated with images that provide additional context or categorization. While pure visual similarity search is powerful, it has limitations:

• It can only find images that “look” similar
• It can’t understand abstract concepts or categories
• It doesn’t recognize the semantic meaning of image content

Tags help overcome these limitations by attaching human-defined categories, descriptions, or metadata to images. This creates a hybrid search system that combines:

1. Visual similarity: Finding images that look alike
2. Semantic relevance: Finding images with similar meaning or purpose

The Tag-Based Search Process

The tag-based search process in Aspose.Imaging Cloud has three main steps:

1. Tag Creation: Associate a tag name with a reference image
2. Auto-Tagging: The system automatically applies this tag to visually similar images
3. Tag-Based Search: Find images by specifying one or more tags

The power of this approach is that it combines visual similarity with human-defined categories.

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 steps.

Step 2: Add a Tag with a Reference Image

To create a tag and associate it with a reference image:

curl -v "https://api.aspose.cloud/v3/imaging/ai/imageSearch/YOUR_SEARCH_CONTEXT_ID/addTag?tagName=landscape" \
-X POST \
-T /path/to/your/landscape_reference.jpg \
-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
• landscape with your desired tag name
• /path/to/your/landscape_reference.jpg with the path to a reference image for this tag

This command:

1. Creates a tag named “landscape”
2. Associates it with the uploaded reference image
3. The system will use this reference to auto-tag similar images

Step 3: Find Images by Tags

Once you’ve created tags, you can search for images by one or more tags:

curl -v "https://api.aspose.cloud/v3/imaging/ai/imageSearch/YOUR_SEARCH_CONTEXT_ID/findByTags?similarityThreshold=90.0&maxCount=10" \
-X POST \
-d '["landscape", "mountains"]' \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace the placeholders as before, and adjust the following parameters:

• similarityThreshold: Minimum similarity score (0-100) for tag matching
• maxCount: Maximum number of results to return
• ["landscape", "mountains"]: Array of tags to search for (replace with your actual tags)

Step 4: Interpret the Results

You’ll receive a response like this:

{
  "Results": [
    {
      "ImageId": "mountain_sunset.jpg",
      "Similarity": 95.7
    },
    {
      "ImageId": "alpine_lake.jpg",
      "Similarity": 92.3
    }
  ],
  "Code": 200,
  "Status": "OK"
}

The response includes:

• Images that match the requested tags
• Similarity scores indicating how well they match
• Results sorted by similarity (highest first)

Try It Yourself

Now, let’s practice working with tags:

1. Obtain an access token using the curl command
2. Create at least three different tags with appropriate reference images (e.g., “portrait”, “landscape”, “cityscape”)
3. Search for images using one tag
4. Search for images using multiple tags
5. Experiment with different similarity thresholds to see how it affects results

Using SDK Libraries

.NET SDK Example

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

namespace AsposeImagingCloudTutorials
{
    class FindImagesByTagsExample
    {
        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";
            
            // First create a tag with reference image
            string tagName = "landscape";
            string imagePath = @"C:\path\to\your\landscape_reference.jpg";
            
            try
            {
                // Read the image into a byte array
                byte[] imageData = File.ReadAllBytes(imagePath);
                
                // Add tag with reference image
                api.CreateImageTag(searchContextId, imageData, tagName);
                
                Console.WriteLine("Tag '" + tagName + "' successfully added to search context");
                
                // Now search for images with this tag
                List<string> tags = new List<string> { tagName };
                double similarityThreshold = 70.0;
                int maxCount = 10;
                
                SearchResultsSet results = api.FindImagesByTags(searchContextId, tags, similarityThreshold, maxCount);
                
                // Print the results
                Console.WriteLine("Found " + results.Results.Count + " images matching tag '" + tagName + "':");
                foreach (SearchResult result in results.Results)
                {
                    Console.WriteLine("Image ID: " + result.ImageId + ", Similarity: " + result.Similarity);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("Error: " + ex.Message);
            }
        }
    }
}

Java SDK Example (Add Tag with Reference Image)

import com.aspose.imaging.cloud.sdk.api.ImagingApi;

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

public class AddTagToSearchContextExample {
    
    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";
        
        // Tag name
        String tagName = "landscape";
        
        // Path to your reference image
        String imagePath = "/path/to/your/landscape_reference.jpg";
        
        try {
            // Read the image into a byte array
            File imageFile = new File(imagePath);
            byte[] imageData = Files.readAllBytes(imageFile.toPath());
            
            // Add tag with reference image
            api.createImageTag(searchContextId, imageData, tagName, null, null);
            
            System.out.println("Tag '" + tagName + "' successfully added to search context");
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Java SDK Example (Find Images by Tags)

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.util.Arrays;
import java.util.List;

public class FindImagesByTagsExample {
    
    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";
        
        // Tags to search for
        List<String> tags = Arrays.asList("landscape", "mountains");
        
        // Search parameters
        Double similarityThreshold = 70.0; // Minimum similarity score (0-100)
        Integer maxCount = 10; // Maximum number of results
        
        try {
            // Find images by tags
            SearchResultsSet results = api.findImagesByTags(searchContextId, tags, similarityThreshold, maxCount, null, null);
            
            // Print the results
            System.out.println("Found " + results.getResults().size() + " images matching tags " + tags + ":");
            for (SearchResult result : results.getResults()) {
                System.out.println("Image ID: " + result.getImageId() + ", Similarity: " + result.getSimilarity());
            }
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Advanced Tag-Based Search Strategies

Here are some advanced strategies to make the most of tag-based image search:

1. Hierarchical Tags

Create a hierarchy of tags to enable more precise searches:

• General categories: “vehicle”, “building”, “food”
• Subcategories: “car”, “truck”, “skyscraper”, “house”, “dessert”, “meal”
• Specific items: “sedan”, “pickup”, “apartment”, “cottage”, “cake”, “pasta”

This allows users to search at different levels of specificity.

2. Attribute Tags

Use tags to capture attributes that visual similarity alone might miss:

• Colors: “red”, “blue”, “monochrome”
• Styles: “vintage”, “minimalist”, “abstract”
• Moods: “happy”, “serene”, “dramatic”
• Composition: “portrait”, “landscape”, “closeup”

3. Combining Tags for Complex Queries

Implement multi-tag searches to find images that match specific combinations:

• “landscape” + “sunset” to find sunset landscapes
• “portrait” + “outdoor” + “smiling” to find outdoor portrait photos with smiling subjects
• “food” + “dessert” + “chocolate” to find chocolate desserts

4. Semantic Tag Groups

Group related tags to handle synonyms and related concepts:

• Group “car”, “automobile”, “vehicle” to find all car-related images
• Group “beach”, “seaside”, “shore” to find all beach scenes
• Group “pet”, “dog”, “cat” to find all pet-related images

Best Practices for Effective Tagging

1. Be Consistent: Use a consistent tagging schema across your entire image collection
2. Choose Clear Tags: Use unambiguous, descriptive tags that users would naturally search for
3. Use Multiple Tags: Apply multiple relevant tags to each image to increase findability
4. Balance Specificity: Include both general and specific tags
5. Consider Multi-Language: For international applications, consider tags in multiple languages
6. Review and Refine: Periodically review your tagging system and refine it based on search patterns

Tag-Based Search vs. Visual Similarity Search

Understanding when to use each approach is important:

For optimal results, combine both approaches in your application.

What You’ve Learned

In this tutorial, you’ve learned:

• What image tags are and how they enhance reverse image search
• How to add tags with reference images to your search context
• How to find images using one or more tags
• Advanced tagging strategies for more effective search
• Best practices for implementing tag-based image search

Troubleshooting Tips

• No Results: If tag searches return no results, check that you’ve added reference images for those tags
• Poor Matches: If tag matches are poor, consider using multiple reference images per tag
• Case Sensitivity: Tag names are typically case-sensitive; be consistent in how you define and search for them
• Special Characters: Avoid special characters in tag names that might cause API issues

Next Steps

Now that you know how to work with image tags, you’re ready to move on to the next tutorial in our series:

→ Tutorial: Managing Image Features

In the next tutorial, you’ll learn how to update and manage the features extracted from your images.

Further Practice

To reinforce what you’ve learned:

• Create a comprehensive tagging system for a small image collection
• Implement a multi-tag search that finds images matching all specified tags
• Create a script that adds multiple reference images for the same tag
• Experiment with using tags to find images that are conceptually related but visually different

Helpful Resources

• Product Page
• Documentation
• API Reference
• Free Support
• Free Trial

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