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.

---

## 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, and the MCP-to-code parameter mapping (see `/camera-interface`)
- The use-case encoding table and the FFMPEG error catalog (see `/camera-interface`)
- System ID allocation and DataLogger topology (see `/pipeline`)
- The `axvs` command-line surface (see `/cli-reference`)
- Archive assembly and video file validation after a session (see `/post-recording`)
- 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`.

Every tool in this skill returns a plain string or a dictionary and never raises. A failure arrives as a string
beginning `Error:` or as a dictionary carrying an `error` key, so check every return for that marker before treating
the call as successful. `write_genicam_node_tool` carries the one exception, reporting a write that landed while its
read-back failed without the prefix, since the write needs no retry and only its confirmation is missing.

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

`set_cti_file_tool` takes one parameter, `file_path` (`str`, required): the absolute path to the vendor-supplied `.cti`
GenTL Producer file. **Always ask the user** for it. It returns `CTI configured: {path}` on success, or a string
beginning `Error:` when the path is missing, is not a file, or the library rejects the Producer.

`check_runtime_requirements_tool` returns a pipe-separated status line:
```text
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, or the configured file fails to load. Harvesters cameras
  cannot be used until a loadable Producer is configured.

`get_cti_status_tool` returns `CTI: {path}` for a valid configured Producer, or `CTI: Not configured` when none is set
or the configured path fails to load.

The `AXVS_CTI_PATH` environment variable supplies the Producer path for a single runtime and replaces the path persisted
by `set_cti_file_tool` without falling back to it. Check the variable whenever the reported path is unexpected, or when
`CTI: Not configured` follows a successful `set_cti_file_tool` call.

### GenICam platform support

The GenICam (Harvesters) camera interface installs with ataraxis-video-system on every supported host: Linux, Windows,
and Apple Silicon Macs running macOS 13 or later. Intel Macs cannot install the library. Every GenICam tool is therefore
available on any host that runs the MCP server, once a GenTL Producer (.cti) file is configured.

### Camera discovery

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

Output format:
```text
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.

When nothing is found, the tool returns `No cameras discovered on the system.` Harvesters discovery is skipped silently
when no GenTL Producer (.cti) file is configured or the configured file is missing, so an OpenCV-only listing warrants a
`get_cti_status_tool` call before concluding that no GenICam camera is attached.

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

A session writes exactly one `{system_id:03d}.mp4` (`112.mp4` for MCP sessions) for its whole lifetime, and the file is
finalized only when the session stops. `stop_frame_saving_tool` clears a flag, so a later `start_frame_saving_tool` call
resumes appending to the same file. Several save/stop cycles in one session therefore produce one video, not several. To
get separate files, stop the session and start a new one.

`start_video_session_tool`, `start_frame_saving_tool`, and `stop_frame_saving_tool` report success as
`Session started: ...`, `Recording started`, and `Recording stopped` respectively. A failed start reports the failure in
its return value, so an unchecked failure leaves a later recording call looking successful.

**`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)                   |

- `monochrome` and every parameter listed after it (`video_encoder`, `encoder_speed_preset`,
  `output_pixel_format`, `quantization_parameter`) are keyword-only. Pass them by name.
- `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"`.
- `monochrome` applies to the `"opencv"` and `"mock"` interfaces only. The `"harvesters"` interface takes its
  color mode from the camera's own GenICam configuration, so the flag has no effect there.
