Spring Vision

The Ultimate Computer Vision Framework for Spring Boot Applications

Spring Vision is a computer vision framework that brings AI capabilities to your Spring Boot applications. Built on the Deep Java Library (DJL), it provides a simple API for common computer vision tasks. Core models (YOLO, RetinaFace) are bundled in the JAR - no downloads required for production use!

✨ Features

🚀 Easy Setup: Get started quickly with auto-configuration and sensible defaults.
📦 Self-Contained JARs: Core AI models (YOLO, RetinaFace) bundled - no downloads needed!
🤖 DJL-Powered: Built on Deep Java Library for modern AI model management.
🔌 Multiple Engines: Support for PyTorch, ONNX Runtime, TensorFlow backends.
🌐 Cross-Platform: Works on Linux, macOS, and Windows.
🏗️ Spring Boot Integration: Health checks, metrics, and Spring ecosystem compatibility.
⚡ Production Ready: 8+ computer vision capabilities ready for deployment.

🚀 Getting Started

Quick Install (Recommended for End Users)

For the easiest installation experience, run our CLI setup tool directly with JBang:

# Run the CLI setup tool to automatically download and configure everything
jbang https://github.com/codesapienbe/spring-vision/releases/download/v0.0.4/cli-0.0.4.jar

That's it! The CLI tool will automatically:

✅ Check for JBang installation and guide you if needed
📦 Download the latest Spring Vision MCP Server JAR (~983MB)
💾 Store it locally in ~/.springvision/ (no re-downloads needed!)
ℹ️ Show you how to configure your MCP client
🚀 Set up everything automatically with no manual steps required!

Manual Installation

Spring Vision includes an MCP (Model Context Protocol) server with bundled AI models. Build and run manually:

# Clone the repository
git clone https://github.com/codesapienbe/spring-vision.git
cd spring-vision

# Build with models (downloads YOLO/RetinaFace during build)
mvn clean install -Pdownload-models

# Run the MCP server with JBang
jbang run.java

Or use the Makefile (includes model download):

make build  # Downloads and bundles models
make run    # Runs the server

Using as a Library

1. Add Repository

Spring Vision artifacts are published to GitHub Packages. Add the repository to your POM (no authentication required for public access):

<repositories>
    <repository>
        <id>github</id>
        <name>GitHub Packages</name>
        <url>https://maven.pkg.github.com/codesapienbe/spring-vision</url>
    </repository>
</repositories>

2. Add Dependency

<dependency>
    <groupId>io.github.codesapienbe.springvision</groupId>
    <artifactId>starter</artifactId>
    <version>0.0.4</version>
</dependency>

3. Use in Your Code

@RestController
public class VisionController {

    @Autowired
    private VisionTemplate visionTemplate;

    @PostMapping("/detect-faces")
    public List<Detection> detectFaces(@RequestParam("file") MultipartFile file) {
        return visionTemplate.detectFaces(file.getBytes());
    }
}

That's it! Your Spring Boot application now has state-of-the-art computer vision capabilities powered by DJL.

🤖 MCP Client Configuration

After running the CLI tool, configure your MCP client (Claude Desktop, VS Code, etc.) to use Spring Vision:

Using the CLI Tool Output

The CLI tool will show you the exact configuration. Here's an example:

{
  "mcpServers": {
    "spring-vision": {
      "command": "jbang",
      "args": ["/home/youruser/.springvision/mcp-0.0.4.jar"]
    }
  }
}

Manual Configuration

Find your MCP config file:
- Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
- VS Code: ~/.cursor/mcp.json
- Other clients: Check their documentation

Add Spring Vision configuration:

{
  "mcpServers": {
    "spring-vision": {
      "command": "jbang",
      "args": ["~/.springvision/mcp-0.0.4.jar"]
    }
  }
}

Restart your MCP client to load the new configuration

Testing the Setup

After configuration, restart your MCP client. You should see Spring Vision tools available with capabilities like:

Face detection and recognition
Object detection
Image classification
Text extraction (OCR)
And many more!

⚙️ Configuration

Basic Setup

Spring Vision works out of the box with minimal configuration:

spring:
  vision:
    djl:
      enabled: true
      engine: pytorch  # or tensorflow, onnx
      device: cpu      # or gpu for GPU acceleration

GPU Support (Optional)

For GPU acceleration, use:

spring:
  config:
    activate:
      on-profile: gpu
  vision:
    djl:
      device: gpu

🚀 DJL Backend Features

📦 Bundled Core Models: YOLOv8 and RetinaFace models included in JAR (no downloads needed)
🔄 Runtime Downloads: Advanced AI models download on-demand from DJL Model Zoo
⚙️ Multi-Engine Support: PyTorch, ONNX Runtime, TensorFlow backends
🚀 GPU Acceleration: CUDA support for faster inference (optional)
🎯 Production Ready: 8+ computer vision capabilities with zero-configuration

