visualization

name	visualization
description	Launches and manages cindra GUI viewers for visual inspection of processing results, queries live viewer display state, and guides users through viewer interactions. Covers ROI, tracking, and registration viewers via the cindra-gui MCP server. Use when the user asks to visualize results, inspect ROIs, review registration quality, examine tracking, launch a viewer, or when a processing workflow completes and visual inspection is needed.
user-invocable	true

Visualization

Launches, manages, and assists with cindra GUI viewers for visual inspection of pipeline results.

---

Scope

Covers:

• Launching ROI, tracking, and registration viewers via cindra-gui MCP tools
• Managing viewer lifecycle (listing active viewers, closing viewers)
• Querying and interpreting live viewer display state
• Guiding users through viewer controls and interaction patterns
• Viewer prerequisites and data requirements
• Combining GUI viewer state with headless query tools for data-driven assistance
• Curating cell/non-cell labels in the ROI viewer and exporting them as a classifier training dataset

Does not cover:

• Processing workflow orchestration (see /single-recording-processing, /multi-recording-processing)
• Output data formats, array shapes, or file references (see /single-recording-results, /multi-recording-results)
• Configuration parameters or tuning guidance (see /single-recording-configuration, /multi-recording-configuration)
• MCP server connectivity or environment issues (see /cindra-mcp-environment-setup)

Handoff rules: If the user asks about processing status or batch jobs, invoke /single-recording-processing or /multi-recording-processing. If the user asks about output file formats or data interpretation without a viewer, invoke /single-recording-results or /multi-recording-results.

---

Agent requirements

You MUST use the cindra-gui MCP tools for all viewer operations. Do not launch viewer windows via CLI commands, scripts, or Python imports. If cindra-gui MCP tools are not available, invoke /cindra-mcp-environment-setup to diagnose and resolve connectivity issues.

When assisting the user with data interpretation in a viewer, combine query_viewer_state_tool from the cindra-gui MCP server with the headless query tools from the cindra MCP server. The GUI tools manage the viewer window, and the headless query tools provide the underlying data.

---

Available tools

Viewer lifecycle tools (cindra-gui MCP server)

Tool	Purpose
launch_viewer_tool	Spawns a GUI viewer subprocess for the user to interact with
list_viewers_tool	Lists active viewers with type, output root, alive status, and active dataset
close_viewer_tool	Terminates a viewer subprocess and cleans up state files
query_viewer_state_tool	Returns the live display state of an active viewer

Headless query tools (cindra MCP server)

Use these headless query tools alongside viewer state to provide data-driven assistance. These tools are documented in detail by /single-recording-results and /multi-recording-results. The get_recording_status_tool (cindra MCP server) is also used to confirm processing is complete before launching a viewer (see the launch-and-inspect workflow).

Tool	Use with viewer
query_single_recording_metadata_tool	Any viewer
query_registration_quality_tool	Registration
query_detection_summary_tool	ROI
query_roi_statistics_tool	ROI
query_traces_tool	ROI
query_multi_recording_overview_tool	ROI, Tracking
query_multi_recording_registration_quality_tool	Tracking
query_multi_recording_tracking_summary_tool	Tracking
query_cross_recording_traces_tool	ROI (multi-recording)

---

Viewer types

All three viewers load the recording's combined dataset (combined_metadata.npz) on startup, so the single-recording combination phase must have succeeded for the target recording before any viewer is launched.

Every viewer takes one path, output_root, which is the recording's pipeline output root and therefore the parent of its cindra directory. It is the same value get_recording_status_tool and every results query tool take, and launch_viewer_tool and list_viewers_tool both report it back under that name.

ROI viewer

Inspects ROI masks and fluorescence traces from single-recording or multi-recording data.

Launch:

launch_viewer_tool(viewer_type="roi", output_root="<path>")
launch_viewer_tool(viewer_type="roi", output_root="<path>", dataset="<name>")

Prerequisites:

• For multi-recording mode, multi-recording processing must be complete for the specified dataset

Parameters:

• output_root: Absolute path to the recording's pipeline output root, the parent of its cindra/ directory
• dataset: Optional multi-recording dataset name, which enables tracked ROI mode when provided

Capabilities:

• View ROI spatial masks overlaid on detection images (mean, enhanced mean, correlation map, maximum projection, corrected structural)
• Color ROIs by statistics (random, skewness, compactness, footprint, aspect ratio, solidity, colocalization probability, recording count, cell probability, correlations, classification)
• Inspect fluorescence traces (raw, neuropil, corrected, spikes) for selected ROIs
• Toggle channel 2 overlay for dual-channel recordings
• Reclassify ROIs by toggling cell/non-cell labels in classify mode, which never rewrites the recording's cell_classification.npy
• Export the flipped labels as a classifier training dataset through the Classifier panel, which the Classifier curation workflow covers
• Adjust opacity and colormap
• View multi-recording tracked ROIs across datasets

Tracking viewer

Inspects multi-recording ROI tracking quality across recordings within a dataset.

Launch:

launch_viewer_tool(viewer_type="tracking", output_root="<path>", dataset="<name>")

Prerequisites:

• Multi-recording processing must be complete for the specified dataset

Parameters:

• output_root: Absolute path to the output root of any recording in the multi-recording dataset
• dataset: Multi-recording dataset name (defaults to first available if omitted)

Capabilities:

• Cycle through recordings to compare ROI positions across sessions
• Switch between native and transformed coordinate spaces
• View original, deformed, template, and tracked mask layers
• Toggle channel 2 overlay for dual-channel recordings
• Auto-cycle through recordings at 500 ms intervals
• Select individual ROIs to inspect tracking consistency

Registration viewer

Inspects motion correction (registration) quality for a single recording. Launches two windows: a binary player for frame-by-frame playback and a PC viewer for principal component metrics.

Launch:

launch_viewer_tool(viewer_type="registration", output_root="<path>")

Parameters:

• output_root: Absolute path to the recording's pipeline output root, the parent of its cindra/ directory
• dataset: Ignored, because the registration viewer reads a single recording's own registration output

Capabilities:

• Binary player: Play back registered frames at 5x speed, step through frames with arrow keys, toggle channel 2 overlay
• PC viewer: Animate principal component extreme images per plane, cycle through PCs to identify residual motion artifacts

---

Viewer state reference

Use query_viewer_state_tool to read the live display state of any active viewer. The returned dictionary structure depends on the viewer type.

ROI viewer state

Field	Type	Description
viewer_type	str	Always "roi"
loaded	bool	Whether recording data has finished loading
channel_2_active	bool	Whether channel 2 overlay is toggled on
background_view	str	Active background image (see Background views)
roi_color_mode	str	Active ROI coloring statistic (see ROI color modes)
colormap	str	Active colormap name
selected_roi_indices	list[int]	Indices of currently selected ROIs
primary_roi_index	int|null	Focused ROI whose stats fill the info bar, or null
opacity	int	ROI overlay opacity (slider value)
classify_mode	bool	Whether classify mode is on (clicks flip labels)
trace_visibility	dict	Visibility flags for each trace type (see below)
temporal_bin_size	int	Temporal binning window for correlation computation
colocalization_threshold	float	Colocalization threshold. Always the 0.6 default
roi_count	int	Total number of ROIs in the recording
frame_count	int	Frames in the visualized traces
two_channels	bool	Whether the recording has two functional channels
all_recordings_visible	bool	Whether the stacked all-recordings trace view is on
roi_source	str	Current ROI source dropdown text

trace_visibility sub-fields:

Field	Type	Description
fluorescence	bool	Raw cell fluorescence trace visible
neuropil	bool	Neuropil fluorescence trace visible
corrected	bool	Neuropil-subtracted corrected trace visible
spikes	bool	Deconvolved spike estimate trace visible

Tracking viewer state