- `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 every platform, macOS
  included, the value must be None or a positive integer that does not exceed `frame_rate`. The bound is
  validated before the macOS branch disables the preview, so an out-of-range value fails the start there too.
- `quantization_parameter` must be between 0 and 51 inclusive. There is no sentinel value.

**`stop_video_session_tool` return structure:**

```text
{"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. While a session object exists, `status` is `"running"` or
`"stopped"`, and the dictionary also carries `name` (always `"live_camera"` for MCP sessions), `interface`,
`camera_index`, `resolution`, `frame_rate`, `monochrome`, `encoder`, `encoder_speed_preset`, `output_pixel_format`,
`quantization_parameter`, `gpu_encoding`, `output_directory`, `display_frame_rate`, `video_file`, and `log_directory`.

### GenICam configuration

These tools are for Harvesters cameras only. They connect to the camera temporarily, perform the operation, and
disconnect. A camera that discards node state across a device close therefore serves its previous values to the next
call and to the recording, so a setting that has to survive belongs in a camera UserSet.

| 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:**
- `camera_index` defaults to `0` and `node_name` defaults to `""`
- With `node_name` provided: returns detailed metadata (type, value, access mode, range, unit, description)
- With `node_name` empty: returns `Found {N} writable GenICam nodes:` followed by one `  {name} = {value}` line
  per node. A node that cannot be read renders as `<unreadable>` and the listing continues

**`write_genicam_node_tool` behavior:**
- The `value` parameter is always a string, automatically coerced to the node's native type (int, float, bool,
  or enum string)
- The tool reads the node back over the same connection and reports the value the camera holds beside the one
  requested. A node that advertises ReadWrite access can still round the write to its step increment or reject it, so
  the reported value is the one in force

**`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,
  and when `false`, warns but proceeds. It is keyword-only, as is `load_genicam_config_tool`'s `blacklisted_nodes`
- The dump confirmation counts one entry per selector combination for selector-addressed nodes, so the reported
  node count can exceed the number of distinct feature names

**`blacklisted_nodes` (read/dump/load tools):**
- Optional `list[str] | None`. When omitted, it 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:**

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

**`write_camera_manifest_tool` return structure:**

```text
{"manifest_path": "/path/to/camera_manifest.yaml", "registered_source": {"id": 51, "name": "face_camera"},
 "status": "success"}
