Neural Enhance Deployment & Usage Guide

Super Resolution for images using deep learning with Theano.

1. Prerequisites

System Requirements

• Python: 3.5 or higher
• OS: Linux (Ubuntu 16.04+ recommended), macOS, or Windows with WSL
• Memory: 4GB+ RAM (8GB+ recommended for large images)
• GPU: Optional but strongly recommended (NVIDIA with CUDA support)

Required Software

• Python 3 development headers
• BLAS/OpenBLAS libraries (for numerical computation)
• libjpeg and libpng (image I/O)
• CUDA Toolkit 8.0+ and cuDNN 5.1+ (for GPU acceleration)

Accounts & API Keys

• None required for local deployment
• (Optional) AWS/GCP account if deploying to cloud GPU instances

2. Installation

Clone Repository

git clone https://github.com/alexjc/neural-enhance.git
cd neural-enhance

Install Python Dependencies

pip install -r requirements.txt

Typical requirements include:

• Theano >= 0.8.0
• Lasagne >= 0.1
• Pillow (PIL)
• NumPy
• SciPy

Download Pre-trained Models

Models are typically downloaded automatically on first run, or manually place them in the project root:

# Example for photo model (check releases for actual URLs)
wget https://github.com/alexjc/neural-enhance/releases/download/v0.3/ne-enhance-photo-0.3.pkl.bz2

3. Configuration

Environment Variables

Theano Configuration (required for GPU support):

# For GPU processing
export THEANO_FLAGS="device=gpu,floatX=float32,lib.cnmem=0.8"

# For CPU processing
export THEANO_FLAGS="device=cpu,floatX=float32"

Model Path (optional):

export NEURAL_ENHANCE_MODEL_PATH="/path/to/models"

Model Files

Ensure model files (.pkl.bz2 format) are accessible in:

• Current working directory, or
• Path specified by --model argument

Available model types via --type:

• photo (default): Optimized for photographs
• art: Optimized for artwork/illustrations

4. Build & Run

Basic Usage (CPU)

python3 enhance.py --zoom 2 input.jpg

GPU Acceleration

THEANO_FLAGS="device=gpu,floatX=float32" python3 enhance.py --zoom 2 input.jpg

Batch Processing

python3 enhance.py --zoom 2 *.jpg

Advanced Options

python3 enhance.py \
  --zoom 4 \
  --type photo \
  --rendering-tile 128 \
  --rendering-overlap 32 \
  --rendering-histogram \
  input.jpg

Parameter Reference:

• --zoom: Upscaling factor (2, 4, etc.)
• --rendering-tile: Tile size in pixels (default: 80). Increase for better quality, decrease for lower memory usage
• --rendering-overlap: Overlap between tiles (default: 24). Prevents seam artifacts
• --rendering-histogram: Match output color histogram to input (reduces color drift)
• --type: Model type (photo or art)
• --model: Path to specific model file (.pkl.bz2)

Output

Enhanced images are saved with suffix _enhanced.png in the current directory.

5. Deployment

Docker Deployment (Recommended)

Create a Dockerfile:

FROM nvidia/cuda:8.0-runtime-ubuntu16.04

RUN apt-get update && apt-get install -y \
    python3 python3-pip \
    libopenblas-dev libjpeg-dev libpng-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip3 install -r requirements.txt

COPY . .
CMD ["python3", "enhance.py"]

Build and run:

docker build -t neural-enhance .
docker run --runtime=nvidia -v $(pwd)/images:/images neural-enhance --zoom 2 /images/photo.jpg

Cloud Deployment (GPU Instances)

AWS EC2:

1. Launch p2.xlarge or p3.2xlarge instance with Deep Learning AMI
2. Install dependencies and clone repo
3. Process images via S3 input/output buckets

Google Cloud Platform:

1. Create VM with GPU (NVIDIA Tesla K80 or higher)
2. Install CUDA drivers and toolkit
3. Deploy using startup script:

#!/bin/bash
apt-get update
apt-get install -y python3-pip git
git clone https://github.com/alexjc/neural-enhance.git
cd neural-enhance && pip3 install -r requirements.txt

Production API Server

Wrap the CLI in a web service using Flask:

from flask import Flask, request, send_file
import subprocess
import tempfile
import os

app = Flask(__name__)

@app.route('/enhance', methods=['POST'])
def enhance():
    file = request.files['image']
    zoom = request.form.get('zoom', 2)
    
    with tempfile.TemporaryDirectory() as tmpdir:
        input_path = os.path.join(tmpdir, 'input.jpg')
        file.save(input_path)
        
        subprocess.run([
            'python3', 'enhance.py',
            '--zoom', str(zoom),
            input_path
        ], cwd='/app')
        
        output_path = os.path.join(tmpdir, 'input_enhanced.png')
        return send_file(output_path)

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

6. Troubleshooting

Theano GPU Errors

Problem: ERROR: Theano cannot compile CUDA code

• Solution: Ensure CUDA is in PATH:

export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

Memory Errors (CNMEM)

Problem: CNMEM_STATUS_OUT_OF_MEMORY

• Solution: Reduce CNMEM allocation or tile size:

export THEANO_FLAGS="device=gpu,floatX=float32,lib.cnmem=0.5"
# Or reduce tile size:
python3 enhance.py --rendering-tile 64 input.jpg

Model Loading Errors

Problem: FileNotFoundError: [Errno 2] No such file or directory: '*.pkl.bz2'

• Solution: Download models manually or check internet connection for auto-download
• Verify model file permissions: chmod 644 *.pkl.bz2

Tile Artifacts

Problem: Visible seams in output image

• Solution: Increase overlap:

python3 enhance.py --rendering-overlap 48 input.jpg

Slow Performance on CPU

Problem: Processing takes >5 minutes per image

• Solution:
  • Reduce tile size: --rendering-tile 40
  • Ensure OpenBLAS is installed: sudo apt-get install libopenblas-dev
  • Set OpenBLAS threads: export OPENBLAS_NUM_THREADS=4

Color Distortion

Problem: Output colors differ significantly from input

• Solution: Enable histogram matching:

python3 enhance.py --rendering-histogram input.jpg