🖼️ @phantasm0009/image-zen

Local-first image optimizer with AI-powered processing - no cloud dependencies

🚀 Features

🎯 Zero-Cloud AI Tools: Background removal, super-resolution, and smart compression using TensorFlow Lite
⚡ Local Processing: Complete offline processing with pre-trained models
🛠️ CLI + API Support: Use from command line or integrate into your apps
🔗 Extensible Pipeline: Chain multiple operations seamlessly
🏃‍♂️ High Performance: Squoosh compression + TensorFlow Lite acceleration
📦 All-in-One: Pre-trained models downloaded automatically

🎯 Core Capabilities

Feature	Technology	Performance
Background Removal	TensorFlow Lite + RobustVideoMatting	~800ms avg
Super-resolution	TensorFlow Lite + EDSR models	~1.2s avg
Smart Compression	Squoosh + multiple codecs	~300ms avg
Format Conversion	Support for JPG, PNG, WebP, AVIF	~200ms avg

📦 Installation

# Install globally for CLI usage
npm install -g @phantasm0009/image-zen

# Or install locally for API usage
npm install @phantasm0009/image-zen

Note: On first install, TensorFlow Lite models (~17MB total) will be downloaded automatically for offline AI processing.

🚀 Quick Start

CLI Usage

# Remove background from image
image-zen remove-bg photo.jpg -o clean.png

# Upscale image 2x with AI
image-zen upscale small.jpg --scale 2 -o large.png

# Compress with Squoosh optimization
image-zen compress *.jpg --quality 80 --format webp

# Enhanced pipeline processing
image-zen enhance photo.jpg -t remove-bg,upscale,compress -s 2 -q 85

API Usage

import { ImageZen, compress, removeBackground } from '@phantasm0009/image-zen';

// Create instance
const zen = new ImageZen({ verbose: true });

// AI background removal with TensorFlow Lite
const bgRemoved = await zen.removeBackground('photo.jpg');

// AI upscaling with EDSR models
const upscaled = await zen.upscale('small.jpg', 2);

// Squoosh compression
const compressed = await zen.compress('large.jpg', {
  quality: 80,
  format: 'webp'
});

// Enhanced pipeline
await zen.enhance('input.jpg', {
  tasks: ['remove-bg', 'upscale', 'compress'],
  scale: 2,
  compression: { quality: 85, format: 'webp' },
  output: 'output.webp'
});

// Direct function usage
const result = await compress('image.jpg', { quality: 70 });

🛠️ CLI Reference

Commands

`remove-bg <input>`

AI-powered background removal using TensorFlow Lite

image-zen remove-bg photo.jpg -o clean.png -f png

Options:

-o, --output <path> - Output path or directory
-f, --format <format> - Output format (png, webp) [default: png]

`upscale <input>`

AI super-resolution using EDSR TensorFlow Lite models

image-zen upscale small.jpg -s 4 -o large.png

Options:

-s, --scale <number> - Scale factor (2, 4) [default: 2]
-o, --output <path> - Output path or directory
-f, --format <format> - Output format [default: png]

`compress <input>`

Smart compression using Squoosh library

image-zen compress *.jpg -q 80 -f webp -o compressed/

Options:

-q, --quality <number> - Compression quality (1-100) [default: 80]
-f, --format <format> - Output format (webp, avif, mozjpeg, oxipng) [default: webp]
-o, --output <path> - Output path or directory

`enhance <input>`

Apply multiple AI enhancements in pipeline

image-zen enhance photo.jpg -t remove-bg,upscale,compress -s 2 -q 85

Options:

-t, --tasks <tasks> - Comma-separated tasks [default: compress]
-s, --scale <number> - Scale factor for upscaling [default: 2]
-q, --quality <number> - Compression quality [default: 80]
-f, --format <format> - Output format [default: webp]
-o, --output <path> - Output path or directory

`info`

Show package information and model status

📚 API Reference

Class: ImageZen

Constructor

const zen = new ImageZen(options);

Options:

verbose (boolean) - Enable verbose logging

Methods

`removeBackground(input, options)`

AI background removal using TensorFlow Lite

input: string | Buffer - Image path or buffer
options: Object - Processing options
Returns: Promise<Buffer> - Processed image

`upscale(input, scale, options)`