Field	Type	Description
viewer_type	str	Always "tracking"
loaded	bool	Whether multi-recording data has finished loading
active_dataset	str	Active multi-recording dataset name
available_datasets	list[str]	List of available dataset names
current_recording_index	int	Index of the currently displayed recording
current_recording_id	str	Identifier of the currently displayed recording
recording_count	int	Total number of recordings in the dataset
background_view	str	Active background image (see Background views)
coordinate_space	str	Active coordinate space ("native" or "transformed")
mask_layer	str	Active mask layer (see Mask layers)
channel_2_active	bool	Whether channel 2 overlay is toggled on
opacity	int	ROI overlay opacity (slider value)
selected_roi_indices	list[int]|null	Selected ROI indices, or null when all are visible
last_clicked_roi_index	int|null	Index of the most recently clicked ROI, or null
mask_count	int	Number of masks in the active layer
auto_cycling	bool	Whether auto-recording cycling is active

Registration viewer state

Returns a nested dictionary with two sub-viewers:

Field	Type	Description
viewer_type	str	Always "registration"
binary_player	dict	Binary player state (see below)
pc_viewer	dict	PC viewer state (see below)

binary_player sub-fields:

Field	Type	Description
current_frame	int	Currently displayed frame index
frame_count	int	Total frames available for playback
channel_2_active	bool	Whether channel 2 is displayed
two_channels	bool	Whether the recording has two channels
playing	bool	Whether playback is active
frame_step	int	Frame step size for navigation (default 100)

pc_viewer sub-fields:

Field	Type	Description
current_plane	int	Currently displayed plane index
current_plane_label	str	Human-readable label of the displayed plane
plane_count	int	Total number of imaging planes
current_pc	int	Currently displayed principal component number
pc_count	int	Total number of principal components
playing	bool	Whether PC extreme animation is active
loaded	bool	Whether PC data has finished loading

---

Enum value reference

Enum-valued state fields report a lowercase value whose on-screen dropdown label can differ from the title-cased form. Read the exact label from the Dropdown label column in viewer-enums.md, which holds the full value lists for background_view, roi_color_mode, mask_layer, and coordinate_space.

---

Visualization workflows

Launch and inspect workflow

1. Check prerequisites. Verify processing is complete for the recording with get_recording_status_tool from the cindra MCP server, and require single_recording.status to equal completed. The values binarizing, registering, processing, and combining report a run that is still in flight, and not_started, scheduled, and failed report a recording with no viewable output.

   For viewer_type="tracking", and for a roi launch that passes dataset, also require the multi_recording section of the same response to report that dataset complete, or verify_multi_recording_output_tool to return complete: true. launch_viewer_tool validates only that the path is an existing directory and discards the subprocess output, so a viewer over a dataset that never ran still reports a live viewer_id and only fails later inside the query tools. Invoke /multi-recording-processing when the dataset is incomplete.

2. Launch viewer. Call launch_viewer_tool with the appropriate viewer_type, output_root, and optional dataset. Store the returned viewer_id.

3. Wait for loading. Query state with query_viewer_state_tool until loaded is true. The viewer subprocess needs time to read data from disk. The registration viewer reports its readiness through pc_viewer.loaded, so poll that field, or treat the presence of the binary_player and pc_viewer sub-states as the loaded signal. If loaded remains false after 10-15 seconds, check for errors by verifying the viewer is still alive via list_viewers_tool.

4. Assist the user. Respond to user questions by combining viewer state with headless query tools. For example, if the user asks about a specific ROI, query its statistics via query_roi_statistics_tool while referencing the viewer state to understand what the user is currently seeing.

Classifier curation workflow

Produces the custom classifier training dataset that the main.custom_classifier_path configuration parameter consumes. The ROI viewer's Classifier panel is the only interface that writes this file.

1. Launch the ROI viewer over a recording whose single-recording processing completed, omitting dataset. Both builder buttons return without acting in tracked ROI mode.

2. Enable Classify. Toggling the Classify button makes a click flip the clicked ROI's label instead of selecting it for trace plotting.

