Skip to content

Latest commit

 

History

History

scipix

README.md

SciPix - Rust OCR Engine for Scientific Documents & Math Equations

Crates.io Documentation Downloads License: MIT Rust CI

🔬 Production-ready Rust OCR library for extracting LaTeX, MathML, and text from scientific images

Convert mathematical equations, scientific papers, and technical diagrams to structured text with GPU-accelerated inference

Installation | Quick Start | SDK Usage | CLI Reference | Tutorials | API Reference

Why SciPix?

SciPix is a blazing-fast, memory-safe OCR (Optical Character Recognition) engine written in pure Rust. Unlike traditional OCR tools, SciPix is purpose-built for scientific documents, mathematical equations, and technical diagrams — making it the ideal choice for researchers, academics, and developers working with STEM content.

Use Cases

  • 📄 Academic Paper Digitization - Extract text and equations from scanned research papers
  • 🧮 Math Homework Assistance - Convert handwritten equations to LaTeX for AI tutoring apps
  • 📊 Technical Documentation - Process engineering diagrams and scientific charts
  • 🔬 Research Data Extraction - Batch process journal articles and extract structured data
  • 🤖 AI/LLM Integration - Feed scientific content to language models via MCP protocol

Key Features

Feature Description
🚀 ONNX Runtime GPU-accelerated neural network inference with CUDA, TensorRT, and CoreML support
📐 LaTeX Output Accurate mathematical equation recognition with LaTeX, MathML, and AsciiMath export
⚡ SIMD Optimized 4x faster image preprocessing with AVX2, SSE4, and NEON vectorization
🌐 REST API Production-ready HTTP server with rate limiting, caching, and authentication
💻 CLI Tool Batch processing, PDF conversion, and watch mode for continuous OCR
🦀 Pure Rust SDK Type-safe, async/await native library with zero-copy image processing
🔌 WebAssembly Run OCR directly in browsers with full WASM support
🤖 MCP Server Integrate with Claude, ChatGPT, and other AI assistants via Model Context Protocol
📦 Cross-Platform Linux, macOS, Windows, and ARM64 support out of the box

Performance Benchmarks

Operation SciPix Tesseract Mathpix
Simple Text OCR 50ms 120ms 200ms*
Math Equation 80ms N/A 150ms*
Batch (100 images) 2.1s 8.5s N/A
Memory Usage 45MB 180MB Cloud

*API latency, not processing time

Installation

From crates.io (Rust SDK)

cargo add ruvector-scipix

Or add to your Cargo.toml:

[dependencies]
ruvector-scipix = "0.1.16"

# With specific features
ruvector-scipix = { version = "0.1.16", features = ["ocr", "math", "optimize"] }

From Source (CLI & Server)

# Clone the repository
git clone https://github.com/ruvnet/ruvector.git
cd ruvector/examples/scipix

# Build CLI and Server
cargo build --release

# Install globally (optional)
cargo install --path .

Pre-built Binaries

# Download latest release (Linux)
curl -L https://github.com/ruvnet/ruvector/releases/latest/download/scipix-cli-linux-x64 -o scipix-cli
chmod +x scipix-cli

# Download latest release (macOS)
curl -L https://github.com/ruvnet/ruvector/releases/latest/download/scipix-cli-darwin-arm64 -o scipix-cli
chmod +x scipix-cli

Feature Flags

Flag Description Default
default preprocess, cache, optimize ✅
ocr ONNX-based OCR engine ❌
math Math expression parsing ❌
preprocess Image preprocessing ✅
cache Result caching ✅
optimize SIMD & parallel optimizations ✅
wasm WebAssembly support ❌

Quick Start

30-Second Setup

# Build and run the server
cd examples/scipix
cargo run --release --bin scipix-server

# In another terminal, test the API
curl http://localhost:3000/health
# {"status":"healthy","version":"0.1.16"}

Process Your First Image

