Skip to content

README-DEMO.md

Latest commit

 

History

History
190 lines (132 loc) · 5.77 KB

README-DEMO.md

File metadata and controls

190 lines (132 loc) · 5.77 KB
Raw

Demo Recording Guide

This document explains how to record a high-quality demo GIF/video for VisionFlow Studio.

Quick Start (Automated Verification First)

Before recording, verify the system is in canonical state:

# Reset DB to seeded canonical state
pnpm seed:db -- --reset

# Run Phase 23 full E2E proof
pnpm meta:harness:phase23

Expected result: ALL HARNESSES PASSED (DB + API + Playwright)

Recording Setup

Tools recommended:

  • Windows: ScreenToGif (recommended — free, lightweight)
  • macOS: LICEcap or built-in Screen Recording
  • Cross-platform: LICEcap

Display settings:

  • Resolution: 1280×720 or 1920×1080
  • Frame rate: 15 FPS (sufficient for UI animations)
  • Output: GIF or WebM, max 5MB

Recording area:

  • Capture only the browser window, not the full desktop
  • Leave 10px padding on all sides
  • Remove browser bookmarks bar

Demo Flow Script

Record the following 9-step flow. Target duration: 45–60 seconds. A full manual walkthrough is available in DEMO-CHECKLIST.md.

Step 1: Overview + Backend Readiness (5s)

Open VisionFlow Studio at http://localhost:5173. Show all 8 navigation sections. Point out the ReadinessStrip — it reads real backend state from /api/health/runtime/status, not mock data. Shows: Database ready, Queue ready, CV Worker configured.

Step 2: Media Upload (8s)

Navigate to Media tab. Upload a sample image. Show:

  • Real-time upload progress bar
  • SHA-256 dedupe indicator
  • Thumbnail generated by CV worker (real Pillow → WebP)
  • Asset table with dimensions extracted by sharp

Step 3: Dataset Versioning (8s)

Navigate to Versions tab. Show:

  • Canonical LOCKED dataset version: parking_v3
  • Split distribution: TRAIN / VALID / TEST
  • Locked versions show a lock indicator
  • Image dimensions from real sharp extraction

Step 4: Annotation (8s)

Navigate to Annotate tab. Show:

  • Bounding boxes for car / van / truck on north-gate-frame-1482.jpg
  • Color-coded labels (green = ground truth)
  • Label selector dropdown
  • Locked dataset rejects annotation mutations (enforced by API)

Step 5: Pipeline Builder (6s)

Navigate to Pipeline tab. Show:

  • Visual pipeline graph: Input → Resize → Detector → NMS → Output
  • YOLOv8n detector node config: 640×640, confidence 0.25, NMS 0.45
  • Pipeline validation passing

Step 6: Job Execution (8s)

Navigate to Jobs tab. Show:

  • Canonical SUCCEEDED job: job_2026_04_28_2036
  • Job metadata: dataset version, pipeline, model, progress log
  • 3 real predictions with label, confidence, and bounding box geometry
  • Predictions persisted in PostgreSQL via NestJS API

Step 7: Prediction Overlay & Evaluation Metrics (6s)

In the Jobs panel, show:

  • Evaluation metrics: Precision, Recall, F1, Mean IoU (all 1.0 for perfect match)
  • Per-class breakdown: car, van, truck — each with TP=1, FP=0, FN=0
  • Reports persisted with deterministic inputHash and metricsHash
  • Run pnpm harness:phase22a to see the hash verification

Step 8: Timeline Replay (4s)

Navigate to Replay tab. Show:

  • BBox morph animation between frames
  • Ground truth / prediction toggle
  • Playback controls

Step 9: Dataset Diff (4s)

Navigate to Diff tab. Show:

  • Version comparison interface
  • IoU-based added/removed/changed annotation detection

Post-Recording

  1. Optimize the GIF at ezgif.com/optimize:

    • Reduce colors to 128 or 64
    • Set lossy compression to 10–20
    • Target: < 3MB

  2. Trim precisely using ezgif.com/crop if needed

  3. Save as WebM if GIF size is problematic (better compression at same quality)

  4. Place the file:

    docs/demo/demo.gif       ← GIF format
# or
docs/demo/demo.mp4       ← MP4 format (if small enough)

  5. Update README.md reference if using a different path

Automated Verification Commands

# Full Phase 23 proof (DB + API + Playwright)
pnpm meta:harness:phase23

# Phase 22A: 18-point fixture infrastructure
pnpm harness:phase22a

# Phase 22B: 8-point API production path
pnpm meta:harness:phase22b -- --strict --with-api

# Playwright production-path smoke (11 tests)
cd apps/web && pnpm exec playwright test e2e/production-path.spec.ts

# Playwright full vertical slice (19 tests)
cd apps/web && pnpm exec playwright test e2e/full-vertical-slice.spec.ts

# API smoke
curl http://localhost:3000/api/health
curl http://localhost:3000/api/health/runtime/status
curl http://localhost:3000/api/projects/proj_parking_lot/datasets
curl "http://localhost:3000/api/projects/proj_parking_lot/dataset-versions/dataset_proj_parking_lot_parking_v3/export/coco"

Fallback: Static Screenshots

If recording a GIF is not possible, use high-quality static screenshots:

  1. Take screenshots at each step above

  2. Use Cloud Convert to create an animated GIF

  3. Or embed individual images in the README using markdown:

    ## Demo

### Media Upload
![Media Upload](docs/demo/screenshots/media-upload.png)

### Dataset Versioning
![Dataset Versioning](docs/demo/screenshots/versions.png)

### Annotation
![Annotation](docs/demo/screenshots/annotate.png)

### Pipeline Builder
![Pipeline](docs/demo/screenshots/pipeline.png)

### Evaluation Results
![Evaluation](docs/demo/screenshots/evaluation.png)

Recording Tips

  • Practice first — Run through the flow 2–3 times before recording
  • Clean state — Reset browser cache and localStorage before recording
  • No audio — Keep the demo silent
  • No cursor trail — Disable cursor effects
  • Consistent speed — Use the same pacing throughout
  • End cleanly — Let the final screen sit for 1–2 seconds before stopping