### Install and launch VisionStyle Studio Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Install the package with the studio and yolo extras, then start the studio server which opens at http://127.0.0.1:8420. ```bash pip install "visionstyle[studio,yolo]" visionstyle studio # opens http://127.0.0.1:8420 ``` -------------------------------- ### VisionStyle CLI Commands Source: https://github.com/baselhusam/visionstyle/blob/main/examples/README.md Command-line examples for rendering images and videos, generating a gallery, and launching the studio. Use `visionstyle render` with a preset and optional model/tracking flags, `visionstyle gallery` for a photo gallery, and `visionstyle studio` to start the interactive studio. ```bash visionstyle render sample -s cinematic -o out.jpg visionstyle render clip.mp4 -s tracking --model yolo26n.pt --track -o out.mp4 visionstyle gallery my_photo.jpg --model yolo26n.pt -o gallery.png visionstyle studio ``` -------------------------------- ### Run studio with a custom presets directory Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Start the studio with a project-specific presets directory so saved presets are stored in the project. ```bash visionstyle studio --presets-dir ./styles ``` -------------------------------- ### Development setup and testing commands Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Commands to sync dependencies, run tests, lint, and type-check the Python project, plus npm commands for the Studio frontend. The Vite dev server runs on :5173 and proxies /api to :8420; the build outputs to src/visionstyle/studio/static. ```bash 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) ``` -------------------------------- ### Install visionstyle from GitHub Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Install the unreleased development version from the main branch. ```shell pip install git+https://github.com/baselhusam/visionstyle.git ``` -------------------------------- ### Install visionstyle with YOLO extras Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Installs the visionstyle package with the YOLO extra, which adds Ultralytics YOLO support for from_ultralytics, the CLI --model flag, and video tracking. ```bash pip install "visionstyle[yolo]" ``` -------------------------------- ### VisionStyle CLI usage examples Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Shows common visionstyle commands for rendering images, videos, webcam, and galleries, plus preset and schema management. The detections.json file is a list of objects with xyxy, class_name, confidence, and track_id fields. ```bash 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 ``` -------------------------------- ### Install visionstyle with extras Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Install with the yolo extra for Ultralytics support, the studio extra for the Studio, or all extras. ```shell pip install "visionstyle[yolo]" # + ultralytics for demos / CLI models pip install "visionstyle[studio]" # + fastapi / uvicorn for the Studio pip install "visionstyle[all]" ``` -------------------------------- ### Install visionstyle with pip Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Install the visionstyle package from PyPI. Requires Python 3.10+. ```bash pip install visionstyle ``` -------------------------------- ### Import and annotate with visionstyle Source: https://github.com/baselhusam/visionstyle/blob/main/docs/design-system.html Core usage example showing how to import the visionstyle library and annotate a frame with detections using the 'cinematic' style. Requires Python 3.10+ and OpenCV. ```python import visionstyle as vs out = vs.annotate(frame, dets, style="cinematic") ``` -------------------------------- ### Install visionstyle with studio and yolo extras Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Install the package with the studio and yolo extras to use the Studio and YOLO models. The Studio runs at http://127.0.0.1:8420. ```shell pip install "visionstyle[studio,yolo]" visionstyle studio # → http://127.0.0.1:8420 ``` -------------------------------- ### YAML: Cinematic preset excerpt Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Example preset file showing the YAML structure for a cinematic style, including palette, box, stroke, fill, label, effects, and trail settings. This is the preset loaded by vs.Style.preset("cinematic") in the Python example. ```yaml # src/visionstyle/presets/cinematic.yaml (excerpt) name: cinematic palette: {colors: cinematic, by: class} box: {shape: rounded, corner_radius: 10} stroke: {thickness: 2} fill: {enabled: true, opacity: 0.1, mode: gradient} label: components: [text, confidence] background: pill font_weight: 600 effects: glow: {enabled: true, radius: 10, intensity: 0.55} vignette: {enabled: true, strength: 0.5, radius: 0.9} grain: {enabled: true, amount: 0.04} trail: {enabled: true, length: 36, line: ribbon, glow: true} ``` -------------------------------- ### Build local preview site and serve Source: https://github.com/baselhusam/visionstyle/blob/main/site/README.md Creates a _site directory, extracts and runs the build steps from the GitHub Actions workflow, then serves the site locally on port 8787. _site/ is git-ignored. ```bash mkdir -p _site && awk '/run: \|/{f=1;next} /- uses: actions\/configure-pages/{f=0} f' .github/workflows/pages.yml | sed 's/^ //' | bash && python3 -m http.server 8787 --directory _site ``` -------------------------------- ### Load a preset from a file Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Load a preset from a YAML file in the project directory. ```python vs.Style.load("styles/my-look.yaml") ``` -------------------------------- ### Basic usage: detections, style, and annotate Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Shows the core workflow: create Detections, choose a Style preset, and render with an Annotator. Detections accept pixel boxes in xyxy format; frames are BGR uint8 like OpenCV, pass rgb=True for RGB arrays. Keep one Annotator per video stream so trails and animations carry across frames. ```python 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") ``` -------------------------------- ### Save and share styles Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Shows how to save a style to a file or as a preset, then load it by name. Presets are looked up in $VISIONSTYLE_PRESETS_DIR, then ~/.visionstyle/presets, then built-ins, then as a file path. ```python 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.list Source: https://github.com/baselhusam/visionstyle/blob/main/README.md List all available presets, including built-in and user-defined ones. ```APIDOC ## presets.list ### Description List all available presets, including built-in and user-defined ones. ### Function Signature `vs.presets.list()` ### Returns - **list** - List of preset names. ### Example ```python vs.presets.list() ``` ``` -------------------------------- ### List available presets with visionstyle presets list Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Lists all available presets from the command line. ```bash visionstyle presets list ``` -------------------------------- ### List, show, and export presets with visionstyle CLI Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Use the visionstyle CLI to list all available presets, preview a preset's style, or export a preset to a YAML file for customization. The export command writes the preset to the specified output file. ```bash visionstyle presets list visionstyle presets show cinematic visionstyle presets export cinematic -o my-look.yaml ``` -------------------------------- ### Regenerate frontend schema and types Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Run this when src/visionstyle/style/schema.py changes to regenerate the frontend schema and TypeScript types. ```bash uv run visionstyle schema -o studio/schema.json && (cd studio && npm run gen:types) ``` -------------------------------- ### Load a saved preset by name Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Load a preset saved in the default directory (~/.visionstyle/presets) by its name. ```python vs.Style.preset("my-look") ``` -------------------------------- ### Python: Configure and annotate with VisionStyle Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Shows the core Python API: create detections, load a preset, customize style, annotate a frame, and save a preset. All sizes are defined at ~1080p and scale with the frame when style.scale is set to "auto". ```python # 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: vs.Detections.from_ultralytics(model.predict(frame)[0]) style = vs.Style.preset("cinematic") style.label.components = ["track_id", "text"] style.trail.enabled = True annotator = vs.Annotator(style) # one per stream out = annotator.annotate(frame, dets) style.save_preset("my-look") # ~/.visionstyle/presets/my-look.yaml ``` -------------------------------- ### Render images, videos, webcam, and gallery Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Render stills, videos, or a webcam index with the specified style and model. The gallery command renders every preset at once. ```shell 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 visionstyle gallery photo.jpg --model yolo26n.pt -o gallery.png ``` -------------------------------- ### Render preset images and thumbnails Source: https://github.com/baselhusam/visionstyle/blob/main/site/README.md Run from the project root to render every built-in preset (or only the names you pass) on street.jpg with its shipped detections and synthetic trails, like the Studio preview. Writes 1400 px renders and 288 × 180 thumbnails. A new preset also needs its tab and frame added to the explorer in index.html and the counter's total updated. ```bash uv run python docs/presets.py ``` -------------------------------- ### Show a preset's YAML with visionstyle presets show Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Displays the YAML content of the 'cinematic' preset. ```bash visionstyle presets show cinematic ``` -------------------------------- ### Set presets directory via environment variable Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Set the presets directory environment variable to load presets by name from a custom location. ```bash VISIONSTYLE_PRESETS_DIR=./styles ``` -------------------------------- ### Style Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Create a Style object to configure the visual appearance of annotations. Styles can be loaded from presets, YAML files, or built in code, and can be saved and shared. ```APIDOC ## Style ### Description Create a Style object to configure the visual appearance of annotations. Styles can be loaded from presets, YAML files, or built in code, and can be saved and shared. ### Class Methods - `Style.preset(name)` - Load a style from a preset name (built-in or user-defined). - `Style.preset("my-look")` - Load a user-defined preset by name. ### Instance Methods - `style.save(path)` - Save the style to a YAML file at the given path. - `style.save_preset(name)` - Save the style as a preset in `~/.visionstyle/presets/`. ### Attributes - `style.label.components` (list) - Ordered label components (e.g., `["track_id", "text"]`). - `style.trail.enabled` (bool) - Enable or disable tracking trails. - `style.scale` (str) - Scaling mode, e.g., `"auto"`. - `style.object_scale` (dict) - Object-based scaling settings. ### Example ```python style = vs.Style.preset("cinematic") style.label.components = ["track_id", "text"] style.trail.enabled = True ``` ``` -------------------------------- ### Annotator Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Create an Annotator object to render annotations on frames. Use one Annotator per video stream to maintain trails and animations across frames. ```APIDOC ## Annotator ### Description Create an Annotator object to render annotations on frames. Use one Annotator per video stream to maintain trails and animations across frames. ### Constructor `vs.Annotator(style)` ### Parameters - **style** (Style) - Required - The style to use for rendering. ### Methods - `annotator.annotate(frame, dets)` - Render detections on a frame and return the annotated frame. ### Example ```python annotator = vs.Annotator(style) out = annotator.annotate(frame, dets) ``` ``` -------------------------------- ### Style your first frame with Python API Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Use the Python API to annotate an image with detections from a YOLO model. Requires the [yolo] extra. If no model is handy, use the sample command. ```python 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")) ``` -------------------------------- ### Detections Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Create a Detections object to hold bounding boxes and optional metadata for objects in a frame. Supports multiple coordinate formats and can be created from Ultralytics predictions. ```APIDOC ## Detections ### Description Create a Detections object to hold bounding boxes and optional metadata for objects in a frame. Supports multiple coordinate formats and can be created from Ultralytics predictions. ### Constructor `vs.Detections(xyxy, class_name=None, confidence=None, track_id=None)` ### Parameters - **xyxy** (list of list of int) - Required - Bounding boxes in pixel coordinates `[x1, y1, x2, y2]`. - **class_name** (list of str) - Optional - Class names for each detection. - **confidence** (list of float) - Optional - Confidence scores for each detection. - **track_id** (list of int) - Optional - Track IDs for each detection. ### Alternative Constructors - `Detections.from_xywh(...)` - Create from `[x, y, width, height]` format. - `Detections.from_xywh_topleft(...)` - Create from `[x, y, width, height]` with top-left origin. - `Detections.from_dicts(...)` - Create from a list of dictionaries. - `Detections.from_ultralytics(prediction)` - Create from an Ultralytics prediction result. ### Example ```python 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], ) ``` ``` -------------------------------- ### annotate (one-liner) Source: https://github.com/baselhusam/visionstyle/blob/main/README.md Render annotations on a single frame with a one-liner function. Useful for still images. ```APIDOC ## annotate (one-liner) ### Description Render annotations on a single frame with a one-liner function. Useful for still images. ### Function Signature `vs.annotate(frame, dets, style="minimal")` ### Parameters - **frame** (numpy.ndarray) - Required - BGR image array. - **dets** (Detections) - Required - Detections object. - **style** (str or Style) - Optional - Style preset name or Style object. Defaults to `"minimal"`. ### Returns - **out** (numpy.ndarray) - Annotated frame. ### Example ```python out = vs.annotate(frame, dets, style="minimal") ``` ``` -------------------------------- ### Annotate frame with cinematic preset Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Call vs.annotate with the 'cinematic' preset to style detections. Shown in the hero comparison. ```python vs.annotate(frame, dets, style="cinematic") ``` -------------------------------- ### Load a preset style with vs.Style.preset Source: https://github.com/baselhusam/visionstyle/blob/main/site/index.html Loads the 'cinematic' preset by name into a Style object. The preset is a plain YAML file that can be copied, edited, and loaded by name. ```python style = vs.Style.preset("cinematic") ``` -------------------------------- ### Re-encode promo film with ffmpeg Source: https://github.com/baselhusam/visionstyle/blob/main/site/README.md Use this ffmpeg command to re-encode a new promo cut for the site's 30-second film. It produces an H.264 MP4 with AAC audio and fast-start flags, suitable for web delivery. ```bash ffmpeg -i cut.mp4 -c:v libx264 -crf 29 -preset slow -pix_fmt yuv420p -c:a aac -b:a 112k -movflags +faststart site/media/visionstyle-ad.mp4 ``` -------------------------------- ### Interactive lab controls for theme, style, stroke, and detection selection Source: https://github.com/baselhusam/visionstyle/blob/main/docs/design-system.html JavaScript for the interactive lab component. Handles theme toggling (light/dark), style switching (solid/corners), stroke width adjustment, and detection selection with ARIA attributes. Updates the DOM and CSS custom properties accordingly. ```javascript (() => { const lab = document.querySelector('[data-lab]'); if (!lab) return; const selectionCopy = lab.querySelector('[data-selection-copy]'); const selectedName = lab.querySelector('[data-selected-name]'); const themeOutput = lab.querySelector('[data-theme-output]'); const styleOutput = lab.querySelector('[data-style-output]'); const strokeOutput = lab.querySelector('[data-stroke-output]'); const setTheme = (theme) => { lab.dataset.theme = theme; lab.classList.toggle('is-light', theme === 'light'); lab.querySelectorAll('[data-lab-theme]').forEach((button) => button.classList.toggle('active', button.dataset.labTheme === theme)); themeOutput.textContent = theme === 'light' ? 'Paper' : 'Night'; }; lab.querySelectorAll('[data-lab-theme]').forEach((button) => button.addEventListener('click', () => setTheme(button.dataset.labTheme))); lab.querySelectorAll('[data-lab-style]').forEach((button) => button.addEventListener('click', () => { const style = button.dataset.labStyle; lab.classList.toggle('is-solid', style === 'solid'); lab.querySelectorAll('[data-lab-style]').forEach((item) => item.classList.toggle('active', item === button)); styleOutput.textContent = style === 'solid' ? 'Solid' : 'Corners'; })); const stroke = lab.querySelector('[data-stroke]'); stroke.addEventListener('input', () => { lab.style.setProperty('--stroke', `${stroke.value}px`); strokeOutput.textContent = `${stroke.value} px`; }); lab.querySelectorAll('[data-switch]').forEach((button) => button.addEventListener('click', () => { const enabled = button.getAttribute('aria-pressed') !== 'true'; button.setAttribute('aria-pressed', String(enabled)); lab.classList.toggle(button.dataset.switch === 'glow' ? 'glow' : 'no-trail', button.dataset.switch === 'glow' ? enabled : !enabled); })); lab.querySelectorAll('[data-detection]').forEach((detection) => detection.addEventListener('click', () => { lab.querySelectorAll('[data-detection]').forEach((item) => { const active = item === detection; item.classList.toggle('is-selected', active); item.setAttribute('aria-pressed', String(active)); }); const person = detection.dataset.detection === 'person'; selectedName.textContent = person ? 'PERSON 14' : 'CAR'; selectionCopy.textContent = person ? 'PERSON 14 is selected. The controls below alter its visual treatment.' : 'CAR is selected. The same visual controls update its detection frame in context.'; })); })(); ```