Current Capabilities

Spring Vision 0.0.4 provides these computer vision capabilities (all models included in JAR):

✅ Production Ready

Face Detection - High-accuracy RetinaFace model (included)
Object Detection - YOLOv8 models (included)
Pose Estimation - YOLOv8 pose models (included)
Barcode/QR Scanning - ZXing library (included)
Metadata Extraction - EXIF/GPS/camera data (included)
Image Annotation - Drawing utilities (included)

🤖 AI-Powered (Runtime Download)

Text Recognition (OCR) - DJL OCR models
Image Classification - ResNet/Inception models
Segmentation - Instance/Semantic segmentation
Action Recognition - Activity detection models
Face Embeddings - Face recognition vectors

🛡️ Security & Safety

NSFW Detection - Content filtering
Deepfake Detection - AI-generated media detection
Threat Detection - Weapons/object detection
Biometric Authentication - Face-based access control

❤️ Health & Wellness

Fall Detection - Pose-based fall analysis
Stress Analysis - Emotion-based stress detection
Heart Rate - rPPG analysis from faces
Demographics - Age/gender estimation

Architecture

Spring Vision uses a modern, capability-based architecture built on the Deep Java Library (DJL):

Core Components

spring-vision-core - Main framework with VisionTemplate and capabilities
spring-vision-starter - Auto-configuration and REST API
spring-vision-mcp - MCP server integration

Architecture Layers

Application Layer: REST API endpoints (/api/vision/*)
Framework Core: VisionTemplate provides unified API for all vision tasks
DJL Backend: Deep Java Library handles model management and inference
Vision Capabilities: Modular detection and analysis capabilities

Key Features

Single Dependency: One starter brings all computer vision capabilities
Model Bundling: Core models (YOLO, RetinaFace) included in JAR
Auto-Configuration: Zero-configuration setup with intelligent defaults
Runtime Downloads: Advanced models download on-demand

CLI Setup Commands

The Spring Vision CLI tool provides several options:

# Basic setup (downloads latest version)
jbang https://github.com/codesapienbe/spring-vision/releases/latest/download/cli-0.0.4.jar

# Force re-download even if JAR exists
jbang https://github.com/codesapienbe/spring-vision/releases/latest/download/cli-0.0.4.jar --force

# Show help
jbang https://github.com/codesapienbe/spring-vision/releases/latest/download/cli-0.0.4.jar --help

# Show version
jbang https://github.com/codesapienbe/spring-vision/releases/latest/download/cli-0.0.4.jar --version

# Disable colors (for CI/CD)
jbang https://github.com/codesapienbe/spring-vision/releases/latest/download/cli-0.0.4.jar --no-color

# Verbose output (for debugging)
jbang https://github.com/codesapienbe/spring-vision/releases/latest/download/cli-0.0.4.jar --verbose

Managing Your Installation

# Update to latest version
jbang https://github.com/codesapienbe/spring-vision/releases/latest/download/cli-0.0.4.jar --force

# Check JAR location
ls -la ~/.springvision/

# Remove downloaded JAR
rm ~/.springvision/mcp-*.jar

GPU Acceleration (Optional)

For GPU acceleration, use the gpu profile:

mvn clean package -P gpu
java -jar target/your-app.jar --spring.profiles.active=gpu

Note: GPU support requires NVIDIA CUDA drivers and is optional for development.

Contributing

We welcome contributions! Please see the Contributing guide for more information.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Spring Vision

✨ Features

🚀 Getting Started

Quick Install (Recommended for End Users)

Manual Installation

Using as a Library

1. Add Repository

2. Add Dependency

3. Use in Your Code

🤖 MCP Client Configuration

Using the CLI Tool Output

Manual Configuration

Testing the Setup

⚙️ Configuration

Basic Setup

GPU Support (Optional)

🚀 DJL Backend Features

Current Capabilities

✅ Production Ready

🤖 AI-Powered (Runtime Download)

🛡️ Security & Safety

❤️ Health & Wellness

Architecture

Core Components

Architecture Layers

Key Features

CLI Setup Commands

Managing Your Installation

GPU Acceleration (Optional)

Contributing

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Spring Vision

✨ Features

🚀 Getting Started

Quick Install (Recommended for End Users)

Manual Installation

Using as a Library

1. Add Repository

2. Add Dependency

3. Use in Your Code

🤖 MCP Client Configuration

Using the CLI Tool Output

Manual Configuration

Testing the Setup

⚙️ Configuration

Basic Setup

GPU Support (Optional)

🚀 DJL Backend Features

Current Capabilities

✅ Production Ready

🤖 AI-Powered (Runtime Download)

🛡️ Security & Safety

❤️ Health & Wellness

Architecture

Core Components

Architecture Layers

Key Features

CLI Setup Commands

Managing Your Installation

GPU Acceleration (Optional)

Contributing