camera-setup

name	camera-setup
description	Guides use of ataraxis-video-system MCP tools for camera discovery, runtime verification, interactive video session testing, and GenICam camera configuration. Use when discovering connected cameras, verifying system encoding requirements, testing camera acquisition, or reading and writing GenICam node values.
user-invocable	false

Camera setup

Guides the use of the ataraxis-video-system MCP tools for system verification, camera discovery, interactive testing, and GenICam configuration. This skill covers all MCP tool interactions; for writing code that integrates VideoSystem into an acquisition system, use /camera-interface instead.

---

Scope

Covers:

• Verifying runtime requirements (FFMPEG, GPU, CTI)
• Discovering connected cameras and their properties
• Managing CTI file configuration for Harvesters cameras
• Running interactive video capture sessions via MCP
• Reading, writing, dumping, and loading GenICam node configurations

Does not cover:

• Writing VideoSystem integration code (see /camera-interface)
• MCP server connectivity issues (see /video-mcp-environment-setup)

---

MCP tool reference

The ataraxis-video-system MCP server exposes 27 tools. This skill covers the 15 tools most relevant to camera setup, organized into five groups. Log processing and analysis tools are documented in /log-processing and /log-processing-results.

System verification

Tool	Purpose
check_runtime_requirements_tool	Verifies FFMPEG, NVIDIA GPU, and CTI file availability
get_cti_status_tool	Checks whether a GenTL Producer (.cti) file is configured
set_cti_file_tool	Configures the CTI file path for Harvesters camera support

check_runtime_requirements_tool returns a pipe-separated status line:

FFMPEG: OK | GPU: OK | CTI: OK

• FFMPEG: Missing means FFMPEG is not installed or not on PATH. Video encoding will fail.
• GPU: None means no NVIDIA GPU is available. CPU encoding still works but is slower.
• CTI: None means no GenTL Producer file is configured. Harvesters cameras will not be discoverable.

Camera discovery

Tool	Purpose
list_cameras_tool	Discovers all cameras accessible through OpenCV and Harvesters interfaces

Output format:

OpenCV #0: 1920x1080@30fps
Harvesters #0: Allied Vision Mako G-040B (DEV_1234) 1936x1216@40fps

Each line shows the interface type, camera index, and native resolution/frame rate. Harvesters cameras also show model and serial number. The camera index is the value to pass to start_video_session_tool or to the VideoSystem constructor.

Video session management

Tool	Purpose
start_video_session_tool	Starts camera acquisition with configurable encoding
stop_video_session_tool	Stops active session, assembles log archives, returns output paths
start_frame_saving_tool	Begins recording acquired frames to MP4
stop_frame_saving_tool	Stops recording, keeps acquisition active
get_session_status_tool	Returns detailed session status including encoding params and output paths

Only one video session can be active at a time.

start_video_session_tool parameter details:

Parameter	Type	Default	Description
output_directory	str	(required)	Path to directory for video output. Always ask the user.
interface	str	"opencv"	Camera interface: "opencv", "harvesters", or "mock"
camera_index	int	0	Camera index from list_cameras_tool output
width	int	600	Frame width in pixels
height	int	400	Frame height in pixels
frame_rate	int	30	Target acquisition frame rate in FPS
gpu_index	int	-1	GPU index for hardware encoding (-1 for CPU)
display_frame_rate	int / None	25	Preview display rate in FPS (None disables preview)
monochrome	bool	false	Capture in grayscale instead of color
video_encoder	str	"H264"	Video encoder: "H264" or "H265"
encoder_speed_preset	int	3	Speed preset from 1 (fastest) to 7 (slowest)
output_pixel_format	str	"yuv420p"	Pixel format: "yuv420p" or "yuv444p"
quantization_parameter	int	15	Compression quality (0 = best, 51 = worst)

• interface: "mock" produces synthetic frames with no hardware involvement and is intended only for pipeline/library testing; to test a real camera use "opencv" or "harvesters".
• display_frame_rate: on macOS, preview display is automatically disabled regardless of this value, so the absence of a preview window on macOS is expected and not a session failure. On other platforms it must not exceed frame_rate.

