# kuva

**kuva** is a scientific plotting library for Rust that renders plots to SVG. It targets bioinformatics use cases and ships with 60 plot types — from standard scatter and bar charts to Manhattan plots, UpSet plots, phylogenetic trees, and synteny diagrams. A `kuva` CLI binary lets you render plots directly from the shell without writing any Rust.

## Design

The API follows a builder pattern. Every plot type is constructed with `::new()`, configured with method chaining, and rendered through a single pipeline:

```
plot struct  →  Plot enum  →  Layout  →  SVG / PNG / PDF
```

## Quick start

```rust,no_run
use kuva::prelude::*;

let data = vec![(1.0_f64, 2.0_f64), (3.0, 5.0), (5.0, 4.0)];

let plot = ScatterPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_size(5.0);

let plots: Vec<Plot> = vec![plot.into()];
let layout = Layout::auto_from_plots(&plots)
    .with_title("My Plot")
    .with_x_label("X")
    .with_y_label("Y");

let svg = render_to_svg(plots, layout);
std::fs::write("my_plot.svg", svg).unwrap();
```

## Prelude

`use kuva::prelude::*` brings all 60 plot structs, `Plot`, `Layout`, `Figure`, `Theme`, `Palette`, `render_to_svg`, and everything else you typically need into scope in one line.

Every plot struct implements `Into<Plot>`, so you can write `plot.into()` instead of `Plot::Scatter(plot)`.

For PNG or PDF output, use `render_to_png` and `render_to_pdf` (require feature flags `png` and `pdf` respectively):

```rust,no_run
use kuva::prelude::*;

let plots: Vec<Plot> = vec![/* ... */];
let layout = Layout::auto_from_plots(&plots);

// SVG — always available
let svg: String = render_to_svg(plots, layout);

// PNG — feature = "png"
let png: Vec<u8> = render_to_png(plots, layout, 2.0).unwrap();

// PDF — feature = "pdf"
let pdf: Vec<u8> = render_to_pdf(plots, layout).unwrap();
```

## Regenerating documentation assets

The SVG images embedded in these docs are generated by standalone example programs in the `examples/` directory. Regenerate all assets at once with:

```bash
bash scripts/gen_docs.sh
```

Or regenerate a single plot type:

```bash
cargo run --example scatter
cargo run --example histogram
# etc. — one example per plot type in examples/
```

## Building the book

Install [mdBook](https://rust-lang.github.io/mdBook/), then:

```bash
mdbook build docs    # produce docs/book/
mdbook serve docs    # live-reload preview at http://localhost:3000
```
