Metadata-Version: 2.4
Name: rivia
Version: 0.2.0
Summary: A modern Python interface for HEC-RAS Visualization, Information, and Automation
Author: Gyan Basyal, WEST Consultants, Inc.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gyanz/rivia
Project-URL: Repository, https://github.com/gyanz/rivia
Project-URL: Issues, https://github.com/gyanz/rivia/issues
Keywords: hec-ras,hydraulics,hydrology,modeling,water-resources
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: h5py
Requires-Dist: pywin32; sys_platform == "win32"
Requires-Dist: psutil; sys_platform == "win32"
Requires-Dist: pydantic>=2
Provides-Extra: geo
Requires-Dist: geopandas; extra == "geo"
Requires-Dist: rasterio; extra == "geo"
Requires-Dist: matplotlib; extra == "geo"
Requires-Dist: numba; extra == "geo"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

# RIVIA

**RAS Interface for Visualization, Information, and Automation**

A modern, modular Python library for interacting with [HEC-RAS](https://www.hec.usace.army.mil/software/hec-ras/) hydraulic modeling software.

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey.svg)](https://www.hec.usace.army.mil/software/hec-ras/)
[![Documentation](https://readthedocs.org/projects/rivia/badge/?version=latest)](https://rivia.readthedocs.io/en/latest/)
[![PyPI](https://img.shields.io/pypi/v/rivia.svg)](https://pypi.org/project/rivia/)

## Documentation

Full documentation is available at [rivia.readthedocs.io](https://rivia.readthedocs.io).

## Overview

`rivia` provides a clean, Pythonic interface for working with HEC-RAS projects:

- **Control HEC-RAS** via COM automation — open projects, switch plans, run simulations
- **Read and write** HEC-RAS text input files (`.prj`, `.g*`, `.p*`, `.f*`, `.u*`)
- **Access HDF5 results** — water surface, velocity, depth, and other outputs
- **Export rasters** — pixel-perfect RASMapper-equivalent rasters (WSE, depth, velocity, etc.)
- **Export terrain** — mosaic and modify terrain from HEC-RAS terrain HDF files

## Requirements

- **Windows** — HEC-RAS is Windows-only
- Python 3.10+
- HEC-RAS 5.x or later installed

## Installation

```bash
pip install rivia
```

With geospatial extras (required for raster export):

```bash
pip install rivia[geo]
```

## Quick Example

```python
from rivia.model import Project

# Open a HEC-RAS project
model = Project("path/to/project.prj")
print(model.version)       # e.g. "6.30"

# Switch plans
model.set_plan(title="Base Condition")
model.set_plan(short_id="BC")
model.set_plan(index=0)

# Run model
model.run(hide_window=False)

# Read HDF results
area = model.results.flow_areas["Perimeter 1"]
wse_max = area.max_water_surface

# Export a WSE raster
vrt = model.export_wse(timestep=None, render_mode="sloping")
print(vrt.path)
```

## Package Structure

```
rivia/
├── controller/  # COM interface to run/control HEC-RAS
├── model/       # Project — primary project interface; read/write text input files, read HDF results
├── hdf/         # Read HEC-RAS HDF5 geometry and result files
├── geo/         # Geospatial operations: raster export (geopandas/rasterio)
└── utils/       # Shared helpers
```

## Development

```bash
git clone https://github.com/gyanz/rivia.git
cd rivia
pip install -e ".[dev,geo,docs]"

# Run tests
pytest tests/ -x --tb=short

# Lint
ruff check src/

# Type check
mypy src/rivia

# Build docs
sphinx-build -b html docs docs/_build/html
```

## License

Copyright 2025 Gyan Basyal and WEST Consultants, Inc.

Licensed under the [Apache License, Version 2.0](LICENSE).