AI upscaling using EDSR models

input: string | Buffer - Image path or buffer
scale: number - Scale factor (2 or 4)
options: Object - Processing options
Returns: Promise<Buffer> - Upscaled image

`compress(input, options)`

Smart compression using Squoosh

input: string | Buffer - Image path or buffer
options: Object - Compression options
- quality: number (1-100) - Compression quality
- format: string - Output format (webp, avif, mozjpeg, oxipng)
- progressive: boolean - Progressive encoding
- optimizeForSize: boolean - Size optimization
- effort: number (0-6) - Compression effort
Returns: Promise<Buffer> - Compressed image

`enhance(input, config)`

Enhanced processing pipeline

input: string | Buffer - Image path or buffer
config: Object - Processing configuration
- tasks: Array - Processing tasks
- output: string - Output file path
- scale: number - Upscaling factor
- compression: Object - Compression options
Returns: Promise<Buffer | string> - Result or output path

🎨 Advanced Examples

AI-Powered Background Removal

const zen = new ImageZen({ verbose: true });

// High-quality background removal
const result = await zen.removeBackground('portrait.jpg', {
  format: 'png' // Preserve transparency
});

await fs.writeFile('portrait_clean.png', result);

Super-Resolution Upscaling

// 4x upscaling with AI enhancement
const upscaled = await zen.upscale('low_res.jpg', 4, {
  algorithm: 'lanczos3', // Fallback if TFLite model unavailable
  sharpen: true,
  enhanceDetails: true
});

Squoosh-Powered Compression

// Multi-format optimization
const formats = ['webp', 'avif', 'mozjpeg'];

for (const format of formats) {
  const compressed = await zen.compress('photo.jpg', {
    format,
    quality: await zen.getOptimalQuality('photo.jpg', format),
    optimizeForSize: true
  });
  
  await fs.writeFile(`photo.${format}`, compressed);
}

Batch Processing with Progress

const files = glob.sync('./photos/*.jpg');

const results = await zen.compressBatch(files, {
  format: 'webp',
  quality: 85
}, (current, total, result) => {
  console.log(`Progress: ${current}/${total} - ${result.file}`);
  if (result.success) {
    console.log(`  Saved ${result.compressionRatio}% space`);
  }
});

🔧 Technology Stack

AI Models (TensorFlow Lite)

Background Removal: RobustVideoMatting (14.2MB)
2x Upscaling: EDSR 2x model (1.5MB)
4x Upscaling: EDSR 4x model (1.5MB)

Compression Engine

Squoosh Library: Google's advanced image compression
Supported Codecs: WebP, AVIF, MozJPEG, OxiPNG
Optimization: Automatic quality selection and size optimization

Performance Features

Tile-based Processing: Handle large images efficiently
Memory Management: Automatic cleanup and optimization
Batch Processing: Parallel processing with progress tracking
Fallback Methods: Graceful degradation when models unavailable

📊 Performance Benchmarks

Operation	TensorFlow Lite	Fallback	Memory Usage
Background Removal	800ms	300ms	~250MB
2x Upscaling	1.2s	400ms	~300MB
4x Upscaling	3.5s	1.1s	~600MB
Squoosh Compression	300ms	-	~150MB

Benchmarks on M1 MacBook Pro with 16GB RAM

🔧 Supported Formats

Input Formats

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)
TIFF (.tiff)
BMP (.bmp)

Output Formats

WebP - Best overall compression
AVIF - Next-gen format, excellent compression
MozJPEG - Optimized JPEG with better compression
OxiPNG - Optimized PNG with lossless compression

⚙️ Requirements

Node.js: 16.0.0 or higher
Memory: 2GB RAM minimum (4GB recommended for 4x upscaling)
Storage: 150MB for package, models, and dependencies
Internet: Required only for initial model download

🚀 Model Management

Models are automatically downloaded on first install:

# Check model status
image-zen info

# Manually trigger model download
npm run postinstall

# Models are stored in: node_modules/@phantasm0009/image-zen/models/

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

MIT License - see the LICENSE file for details.

💖 Support

If you find this package useful, consider:

⭐ Starring the repository
🐛 Reporting bugs
💡 Suggesting features
💝 Sponsoring development

🔗 Links

Made with ❤️ by phantasm0009 | Local-first AI for everyone