Metadata-Version: 2.4
Name: vcds-plotter
Version: 0.3.0
Summary: Plot VCDS CSV data with Matplotlib – a small, testable CLI tool.
Author-email: Supporterino <lars@roth-kl.de>
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pandas>=2.0
Requires-Dist: matplotlib>=3.8

# VCDS‑Plotter

> **Visualise raw CSV logs from a Volkswagen Car‑Diagnostic System (VCDS) with a single command.**

`vcds-plotter` is a lightweight Python package that turns the raw CSV files produced by VCDS into clear, multi‑series plots.  
It is intentionally simple: no GUI, no heavy dependencies – just `matplotlib` and the standard library.

> *If you’re a developer or power‑user, checkout the [contributing guide](CONTRIBUTING.md) – the code is small and welcoming.*

---

## 📖 Table of Contents

| Section | Description |
|---------|-------------|
| [Features](#features) | What the tool can do |
| [Installation](#installation) | How to get it running |
| [Configuration](#configuration) | Where VCDS logs are expected |
| [Usage](#usage) | Quick start and advanced options |
| [Examples](#examples) | Real‑world command snippets |
| [Troubleshooting](#troubleshooting) | Common issues & fixes |
| [Development](#development) | Build, test, lint |
| [Contributing](#contributing) | How to help |
| [License](#license) | Legal stuff |

---

## ✨ Features

* **Fast, zero‑config plotting** – a single command shows the newest log or a file you pick.
* **Fine‑grained metric selection** – include / exclude specific measurements.
* **Custom groups** – plot a subset of metrics in their own figure with a title you choose.
* **Unit‑based grouping** – automatically split metrics by unit (e.g., `km/h`, `%`) into separate figures.
* **Convenience helpers** – list all available metrics or CSV files with a flag.

---

## 📦 Installation

```bash
# From PyPI (recommended)
pip install vcds-plotter
```

> The console script is installed as `vcds‑plot`.  
> See the help output for all options:

```bash
vcds-plot --help
```

### From source

If you want to tweak the code or run tests:

```bash
git clone https://github.com/yourorg/vcds-plotter.git
cd vcds-plotter

# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate   # Windows: .\.venv\Scripts\activate

# Install dev dependencies
pip install -e ".[dev]"
```

---

## ⚙️ Configuration

The package expects VCDS logs to live in a directory called `logs/` relative to the current working directory.  
You can change this by editing the `LOGS_DIR` constant in `vcds_plotter/config.py` or, if you prefer, set the environment variable `VCDS_LOGS_DIR` before running.

```python
# vcds_plotter/config.py
LOGS_DIR = Path(os.getenv("VCDS_LOGS_DIR", "logs")).resolve()
```

---

## 🚀 Usage

### 1️⃣ Basic plot – newest file, grouped by unit

```bash
vcds-plot --group-by-unit
```

### 2️⃣ Select specific metrics

```bash
vcds-plot --metric Motordrehzahl,Temperatur --exclude SensorX
```

* `--metric` – comma‑separated list of measurements to *include*.
* `--exclude` – measurements to skip (useful for noisy sensors).

### 3️⃣ Custom groups

```bash
vcds-plot --group "Engine & temp=Motordrehzahl,Temperatur"
```

* `--group` accepts one or more `NAME=METRICS` pairs.  
  Each group gets its own figure titled with `NAME`.

### 4️⃣ Explicit file

```bash
vcds-plot --file /path/to/log_2023-09-12.csv
```

### 5️⃣ Listing helpers

```bash
# List all CSV files in the logs directory
vcds-plot --list-files

# Show every measurement name available in a file
vcds-plot --list-metrics --file /path/to/file.csv
```

---

## 🛠️ Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `No CSV file found in logs/` | The `logs/` directory is missing or empty. | Create the folder and copy VCDS logs into it, or set `VCDS_LOGS_DIR`. |
| `No metrics left after applying filters.` | The filter lists are empty or exclude all available metrics. | Double‑check the metric names (case‑sensitive) and try without `--exclude`. |
| Plot window freezes | Very large CSV file or too many metrics. | Use `--exclude` to trim, or plot in groups (`--group-by-unit`). |
| Matplotlib errors | Outdated `matplotlib` or missing backend. | Upgrade: `pip install --upgrade matplotlib`. |

---

## 🤝 Contributing

We welcome issues, pull requests, and suggestions!  
Please read the [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to set up a dev environment, run tests, and follow our coding style.

---

## 📄 License

MIT © Supporterino  
See the [LICENSE](LICENSE) file for details.

---

Happy plotting! 🚗💨
