Image

Overview

OneNode uses AI-powered vision models to understand and index image content for semantic search. The Image class provides intelligent image processing capabilities with automatic format detection, enabling powerful visual search across your image content.

Note: The Image class is designed specifically for semantic search. For simple image storage without search capabilities, use regular file uploads instead.

Key Features:

  • Semantic Indexing: Enable intelligent image understanding with the fluent .enableIndex() method.
  • Automatic Format Detection: Supports multiple image formats with magic byte detection.
  • AI Vision Processing: Converts images to searchable text descriptions using advanced vision models.
  • Asynchronous Processing: Image analysis happens in the background without blocking your application.
  • Multiple Input Types: Accept files, URLs, base64, binary data, and more.
  • Server Defaults: Unspecified parameters automatically use optimized server-side defaults.

Basic Usage

The Image class should be used with the .enableIndex() method to enable semantic search capabilities:

from onenode import Image

# Step 1: Create Image instance
product_image = Image("product.jpg")

# Step 2: Enable indexing
product_image.enable_index()

# Step 3: Use in document
{
  "field_name": product_image
}

This creates an Image object with semantic indexing enabled using server defaults for the vision model, embedding model, and text processing strategy.

🔗 Automatic URL Generation

When you insert an Image into your collection, OneNode automatically uploads your image to secure cloud storage and generates a publicly accessible URL. This URL is then assigned to the image object, making it easy to display your images in applications while keeping them searchable.

Input Methods

The Image class accepts multiple input formats with automatic type detection:

from onenode import Image

# From file path (type detected from extension)
image = Image("path/to/image.jpg")

# From binary data (type detected from magic bytes)
with open("image.jpg", "rb") as f:
    image = Image(f.read())

# From file-like object (type detected from magic bytes)
with open("image.jpg", "rb") as f:
    image = Image(f)

# From base64 string (type detected from magic bytes)
image = Image("base64_encoded_data")

# From data URL (type extracted from URL)
image = Image("data:image/jpeg;base64,...")

# From URL (type detected from extension)
image = Image("https://example.com/image.png")

# Enable indexing
image.enable_index()

Configuration Reference

Note: All configuration parameters are completely optional and recommended only for advanced users. OneNode automatically uses optimized defaults that work well for most use cases.

ParameterTypeDescriptionDefault
vision_modelstringVision model for image analysisServer optimized
emb_modelstringEmbedding model for text vectorsServer optimized
max_chunk_sizenumberMaximum chunk size for descriptionsServer optimized
chunk_overlapnumberCharacter overlap between chunksServer optimized
separatorsstring[]Text splitting patterns for descriptionsServer optimized
is_separator_regexbooleanEnable regex in separatorsfalse
keep_separatorbooleanPreserve separators in chunksfalse

Advanced Customization

The following examples show how to customize Image indexing behavior for specific use cases. These configurations are optional and should only be used when you need specific behavior.

Vision Model

Specify a specific vision model for quality, speed, or cost optimization:

from onenode import Image, Models

# Using a specific vision model for higher quality image analysis
hero_image = Image("hero_banner.jpg")

# Configure with a high-quality vision model
vision_config = {
    "vision_model": Models.ImageToText.OpenAI.GPT_4O
}

hero_image.enable_index(**vision_config)

# Use in document
{
    "hero_banner": hero_image
}

Embedding Model

Configure both vision and embedding models for optimal results:

from onenode import Image, Models

# Configure both vision and embedding models
gallery_image = Image("gallery_1.jpg")

# High-quality models for important visual content
quality_config = {
    "vision_model": Models.ImageToText.OpenAI.GPT_4O,
    "emb_model": Models.TextToEmbedding.OpenAI.TEXT_EMBEDDING_3_LARGE
}

gallery_image.enable_index(**quality_config)

# Use in document
{
    "gallery_image": gallery_image
}

Chunk Size

Control chunk size for different image complexity levels:

from onenode import Image

# For detailed images - larger chunks to maintain context
detailed_diagram = Image("architecture_diagram.jpg")

detailed_config = {
    "max_chunk_size": 800  # Larger chunks for complex descriptions
}

detailed_diagram.enable_index(**detailed_config)

# For simple product images - smaller chunks for precise matching
product_thumb = Image("product_thumbnail.jpg")

simple_config = {
    "max_chunk_size": 200  # Smaller chunks for simple descriptions
}

product_thumb.enable_index(**simple_config)

# Use in documents
{
    "architecture_diagram": detailed_diagram,
    "product_thumbnail": product_thumb
}

Chunk Overlap

Configure overlap between chunks to preserve visual context:

from onenode import Image

# High overlap for complex visual content with interconnected elements
technical_image = Image("technical_schematic.jpg")

high_overlap_config = {
    "max_chunk_size": 400,
    "chunk_overlap": 80  # High overlap to preserve context between visual elements
}

technical_image.enable_index(**high_overlap_config)

# Low overlap for images with distinct sections
infographic = Image("business_infographic.jpg")