See the encoding parameter guidance section below for recommendations on encoder, preset, pixel format, and quantization parameter selection.

stop_video_session_tool return structure:

{"status": "stopped", "video_file": "/path/to/112.mp4", "log_directory": "/path/to/...",
 "archives_assembled": true, "source_ids": ["112"]}

get_session_status_tool return structure:

Returns {"status": "inactive"} when no session exists. When a session is active, returns a dictionary with interface, resolution, frame rate, encoder, preset, pixel format, quantization parameter, GPU encoding flag, output directory, video file path, and log directory.

GenICam configuration

These tools are for Harvesters cameras only. They connect to the camera temporarily, perform the operation, and disconnect.

Tool	Parameters	Purpose
read_genicam_node_tool	camera_index, node_name, blacklisted_nodes	Reads a single node or lists all writable nodes
write_genicam_node_tool	camera_index, node_name, value	Sets a GenICam node value
dump_genicam_config_tool	camera_index, output_file, blacklisted_nodes	Exports full camera config to YAML
load_genicam_config_tool	camera_index, config_file, strict_identity, blacklisted_nodes	Applies config from YAML to camera

read_genicam_node_tool behavior:

• With node_name provided: returns detailed metadata (type, value, access mode, range, unit, description)
• With node_name empty: lists all writable nodes with current values

write_genicam_node_tool behavior:

• The value parameter is always a string; it is automatically coerced to the node's native type (int, float, bool, or enum string)

dump_genicam_config_tool / load_genicam_config_tool:

• Always ask the user for the output_file or config_file path before calling these tools
• strict_identity (default false): when true, aborts if camera model/serial does not match the config file; when false, warns but proceeds

blacklisted_nodes (read/dump/load tools):

• Optional list[str] | None; when omitted, defaults to {"CustomerIDKey", "CustomerValueKey", "TestPattern"}
• Pass an empty list ([]) to disable blacklisting and operate on all matching nodes

Camera manifest management

Camera manifests (camera_manifest.yaml) identify which log archives in a DataLogger output directory were produced by ataraxis-video-system and associate each source ID with a human-readable name. Manifests are written automatically by VideoSystem.__init__() and by start_video_session_tool. These tools provide manual manifest management for retroactive tagging or inspection.

Tool	Parameters	Purpose
read_camera_manifest_tool	manifest_path	Reads a manifest and returns its source entries
write_camera_manifest_tool	log_directory, source_id, name	Registers a camera source in the manifest

read_camera_manifest_tool return structure:

{"manifest_path": "/path/to/camera_manifest.yaml", "sources": [{"id": 51, "name": "face_camera"}], "total_sources": 1}

write_camera_manifest_tool behavior:

• Creates a new manifest if one does not exist; appends to the existing manifest otherwise
• The name parameter must be a non-empty string (e.g., "face_camera", "body_camera")
• Use this tool to retroactively tag log archives from sessions that predate the manifest system

---

Workflows

Pre-implementation system check

Run this before any camera work to verify the host system is ready:

1. Call check_runtime_requirements_tool
2. If FFMPEG is missing, instruct the user to install FFMPEG n8.1
3. If GPU is None and hardware encoding is desired, verify NVIDIA drivers
4. If CTI is None and Harvesters cameras are needed, call set_cti_file_tool with the user's CTI path

Camera discovery

1. Call list_cameras_tool
2. Record camera indices for configuration
3. If no cameras appear:
   • Check physical USB/GigE connections
   • Verify camera drivers are installed
   • For Harvesters: call get_cti_status_tool and set_cti_file_tool if needed
   • Check for port conflicts with other applications

Interactive camera testing

Use this workflow to verify a camera works before writing integration code:

1. Ask the user for an output directory
2. Call start_video_session_tool with the camera index from discovery
3. Verify the session starts (check get_session_status_tool returns "running")
4. Call start_frame_saving_tool to test recording
5. Call stop_frame_saving_tool to end recording
6. Call stop_video_session_tool to release resources
7. Verify the output .mp4 file was created in the output directory

GenICam camera configuration

Use this workflow to inspect or modify Harvesters camera settings:

Inspect current configuration:

1. Call read_genicam_node_tool with empty node_name to list all writable nodes
2. Call read_genicam_node_tool with a specific node_name for detailed metadata

Modify a single setting:

1. Call read_genicam_node_tool to check the current value and valid range/entries
2. Call write_genicam_node_tool with the new value
3. Call read_genicam_node_tool again to confirm the change took effect

Save and restore configuration:

1. Ask the user for a YAML file path
2. Call dump_genicam_config_tool to export the current configuration
3. On a different session or camera, call load_genicam_config_tool to apply the saved configuration

---

Encoding parameter guidance

Encoder selection

Factor	H264	H265
Compatibility	Wider player support	May require newer players
Compression	Good	~30-50% better at same quality
Encoding speed	Faster	Slower (use GPU to offset)
Default	Yes (MCP default)	Recommended for production via code

Speed preset selection

Use Case	Preset	Rationale
Quick camera test	FAST (3)	Fast encoding, broad compatibility
Extended test recording	MEDIUM (4)	Balance of speed and file size
Quality evaluation	SLOW (5)	Better compression for evaluating camera output

All recommendations are healthy starting points. Actual parameters must be fine-tuned by the end user for their specific camera, scene content, and throughput requirements.

Pixel format guidance

Format	When to Use
YUV420	Default; monochrome cameras; storage-sensitive; behavioral video
YUV444	Color-critical scientific imaging; maximum color fidelity

Monochrome cameras gain nothing from YUV444 since all chrominance channels are zero.

Quantization parameter guidance

QP Range	Quality Level	Use Case
0-5	Near-lossless	Scientific imaging requiring maximum detail
10-15	High quality	Default for production; good balance
15-20	Good quality	Behavioral video where pixel-perfect is not needed
20-25	Moderate	Archival; long recordings with storage constraints
25-35	Low quality	Preview and testing only
35-51	Very low	Not recommended

The default QP of 15 is calibrated for H265 and is likely too low for H264. As a rough starting point, a slightly higher QP (around 15-20) is a reasonable place to begin for H264; tune it for your scene and throughput rather than treating it as a documented equivalence.

---

Bridge to code integration

When transitioning from MCP-based testing to writing VideoSystem code, use this mapping.

Parameter mapping

MCP Parameter	VideoSystem Parameter	Key Difference
output_directory	output_directory	str → Path; wrap in Path()
interface	camera_interface	str → CameraInterfaces enum
camera_index	camera_index	Same (int)
width	frame_width	Name differs
height	frame_height	Name differs
frame_rate	frame_rate	MCP requires explicit value; code default is None (camera native)
gpu_index	gpu	Name differs
display_frame_rate	display_frame_rate	MCP default: 25; code default: None
monochrome	color	Inverted: monochrome=True → color=False
video_encoder	video_encoder	str → VideoEncoders enum
encoder_speed_preset	encoder_speed_preset	int → EncoderSpeedPresets enum
output_pixel_format	output_pixel_format	str → OutputPixelFormats enum
quantization_parameter	quantization_parameter	Same (int)
(fixed at 112)	system_id	Code should use 51-100 range
(auto-created)	data_logger	Code must create and manage DataLogger
(fixed: "live_camera")	name	New required param; code must provide a descriptive camera name

System ID semantics

ID	Assignment	Context
51-100	Camera VideoSystem instances	Advised range; all other IDs used by other assets
111	CLI (axvs run)	Fixed; interactive terminal testing
112	MCP server sessions	Fixed; agent-driven testing

Workflow: MCP discovery to code integration

