motion-sampler

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Motion Sampler Skill

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
**版本:**1.0 **类型:**视频帧提取 **用途:**从行车记录仪视频中提取代表性帧样本,无需存储完整视频即可了解运动轨迹

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.
Motion Sampler Skill会定期从行车记录仪视频中提取帧,生成车辆移动及位置变化的紧凑视觉摘要。与保存原始视频相比,这能实现90-95%的存储缩减,同时保留空间和时间上下文信息。

Use Cases

适用场景

  1. Motion trajectory analysis - Understand vehicle path through a sequence of locations
  2. Storage optimization - Reduce dashcam archive size by 90%+ while retaining visual record
  3. Quick visual review - Browse through hours of footage via representative frames
  4. Location identification - Identify where vehicle was at specific times
  5. Event timeline - Create visual timeline of trips without watching full videos
  1. 运动轨迹分析 - 通过一系列位置点了解车辆行驶路径
  2. 存储优化 - 将行车记录仪存档大小缩减90%以上,同时保留视觉记录
  3. 快速视觉回顾 - 通过代表性帧浏览数小时的录像
  4. 位置识别 - 确定车辆在特定时间的位置
  5. 事件时间线 - 无需观看完整视频即可创建行程的视觉时间线

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.
使用自然语言请求帧提取:
示例请求:
从CARDV文件夹中的所有Movie_F视频中每10秒提取一帧。

对Movie_R行车记录仪视频进行帧采样,每15秒提取一帧。

为所有停车摄像头视频创建运动样本,采样间隔为5秒。

提取2025年7月27日至29日的Movie_F和Movie_R视频的代表性帧。

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
  • camera (string): 要处理的摄像头类型
    • 可选值:
      Movie_F
      ,
      Movie_R
      ,
      Park_F
      ,
      Park_R
      all
    • 默认值:
      Movie_F
  • source_dir (路径): 包含摄像头文件夹的根目录
    • 示例:
      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
  • sample_interval (float): 提取帧的时间间隔(秒)
    • 范围:1.0 - 60.0
    • 默认值:10.0
    • 示例:5.0(密集采样)、15.0(稀疏采样)
  • output_dir (路径): 提取帧的保存目录
    • 默认值:
      {source_dir}/MOTION_SAMPLES
  • jpeg_quality (int): JPEG压缩质量
    • 范围:50 - 100
    • 默认值:92(视觉无损)
    • 值越小:文件越小,质量略有下降
  • max_workers (int): 并行处理线程数
    • 范围:1 - 8
    • 默认值:4
    • 数值越高:速度越快,但CPU占用越高
  • date_filter (string): 仅处理特定日期的视频
    • 格式:
      YYYYMMDD
      YYYYMMDD-YYYYMMDD
      (日期范围)
    • 示例:
      20250727
      20250727-20250729
  • min_duration (float): 跳过时长小于该值的视频(秒)
    • 默认值:3.0

Advanced (Future GPU Enhancement)

高级参数(未来GPU增强版)

  • 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
  • use_nvdec (bool): 使用NVIDIA硬件解码
    • 默认值:false(v1.0版本仅支持CPU)
    • 未来规划:设为true可实现3-5倍提速
  • gpu_id (int): 多GPU环境下的CUDA设备ID
    • 默认值: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
└── ...
{output_dir}/
├── INDEX.csv                                      # 完整元数据
├── 20250727150654_052278A_F001_001000ms.jpg      # 第1帧,对应视频1秒处
├── 20250727150654_052278A_F002_011000ms.jpg      # 第2帧,对应视频11秒处
├── 20250727150654_052278A_F003_021000ms.jpg      # 第3帧,对应视频21秒处
└── ...

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
{YYYYMMDDHHMMSS}_{FILEIDA/B}_{POSITION}_{TIMESTAMP_MS}ms.jpg

示例:20250727150654_052278A_F003_021000ms.jpg
         └─────┬─────┘ └──┬──┘  └┬┘   └───┬───┘
           日期/时间   文件ID  帧位置  时间戳

组成部分:
- YYYYMMDDHHMMSS: 视频开始时间
- FILEIDA/B: 摄像头文件ID + 后缀(A=前视,B=后视)
- F###: 帧位置(F001、F002、F003...)
- ######ms: 视频内的毫秒级时间戳

INDEX.csv Schema

INDEX.csv 字段说明

