Skip to content
thumborPublic

About

remotecv is an OpenCV server for facial and feature recognition.

Topics

Resources

Security policy

Stars

99 stars

Watchers

28 watching

Forks

Repository files navigation

Coverage Status

RemoteCV

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

Requirements

  • Python >=3.11,<3.16
  • 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.

Installation

Install RemoteCV from PyPI:

pip install remotecv

For local development:

git clone https://github.com/thumbor/remotecv.git
cd remotecv
make setup
make pre-commit  # only needed once per clone

make setup uses an existing uv installation, or installs the pinned version into .uv-venv when uv is not available, and syncs the locked development environment into .venv. Run commands in it with uv run --locked <command>, or through the Makefile targets below. When make setup installed uv for you, it is not on PATH: call it as .uv-venv/bin/uv in the commands on this page.

Dependencies are locked in uv.lock. After changing them in pyproject.toml, run uv lock and commit the updated lockfile.

Running RemoteCV

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

remotecv

You can also use the Makefile shortcut:

make run

Common examples

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 (credentials come from the environment, see Secrets):

export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

remotecv \
  --backend=celery \
  --celery-commands=worker \
  --celery-commands=--loglevel=INFO

Configuration

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

Purpose CLI option Environment variable Default
Queue backend --backend BACKEND pyres
Redis host --host REDIS_HOST localhost
Redis port --port REDIS_PORT 6379
Redis mode --redis-mode REDIS_MODE single_node
Redis TTL for stored detections --redis-key-expire-time REDIS_KEY_EXPIRE_TIME 1209600
Worker timeout --timeout DETECTOR_TIMEOUT unset
Worker TTL --worker-ttl WORKER_TTL unset
Result store backend --store DETECTOR_STORAGE remotecv.result_store.redis_store
Image loader --loader IMAGE_LOADER remotecv.http_loader
Image fetch timeout (seconds) --loader-timeout IMAGE_LOADER_TIMEOUT 20.0
Image max size (bytes) --loader-max-body-size IMAGE_LOADER_MAX_BODY_SIZE 0 (no limit)
Image fetch User-Agent --loader-user-agent IMAGE_LOADER_USER_AGENT remotecv/<version>
Metrics backend --metrics METRICS_CLIENT remotecv.metrics.logger_metrics
Log level --level LOG_LEVEL debug
Log format --format LOG_FORMAT Python logging default for this project
Healthcheck bind address --server-host HTTP_SERVER_HOST 0.0.0.0
Healthcheck port --server-port HTTP_SERVER_PORT 8080
Enable healthcheck --with-healthcheck WITH_HEALTHCHECK disabled
Sentry DSN --sentry-url SENTRY_URL unset
Clear image metadata --clear-image-metadata CLEAR_IMAGE_METADATA disabled
Max image pixels --max-image-pixels MAX_IMAGE_PIXELS 89478485 (Pillow default, 0 disables)
Memcached hosts --memcached-hosts MEMCACHED_HOSTS localhost:11211

Sentry events are tagged with the release remotecv@<version> unless the SDK detects one on its own, for example from SENTRY_RELEASE, the git revision or a platform variable such as HEROKU_SLUG_COMMIT.

Secrets

Every option that carries a secret also has an environment variable, and that is the form to use for it:

Secret Environment variable CLI option (avoid)
Redis password REDIS_PASSWORD --password
Redis Sentinel password REDIS_SENTINEL_PASSWORD --sentinel-password
Redis Sentinel master password REDIS_MASTER_PASSWORD --master-password
AWS secret access key AWS_SECRET_ACCESS_KEY --key-secret

A value passed on the command line is visible to every user on the host through ps and /proc, and is often captured verbatim by process supervisors and container orchestrators in their own logs. A process's environment is only readable by its owner and root. Under an orchestrator, inject the variables from its secret store rather than writing the values into the manifest, where everyone who can read the manifest sees them. Running --help with the variables set is safe: show_envvar prints the variable name, never its value.

Built-in detectors

ImageProcessor ships with the following detector names:

  • face
  • feature
  • glass
  • profile
  • all

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

Result storage

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.

Development workflow

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

Project layout

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

Security

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

About

remotecv is an OpenCV server for facial and feature recognition.

Topics

Resources

Security policy

Stars

99 stars

Watchers

28 watching

Forks

Releases

Packages

Used by

Contributors

Languages