motion-sampler
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMotion 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
适用场景
- 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
- 运动轨迹分析 - 通过一系列位置点了解车辆行驶路径
- 存储优化 - 将行车记录仪存档大小缩减90%以上,同时保留视觉记录
- 快速视觉回顾 - 通过代表性帧浏览数小时的录像
- 位置识别 - 确定车辆在特定时间的位置
- 事件时间线 - 无需观看完整视频即可创建行程的视觉时间线
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, orPark_Rall - Default:
Movie_F
- Options:
-
source_dir (path): Root directory containing camera folders
- Example:
C:\Users\yousu\Desktop\CARDV
- Example:
-
camera (string): 要处理的摄像头类型
- 可选值:,
Movie_F,Movie_R,Park_F或Park_Rall - 默认值:
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
- Default:
-
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: or
YYYYMMDD(range)YYYYMMDD-YYYYMMDD - Example: or
2025072720250727-20250729
- Format:
-
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 - 示例:或
2025072720250727-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.06Columns:
- : Source MP4 filename
original_video - : Extracted JPEG filename
frame_file - : Camera type (Movie_F/Movie_R/Park_F/Park_R)
camera - : YYYYMMDD
date - : Frame position (F001, F002...)
position - : Milliseconds into video
timestamp_ms - : Seconds into video
timestamp_s - : Frame number in video (at 24fps)
frame_number - : JPEG file size in KB
file_size_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字段说明:
- : 源MP4文件名
original_video - : 提取的JPEG文件名
frame_file - : 摄像头类型(Movie_F/Movie_R/Park_F/Park_R)
camera - : 日期(YYYYMMDD格式)
date - : 帧位置(F001、F002...)
position - : 视频内的毫秒级时间戳
timestamp_ms - : 视频内的秒级时间戳
timestamp_s - : 视频中的帧序号(按24fps计算)
frame_number - : JPEG文件大小(KB)
file_size_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
| 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
输入: 418个Movie_F/R视频,平均时长60秒,总大小约45 GB
| 采样间隔 | 每视频提取帧数 | 总提取帧数 | 存储占用 | 缩减比例 |
|---|---|---|---|---|
| 5秒 | 12 | 5,016 | 9 GB | 80% |
| 10秒 | 7 | 2,926 | 5 GB | 89% |
| 15秒 | 5 | 2,090 | 3.7 GB | 92% |
| 30秒 | 3 | 1,254 | 2.2 GB | 95% |
假设4K分辨率下每帧平均大小为1.7 MB
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
针对每个视频:
- 跳过缓冲区域: 从1.0秒开始,到视频时长-1.0秒结束(避免黑帧)
- 计算采样时间戳: 从1.0秒开始,每隔N秒取一个时间点
- 必含结束帧: 始终包含视频时长-1.0秒处的最后一帧
- 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 endpython
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.MP4SKIP: 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 to 6-8 (if you have 8+ CPU cores)
max_workers解决方案: 将增加到6-8(如果您的CPU有8个及以上核心)
max_workersIssue: Large Output Size
问题:输出文件过大
Solution: Reduce to 85 or increase to 15-20s
jpeg_qualitysample_interval解决方案: 将降低到85,或把增加到15-20秒
jpeg_qualitysample_intervalIssue: Missing Some Videos
问题:部分视频未被处理
Cause: Videos shorter than (default 3s) are skipped
Solution: Lower to 1.0s if you need very short clips
min_durationmin_duration原因: 时长小于(默认3秒)的视频会被跳过
解决方案: 如果需要处理极短视频,将降低到1.0秒
min_durationmin_durationIssue: Out of Memory
问题:内存不足
Cause: Too many parallel workers on low-RAM system
Solution: Reduce to 2
max_workers原因: 低内存系统上开启了过多并行线程
解决方案: 将减少到2
max_workersFuture 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 benchmarksG:\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.
本工具属于行车记录仪分析套件的一部分,专为个人行车记录仪存档管理和运动轨迹分析设计。