3. Correct the labels. Ask the user to flip every ROI the built-in classifier judged wrongly. The flips stay in the viewer session, so query_roi_statistics_tool keeps reporting the on-disk labels while the viewer shows the flipped ones.

4. Export. New writes the labels and their three features to a .npz chosen through a save dialog. Add to Existing concatenates them onto a dataset chosen through an open dialog and writes the merged result. Neither button refits the classifier, so the exported file holds training data alone.

5. Accumulate to the sample floor. The classifier fits a 100-node probability grid and rejects a dataset holding fewer than 100 samples when it loads one. A recording carrying fewer ROIs than that reaches a usable file only after Add to Existing merges it with others.

6. Hand off. Supply the finished file to the pipeline through main.custom_classifier_path, which /single-recording-configuration owns.

State-driven assistance workflow

When the user asks questions about what they see in a viewer:

1. Query viewer state. Call query_viewer_state_tool to understand the current display configuration (which background, which color mode, which ROIs are selected).

2. Query underlying data. Use the appropriate headless query tool to retrieve the actual data values. For example:

   • User sees colored ROIs → query roi_color_mode from state, then use query_roi_statistics_tool to get the statistic values
   • User asks about a trace → check trace_visibility and selected_roi_indices from state, then use query_traces_tool for the actual trace data
   • User asks about registration quality → check binary_player.current_frame from state, then use query_registration_quality_tool for offset statistics

3. Explain in context. Combine the viewer state with the queried data to give the user a contextual answer about what they are seeing.

Runtime state awareness

Viewers are interactive, so the user can switch datasets, change display settings, and navigate recordings at any time via the GUI controls. The launch-time parameters passed to launch_viewer_tool may not reflect the current viewer state.

Always re-query before answering. Before responding to any user question about a viewer, call query_viewer_state_tool to read the live display state. Do not rely on cached state from previous queries or launch-time parameters.

Allow for write latency. The viewer writes its state at most every 250 ms, and only when it changes. After prompting the user to change a setting, allow a brief moment or re-query once before trusting the result, since a query issued immediately after the change may still return the prior state.

Dataset tracking. Both list_viewers_tool and query_viewer_state_tool report the active_dataset field, which reflects the dataset currently displayed by the viewer. This may differ from the dataset parameter provided at launch if the user switched datasets via the viewer's dropdown controls. Use active_dataset (not dataset) when determining what the viewer is currently showing.

Multi-viewer workflow

Multiple viewers can run simultaneously for the same or different recordings. Each viewer gets a unique viewer_id. Use list_viewers_tool to track all active instances.

Common multi-viewer patterns:

• Registration viewer + ROI viewer for the same recording (verify registration then inspect ROIs)
• ROI viewers for different recordings in a multi-recording dataset (compare across sessions)
• Tracking viewer + ROI viewer for the same dataset (verify tracking then inspect ROI traces)

---

User assistance guide

ROI viewer assistance

"What am I looking at?". Query viewer state. Report the background view, ROI color mode, number of ROIs, whether classify mode is active, and which traces are visible.

"Are these good ROIs?". Query roi_color_mode from state. If it is not cell_classification or cell_probability, suggest switching to one of those color modes to see classifier output. Both are hidden when active_dataset is non-null, because the multi-recording tracked-ROI view carries no classifier output, so fall back to query_roi_statistics_tool alone there. Use query_roi_statistics_tool to retrieve compactness, solidity, and skewness statistics for the visible ROIs. Explain what each statistic means:

• Compactness near 1.0 indicates circular footprints (typical neurons)
• Solidity near 1.0 indicates filled footprints without holes
• Skewness > 0 indicates right-skewed fluorescence (active cells tend to have positive skew)

"Show me the most active cells". Suggest coloring by skewness (high skewness correlates with activity) or by cell_probability to see classifier confidence (unavailable in multi-recording tracked-ROI mode). Use query_roi_statistics_tool sorted by skewness descending to identify the top ROIs.

