RemoteCV is a background worker for OpenCV-based image detection. It is most commonly used by Thumbor to offload face and feature detection, but it can also be integrated into any system that needs asynchronous image analysis with cached results.

The worker supports:

• Redis + PyRes as the default queue backend
• Celery with Amazon SQS
• Built-in OpenCV detectors for face, profile, glasses, feature, and combined detection
• Pluggable image loaders, metrics backends, and result stores
• Optional HTTP healthcheck endpoint

• Python >=3.10,<3.15
• Redis for the default backend and default result store
• OpenCV runtime dependencies supported by opencv-python-headless

If you want to run the Celery backend, install celery in the same environment. The CLI supports it, but Celery is not part of the core runtime dependencies installed by pip install remotecv.

Install RemoteCV from PyPI:

pip install remotecv

For local development:

git clone https://github.com/thumbor/remotecv.git
cd remotecv
python -m venv .venv
. .venv/bin/activate
pip install -U pip
make setup
pre-commit install

The default worker uses the PyRes backend and connects to Redis on localhost:6379:

remotecv

You can also use the Makefile shortcut:

make run

Start the default worker with a healthcheck endpoint:

remotecv --with-healthcheck --server-port=8888

Connect to a different Redis instance:

remotecv --host=redis.internal --port=6379 --database=1

Use Redis Sentinel mode:

remotecv \
  --redis-mode=sentinel \
  --sentinel-instances=sentinel-1:26379,sentinel-2:26379 \
  --master-instance=mymaster

Run with Celery + SQS:

remotecv \
  --backend=celery \
  --region=us-east-1 \
  --key-id="$AWS_ACCESS_KEY_ID" \
  --key-secret="$AWS_SECRET_ACCESS_KEY" \
  --celery-commands=worker \
  --celery-commands=--loglevel=INFO

RemoteCV can be configured either by CLI flags or environment variables. These are the options you are most likely to use:

ImageProcessor ships with the following detector names:

• face
• feature
• glass
• profile
• all

You can combine detectors with + in queued jobs, for example face+profile.

By default, detection results are stored in Redis using the key pattern thumbor-detector-<key>.

RemoteCV also includes a Memcached-backed result store implementation in remotecv.result_store.memcache_store. If you use it, make sure the appropriate Memcached client dependency is installed in your environment.

Run unit tests:

make unit

Run the full local test flow with Redis containers:

make test

Start and stop the test Redis/Sentinel stack manually:

make run-redis
make stop-redis

Run code quality checks:

make black
make flake
make pylint
make lint

remotecv/
  worker.py             CLI entry point and runtime configuration
  image_processor.py    Detector orchestration
  image.py              Image parsing and normalization
  http_loader.py        Remote image loading
  unique_queue.py       PyRes worker implementation
  celery_tasks.py       Celery/SQS integration
  detectors/            OpenCV detectors and cascade files
  metrics/              Metrics backends
  result_store/         Detection result store implementations
tests/
  fixtures/             Sample images and Redis/Sentinel fixtures

Please do not report security issues in public issues. See SECURITY.md for the recommended disclosure process.