1. Use list_cameras_tool to discover camera indices and native resolution/FPS
2. Use start_video_session_tool to test the camera works at desired parameters
3. Use GenICam tools to find and configure optimal camera settings (Harvesters only)
4. Translate discoveries to VideoSystem constructor parameters using the mapping table above
5. Use production encoding defaults (H265, SLOW, YUV444) or customize per the encoding guidance

---

Troubleshooting

Symptom	Likely Cause	Resolution
check_runtime_requirements_tool → FFMPEG Missing	FFMPEG not installed	Install FFMPEG n8.1 and ensure it is on PATH
check_runtime_requirements_tool → GPU None	No NVIDIA GPU or drivers	Install NVIDIA drivers, or use CPU encoding (gpu=-1)
list_cameras_tool returns no cameras	No cameras connected	Check physical connections, drivers, CTI configuration
start_video_session_tool → error	Session already active	Call stop_video_session_tool first
start_video_session_tool → directory error	Output directory does not exist	Create the directory or provide a valid path
GenICam tool errors	Camera not Harvesters-compatible	GenICam tools only work with Harvesters cameras
write_genicam_node_tool fails	Node is read-only or value invalid	Use read_genicam_node_tool to check access mode and range
MCP tools unavailable	Server not running	Use /video-mcp-environment-setup to diagnose

---

CLI reference (human-facing — do not invoke)

CLI reference — for answering user questions only. The axvs command-line interface is a human-facing tool. Agents must never invoke axvs commands — every agent-driven operation has an equivalent MCP tool (noted in the table). This section exists solely so the agent can answer user questions about the CLI.

Command	Key options	Purpose	MCP equivalent
axvs run	-i/--interface, -c/--camera-index, -g/--gpu-index, -o/--output-directory, -m/--monochrome, -w/--width, -h/--height, -f/--frame-rate	Interactive single-camera live imaging test	start_video_session_tool / stop_video_session_tool
axvs cti set	-f/--file-path	Configures the GenICam GenTL Producer (.cti) file	set_cti_file_tool
axvs cti check	(none)	Verifies the configured CTI file is valid	get_cti_status_tool
axvs check devices	(none)	Discovers connected cameras and their indices	list_cameras_tool
axvs check compatibility	(none)	Checks FFMPEG/GPU video-encoding requirements	check_runtime_requirements_tool
axvs configure read	-c/--camera-index, -n/--node-name, -b/--blacklisted-node, --no-blacklist	Reads a GenICam node or lists writable nodes	read_genicam_node_tool
axvs configure write	-c/--camera-index, -n/--node-name, -v/--value	Writes a GenICam node value	write_genicam_node_tool
axvs configure dump	-c/--camera-index, -o/--output-file, -b/--blacklisted-node, --no-blacklist	Exports the full camera config to YAML	dump_genicam_config_tool
axvs configure load	-c/--camera-index, -f/--config-file, --strict, -b/--blacklisted-node, --no-blacklist	Applies a YAML config to the camera	load_genicam_config_tool

The axvs run session is driven by interactive keypresses (q to terminate, w to start saving frames, s to stop saving frames) that have no MCP analogue; the MCP session is tool-driven.

---

Related skills

Skill	Relationship
/camera-interface	Covers writing VideoSystem integration code after testing via MCP
/post-recording	Downstream: verification after recording sessions
/log-input-format	Reference: documents the archive format produced by this workflow
/log-processing	Downstream: processes archives from camera sessions
/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 all tool interactions

---

Verification checklist

Camera Setup:
- [ ] Verified runtime requirements (FFMPEG, GPU, CTI) via check_runtime_requirements_tool
- [ ] Configured CTI file if Harvesters cameras are needed
- [ ] Discovered cameras and recorded indices via list_cameras_tool
- [ ] Tested camera with interactive video session
- [ ] Verified recording produces valid MP4 output
- [ ] Configured GenICam nodes if using Harvesters cameras (optional)
- [ ] Encoding parameters understood (see encoding guidance section)
- [ ] Parameter mapping to code reviewed (if transitioning from MCP to code)