# Matplotlib Visualization Configuration

Use `vipr.visualization` in YAML to control matplotlib output globally and per diagram.

## Scope

The configuration is used for:
- Tier-1 auto-generated diagram images (`*_plot.svg/png/pdf`) (automatic)
- Tier-2 images (`dc.image(...).set_from_matplotlib(...)`) only when plugin code explicitly resolves and applies style
  (for example via `resolve_plot_style(app, plot_id)`, `style.apply_figure(fig)`, and `**style.to_export_kwargs()`)

## YAML Schema

```yaml
vipr:
  visualization:
    plot_style:                    # global defaults
      export:
        format: svg                # svg | png | pdf
        dpi: 180                   # 72..600
      figure:
        figsize: [11.0, 6.5]       # inches
      rc:
        font.size: 11
        axes.labelsize: 11
        axes.titlesize: 13
        xtick.labelsize: 10
        ytick.labelsize: 10

    diagrams:                      # per-diagram overrides
      reflectivity_matplotlib:
        export:
          format: png
          dpi: 300
        figure:
          figsize: [14.0, 8.0]
```

## Merge Rules

For a given `diagram_id`, VIPR resolves style in this order:
1. Built-in defaults
2. `vipr.visualization.plot_style`
3. `vipr.visualization.diagrams.<diagram_id>`

Only explicitly set keys in `diagrams.<diagram_id>` override global values.

## `diagram_id` vs Filename

Configuration uses the internal `diagram_id`, not the generated filename.

Example:
- `diagram_id`: `mode_2_sld_profile`
- generated file: `mode_2_sld_profile_plot.svg`

Set config like:

```yaml
vipr:
  visualization:
    diagrams:
      mode_2_sld_profile:
        export:
          format: svg
          dpi: 300
        figure:
          figsize: [14.0, 8.0]
```

## Typical IDs (Reflectometry)

- `reflectivity_matplotlib`
- `reflectivity_primary`
- `sld_profile`
- `residuals_vs_q`
- `mode_1_sld_profile`, `mode_2_sld_profile`, ...
- `marginals_mode_1`, `marginals_mode_2`, ...

## Notes

- `dpi` has limited effect for pure SVG/PDF vectors.
- The web UI inline preview expects browser-displayable image formats; use PDF mainly for file/CLI exports.
- In batch runs, filenames may be prefixed (`item0_...`), but `diagram_id` stays unchanged.

## Example: Export all plots as PDF (CLI use)

Add the `visualization` block to your VIPR config file:

```yaml
vipr:
  visualization:
    plot_style:
      export:
        format: pdf
```

All diagrams will be saved as `*.pdf` inside the `images/` result directory.

To export only a specific diagram as PDF while keeping others as SVG:

```yaml
vipr:
  visualization:
    plot_style:
      export:
        format: svg
    diagrams:
      reflectivity_matplotlib:
        export:
          format: pdf
```
