motion-sampler

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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
```
  ,
```
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

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 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

高级功能

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.

本工具属于行车记录仪分析套件的一部分，专为个人行车记录仪存档管理和运动轨迹分析设计。