visionstyle 0.1.1

Beautiful, fully configurable bounding boxes for object detection.
Boxes, labels, fills, glow, glass, film grain and tracking trails, described by one Style,
tuned live in the Studio, saved as YAML and rendered with one call.

Website · Quickstart · Styles · Studio · Python API · CLI · Changelog

_{YOLO26n detections on a rainy Manhattan crossing, rendered with style="cinematic".}

Quickstart

pip install "visionstyle[yolo]"

import cv2
import visionstyle as vs
from ultralytics import YOLO

frame = cv2.imread("street.jpg")
result = YOLO("yolo26n.pt")(frame)[0]

dets = vs.Detections.from_ultralytics(result)
cv2.imwrite("out.jpg", vs.annotate(frame, dets, style="cinematic"))

No model handy? visionstyle render sample -s neon -o out.jpg renders a bundled photo with its shipped detections.

visionstyle only draws, so any detector works: pass boxes as lists, NumPy arrays or torch tensors (see Python API).

Install options

Python 3.10 – 3.13.

Why visionstyle

• One object describes the look. A Style covers boxes, strokes, fills, line patterns, labels, effects and trails. Every option is a typed, validated attribute, and the whole thing round-trips to YAML.
• Twenty-two presets to start from. Use one by name, or copy its YAML and make it yours.
• Looks the same at any resolution. Sizes are in reference pixels and scale with the frame, and each object's outline and label scale with its size, so distant objects stay light.
• Built for video. Keep one Annotator per stream and you get tracking trails, marching dashes, hue cycling and pulses that carry across frames.
• A Studio to design in. Tune a style visually on your own image or video. The Python package renders every preview, so what you see is exactly what annotate() produces.

What it can draw

Nine looks, each built to show off a different part of Style: box shapes, line patterns, fills, label treatments, effects and trails. Every tile is rendered by the package itself, and the style behind each one is in docs/showcase.py if you want to borrow it.

Presets

Twenty-two ready-made presets to start from. Each one is a plain YAML file you can copy and edit (see all of them on the same scene).

Twelve general-purpose looks:

Ten built for a job, a field or an audience:

target draws every detection it's given, so pass only the one you're following (for example dets.subset(dets.track_id == 3)), or hide the others in the Studio's Objects tab.

visionstyle presets list
visionstyle presets show cinematic
visionstyle presets export cinematic -o my-look.yaml

Studio

Design a style visually on your own image, video and model, then save it as a preset the package loads by name.

pip install "visionstyle[studio,yolo]"
visionstyle studio          # opens http://127.0.0.1:8420

1. Source. Pick a bundled scene or upload an image or video, set the confidence threshold and run detection. Videos are tracked once, up to a minute long, and the detections are saved with the video, so restyling, scrubbing and moving the confidence slider replay them without running the model again. Longer uploads can be trimmed to their first minute. The sample video ships with its tracks; tracking a new video needs the yolo extra.
2. Design. Start from a preset, then adjust box, stroke, fill, line, label, effects, tracking and global settings, or search for any setting by name. Save next to the Style menu stores the look as a named preset.
3. Objects. Filter by class, hide objects or isolate a single track. Scrub or play the timeline, and save the annotated frame from the preview menu.
4. Export. Copy or download the YAML, a self-contained Python snippet, or a prompt for AI coding tools.

Saved presets go to ~/.visionstyle/presets and load by name anywhere on that machine with vs.Style.preset("my-look"). To keep them in a project instead, run visionstyle studio --presets-dir ./styles, commit styles/<name>.yaml, and load it with vs.Style.load("styles/my-look.yaml") (or set VISIONSTYLE_PRESETS_DIR=./styles to load by name).

Python API

import cv2
import visionstyle as vs

frame = cv2.imread("street.jpg")

# 1. Detections: boxes in pixels, everything else optional
dets = vs.Detections(
    xyxy=[[590, 650, 720, 1040], [1060, 660, 1520, 1000]],
    class_name=["person", "car"],
    confidence=[0.93, 0.88],
    track_id=[14, 31],
)
# or: dets = vs.Detections.from_ultralytics(model.predict(frame)[0])

# 2. A style: preset name, YAML path, or built in code
style = vs.Style.preset("cinematic")
style.label.components = ["track_id", "text"]   # every option is a typed attribute
style.trail.enabled = True

# 3. Render. Keep one Annotator per video stream so trails and animations carry across frames.
annotator = vs.Annotator(style)
out = annotator.annotate(frame, dets)

# One-liner for stills
out = vs.annotate(frame, dets, style="minimal")

xyxy is pixel x1, y1, x2, y2; Detections.from_xywh, from_xywh_topleft and from_dicts cover other formats. Frames are BGR uint8 like OpenCV; pass rgb=True for RGB arrays.

What you can configure

Save and share styles

style.save("my_style.yaml")                 # anywhere
style.save_preset("my-look")                # ~/.visionstyle/presets/my-look.yaml
vs.Style.preset("my-look")                  # found by name from now on
vs.presets.list()                           # built-in + yours

Presets are looked up in $VISIONSTYLE_PRESETS_DIR, then ~/.visionstyle/presets, then the built-ins, then as a file path.

CLI

visionstyle render photo.jpg -s neon --model yolo26n.pt -o out.jpg
visionstyle render clip.mp4  -s tracking --model yolo26n.pt --track -o out.mp4
visionstyle render 0         -s hud --model yolo26n.pt --track -o webcam.mp4   # webcam index
visionstyle render photo.jpg -d detections.json -s corners                    # no model needed
visionstyle gallery photo.jpg --model yolo26n.pt -o gallery.png               # every preset at once
visionstyle presets list | show NAME | export NAME -o my.yaml
visionstyle schema -o style.schema.json

detections.json is a list of {"xyxy": [...], "class_name": "...", "confidence": 0.9, "track_id": 1}.

Development

uv sync --all-extras --group dev
uv run pytest && uv run ruff check . && uv run mypy src

cd studio && npm install
npm run dev            # Vite dev server on :5173, proxying /api to :8420
npm run build          # -> src/visionstyle/studio/static (bundled into the wheel)

When src/visionstyle/style/schema.py changes, regenerate the frontend schema and types:

uv run visionstyle schema -o studio/schema.json && (cd studio && npm run gen:types)

Credits

Sample photos: see CREDITS.md. Fonts: Inter and JetBrains Mono, both under the SIL Open Font License.

Author

Built by Basel Mather. See more of my work at baselhusam.com.

Released under the MIT License.