# 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`:
```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:
```env
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
```rust
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
```rust
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
```rust
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:
```rust
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:
```bash
# 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:
```bash
cargo test
```
## License
MIT License - see LICENSE file for details.