# River Outfall Status Visualizer

> Analyze river outfall Excel workbooks and build report-ready river outfall status visualizations that compare current, normal, 20-year, and 50-year water levels, distinguish left-bank and right-bank outfalls, and identify which outfalls are safe, partially submerged, or fully submerged. Use when Codex needs to turn a river longitudinal-profile or outfall inventory workbook into a briefing chart,…

- **Type:** Skill
- **Install:** `agentstack add skill-tiangong-ai-agent-skills-river-outfall-status-visualizer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tiangong-ai](https://agentstack.voostack.com/s/tiangong-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tiangong-ai](https://github.com/tiangong-ai)
- **Source:** https://github.com/tiangong-ai/agent-skills/tree/main/river-outfall-status-visualizer

## Install

```sh
agentstack add skill-tiangong-ai-agent-skills-river-outfall-status-visualizer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# River Outfall Status Visualizer

## Core Goal

- Convert one Excel workbook into:
- A scenario-aware river outfall status summary.
- A standalone HTML chart suitable for briefing and review.
- A reusable mock workbook that follows the same template.
- Keep the chart vertically truthful. `Y` values must always use real elevation.
- Allow horizontal zoom without resizing outfall symbols. Only the outfall anchor positions move with the river layout.
- Distinguish left-bank and right-bank outfalls with side-specific offset, connector direction, label placement, and legend.

## Required Inputs

- Start from a `.xlsx` workbook.
- Prefer the mixed single-sheet format documented in [references/data-schema.md](references/data-schema.md):
- Outfall rows carry code, size, base elevation, mileage, bank side, and scenario water levels.
- Control-node rows carry reach or gate names, mileage, scenario water levels, and optionally `河底高程` / `堤顶高程`.
- If `当前水位` is missing, ask for it or state clearly that the output only supports the available scenarios.
- If the workbook lacks riverbed or channel-bottom data, describe the output as a river outfall status chart, not a true riverbed longitudinal profile.

## Quick Start

1. Generate a directly usable input template:

```bash
python3 scripts/generate_input_template_excel.py \
  --output assets/templates/river-outfall-input-template.xlsx
```

2. Generate or inspect a mock workbook:

```bash
python3 scripts/generate_mock_example_excel.py \
  --output assets/examples/example-river-sample.xlsx
```

3. Compute scenario summaries:

```bash
python3 scripts/calc_submergence.py \
  --input assets/examples/example-river-sample.xlsx \
  --pretty
```

4. Render a standalone HTML report:

```bash
python3 scripts/render_status_report.py \
  --input assets/examples/example-river-sample.xlsx \
  --output assets/examples/example-river-sample-report.html
```

## Workflow

1. Read [references/data-schema.md](references/data-schema.md) before touching the workbook schema.
2. Read [references/status-rules.md](references/status-rules.md) before changing status logic.
3. Read [references/visual-spec.md](references/visual-spec.md) before changing the chart layout or legend.
4. Use `scripts/calc_submergence.py` first when the request is analytical.
5. Use `scripts/render_status_report.py` when the request needs a deliverable chart.
6. Use `scripts/generate_mock_example_excel.py` to create a regression fixture or explain the expected workbook shape.
7. Use `scripts/generate_input_template_excel.py` when the user needs a blank workbook they can fill directly in Excel.
8. Report validation warnings explicitly. Do not silently coerce missing elevations, missing sizes, or ambiguous bank-side values.

## Visual Rules

- Keep `Y` coordinates in true elevation. Do not vertically exaggerate.
- Use mileage for ordering and anchor positioning.
- Keep the page free of browser-level horizontal scrolling. Use wheel zoom in the chart plus the timeline overview for navigation.
- Allow horizontal zoom or compression for layout, but keep outfall symbol widths fixed during zoom.
- Anchor each outfall at its true mileage and base elevation.
- When `河底高程` is present, draw a brown riverbed step profile and fill the active scenario water body above it with blue.
- When `堤顶高程` is present, draw the levee crest as a separate contextual step profile.
- Draw the outfall crown from true geometry height when size data is available.
- Use shape to distinguish geometry type:
- Rectangle for box culverts or rectangular outfalls.
- Circle for circular pipes. Do not flatten circular pipes into ellipses.
- Use bank-side offset to distinguish left-bank and right-bank outfalls:
- Left-bank outfalls offset to the left of the river axis.
- Right-bank outfalls offset to the right of the river axis.
- Reinforce bank side with connector direction, label placement, and legend text.
- Use status as the dominant semantic encoding:
- `未受淹`
- `部分受淹`
- `完全淹没`
- Make the selected scenario visually dominant and keep non-selected scenarios visible but weaker.
- Prefer code plus size on the chart. Keep full outfall names in the detail table when the chart is dense enough that names would harm readability.

## Scripts

- `scripts/generate_mock_example_excel.py`
- Create an anonymized example workbook with mixed outfall and control-node rows.
- `scripts/generate_input_template_excel.py`
- Create a multi-sheet Excel template whose first sheet can be filled directly and whose second sheet explains the fields.
- `scripts/calc_submergence.py`
- Read a workbook, normalize the rows, compute scenario statuses, and print or export a summary.
- `scripts/render_status_report.py`
- Generate a standalone HTML report with scenario switching and horizontal zoom.
- `scripts/river_outfall_status_lib.py`
- Shared parser, validator, geometry, summary, and `.xlsx` read/write helpers.

## References

- [references/data-schema.md](references/data-schema.md)
- Workbook shape, column aliases, and row classification rules.
- [references/status-rules.md](references/status-rules.md)
- Water-level interpretation, crown inference, and tri-state status logic.
- [references/visual-spec.md](references/visual-spec.md)
- Chart semantics, left/right bank encoding, and layout constraints.

## Output Checklist

- State which scenarios were actually present in the source workbook.
- Report total outfall count and counts by status for the highlighted scenario.
- List fully submerged outfall codes explicitly.
- Call out left-bank and right-bank counts when they matter to the request.
- Mention whether `河底高程` / `堤顶高程` were present, because that determines whether the chart includes channel background context or only water lines plus outfalls.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tiangong-ai](https://github.com/tiangong-ai)
- **Source:** [tiangong-ai/agent-skills](https://github.com/tiangong-ai/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tiangong-ai-agent-skills-river-outfall-status-visualizer
- Seller: https://agentstack.voostack.com/s/tiangong-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.