Skimmer

Skimmer is a service that fetches an image from a URL, crops it based on provided bounding box coordinates, caches the result in memory & on the filesystem, and returns the cropped image. It can also sit in front of (potentially high-res) images and serve cached JPEG thumbnails.

Skimmer also integrates with Beholder to fetch frames from videos.

Author: Kevin Barnard (kbarnard@mbari.org)

🔨 Installation

1. Clone the repository:

   git clone https://github.com/mbari-org/skimmer.git
   cd skimmer

2. Install the package:

   pip install .

3. Set up environment variables:

   cp .env.example .env

🚀 Usage

Run scripts for Flask + gunicorn (WSGI) and FastAPI + uvicorn (ASGI) are provided to start the service. Set the appropriate environment variables in .env, then run:

./run_flask.sh

or

./run_fastapi.sh

API

Crop

The main endpoint of the service is /crop, which takes the following query parameters:

• url: The URL of the image or video to crop.
• left: The left coordinate of the bounding box.
• top: The top coordinate of the bounding box.
• right: The right coordinate of the bounding box.
• bottom: The bottom coordinate of the bounding box.
• ms: The timestamp in milliseconds for videos.

The response will be a PNG image representing the cropped region of interest.

• Image:

  curl http://localhost:5000/crop?url=http://example.com/image.jpg&left=0&top=0&right=100&bottom=100
  # image bytes

• Video (@ 1000 ms):

  curl http://localhost:5000/crop?url=http://example.com/video.mp4&left=0&top=0&right=100&bottom=100&ms=1000
  # image bytes

Thumbnail

The /thumbnail endpoint returns a JPEG thumbnail of the full image (or video frame), scaled to fit a preset size with its aspect ratio preserved. It takes the following query parameters:

• url: The URL of the image or video.
• size: The size preset: small, medium, or large (default: medium). Each preset is the longest edge in pixels; see Thumbnail environment variables.
• ms: The timestamp in milliseconds for videos.

Thumbnails are cached on disk separately from ROIs. Sources fetched for a thumbnail are not added to the in-memory image cache, and JPEG sources are decoded at reduced scale (Pillow draft mode), so large images are cheap to thumbnail. Images are never upscaled.

curl "http://localhost:5000/thumbnail?url=http://example.com/image.jpg&size=small"
# JPEG bytes

Health Check

The service also provides a health check endpoint at /health that returns a 200 status code if the service is running and a JSON response with some process info. For example:

curl http://localhost:5000/health
# {"jdkVersion": "Python 3.12.9 (main, Feb  5 2025, 08:49:00) [GCC 11.4.0]", "availableProcessors": 20, "freeMemory": 28491902976, "maxMemory": 33434419200, "totalMemory": 33434419200, "application": "skimmer", "version": "0.1.0", "description": "ROI Service"}

🐳 Docker

Skimmer is available on Docker Hub as mbari/skimmer. To run the service in a Docker container:

docker run \
   -p 5000:5000 \
   --env-file .env \
   -v /path/to/local/cache:/tmp/skimmer_cache \
   mbari/skimmer

Replace /path/to/local/cache with the path to a directory on your host machine where you want to store the cached images persistently.

Compose

An example compose.yaml is provided. To run Skimmer with Docker Compose, first edit the compose file to set the environment variables as desired, then run:

docker compose -f docker/compose.yaml up

⚙️ Environment Variables

App

• APP_HOST: The host address for the Flask application (default: 0.0.0.0).
• APP_PORT: The port for the Flask application (default: 5000).
• APP_WORKERS: The number of worker processes for handling requests (default: 1).

Cache

• IMAGE_CACHE_SIZE_MB: The maximum size of the in-memory cache for full images in megabytes (default: 100). Note that this is per-worker, so the total memory usage will be approximately APP_WORKERS * IMAGE_CACHE_SIZE_MB.
• CACHE_DIR: The directory to store the filesystem cache (default: /tmp/skimmer_cache).
• ROI_CACHE_SIZE_MB: The maximum size of the filesystem cache for ROIs in megabytes (default: 100).

Thumbnail

• THUMBNAIL_SIZE_SMALL, THUMBNAIL_SIZE_MEDIUM, THUMBNAIL_SIZE_LARGE: The longest edge in pixels for each size preset (defaults: 128, 256, 512).
• THUMBNAIL_DEFAULT_SIZE: The preset used when size is omitted (default: medium).
• THUMBNAIL_JPEG_QUALITY: The JPEG quality, 1-95 (default: 85).
• THUMBNAIL_CACHE_SIZE_MB: The maximum size of the filesystem cache for thumbnails in megabytes (default: 500).
• THUMBNAIL_CACHE_DIR: The directory for the thumbnail cache (default: $CACHE_DIR/thumbnails).

Changing a preset size or the quality produces new thumbnails rather than serving stale ones.

Beholder

• BEHOLDER_URL: The URL of the Beholder service to use for fetching images. If unspecified, the service will still work for static images, but it will not be able to fetch frames from video using Beholder.
• BEHOLDER_API_KEY: The API key to use for authenticating with the Beholder service.

Running Tests

Pytest is used for testing. To run the tests, simply run:

pytest

Note that this will use the environment from .env.test for testing.

Custom Headers

The service returns custom headers to indicate the cache status of the image:

• X-Cache: Indicates whether the image was a cache hit or miss. Possible values are HIT or MISS.

---

Copyright © 2025 Monterey Bay Aquarium Research Institute