菜单
Guides creation and configuration of VideoSystem instances for camera acquisition. Covers constructor parameters, lifecycle methods, system ID allocation, and encoding selection. Use when writing code that creates VideoSystem instances or needs to understand the VideoSystem API.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | camera-interface |
| description | Guides creation and configuration of VideoSystem instances for camera acquisition. Covers constructor parameters, lifecycle methods, system ID allocation, and encoding selection. Use when writing code that creates VideoSystem instances or needs to understand the VideoSystem API. |
| user-invocable | false |
Guides creation and configuration of VideoSystem instances. This skill covers the VideoSystem API itself;
for interactive camera discovery and testing via MCP tools, use /camera-setup instead. Overall system
architecture (binding classes, configuration dataclasses, startup orchestration) is the responsibility of
the consuming library or application.
Covers:
Does not cover:
/camera-setup)/video-mcp-environment-setup)Before writing any camera code, verify the current state of the library.
Check the locally installed ataraxis-video-system version against the latest release on GitHub:
pip show ataraxis-video-system
The current version is 4.0.1. If a version mismatch exists, ask the user how to proceed.
| File | What to Check |
|---|---|
../ataraxis-video-system/src/ataraxis_video_system/__init__.py | Exported classes, functions, and public API |
../ataraxis-video-system/src/ataraxis_video_system/video/video_system.py | VideoSystem constructor parameters and methods |
Project pyproject.toml | Current pinned version dependency |
See references/api-reference.md for the complete API reference including:
/camera-setup toolscamera = VideoSystem(
system_id=np.uint8(51),
data_logger=data_logger,
name="behavior_camera",
output_directory=output_directory,
camera_interface=CameraInterfaces.HARVESTERS,
camera_index=0,
video_encoder=VideoEncoders.H265,
encoder_speed_preset=EncoderSpeedPresets.SLOW,
quantization_parameter=15,
gpu=0,
)
Key constructor notes:
name is a required string that identifies the camera for downstream tools. It is written to a
camera_manifest.yaml file in the DataLogger output directory during __init__(), associating
the system_id with the human-readable name. The manifest enables discover_camera_data_tool
to identify axvs-produced log archives and match them with video files.data_logger must be an initialized and started DataLogger instance. The VideoSystem sends frame
timestamps to the logger via its multiprocessing input queue during acquisition.output_directory accepts Path | None. When None, frames are acquired but not saved to disk
(useful for display-only or warm-up without recording).frame_width, frame_height, frame_rate default to None (use camera native settings). For
Harvesters cameras, set resolution and frame rate via GenICam configuration (see /camera-setup)
rather than overriding through these parameters. The VideoSystem overrides are primarily intended
for OpenCV cameras that lack GenICam node control. Exposure, gain, and other GenICam nodes are applied at
configuration time via the /camera-setup tools or, in code, via the HarvestersCamera config methods
(set_node_value, get_configuration, apply_configuration); see the API reference. The deterministic
acquisition script does not reconfigure nodes at runtime.display_frame_rate defaults to None (preview disabled). Set to a positive integer FPS not exceeding
the camera's acquisition frame rate to enable, else __init__ raises TypeError. Frame display is
unsupported on macOS: it is auto-disabled (a warning is emitted), so the value has no effect there.gpu defaults to -1 (CPU encoding). Set to 0+ for NVIDIA GPU encoding.color is a keyword-only parameter defaulting to None. For OpenCV and Mock, None resolves to
monochrome (False) — a color OpenCV camera left at None silently records grayscale, so pass
color=True explicitly to record color. Only Harvesters infers color/mono from the GenICam config.VideoSystem() → start() → [start_frame_saving() → stop_frame_saving()] → stop()
start() begins frame acquisition without saving. Useful for preview or warm-up.start_frame_saving() / stop_frame_saving() toggle recording while acquisition continues.stop() terminates acquisition and releases all resources. Must be called explicitly. It blocks until
all buffered frames are encoded, up to a 10-minute cap; beyond that it force-kills the consumer and
discards remaining frames.Each VideoSystem instance requires a unique system_id (np.uint8) for DataLogger timestamp correlation.
Runtime instances are advised to use IDs in the range 51-100. The output video file is named
{system_id:03d}.mp4 (e.g., 051.mp4 for system_id 51).
| Encoder | Use When |
|---|---|
| H265 | Production workloads (default, better compression) |
| H264 | Compatibility with older video players is required |
| Preset | Value | Use when |
|---|---|---|
| FASTEST | 1 | Maximum throughput, large file size acceptable |
| FASTER | 2 | High throughput with slightly better compression |
| FAST | 3 | Real-time acquisition under CPU/GPU load |
| MEDIUM | 4 | Balanced starting point for real-time acquisition |
| SLOW | 5 | Default; good compression, may buffer under heavy load |
| SLOWER | 6 | Higher compression, offline or low-fps recording |
| SLOWEST | 7 | Maximum compression; offline re-encoding only |
| Format | Use When |
|---|---|
| YUV444 | Default; preserves color accuracy |
| YUV420 | Smaller files acceptable; monochrome cameras gain nothing from YUV444 |
All encoding recommendations in this skill are healthy starting points. Actual parameters must be fine-tuned by the end user for their specific camera, scene content, and throughput requirements.
| Use Case | Encoder | Preset | Pixel Format | QP | GPU | Rationale |
|---|---|---|---|---|---|---|
| Scientific imaging (high-speed) | H265 | SLOWEST (7) | YUV444 | 0-5 | 0 | Maximum quality; GPU offloads encoding cost |
| Behavioral video (color) | H265 | SLOW (5) | YUV420 | 15-20 | 0 | Good balance; YUV420 acceptable for scoring |
| Real-time preview/testing | H264 | FASTEST (1) | YUV420 | 23 | -1 | Minimum encoding cost; CPU-only for simplicity |
| Archival (storage-sensitive) | H265 | SLOWER (6) | YUV420 | 20-25 | 0 | Best compression; still usable visual quality |
| Multi-camera rig (bandwidth) | H265 | FAST (3) | YUV420 | 15 | 0 | Per-camera encoding must be fast; GPU parallelism |
| Factor | CPU | GPU (NVENC) |
|---|---|---|
| Throughput | Limited by core speed | Higher, especially multi-camera |
| Quality at QP | Slightly better at same QP | Slightly lower (NVENC limitation) |
| Multi-camera | Competes with other processes for CPU | Dedicated hardware; handles parallel |
| Availability | Always available | Requires NVIDIA GPU |
H265 produces better compression at equivalent visual quality. To match quality across encoders:
| Visual Quality | H265 QP | H264 QP | Notes |
|---|---|---|---|
| Near-lossless | 0-5 | 0-10 | Scientific use |
| High quality | 10-15 | 15-20 | Production default |
| Good quality | 15-20 | 20-25 | Behavioral video |
| Moderate | 20-25 | 25-30 | Archival |
| Error Pattern | Meaning | Resolution |
|---|---|---|
Unknown encoder 'hevc_nvenc' | NVIDIA NVENC not available | Use CPU encoding (gpu=-1) or install drivers |
Error initializing output stream | Resolution or format incompatible | Check frame dimensions are even numbers |
Queue input is backward in time | Timestamp ordering issue | Ensure frames arrive in order |
CUDA_ERROR_OUT_OF_MEMORY | GPU memory exhausted | Reduce concurrent GPU encoders or resolution |
Too many packets buffered | Encoding too slow for frame rate | Use faster preset or reduce resolution |
| MCP Discovery | Informs Code Parameter | How |
|---|---|---|
list_cameras_tool output | camera_interface, camera_index | Interface type and index transfer directly |
Camera resolution from list_cameras_tool | frame_width, frame_height | Use native resolution or override |
Camera FPS from list_cameras_tool | frame_rate | Set to None for native, or override |
check_runtime_requirements_tool | gpu | If GPU: OK, use gpu=0; if None, use -1 |
| GenICam node values | Camera-level setup | Apply same config before VideoSystem init |
| MCP session success or failure | Encoding feasibility | If MCP session works, code session will too |
| MCP Parameter | VideoSystem Parameter | Key Difference |
|---|---|---|
output_directory (str) | output_directory (Path) | Wrap in Path() |
interface (str) | camera_interface | Use CameraInterfaces enum member |
camera_index (int) | camera_index (int) | Same |
width (int) | frame_width (int) | Name change |
height (int) | frame_height (int) | Name change |
frame_rate (int) | frame_rate (int/None) | Code default None (camera native); MCP requires int |
gpu_index (int) | gpu (int) | Name change |
display_frame_rate | display_frame_rate | MCP default 25; code default None |
monochrome (bool) | color (bool/None) | Inverted: monochrome=True → color=False |
video_encoder (str) | video_encoder | str → VideoEncoders enum |
encoder_speed_preset | encoder_speed_preset | int → EncoderSpeedPresets enum |
output_pixel_format | output_pixel_format | str → OutputPixelFormats enum |
| (fixed at 112) | system_id | Code uses 51-100; MCP uses 112 |
| (auto-created) | data_logger | Code must create and manage DataLogger |
(fixed: "live_camera") | name | New required param; code must provide a descriptive name |
| Capability | MCP Limitation | Code Alternative |
|---|---|---|
| Multi-camera recording | Single session only | Multiple VideoSystem instances |
| Custom DataLogger config | Auto-created with instance_name="mcp_video_session" | Full control over DataLogger |
| Custom system IDs | Fixed at 112 | Any np.uint8 value (51-100 recommended) |
| Custom camera names | Fixed at "live_camera" | Descriptive name per camera (e.g., "face_camera") |
| Output directory = None | Requires directory | Disable saving for preview-only mode |
| Log archive assembly | Auto-assembled on stop | Call assemble_log_archives manually |
check_ffmpeg_availability() must return Truecheck_gpu_availability() must return True; verify NVIDIA driversEncoding cost depends heavily on frame content: high-motion or high-detail scenes are expensive to encode, while static or low-contrast scenes are cheap. A preset that works for a stationary camera may cause drops when the scene changes. Consider this when selecting presets.
display_frame_rate or disable preview (set to None)encoder_speed_preset (lower number)quantization_parameter (reduces quality but lowers encoding cost)gpu=0) if an NVIDIA GPU is availablesystem_id is unique across all active VideoSystem instances| Skill | Relationship |
|---|---|
/camera-setup | Covers MCP-based camera discovery, testing, and encoding parameter guide |
/post-recording | Downstream: verification after recording sessions |
/log-input-format | Reference: documents archive format produced by VideoSystem code |
/log-processing | Downstream: processes archives from VideoSystem instances |
/log-processing-results | Downstream: analyzes frame statistics from processed archives |
/pipeline | Context: end-to-end orchestration and multi-camera planning |
/video-mcp-environment-setup | Prerequisite: MCP server connectivity for API verification |
Camera Interface:
- [ ] Verified ataraxis-video-system version matches requirements (>=4.0.0)
- [ ] Verified cameras are discoverable using /camera-setup workflow
- [ ] Allocated unique system IDs in the 51-100 range (checked existing allocations)
- [ ] DataLogger initialized and started before VideoSystem creation
- [ ] Encoding configuration selected using use-case guidance table
- [ ] MCP test results translated to code parameters (if applicable)
- [ ] Tested acquisition with /camera-setup interactive session before integration
- [ ] stop() called explicitly on all VideoSystem instances during shutdown
Complete reference for ExtractionConfig parameters, generation from manifest, validation, and lifecycle. Covers the full extraction configuration data model, MCP tools for reading, writing, and validating configs, event code semantics, and config lifecycle workflow. Use when creating, reading, writing, or validating extraction configurations for the log processing pipeline.
Guides creation and configuration of MicroControllerInterface, ModuleInterface, and MQTTCommunication instances for microcontroller communication. Covers interface initialization and lifecycle, ModuleInterface subclassing with command and parameter sending, MQTTCommunication setup, controller ID allocation, and DataLogger integration. Use when writing code that creates MicroControllerInterface or MQTTCommunication instances or needs the ataraxis-communication-interface API.
Guides creation of custom hardware Module subclasses in the ataraxis-micro-controller C++ firmware library. Covers SetupModule, SetCustomParameters, and RunActiveCommand implementation, stage-based command execution, PACKED_STRUCT parameter structures, event codes, SendData patterns, and main.cpp integration with Kernel and Communication. Use when writing or modifying firmware Module subclasses, or when implementing the microcontroller side of an ataraxis-communication-interface module.
End-to-end orchestration guide for the ataraxis-video-system recording and analysis pipeline. Covers canonical phase ordering with handoff conditions, multi-camera planning with system ID allocation and DataLogger topology, and decision trees for interface, encoding, and processing configuration. Use when planning a full recording workflow, setting up multi-camera rigs, or deciding between MCP and code.
Guides post-recording verification and handoff: log archive assembly, video file validation, output completeness checks, and readiness assessment for downstream log processing. Use after stopping a video session to verify outputs before processing frame timestamps.
Performs in-depth codebase exploration at the start of a coding session. Builds comprehensive understanding of project structure, architecture, key components, and patterns. Use when starting a new session, when asked to understand or explore the codebase, when asked "what does this project do", when exploring unfamiliar code, or when the user asks about project structure or architecture.