Stateless FastAPI service that fetches a landscape double-DVD combo poster, crops one portrait panel, and returns the PNG bytes in the response. Nothing is written to disk.
| Param | Required | Default | Description |
|---|---|---|---|
url |
yes | — | Source image URL (http / https) |
side |
no | auto |
left | right | auto (half holding the largest face, or a face-centred crop if that face sits across the middle; else the right half) |
midline |
no | 0.5 |
Vertical split position as a fraction of width (0–1, exclusive) |
spine_trim |
no | 0.02 |
Fraction of the returned half's width to trim off its inner edge (nearest the midline), to drop the spine/gutter divider. 0 disables it. |
target_ratio |
no | — (off) | Desired output aspect ratio as W:H (e.g. 2:3) or a decimal (e.g. 0.6667). Center-crops the panel to this exact ratio after spine trim. Only ever crops — never pads or upscales. |
- 200 —
Content-Type: image/png(cropped panel) - 400 — bad/missing URL, invalid image / MIME mismatch, invalid
midline/spine_trim/target_ratio - 413 — file or decoded dimensions too large
The response carries X-Poster-Layout: single or double so callers can tell which path ran.
- 502 — could not fetch the source URL
- 500 — unexpected server error (logged with full traceback server-side; response body is a generic JSON error, never a bare error page)
Returns {"status": "ok"}.
docker compose up --build -dService listens on http://localhost:8000.
curl http://localhost:8000/health
curl "http://localhost:8000/poster?url=https%3A%2F%2Fexample.com%2Fcombo-cover.jpg&side=auto" -o poster.pngTo pick up code changes, rebuild and recreate:
docker compose up --build -dIf it still 500s after a rebuild, check the traceback in docker compose logs — the global exception handler logs every unhandled error server-side even though the client just sees a generic JSON body.
Stop with:
docker compose downdocker build -t poster-splitter .
docker run -p 8000:8000 poster-splitter
curl "http://localhost:8000/poster?url=https%3A%2F%2Fexample.com%2Fcombo-cover.jpg&side=auto" -o poster.pngImages are published to GitHub Container Registry on pushes to main/master and on v* tags.
docker pull ghcr.io/<OWNER>/<REPO>:latest
docker run -p 8000:8000 ghcr.io/<OWNER>/<REPO>:latestOr point Compose at the published image:
services:
poster-splitter:
image: ghcr.io/<OWNER>/<REPO>:latest
ports:
- "8000:8000"
restart: unless-stoppedReplace <OWNER> / <REPO> with your GitHub user or org and repository name (lowercase).
Needs system libmagic (e.g. libmagic1 on Debian/Ubuntu).
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000Tests:
pip install -r requirements-dev.txt
pytestMake sure only one OpenCV package is in requirements.txt (opencv-python-headless is the right one for a headless server). Having both opencv-python and opencv-python-headless installed at once corrupts the cv2 module and breaks detection at runtime with errors like AttributeError: module 'cv2' has no attribute 'CascadeClassifier'.
- SSRF: rejects any address that isn't globally routable (private, loopback, link-local, CGNAT, IPv4-mapped IPv6, …), both on the original URL and on every redirect hop — hops are walked and validated manually (not via httpx's built-in
follow_redirects) so a malicious redirect target is never connected to - DNS rebinding: each host is resolved once and the connection goes to that vetted IP (Host header and TLS SNI/certificate check still use the hostname), so a second, different DNS answer is never used. Proxy environment variables are ignored for the same reason
- Dual MIME check:
Content-Typeheader + magic-byte sniff - Streaming download with 10 MB hard cap and a 30 s deadline for the whole fetch
- Pixel cap (~40 megapixels), enforced by OpenCV from the image header before decoding (
OPENCV_IO_MAX_IMAGE_PIXELS), so a tiny compressed "bomb" is never expanded - Image work runs in a thread pool, at most
MAX_CONCURRENT_JOBSat a time, so one large poster doesn't stall other requests or/health - Fetch errors return a generic message; details go to the server log only
- Fetches look like a browser loading an image: a random real-browser
User-Agent(kept across redirects), imageAccept, and a same-siteReferer. A429is retried once with a differentUser-Agentafter the server'sRetry-After(capped at 5 s) - The Docker image runs as a non-root user
- Aspect ratio gate: 0.95–2.2 is treated as a double-poster; any other ratio is handled as a single cover
- Any unexpected exception anywhere in the app is caught by a global handler, logged with a full traceback, and returned as a structured JSON
500— never a bare error page
This is the default when side is omitted.
- Run YuNet face detection (
cv2.FaceDetectorYN, ONNX) once over the whole poster and take the largest face - If that face's box overlaps the cut (the midline plus the
spine_trimstrip on each side of it), the image is most likely one wide photo and splitting would cut the face. Don't split: crop to one cover's ratio (target_ratioif given, else2:3) centred on the face, shifted as needed to stay inside the image.midlineandspine_trimonly decide whether this happens - Otherwise the face is inside one cover: return that half (split, spine trim and ratio crop as below)
- If no face is found, return the right half
Requires the model file at app/models/face_detection_yunet_2023mar.onnx (or wherever FACE_MODEL_PATH points — see below). It is loaded and warmed up at startup. If it's missing or unreadable, or inference fails on one image, auto returns the right half rather than failing the request.
| Var | Default | Description |
|---|---|---|
FACE_MODEL_PATH |
app/models/face_detection_yunet_2023mar.onnx |
Path to the YuNet ONNX face-detection model (MIT, from opencv_zoo) |
MAX_CONCURRENT_JOBS |
CPU count | Posters decoded/split/encoded at once (bounds CPU and memory) |
When the panel is split (every case except an auto face across the middle), it goes through, in order:
- Split at
midlineinto left/right halves - Select a half (
left/right;autotakes the half with the largest face, else the right) - Spine trim — remove
spine_trimfraction off the half's inner edge - Ratio crop (if
target_ratiogiven) — center-crop to the exact requested aspect ratio
If the source image's width/height is outside the double-poster band (0.95–2.2) it is handled as a single cover and not split. side, midline and spine_trim are ignored, and the image is cropped to target_ratio if given, otherwise to the single-cover ratio 2:3. The crop window is centred on the largest detected face, shifted as needed to stay inside the image; with no face (or no face detector) it is a plain center crop. The 0.95 boundary sits near the midpoint between one 2:3 cover (0.67) and two side by side (1.33), so an image is handled as whichever layout it is closer to.