```

Returns an `error` dictionary instead when the log directory is absent or is not a directory, when `name` is empty, or
when the write fails. Confirm `status` is `success` before running discovery against the directory.

**`write_camera_manifest_tool` behavior:**
- Creates a new manifest if one does not exist. Otherwise it replaces the entry already registered under the same
  `source_id`, and appends a new entry only when the manifest carries none for that ID
- The write runs under a `.lock` file beside the manifest and aborts if the lock cannot be taken within 10 seconds
- The `name` parameter must be a non-empty string (e.g., `"face_camera"`, `"body_camera"`)
- The tool never creates the `log_directory`, so it tags a directory that already holds log archives

---

## Workflows

### Pre-implementation system check

1. Call `check_runtime_requirements_tool`
2. If FFMPEG is missing, instruct the user to install FFMPEG n9.0.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. If the
   user reports a CTI path you did not configure, check whether `AXVS_CTI_PATH` is set in their environment

### Camera discovery

1. Call `list_cameras_tool`
2. Record camera indices for configuration
3. If no cameras appear, work through the Troubleshooting section below, which indexes each discovery symptom against
   its likely cause and resolution

### Interactive camera testing

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

**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. The response names the requested value and the value the camera
   reports for the node on that same connection
3. Call `read_genicam_node_tool` again to confirm the value survived the connection close

Set `PixelFormat` to an 8-bit format (Mono8, BGR8, RGB8) before recording. The VideoSystem constructor grabs a probe
frame and rejects the camera with a ValueError when the frames are not 8-bit, so a camera left on Mono12 or Mono16 fails
to start.

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

`/camera-interface` owns the use-case encoding table, the encoder and pixel format trade-offs, the H264-to-H265
quantization equivalence, and the FFMPEG error catalog. Read those from there.

The MCP defaults (`H264`, preset `3`, `yuv420p`, QP `15`) are tuned for a quick compatibility-first test, not for
production. Two of them deserve attention while testing:

- **Preset.** `3` (FAST) suits a quick camera test. Raise it to `4` for an extended test recording, and to `5` when the
  point of the session is evaluating the camera's own image quality.
- **Quantization parameter.** The default of `15` is calibrated for H265 and is likely too low for the H264 default a
  session starts with. Around 15-20 is a reasonable place to begin for H264. Tune it for the scene.

---

## Bridge to code integration

Once an MCP session records the camera correctly, carry its settled parameters into code:

1. Use `list_cameras_tool` to discover camera indices and native resolution and frame rate
2. Use `start_video_session_tool` to confirm the camera works at the desired parameters
3. Use the GenICam tools to find and apply the camera's own optimal settings (Harvesters only)
4. Invoke `/camera-interface` and translate the settled parameters through its MCP-to-code mapping table

**The mapping table lives in `/camera-interface` alone.** Several MCP parameters change name (`width` becomes
`frame_width`), one inverts (`monochrome` becomes `color`), several change type from string to enum, and three code
parameters have no MCP counterpart at all. Do not translate them from memory.

An MCP session is fixed at `system_id=112` and `name="live_camera"`, so neither value transfers to code. `/pipeline`
owns system ID allocation and the DataLogger topology that constrains it.

---

## Troubleshooting

| Symptom                                            | Likely cause                              | Resolution                                                                                             |
|----------------------------------------------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------|
| `check_runtime_requirements_tool` → FFMPEG Missing | FFMPEG not installed                      | Install FFMPEG n9.0.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, and whether another application holds the port |
| `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                                                        |
| GenICam error naming a discovered camera count     | `camera_index` names no discovered camera | Re-run `list_cameras_tool` and use a reported index. A count of zero points at the Producer            |
| Session start fails on frame data type             | Camera set to a wider-than-8-bit format   | Write `PixelFormat` to Mono8, BGR8, or RGB8                                                            |
| `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 equivalents

Every tool group in this skill except camera manifest management has an `axvs` command a user can run by hand, and
`/cli-reference` is canonical for all of them. **You MUST never invoke `axvs` commands.** Invoke `/cli-reference` when
the user asks what a command does, or when `/video-mcp-environment-setup` has established that the server cannot be
restored and the work must move to the terminal.

| Tool group                 | User-facing command                                                            |
|----------------------------|--------------------------------------------------------------------------------|
| CTI configuration          | `axvs cti set`, `axvs cti check`                                               |
| Runtime and discovery      | `axvs check compatibility`, `axvs check devices`                               |
| Video session              | `axvs run`                                                                     |
| GenICam configuration      | `axvs configure read`, `write`, `dump`, `load`                                 |
| Camera manifest management | No CLI path. `read_camera_manifest_tool` and `write_camera_manifest_tool` only |

---

## Related skills

| Skill                          | Relationship                                                      |
|--------------------------------|-------------------------------------------------------------------|
| `/camera-interface`            | Owns the MCP-to-code mapping and the use-case encoding guidance   |
| `/post-recording`              | Downstream: verification after recording sessions                 |
| `/cli-reference`               | Reference: the `axvs` commands equivalent to these tools          |
| `/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

```text
Camera Setup, tool-settled (call `check_runtime_requirements_tool` and `list_cameras_tool`):
- [ ] Verified runtime requirements (FFMPEG, GPU, CTI) via check_runtime_requirements_tool
- [ ] Discovered cameras and recorded indices via list_cameras_tool

Camera Setup, reader-judged:
- [ ] Configured CTI file if Harvesters cameras are needed
- [ ] Tested camera with interactive video session
- [ ] Verified recording produces valid MP4 output
- [ ] Configured GenICam nodes if using Harvesters cameras (optional)
- [ ] Every tool return checked for an `Error:` prefix or an `error` key before treating it as success
- [ ] Session stopped and handed to /post-recording for output verification
- [ ] /camera-interface invoked for the parameter mapping, if transitioning from MCP to code
```