BilberryDB - Image Search (Rust)

Developer SDK for creating image search engines, image classification models, image duplication recognition, and Visual recommender systems with BilberryDB.

What it does

This library helps you find images that look similar to a given image. Just provide an image path, and it will return the most similar images from your Bilberry Vector DB.

Installation

Add this to your Cargo.toml:

[dependencies]
bilberrydb = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

Getting API Keys

You need API keys to use BilberryDB:

1. Visit www.bilberrydb.com
2. Go to API Key section
3. Click Create New API Key
4. Enter API Key Name (like "My image search project")
5. Click Create Key

Setup

1. Create a .env file in your project root:

BILBERRY_API_KEY=your_api_key_here
BILBERRY_API_ID=your_registered_email_here

2. Replace your_api_key_here with your actual API key
3. Replace your_registered_email_here with the email you used to register

Usage

Basic Example

use bilberrydb::{init, BilberryConfig};
use dotenv::dotenv;
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv().ok();
    // Load API keys from environment variables
    let api_key = env::var("BILBERRY_API_KEY")
        .expect("Missing BILBERRY_API_KEY environment variable");
    let api_id = env::var("BILBERRY_API_ID")
        .expect("Missing BILBERRY_API_ID environment variable");

    // Connect to BilberryDB
    let client = init(BilberryConfig {
        api_key,
        api_id,
        base_url: None,
    })?;

    // Search for similar images
    let vec = client.get_vec();
    let results = vec.search_by_path("./test-chair.jpg", Some(5)).await?;

    // Show results
    println!("Found {} similar images:", results.len());
    
    for (index, result) in results.iter().enumerate() {
        let filename = result.get_filename();
        println!("{}. Image: {}", index + 1, filename);
        println!("   Similarity: {:.3}", result.get_similarity_score());
        println!("   File Type: {}", result.file_type);
    }

    Ok(())
}

Search with Image Bytes

use bilberrydb::{init, BilberryConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = init(BilberryConfig {
        api_key: "your_api_key".to_string(),
        api_id: "your_email@example.com".to_string(),
        base_url: None,
    })?;

    // Read image data
    let image_data = std::fs::read("path/to/your/image.jpg")?;
    
    // Search using bytes
    let vec = client.get_vec();
    let results = vec.search_by_bytes(&image_data, Some(10)).await?;

    for result in results {
        println!("Similar image: {} (score: {:.3})", 
                 result.get_filename(), result.similarity_score);
    }

    Ok(())
}

Get All Items

use bilberrydb::{init, BilberryConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = init(BilberryConfig {
        api_key: "your_api_key".to_string(),
        api_id: "your_email@example.com".to_string(),
        base_url: None,
    })?;

    let vec = client.get_vec();
    let items = vec.get_all_items(None).await?;

    println!("Total items: {}", items.len());
    for item in items {
        println!("- {}: {} ({} bytes)", 
                 item.id, item.filename, item.file_size);
    }

    Ok(())
}

How to use

1. Replace "path/to/your/image.jpg" with the actual path to your image
2. Change the number in Some(5) to get more or fewer results
3. Run your program: cargo run

What you get back

Each SearchResult includes:

• filename / file_name: Name of the similar image
• similarity_score: How similar it is (higher = more similar)
• file_type: Type of image file (jpg, png, etc.)
• id: Unique ID of the image
• content_type: MIME type of the file
• created_at: When the file was uploaded
• file_size: Size of the file in bytes

API Methods

BilberryVector Methods

• search_by_path(image_path, top_k) - Search using file path
• search_by_bytes(image_data, top_k) - Search using image bytes
• search_by_path_with_options(image_path, options) - Advanced search with options
• search_by_bytes_with_options(image_data, options) - Advanced search with bytes
• get_all_items(content_type) - Get all uploaded items
• download_file(item_id) - Download a file by ID

SearchResult Helper

• result.get_filename() - Get filename (handles both filename and file_name fields)

Error Handling

The library uses Rust's Result type for error handling:

match vec.search_by_path("image.jpg", Some(5)).await {
    Ok(results) => {
        // Handle successful results
        for result in results {
            println!("Found: {}", result.get_filename());
        }
    }
    Err(e) => {
        // Handle errors
        eprintln!("Error: {}", e);
    }
}

Common Issues

"Missing API keys": Make sure your environment variables are set correctly.

"Search failed": Check that:

• Your image path is correct
• Your API keys are valid
• You have internet connection
• The image file exists and is readable

"File not found": Make sure the image path exists and the file is accessible.

Requirements

• Rust 1.70 or higher
• Valid BilberryDB account and API keys
• Internet connection for API calls

Development

To run the examples:

# Set environment variables
export BILBERRY_API_KEY="your_api_key_here"
export BILBERRY_API_ID="your_email@example.com"

# Run the basic search example
cargo run --example basic_search

To run tests:

cargo test

License

MIT License - see LICENSE file for details.