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.
Skimmer also integrates with Beholder to fetch frames from videos.
Author: Kevin Barnard (kbarnard@mbari.org)
🔨 Installation
-
Clone the repository:
git clone https://github.com/mbari-org/skimmer.git cd skimmer
-
Install the package:
pip install .
-
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
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 approximatelyAPP_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).
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 areHITorMISS.
Copyright © 2025 Monterey Bay Aquarium Research Institute
Metadata
Release files for skimmer 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| skimmer-0.3.2.tar.gz | 20.0 kB | Without provenance | Details for skimmer-0.3.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| skimmer-0.3.2-py3-none-any.whl | Python 3 | none | any | Details for skimmer-0.3.2-py3-none-any.whl |
Total release size: 33.1 kB
Release files / skimmer-0.3.2.tar.gz
| Download URL | skimmer-0.3.2.tar.gz |
|---|---|
| Size | 20.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
65ce9ca9a097c76e6970981ab63513c32cb760af8a35ac8c70896775e36cbaf8
|
|
BLAKE2b-256 checksum How to use checksums |
ed27943377625a85e006ebc572235d71941446561f571cc758e340735f92459a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.0
|
Release files / skimmer-0.3.2-py3-none-any.whl
| Download URL | skimmer-0.3.2-py3-none-any.whl |
|---|---|
| Size | 13.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f1e90cdecb8f657b4cffd17cdfcd5bcadaec804ff46fece795f6036429b0fdb7
|
|
BLAKE2b-256 checksum How to use checksums |
12721e913003ef7e7a50f93c853aa1db463fea9668f17a629a59d4f096538e9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.0
|
Security for skimmer 0.3.2
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.