# Encode an image to base64
BASE64_IMAGE=$(base64 -w 0 equation.png)

# Send OCR request
curl -X POST http://localhost:3000/v3/text \
  -H "Content-Type: application/json" \
  -H "app_id: demo" \
  -H "app_key: demo_key" \
  -d "{\"base64\": \"$BASE64_IMAGE\", \"metadata\": {\"formats\": [\"text\", \"latex\"]}}"

SDK Usage

Basic Usage

use ruvector_scipix::{Config, Result};

fn main() -> Result<()> {
    // Load default configuration
    let config = Config::default();

    // Validate configuration
    config.validate()?;

    println!("SciPix version: {}", ruvector_scipix::VERSION);
    Ok(())
}

Image Preprocessing

use ruvector_scipix::preprocess::{PreprocessPipeline, transforms};
use image::open;

fn preprocess_image(path: &str) -> Result<(), Box<dyn std::error::Error>> {
    // Load image
    let img = open(path)?;

    // Create preprocessing pipeline
    let pipeline = PreprocessPipeline::new()
        .with_auto_rotate(true)
        .with_auto_deskew(true)
        .with_noise_reduction(true)
        .with_contrast_enhancement(true);

    // Process image
    let processed = pipeline.process(img)?;

    // Save result
    processed.save("processed.png")?;

    Ok(())
}

OCR Engine (requires ocr feature)

use ruvector_scipix::ocr::{OcrEngine, OcrOptions};
use ruvector_scipix::OcrConfig;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize OCR engine
    let config = OcrConfig::default();
    let engine = OcrEngine::new(config).await?;

    // Load and process image
    let image = image::open("equation.png")?;
    let result = engine.recognize(&image).await?;

    println!("Text: {}", result.text);
    println!("Confidence: {:.2}%", result.confidence * 100.0);

    // Get LaTeX output
    if let Some(latex) = result.latex {
        println!("LaTeX: {}", latex);
    }

    Ok(())
}

Math Parsing (requires math feature)

use ruvector_scipix::math::{parse_expression, to_latex, to_mathml};

fn parse_math() -> Result<(), Box<dyn std::error::Error>> {
    // Parse a mathematical expression
    let expr = parse_expression("x^2 + 2x + 1")?;

    // Convert to different formats
    let latex = to_latex(&expr)?;
    let mathml = to_mathml(&expr)?;

    println!("LaTeX: {}", latex);
    println!("MathML: {}", mathml);

    Ok(())
}

Caching Results

use ruvector_scipix::cache::CacheManager;
use ruvector_scipix::CacheConfig;

fn use_cache() -> Result<(), Box<dyn std::error::Error>> {
    let config = CacheConfig {
        max_size: 1000,
        ttl_seconds: 3600,
        ..Default::default()
    };

    let cache = CacheManager::new(config)?;

    // Store result
    cache.store("image_hash_123", &result)?;

    // Retrieve result
    if let Some(cached) = cache.get("image_hash_123")? {
        println!("Cache hit: {}", cached.latex);
    }

    Ok(())
}

Configuration Presets

use ruvector_scipix::{default_config, high_accuracy_config, high_speed_config};

fn configure() {
    // Default balanced configuration
    let config = default_config();

    // High accuracy (slower, more precise)
    let accurate = high_accuracy_config();

    // High speed (faster, may sacrifice accuracy)
    let fast = high_speed_config();
}

CLI Reference

Installation

# Install from source
cargo install --path examples/scipix

# Or use pre-built binary
./scipix-cli --help

Commands

ocr - Process Single Image

# Basic OCR
scipix-cli ocr --input document.png

# With output file and format
scipix-cli ocr --input equation.png --output result.json --format latex

# Specify output formats
scipix-cli ocr --input image.png --formats text,latex,mathml

Options:

Flag Description Default
-i, --input Input image path Required
-o, --output Output file path stdout
-f, --format Output format (json, text, latex) json
--formats OCR formats (text, latex, mathml, html) text
--confidence Minimum confidence threshold 0.5

batch - Process Multiple Images

# Process directory
scipix-cli batch --input-dir ./images --output-dir ./results

# With parallel processing
scipix-cli batch -i ./images -o ./results --parallel 8

# Recursive with specific formats
scipix-cli batch -i ./docs -o ./output --recursive --format latex

# Watch mode for continuous processing
scipix-cli batch -i ./inbox -o ./processed --watch

Options:

Flag Description Default
-i, --input-dir Input directory Required
-o, --output-dir Output directory Required
-p, --parallel Parallel workers CPU cores
-r, --recursive Process subdirectories false
--watch Watch for new files false
--max-retries Retry failed files 3

serve - Start API Server

# Start with defaults
scipix-cli serve

# Custom address and port
scipix-cli serve --address 0.0.0.0 --port 8080

# With configuration file
scipix-cli serve --config ./config.toml

# Enable debug logging
RUST_LOG=debug scipix-cli serve

Options:

Flag Description Default
-a, --address Bind address 127.0.0.1
-p, --port Port number 3000
-c, --config Config file path None
--workers Worker threads CPU cores

config - Manage Configuration

# Show current configuration
scipix-cli config show

# Initialize default config file
scipix-cli config init

# Set specific values
scipix-cli config set ocr.confidence_threshold 0.8
scipix-cli config set server.port 8080

# Validate configuration
scipix-cli config validate

doctor - Environment Check

# Run full diagnostics
scipix-cli doctor

# Check specific components
scipix-cli doctor --check cpu,memory,deps

# Output as JSON
scipix-cli doctor --format json

# Auto-fix issues
scipix-cli doctor --fix

Checks performed:

  • CPU cores and SIMD capabilities (SSE2, AVX, AVX2, AVX-512, NEON)
  • Memory availability
  • ONNX Runtime installation
  • Model file availability
  • Configuration validity
  • Network port availability

mcp - MCP Server Mode

# Start MCP server for AI integration
scipix-cli mcp

# With debug logging
scipix-cli mcp --debug

# With custom models directory
scipix-cli mcp --models-dir ./custom-models

Available MCP Tools:

Tool Description
ocr_image Process image file with OCR
ocr_base64 Process base64-encoded image
batch_ocr Batch process multiple images
preprocess_image Apply image preprocessing
latex_to_mathml Convert LaTeX to MathML
benchmark_performance Run performance benchmarks

Claude Code Integration:

claude mcp add scipix -- scipix-cli mcp

Tutorials

Tutorial 1: Basic Image OCR

Learn to extract text from images using the REST API.

# Step 1: Start the server
cargo run --bin scipix-server

# Step 2: Encode your image
BASE64=$(base64 -w 0 document.png)

# Step 3: Send OCR request
curl -X POST http://localhost:3000/v3/text \
  -H "Content-Type: application/json" \
  -H "app_id: test" \
  -H "app_key: test123" \
  -d "{\"base64\": \"$BASE64\", \"metadata\": {\"formats\": [\"text\"]}}"

Tutorial 2: Mathematical Equation Recognition

Convert math images to LaTeX format.

curl -X POST http://localhost:3000/v3/text \
  -H "Content-Type: application/json" \
  -H "app_id: test" \
  -H "app_key: test123" \
  -d '{
    "url": "https://example.com/equation.png",
    "metadata": {
      "formats": ["latex", "mathml"],
      "math_mode": true
    }
  }'

Response:

{
  "latex": "\\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}",
  "mathml": "<math>...</math>",
  "confidence": 0.92
}

Tutorial 3: Batch PDF Processing

Process multi-page PDFs asynchronously.

