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.
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.
Parameter | Type | Description | Default |
---|---|---|---|
vision_model | string | Vision model for image analysis | Server optimized |
emb_model | string | Embedding model for text vectors | Server optimized |
max_chunk_size | number | Maximum chunk size for descriptions | Server optimized |
chunk_overlap | number | Character overlap between chunks | Server optimized |
separators | string[] | Text splitting patterns for descriptions | Server optimized |
is_separator_regex | boolean | Enable regex in separators | false |
keep_separator | boolean | Preserve separators in chunks | false |
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
}
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/jpeg
image/jpg
image/png
image/gif
image/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
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.
Share Your Thoughts
Your feedback helps us improve our documentation. Let us know what you think!