Implementing OpenCV

In this guide you’ll create a minimal Flask app that accepts image uploads, processes the uploaded image with OpenCV (for example, compressing JPEG quality), and returns JSON with the path to the processed file. The tutorial covers endpoint validation, saving uploads securely, controlling JPEG compression via a quality form parameter, and troubleshooting common errors when testing with Postman or curl.

What this tutorial covers

Create an upload route that accepts multipart/form-data POSTs with an image file.
Store the original upload in a configured upload folder.
Use OpenCV to compress the image by changing JPEG quality (configurable via a quality form parameter).
Return JSON that points to the processed image path.

Quick install

pip install opencv-python flask

Why this approach (summary)

Simple, production-proximate pattern: use an application factory to create the Flask app, configure an upload folder, and import route registrations inside the app context.
Keep route logic concise and validate inputs early: verify file presence, filename, and the numeric quality range (0–100).
Use OpenCV for image decoding/encoding and to control JPEG compression via cv2.IMWRITE_JPEG_QUALITY.

Files referenced in examples

File	Purpose
`routes.py`	Defines the app routes: the home page and `/upload` POST handler
`app/__init__.py`	Application factory: creates the Flask app and configures `UPLOAD_FOLDER`
`templates/base.html`	Simple HTML form used to test the upload endpoint

Minimal routes (routes.py)

This file assumes it’s imported after the Flask app has been created (for example, via an application factory that imports routes inside an app context). The examples use current_app as a reference to the Flask application; make sure routes is imported while the application context is active. In many projects, using a Blueprint or importing the app instance directly is preferred.

# routes.py
from flask import request, jsonify, render_template
from flask import current_app as app
import os
import cv2

@app.route('/')
def home():
    return render_template('base.html')

Upload endpoint: functionality and validation

The /upload handler below:
- Validates that the request contains an image file part.
- Verifies a filename is present.
- Ensures the configured upload folder exists and saves the original file.
- Reads the image using OpenCV, validates successful decode, and writes a compressed JPEG with the requested quality (default is 10).
- Returns a JSON response with the processed image path.

@app.route('/upload', methods=['POST'])
def upload():
    # Validate that the request contains the 'image' file part
    if 'image' not in request.files:
        return jsonify({'error': 'No image part in the request'}), 400

    image = request.files['image']

    # Validate filename
    if image.filename == '':
        return jsonify({'error': 'No image selected for uploading'}), 400

    # Ensure upload folder exists
    upload_folder = app.config.get('UPLOAD_FOLDER', './uploads')
    os.makedirs(upload_folder, exist_ok=True)

    # Save the uploaded image
    image_path = os.path.join(upload_folder, image.filename)
    image.save(image_path)

    # Get the quality parameter (defaults to 10 if not provided)
    quality = request.form.get('quality', default=10, type=int)

    # Validate the quality parameter
    if quality is None or quality < 0 or quality > 100:
        return jsonify({'error': 'Quality must be an integer between 0 and 100'}), 400

    # Read image with OpenCV
    img = cv2.imread(image_path)
    if img is None:
        return jsonify({'error': 'Failed to read uploaded image with OpenCV'}), 500

    # Compose processed path and write compressed JPEG with the desired quality
    processed_image_path = os.path.join(upload_folder, 'processed_' + image.filename)
    cv2.imwrite(processed_image_path, img, [int(cv2.IMWRITE_JPEG_QUALITY), quality])

    return jsonify({
        'message': 'Image successfully uploaded and processed',
        'processed_image_path': processed_image_path
    }), 200

Application factory example (app/init.py)

When using an application factory set the UPLOAD_FOLDER on the app config. Import routes inside the app context so current_app is available within routes.py. Avoid calling app.run() inside modules that register routes.

# app/__init__.py
from flask import Flask

def create_app():
    app = Flask(__name__)
    # Load additional configuration if needed
    # app.config.from_object('config.Config')

    # Set upload folder
    app.config['UPLOAD_FOLDER'] = './uploads'

    # Register routes (import inside the app context)
    with app.app_context():
        from . import routes  # noqa: F401 - routes registers endpoints on `app`

    return app

Simple HTML form (templates/base.html)

Be sure the form uses enctype="multipart/form-data" and posts to /upload.

<!-- base.html -->
<form action="/upload" method="post" enctype="multipart/form-data">
  <input type="file" name="image" />
  <input type="text" name="quality" placeholder="quality (0-100)" />
  <input type="submit" value="Upload" />
</form>

Testing with curl

Example curl command to test the /upload endpoint locally:

curl -X POST \
  -F "image=@/path/to/your/image.jpg" \
  -F "quality=50" \
  http://localhost:5000/upload

Expected successful JSON response

{
  "message": "Image successfully uploaded and processed",
  "processed_image_path": "./uploads/processed_image.jpg"
}

Troubleshooting common errors

Error	Possible cause	How to fix
405 Method Not Allowed	Request used GET or other method while route only accepts POST	Confirm the request method and ensure `methods=['POST']` is set on the route
403 Forbidden	Server/proxy rules, misconfigured headers, or host restrictions	Check server logs, proxy (nginx/Apache) rules, and firewall settings
404 Not Found	Wrong URL, app did not start, or routes not registered	Verify the URL, ensure the Flask app is running and that `routes` was imported (app factory scenarios)
No response / empty response	Flask not bound to expected host/port or server crashed	Ensure Flask runs on `127.0.0.1:5000` or the intended host, check server logs for errors
OpenCV errors (e.g., `no module named cv2`)	Missing package	Install with `pip install opencv-python`
`cv2.imread()` returns `None`	Invalid image path or unreadable file	Confirm the file was saved correctly and is a supported image format

This Flask development server is not intended for production. Use a production WSGI server (for example, gunicorn or uWSGI) behind a proper web server or load balancer for production deployments.

Additional tips and best practices

Ensure your upload folder exists and is writable by the Flask process, or create it programmatically with os.makedirs(upload_folder, exist_ok=True).
Always validate and sanitize filenames in production. Use werkzeug.utils.secure_filename to avoid path traversal issues and remove unsafe characters.
If you prefer to return the processed image bytes directly instead of a filesystem path, use Flask’s send_file() with the processed path or read the bytes and return them with the appropriate Content-Type.
To view detailed error pages during development, enable debug mode only for local development (for recent Flask versions set FLASK_DEBUG=1 or configure debug in your app’s config).
Consider storing images in a dedicated storage service (S3, GCS) for scalability rather than saving them locally on the web server for production deployments.
If you need to handle large uploads or throttling, add size limits like app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024 to prevent excessive memory or disk usage.

References

This workflow gives you an upload endpoint wired to OpenCV processing and a flexible way to vary JPEG quality via form fields or multipart POST parameters.

Course Introduction

Introduction to AI-Assisted Development

Planning Phase

Development Phase - Backend

Development Phase - Frontend

Project Completion

Implementing OpenCV

Watch Video