add documentation

Author: jasperdewinther

README.md

@@ -8,9 +8,39 @@
 
 </div>
 
+## 📊 Available tools
+
+This repository contains multiple scripts which can be run as is for reporting purposes, or serve as a baseline/guide for custom analysis scripts. Below we list all tools, with example outputs below. We also mention which command line argument should be passed to Evolve to generate the requested graphs.
+
+- **`run_on_android.py`** Launches the Evolve benchmark on a connected Android device over ADB and pulls the result files back to your machine. This script requires ADB (Android Debug Bridge) to be installed.
+- **`compare_deep_analysis.py`** CLI tool that compares two deep-analysis exports and writes the top 20 passes with the largest mean / standard-deviation differences to CSV. Requires `--export-deep-analysis`.
+- **`scores_plotter.ipynb`** Bar chart comparing the Evolve scores per metric across benchmark runs or devices. Requires `--export-scores`.
+
+  <img src="./docs/images/tools/scores_plotter.png" width="700">
+
+- **`per_frame_plotter.ipynb`** Line graph of the per score bucketed execution time/metric (frame time, ray tracing, rasterization, compute, driver, …) throughout the benchmark timeline. Can be used to compare between runs. Requires `--export-per-frame`.
+
+  <img src="./docs/images/tools/per_frame_plotter.png" width="700">
+  <img src="./docs/images/tools/per_frame_metric.png" width="700">
+
+- **`deep_analysis_plotter.ipynb`** Line graph of the execution time per render/compute/rt pass. Can be used to compare between runs. Requires `--export-deep-analysis`.
+
+  <img src="./docs/images/tools/deep_analysis_plotter.png" width="700">
+
+- **`frame_breakdown_stackplot.ipynb`** Stacked area chart breaking down each frame's GPU time by render/compute/rt pass (top 20 passes + other). Requires `--export-deep-analysis`.
+
+  <img src="./docs/images/tools/frame_breakdown_stackplot.png" width="700">
+
+## 📏 Capturing data
+
+These scripts require specific custom Evolve outputs, which can be generated using the following command line arguments when launching evolve. 
+
+ - `run-custom --export-scores scores.csv`
+ - `run-custom --export-per-frame per_frame.csv`
+ - `run-custom --export-deep-analysis deep_analysis.json`
+
 ## 👷‍♀️ Requirements
 
 Please ensure the following dependencies are installed before running scripts from this repository:
 
-- Python 3.7
-- ADB (Android Debug Bridge)
+- Python 3.11+