csv
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
csv
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
字段说明:
  • original_video
    : 源MP4文件名
  • frame_file
    : 提取的JPEG文件名
  • camera
    : 摄像头类型(Movie_F/Movie_R/Park_F/Park_R)
  • date
    : 日期(YYYYMMDD格式)
  • position
    : 帧位置(F001、F002...)
  • timestamp_ms
    : 视频内的毫秒级时间戳
  • timestamp_s
    : 视频内的秒级时间戳
  • frame_number
    : 视频中的帧序号(按24fps计算)
  • file_size_kb
    : JPEG文件大小(KB)

Performance Metrics

性能指标

Current (CPU-only v1.0)

当前版本(仅CPU的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)
  • 处理吞吐量: 6-8个视频/秒(4线程,Intel i7/i9处理器)
  • 提速效果: 多线程实现4倍提速
  • 内存占用: ~500 MB
  • GPU使用率: 0%(仅CPU处理)

Projected (GPU-accelerated v2.0)

预计(GPU加速的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)
  • 处理吞吐量: 20-30个视频/秒(NVDEC + 多线程)
  • 提速效果: 比单线程CPU快10-15倍
  • 内存占用: ~1-2 GB
  • GPU使用率: 30-50%(仅使用NVDEC解码器)

Storage Examples

存储示例

Input: 418 Movie_F/R videos, 60s avg, ~45 GB total
IntervalFrames/VideoTotal FramesStorageReduction
5s125,0169 GB80%
10s72,9265 GB89%
15s52,0903.7 GB92%
30s31,2542.2 GB95%
Assumes 1.7 MB per frame average at 4K resolution
输入: 418个Movie_F/R视频,平均时长60秒,总大小约45 GB
采样间隔每视频提取帧数总提取帧数存储占用缩减比例
5秒125,0169 GB80%
10秒72,9265 GB89%
15秒52,0903.7 GB92%
30秒31,2542.2 GB95%
假设4K分辨率下每帧平均大小为1.7 MB

Algorithm Details

算法细节

Frame Sampling Strategy

帧采样策略

For each video:
  1. Skip buffer zones: Start at 1.0s, end at duration-1.0s (avoids black frames)
  2. Calculate sample timestamps: Every N seconds starting from 1.0s
  3. Always include end frame: Last frame at duration-1.0s
  4. Example for 60s video, 10s interval:
    • F001: 1s, F002: 11s, F003: 21s, F004: 31s, F005: 41s, F006: 51s, F007: 59s
针对每个视频:
  1. 跳过缓冲区域: 从1.0秒开始,到视频时长-1.0秒结束(避免黑帧)
  2. 计算采样时间戳: 从1.0秒开始,每隔N秒取一个时间点
  3. 必含结束帧: 始终包含视频时长-1.0秒处的最后一帧
  4. 60秒视频、10秒间隔示例:
    • F001: 1秒处, F002: 11秒处, F003: 21秒处, F004: 31秒处, F005: 41秒处, F006: 51秒处, F007: 59秒处

Pseudo-code

伪代码

python
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
python
timestamps = []
current_time = 1.0  # 起始偏移量
while current_time < (duration - 1.0):
    timestamps.append(current_time)
    current_time += sample_interval
timestamps.append(duration - 1.0)  # 始终包含结束帧

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
  • 短视频(<3秒): 自动跳过并发出警告
  • 损坏文件: 记录错误日志,继续处理其他文件
  • 无法读取的帧: 跳过该帧,尝试读取下一帧
  • 磁盘已满: 优雅终止处理,保存已完成的部分结果

Error Messages

错误消息示例

SKIP: video.MP4 too short (2.1s)
ERROR: Cannot open corrupted_video.MP4
WARNING: Failed to read frame 120 from video.MP4
SKIP: video.MP4 时长过短(2.1秒)
ERROR: 无法打开损坏文件 corrupted_video.MP4
WARNING: 无法读取 video.MP4 的第120帧

Example Usage

使用示例

Request 1: Standard Extraction

请求1:标准提取

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
使用motion-sampler skill从C:\Users\yousu\Desktop\CARDV路径下的所有Movie_F视频中每10秒提取一帧,保存到MOTION_SAMPLES文件夹。
执行参数:
  • 摄像头类型: Movie_F
  • 源路径: C:\Users\yousu\Desktop\CARDV\Movie_F\
  • 输出路径: C:\Users\yousu\Desktop\CARDV\MOTION_SAMPLES\
  • 采样间隔: 10.0秒
  • 图像质量: 92

