Skip to main content

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
python -m venv .venv
. .venv/bin/activate
pip install -U pip
make setup
pre-commit install

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.

Metadata

Release files for remotecv 5.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for remotecv 5.3.0
File Size Uploaded Provenance Actions
remotecv-5.3.0.tar.gz 961.7 kB Without provenance Details for remotecv-5.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for remotecv 5.3.0
File Interpreter ABI Platform Actions
remotecv-5.3.0-py3-none-any.whl Python 3 none any Details for remotecv-5.3.0-py3-none-any.whl

Total release size: 1.9 MB

Release files / remotecv-5.3.0.tar.gz

Download URL remotecv-5.3.0.tar.gz
Size 961.7 kB
Tags Source
SHA-256 checksum
How to use checksums
2d74a4a78dd90d9150dc258a42296b395ebecfdd65edf4ff4f6880ead36de764
BLAKE2b-256 checksum
How to use checksums
e6a452eb415559ccaec059a9879a60e7cef1a4109ce8feac61c280682fad584c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Release files / remotecv-5.3.0-py3-none-any.whl

Download URL remotecv-5.3.0-py3-none-any.whl
Size 970.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
37066d19443a4e707b16962006d496217dfc399e510f3ed313b856c35d3f0857
BLAKE2b-256 checksum
How to use checksums
1426cdd2e1d9c0da88fb523eed396f82300cd6cf1570d4c82ed6e9abea37410f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Security for remotecv 5.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

5.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page