# Submit PDF job
JOB=$(curl -s -X POST http://localhost:3000/v3/pdf \
  -H "Content-Type: application/json" \
  -H "app_id: test" \
  -H "app_key: test123" \
  -d '{
    "url": "https://example.com/paper.pdf",
    "options": {"format": "mmd", "enable_ocr": true}
  }')

JOB_ID=$(echo $JOB | jq -r '.pdf_id')

# Poll for completion
curl http://localhost:3000/v3/pdf/$JOB_ID \
  -H "app_id: test" -H "app_key: test123"

Tutorial 4: CLI Batch Processing

# Process entire directory
scipix-cli batch \
  --input-dir ./documents \
  --output-dir ./results \
  --format latex \
  --parallel 4 \
  --recursive

# Watch mode for continuous processing
scipix-cli batch \
  --input-dir ./inbox \
  --output-dir ./processed \
  --watch

Tutorial 5: WebAssembly Integration

# Build WASM module
cargo install wasm-pack
wasm-pack build --target web --features wasm
<script type="module">
  import init, { ScipixWasm } from './pkg/ruvector_scipix.js';

  async function processImage() {
    await init();
    const scipix = new ScipixWasm();
    await scipix.initialize();

    const canvas = document.getElementById('canvas');
    const imageData = canvas.getContext('2d').getImageData(0, 0, canvas.width, canvas.height);
    const result = await scipix.recognize(imageData.data);
    console.log('Result:', result);
  }

  processImage();
</script>

Tutorial 6: Using as MCP Server

Integrate SciPix with Claude Code or other AI assistants.

# Add to Claude Code
claude mcp add scipix -- scipix-cli mcp

# Or run standalone
scipix-cli mcp --debug

Then use tools in your AI conversations:

  • "Use the ocr_image tool to extract text from ./screenshot.png"
  • "Convert this LaTeX to MathML: \frac{1}{2}"

API Reference

Authentication

All API endpoints (except /health) require authentication:

app_id: your_application_id
app_key: your_secret_key

Endpoints

POST /v3/text - Image OCR

{
  "base64": "...",
  "url": "https://...",
  "metadata": {
    "formats": ["text", "latex", "mathml"],
    "confidence_threshold": 0.5,
    "math_mode": false
  }
}

POST /v3/strokes - Digital Ink

{
  "strokes": [{"x": [0, 10, 20], "y": [0, 10, 0]}],
  "metadata": {"formats": ["latex"]}
}

POST /v3/pdf - PDF Processing

{
  "url": "https://example.com/doc.pdf",
  "options": {
    "format": "mmd",
    "enable_ocr": true,
    "page_range": "1-10"
  }
}

GET /health - Health Check

{"status": "healthy", "version": "0.1.16"}

Configuration

Environment Variables

SERVER_ADDR=127.0.0.1:3000
RUST_LOG=scipix=info
RATE_LIMIT_PER_MINUTE=100
CACHE_MAX_SIZE=1000
MODEL_PATH=./models

Configuration File

[server]
address = "127.0.0.1"
port = 3000
workers = 4

[ocr]
model_path = "./models"
confidence_threshold = 0.5

[cache]
max_size = 1000
ttl_seconds = 3600

[rate_limit]
requests_per_minute = 100
burst_size = 20

Performance

Operation Time (avg) Throughput
SIMD Grayscale 101µs 4.2x faster
SIMD Resize 2.63ms 1.5x faster
Full Pipeline 0.49ms 4.4x faster
Simple text OCR ~50ms 20 img/s
Math equation ~80ms 12 img/s

Troubleshooting

# Check environment
scipix-cli doctor

# Enable debug logging
RUST_LOG=debug scipix-cli serve

# Verify models installed
ls -la models/

Contributing

# Run tests
cargo test --all-features

# Run linting
cargo clippy --all-features

# Format code
cargo fmt

License

MIT License - see LICENSE for details.

Part of the ruvector ecosystem
Built with Rust 🦀 | Powered by ONNX Runtime