Motion Sampler Skill

Version: 1.0 Type: Video Frame Extraction Purpose: Extract representative frame samples from dashcam videos to understand motion and trajectory without storing full videos

Overview

The Motion Sampler extracts frames at regular intervals from dashcam videos to create a compact visual summary of vehicle movement and location changes. This achieves 90-95% storage reduction compared to keeping original videos while preserving spatial and temporal context.

Use Cases

• Motion trajectory analysis - Understand vehicle path through a sequence of locations

• Storage optimization - Reduce dashcam archive size by 90%+ while retaining visual record

• Quick visual review - Browse through hours of footage via representative frames

• Location identification - Identify where vehicle was at specific times

• Event timeline - Create visual timeline of trips without watching full videos

Natural Language Interface

Use natural language to request frame extraction:

Example Requests:

Extract frames every 10 seconds from all Movie_F videos in the CARDV folder.

Sample frames from Movie_R dashcam videos, one frame every 15 seconds.

Create motion samples for all parking camera videos with 5-second intervals.

Extract representative frames from Movie_F and Movie_R for July 27-29, 2025.

Parameters

Required

camera (string): Camera type to process

• Options: Movie_F , Movie_R , Park_F , Park_R , or all

• Default: Movie_F

source_dir (path): Root directory containing camera folders

• Example: C:\Users\yousu\Desktop\CARDV

Optional

sample_interval (float): Seconds between extracted frames

• Range: 1.0 - 60.0

• Default: 10.0

• Examples: 5.0 (dense sampling), 15.0 (sparse sampling)

output_dir (path): Where to save extracted frames

• Default: {source_dir}/MOTION_SAMPLES

jpeg_quality (int): JPEG compression quality

• Range: 50 - 100

• Default: 92 (visually lossless)

• Lower = smaller files, slightly reduced quality

max_workers (int): Parallel processing threads

• Range: 1 - 8

• Default: 4

• Higher = faster but more CPU usage

date_filter (string): Only process videos from specific date(s)

• Format: YYYYMMDD or YYYYMMDD-YYYYMMDD (range)

• Example: 20250727 or 20250727-20250729

min_duration (float): Skip videos shorter than this (seconds)

• Default: 3.0

Advanced (Future GPU Enhancement)

use_nvdec (bool): Use NVIDIA hardware decoding

• Default: false (CPU-only in v1.0)

• Future: true for 3-5x speedup

gpu_id (int): CUDA device ID if multiple GPUs

• Default: 0

Output Format

Directory Structure

{output_dir}/ ├── INDEX.csv # Comprehensive metadata ├── 20250727150654_052278A_F001_001000ms.jpg # Frame 1 at 1s ├── 20250727150654_052278A_F002_011000ms.jpg # Frame 2 at 11s ├── 20250727150654_052278A_F003_021000ms.jpg # Frame 3 at 21s └── ...

Filename Format

{YYYYMMDDHHMMSS}{FILEIDA/B}{POSITION}_{TIMESTAMP_MS}ms.jpg

Example: 20250727150654_052278A_F003_021000ms.jpg └─────┬─────┘ └──┬──┘ └┬┘ └───┬───┘ Date/Time FileID Pos Timestamp

Components:

• YYYYMMDDHHMMSS: Video start time
• FILEIDA/B: Camera file ID + suffix (A=front, B=rear)
• F###: Frame position (F001, F002, F003...)
• ######ms: Milliseconds into video

INDEX.csv Schema

original_video,frame_file,camera,date,position,timestamp_ms,timestamp_s,frame_number,file_size_kb 20250727150654_052278A.MP4,20250727150654_052278A_F001_001000ms.jpg,Movie_F,20250727,F001,1000,1.0,24,1713.06

Columns:

• original_video : Source MP4 filename

• frame_file : Extracted JPEG filename

• camera : Camera type (Movie_F/Movie_R/Park_F/Park_R)

• date : YYYYMMDD

• position : Frame position (F001, F002...)

• timestamp_ms : Milliseconds into video

• timestamp_s : Seconds into video

• frame_number : Frame number in video (at 24fps)

• file_size_kb : JPEG file size in KB

Performance Metrics

Current (CPU-only v1.0)

• Throughput: 6-8 videos/second (4 workers, Intel i7/i9)

• Speedup: 4x with multi-threading

• Memory: ~500 MB

• GPU Usage: 0% (CPU-only)

Projected (GPU-accelerated v2.0)

• Throughput: 20-30 videos/second (NVDEC + multi-threading)

• Speedup: 10-15x vs single-threaded CPU

• Memory: ~1-2 GB

• GPU Usage: 30-50% (NVDEC decoder only)

Storage Examples

Input: 418 Movie_F/R videos, 60s avg, ~45 GB total

Interval Frames/Video Total Frames Storage Reduction

5s 12 5,016 9 GB 80%

10s 7 2,926 5 GB 89%

15s 5 2,090 3.7 GB 92%

30s 3 1,254 2.2 GB 95%

Assumes 1.7 MB per frame average at 4K resolution

Algorithm Details

Frame Sampling Strategy