Request 2: Dense Sampling for Specific Date

请求2:特定日期的密集采样

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
从2025年7月27日的Movie_R视频中每5秒提取一帧。
执行参数:
  • 摄像头类型: Movie_R
  • 日期过滤: 20250727
  • 采样间隔: 5.0秒
  • 仅处理匹配
    20250727*.MP4
    的视频

Request 3: Sparse Sampling for Long-term Archive

请求3:长期存档的稀疏采样

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)
为所有停车摄像头(Park_F和Park_R)创建运动样本,采样间隔为30秒,在保留视觉记录的同时最小化存储占用。
执行参数:
  • 摄像头类型: Park_F、Park_R(全部)
  • 采样间隔: 30.0秒
  • 预期结果: 每60秒视频提取约3帧
  • 存储占用: 极小(数千个视频仅需约1-2 GB)

Troubleshooting

故障排除

Issue: Processing Very Slow

问题:处理速度极慢

Solution: Increase
max_workers
to 6-8 (if you have 8+ CPU cores)
解决方案: 将
max_workers
增加到6-8(如果您的CPU有8个及以上核心)

Issue: Large Output Size

问题:输出文件过大

Solution: Reduce
jpeg_quality
to 85 or increase
sample_interval
to 15-20s
解决方案: 将
jpeg_quality
降低到85,或把
sample_interval
增加到15-20秒

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
原因: 时长小于
min_duration
(默认3秒)的视频会被跳过 解决方案: 如果需要处理极短视频,将
min_duration
降低到1.0秒

Issue: Out of Memory

问题:内存不足

Cause: Too many parallel workers on low-RAM system Solution: Reduce
max_workers
to 2
原因: 低内存系统上开启了过多并行线程 解决方案: 将
max_workers
减少到2

Future Enhancements (v2.0 Roadmap)

未来增强功能(v2.0路线图)

GPU Acceleration

GPU加速

  • NVDEC hardware video decoding (5-10x speedup)
  • GPU-accelerated JPEG encoding
  • Multi-GPU support for massive archives
  • Automatic GPU/CPU fallback
  • NVDEC硬件视频解码(5-10倍提速)
  • GPU加速JPEG编码
  • 多GPU支持,处理大规模存档
  • 自动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
  • 智能采样(检测运动,跳过静态场景)
  • 人脸/人物检测集成
  • 保留GPS叠加层
  • 生成缩略图条
  • 用于浏览样本的Web查看器

Optimization

优化

  • Incremental processing (skip already-processed videos)
  • Resume from interruption
  • S3/cloud storage output
  • Real-time progress dashboard
  • 增量处理(跳过已处理的视频)
  • 断点续传
  • 支持输出到S3/云存储
  • 实时进度仪表盘

Technical Dependencies

技术依赖

Required

必填依赖

  • Python 3.8+
  • opencv-python (cv2) >= 4.8
  • numpy >= 1.24
  • pandas >= 2.0 (for INDEX.csv)
  • Python 3.8+
  • opencv-python (cv2) >= 4.8
  • numpy >= 1.24
  • pandas >= 2.0(用于生成INDEX.csv)

Optional (for future GPU support)

可选依赖(用于未来GPU支持)

  • cuda >= 11.0
  • opencv-contrib-python (CUDA build)
  • cuda >= 11.0
  • opencv-contrib-python(CUDA版本)

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
G:\My Drive\PROJECTS\skills\motion-sampler\
├── skill.md                          # 当前文档
├── README.md                         # 快速入门指南
├── SKILL_MANIFEST.md                # 文件清单与测试文档
├── scripts/
│   ├── extract_motion_samples.py    # 主提取脚本
│   └── analyze_results.py           # 后处理分析脚本
├── assets/
│   ├── config_template.json         # 默认配置文件
│   └── camera_mapping.json          # 摄像头ID映射文件
└── references/
    ├── SAMPLING_ALGORITHM.md        # 详细算法文档
    └── PERFORMANCE_BENCHMARKS.md    # 速度/存储基准测试文档

JSON API Contract

JSON API接口约定

For programmatic invocation:
json
{
  "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:
json
{
  "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"
}
用于程序化调用:
json
{
  "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
}
响应示例:
json
{
  "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.
本工具属于行车记录仪分析套件的一部分,专为个人行车记录仪存档管理和运动轨迹分析设计。