low_overlap_config = {
    "max_chunk_size": 400,
    "chunk_overlap": 20  # Low overlap for distinct visual sections
}

infographic.enable_index(**low_overlap_config)

# Use in documents
{
    "technical_schematic": technical_image,
    "business_infographic": infographic
}

Custom Separators

Define how image descriptions should be split for structured visual content:

from onenode import Image

# Custom separators for structured visual content descriptions
screenshot_image = Image("dashboard_screenshot.jpg")

# Split by UI sections in the visual description
ui_config = {
    "separators": ["Section:", "Panel:", "\n\n"],  # Split by UI elements and paragraphs
    "max_chunk_size": 300
}

screenshot_image.enable_index(**ui_config)

# Different separators for step-by-step visual content
tutorial_image = Image("tutorial_steps.jpg")

step_config = {
    "separators": ["Step \d+:", "Figure \d+:", "\n\n"],  # Split by steps and figures
    "max_chunk_size": 250
}

tutorial_image.enable_index(**step_config)

# Use in documents
{
    "dashboard_screenshot": screenshot_image,
    "tutorial_visual": tutorial_image
}
💡 Pro Tip

Start with server defaults and only customize when you have specific requirements. You can combine any parameters for your use case.


After Processing

Once your document is saved and processed, you can access key properties of the Image object. Focus on these essential properties:

# After processing, access key properties of your Image
documents = collection.find({"_id": "document_id"})
document = documents[0]  # find() returns a list
image_obj = document["field_name"]

# Access the image URL (where it's stored)
print(image_obj.data)
# Output: "https://media.onenode.com/your-project/your-db/your-collection/doc-id/field_name.jpg"

# Access the vision-generated text chunks (most important for understanding search)
print(image_obj.chunks)
# Output: [
#   "A high-quality wireless headphone with noise cancellation technology",
#   "displayed on white background with modern design"
# ]

# Access the detected MIME type
print(image_obj.mime_type)
# Output: "image/jpeg"

# Check if indexing is enabled
print(image_obj.index_enabled)
# Output: True

Visual Semantic Search Targeting Image Descriptions

Important: Visual semantic search works by having AI vision models analyze your images and generate descriptive text chunks. Search then targets these text descriptions, allowing you to find images based on their visual content using natural language queries.

# Visual semantic search targets chunks from AI-generated image descriptions
# This allows you to find images based on their visual content

# Insert a document with an image
product_image = Image("product_headphones.jpg").enable_index()

collection.insert([{
    "name": "Premium Headphones",
    "category": "Electronics",
    "image": product_image
}])

# Use collection.query() for visual semantic search
results = collection.query("wireless headphones with noise cancellation")

# The search will match based on what the AI vision model saw in the image
for match in results:
    print(f"Found image described as: {match.chunk}")
    print(f"In product: {match.document['name']}")
    print(f"Match score: {match.score}")
    
    # Access the full Image object from the document
    image_obj = match.document["image"]
    print(f"Image URL: {image_obj.data}")
    print(f"All image descriptions: {image_obj.chunks}")

Nested Fields

Image objects can be used in nested structures:

from onenode import Image

# Step 1: Create Image instance for product gallery
hero_image = Image("hero_product.jpg")

# Step 2: Enable indexing
hero_image.enable_index()

# Step 3: Use in nested document structure
{
  "product": {
    "name": "Smart Watch",
    "hero_image": hero_image,
    "gallery": [Image("gallery_1.jpg").enable_index(), Image("gallery_2.jpg").enable_index()]
  }
}

How It Works

🔍

Auto-Detection

Detects image format automatically

👁️

Vision Analysis

AI describes image content

✂️

Text Chunking

Breaks descriptions into pieces

🧮

Embedding

Converts text to vectors

🔗

URL Generation

Creates accessible image URLs

Supported Formats

image/jpegimage/jpgimage/pngimage/gifimage/webp

File Type Detection

The Image class automatically detects file types using multiple methods:

Detection Methods

  • Magic bytes: Binary file headers
  • File extensions: .jpg, .png, .gif, .webp
  • Data URLs: Extracted from data: URLs
  • File objects: From file.type or filename

Magic Byte Signatures

  • JPEG: FF D8 FF
  • PNG: 89 50 4E 47 0D 0A 1A 0A
  • GIF: 47 49 46 38 [37|39] 61
  • WebP: 52 49 46 46 ... 57 45 42 50
Learn More About Image Search

Once your images are indexed, explore powerful search capabilities and learn about related operations to get the most out of your indexed content.

Best Practices

  • Use Image for semantic search only: For simple image storage, use regular file uploads instead.
  • Always use .enableIndex(): Required to enable semantic search features.
  • Start with defaults: Server defaults work well for most use cases.
  • Customize sparingly: Only adjust parameters when you have specific requirements.
  • Let auto-detection work: Trust the automatic format detection instead of manually specifying types.

Got question? Email us and we'll get back to you within 24 hours.