For each video:

• Skip buffer zones: Start at 1.0s, end at duration-1.0s (avoids black frames)

• Calculate sample timestamps: Every N seconds starting from 1.0s

• Always include end frame: Last frame at duration-1.0s

• Example for 60s video, 10s interval:

• F001: 1s, F002: 11s, F003: 21s, F004: 31s, F005: 41s, F006: 51s, F007: 59s

Pseudo-code

timestamps = [] current_time = 1.0 # start offset while current_time < (duration - 1.0): timestamps.append(current_time) current_time += sample_interval timestamps.append(duration - 1.0) # always include end

Error Handling

Automatic Handling

• Short videos (<3s): Skipped with warning

• Corrupted files: Logged as error, processing continues

• Unreadable frames: Frame skipped, next frame attempted

• Disk full: Graceful termination with partial results saved

Error Messages

SKIP: video.MP4 too short (2.1s) ERROR: Cannot open corrupted_video.MP4 WARNING: Failed to read frame 120 from video.MP4

Example Usage

Request 1: Standard Extraction

Use the motion-sampler skill to extract frames every 10 seconds from all Movie_F videos in C:\Users\yousu\Desktop\CARDV. Save to MOTION_SAMPLES folder.

Execution:

• Camera: Movie_F

• Source: C:\Users\yousu\Desktop\CARDV\Movie_F\

• Output: C:\Users\yousu\Desktop\CARDV\MOTION_SAMPLES\

• Interval: 10.0s

• Quality: 92

Request 2: Dense Sampling for Specific Date

Extract frames every 5 seconds from Movie_R videos on July 27, 2025.

Execution:

• Camera: Movie_R

• Date filter: 20250727

• Interval: 5.0s

• Only processes videos matching 20250727*.MP4

Request 3: Sparse Sampling for Long-term Archive

Create motion samples with 30-second intervals for all parking cameras (Park_F and Park_R) to minimize storage while keeping a visual record.

Execution:

• Camera: Park_F, Park_R (both)

• Interval: 30.0s

• Expected: ~3 frames per 60s video

• Storage: Minimal (~1-2 GB for thousands of videos)

Troubleshooting

Issue: Processing Very Slow

Solution: Increase max_workers to 6-8 (if you have 8+ CPU cores)

Issue: Large Output Size

Solution: Reduce jpeg_quality to 85 or increase sample_interval to 15-20s

Issue: Missing Some Videos

Cause: Videos shorter than min_duration (default 3s) are skipped Solution: Lower min_duration to 1.0s if you need very short clips

Issue: Out of Memory

Cause: Too many parallel workers on low-RAM system Solution: Reduce max_workers to 2

Future Enhancements (v2.0 Roadmap)

GPU Acceleration

• NVDEC hardware video decoding (5-10x speedup)

• GPU-accelerated JPEG encoding

• Multi-GPU support for massive archives

• Automatic GPU/CPU fallback

Advanced Features

• Smart sampling (detect motion, skip static scenes)

• Face/person detection integration

• GPS overlay preservation

• Thumbnail strip generation

• Web viewer for browsing samples

Optimization

• Incremental processing (skip already-processed videos)

• Resume from interruption

• S3/cloud storage output

• Real-time progress dashboard

Technical Dependencies

Required

• Python 3.8+

• opencv-python (cv2) >= 4.8

• numpy >= 1.24

• pandas >= 2.0 (for INDEX.csv)

Optional (for future GPU support)

• cuda >= 11.0

• opencv-contrib-python (CUDA build)

File Locations

G:\My Drive\PROJECTS\skills\motion-sampler
├── skill.md # This file ├── README.md # Quick start guide ├── SKILL_MANIFEST.md # File inventory & testing ├── scripts/ │ ├── extract_motion_samples.py # Main extraction script │ └── analyze_results.py # Post-processing analysis ├── assets/ │ ├── config_template.json # Default configuration │ └── camera_mapping.json # Camera ID mapping └── references/ ├── SAMPLING_ALGORITHM.md # Detailed algorithm docs └── PERFORMANCE_BENCHMARKS.md # Speed/storage benchmarks

JSON API Contract

For programmatic invocation:

{ "camera": "Movie_F", "source_dir": "C:\Users\yousu\Desktop\CARDV", "output_dir": "C:\Users\yousu\Desktop\CARDV\MOTION_SAMPLES", "sample_interval": 10.0, "jpeg_quality": 92, "max_workers": 4, "date_filter": null, "min_duration": 3.0, "use_nvdec": false }

Response:

{ "status": "success", "videos_processed": 2146, "frames_extracted": 15022, "total_size_mb": 26750.5, "avg_frames_per_video": 7.0, "processing_time_s": 305.2, "throughput_videos_per_sec": 7.03, "output_dir": "C:\Users\yousu\Desktop\CARDV\MOTION_SAMPLES", "index_file": "C:\Users\yousu\Desktop\CARDV\MOTION_SAMPLES\INDEX.csv" }

License & Attribution

Part of the dashcam analysis suite. Designed for personal dashcam archive management and motion trajectory analysis.