"What do the traces look like?". Check trace_visibility and selected_roi_indices from state. If no ROIs are selected, tell the user they can select one by clicking it in the image panel or by typing its index into the ROI index field (the "Enter an ROI index to select it" box). Use query_traces_tool for the selected ROI indices to provide quantitative trace information.

"Select or highlight a specific ROI (e.g. ROI 20)?". These tools observe only and cannot drive the viewer, so ask the user to type the index into the ROI index field. ROI indices are 0-based and match selected_roi_indices / primary_roi_index in the state, so resolve any "cell N" wording to a 0-based index against roi_count before instructing. Confirm by re-querying state and checking that primary_roi_index matches.

Tracking viewer assistance

"Is the tracking good?". Query tracking viewer state to see the current mask_layer and coordinate_space. Suggest cycling through mask layers (original → deformed → template → tracked) to verify spatial consistency. Use query_multi_recording_tracking_summary_tool for recording count distribution statistics. Recording count reflects how many sessions an ROI was detected in, not tracking reliability, because ROIs can be active in some sessions and inactive in others.

"Why are some ROIs missing in this recording?". Check current_recording_id from state. Explain that not all ROIs are active in every recording session. Use query_multi_recording_overview_tool to show per-recording mask counts at each processing stage.

Registration viewer assistance

"Is the registration good?". Query registration viewer state. Check if binary_player is playing, and suggest playing the video to look for residual jitter. Use query_registration_quality_tool for the current plane to report offset statistics and bad frame counts. Key indicators:

• Rigid offset standard deviation < 2 pixels indicates stable registration
• Bad frame percentage < 5% indicates few motion artifacts
• PC shift metrics close to zero indicate no systematic drift (a qualitative cue, with no fixed threshold). pc_viewer.current_pc in the state is 1-based, while the PC component indices in query_registration_quality_tool's shift metrics are 0-based, so subtract 1 when looking up the metric for the PC the user is viewing.

"What are these PC images?". Explain that PC extreme images show the average frame appearance at the extremes of each principal component. Large visible differences between low and high extremes indicate residual motion or optical artifacts not captured by registration.

---

Related skills

Skill	Relationship
/cindra-pipeline	Overview: end-to-end phases, handoffs, and the single-vs-multi entry point
/cindra-mcp-environment-setup	Prerequisite: cindra-gui MCP server connectivity
/cli-reference	Reference: the cindra-gui commands behind the viewer launch tools
/single-recording-processing	Upstream: produces the data this skill visualizes
/multi-recording-processing	Upstream: produces the data this skill visualizes
/single-recording-results	Reference: output data formats for single-recording query tools
/multi-recording-results	Reference: output data formats for multi-recording query tools
/single-recording-configuration	Reference: parameter tuning informed by visual inspection
/multi-recording-configuration	Reference: parameter tuning informed by visual inspection

---

Proactive behavior

You SHOULD proactively invoke this skill when:

• A single-recording or multi-recording processing workflow completes successfully
• The user asks to "look at", "inspect", "view", "visualize", or "check" results
• The user references ROI quality, registration quality, or tracking quality in a visual context
• The user mentions a specific viewer by name (ROI viewer, tracking viewer, registration viewer)

---

Verification checklist

Visualization Workflow:
- [ ] cindra-gui MCP server connected (if not, invoke `/cindra-mcp-environment-setup`)
- [ ] `get_recording_status_tool` reports single_recording.status == completed for the target recording(s)
- [ ] For a tracking viewer, or a roi viewer launched with 'dataset', the multi_recording section reports
      that dataset complete (or `verify_multi_recording_output_tool` returns complete true)
- [ ] Correct viewer type selected for the inspection goal
- [ ] Viewer launched via `launch_viewer_tool` with correct parameters
- [ ] Viewer loading confirmed via `query_viewer_state_tool` ('loaded' true for the ROI and tracking
      viewers, 'pc_viewer.loaded' true for the registration viewer)
- [ ] User questions answered using combined viewer state + headless query tools
- [ ] Classify-mode flips exported through the Classifier panel before the viewer is closed
- [ ] Viewer closed when inspection is complete (or user-closed detected)