From 78cec4350e2f621103a399c00778ab728f4253f0 Mon Sep 17 00:00:00 2001
From: Arne van Iterson <arne@arnweb.nl>
Date: Sat, 21 Oct 2023 13:40:21 +0200
Subject: [PATCH] README

---
 README.md                  | 86 +++++++++++++++++++++++++++++++++++++-
 src/experiments/dataset.py |  2 +-
 2 files changed, 86 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 6fb2796..5e45f15 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,90 @@
+# Tree Recogniser 7000
+
 This repository contains all files for the Image recognition course of HU Electrical Engineering year 3.
 
 ---
 
-Arne van Iterson
+### Directories and files:
+```
+.
+├── example/                                        (training assignments course)
+├── out/
+│   ├── img                                         (images exported using CVSuite)/
+│   │   └── (tag)_(preprocessor)_(date/time).png
+│   ├── log                                         (preprocessor export from CVSuite)/
+│   │   └── result_(date/time).csv
+│   └── models                                      (exported OpenCV ML models for usage in CVSuite tests)/
+│       └── model_(name).yaml
+├── res/
+│   ├── dataset                                     (dataset for CVSuite, see README)/
+│   │   ├── testing
+│   │   ├── training
+│   │   ├── validation
+│   │   └── *.png
+│   ├── essay/                                      (export photo's and graphs for report)
+│   ├── trees/                                      (initial dataset)
+│   └── *.png                                       (photos required by assignments in .example/)
+├── src/
+│   ├── config/
+│   │   └── config.json                             (CVSuite config, alter config.template.json to desired settings)
+│   ├── experiments/                                (standalone python scripts for experimentation)
+│   ├── helpers/
+│   │   ├── gui/
+│   │   │   └── main.ui                             (pygubu ui configuration)
+│   │   ├── test/                                   (ML test classes for CVSuite)
+│   │   └── *.py                                    (other CVSuite helper classes)
+│   └── suite.py                                    (CVSuite main script)
+├── README.md                                       (this file)
+└── requirements.txt                                (pip install file)
+```
+
+---
+
+### How to:
+#### Use the virtual environment
+1. Make sure you have the Python extension in VSCode
+2. Create a virtual environment using VSCode by entering the Command Palette, selecting "Python: Create Environment..." and choosing venv.
+3. VSCode will automatically include the venv in the integrated terminal, if you want to open it in another terminal, use the appropriate activation script in the `.venv` folder
+```sh
+$ ./.venv/Scripts/activate(.bat/.ps1)
+```
+4. Install required packages using pip
+```sh
+$ pip install -r ./requirements.txt
+```
+
+#### Create a dataset
+1. Rename all images to include a tag and unique id, seperated by an underscore '_'
+    - e.g. `accasia_1210262`
+2. Put all images into `./res/dataset`
+3. Run the dataset tool:
+```bash
+$ python ./src/experiments/dataset.py
+```
+
+#### Run CVSuite (for the first time)
+1. Create `config.json` in the `./src/config/` folder and copy the contents of the template
+2. Edit `config.json` to fit your system, use full paths 
+    - `path` should point to the dataset directory
+    - `models` should point to trained ML models in YAML format
+    - `out` should point to the respective folders in the `./out` folder
+    - `size` determines the display size in the suite
+3. Run CVSuite:
+```sh
+$ python ./src/suite.py
+``` 
+
+#### Train and save a KNN model
+1. Open CVSuite and select the desired training set
+2. Press 'Run analysis for entire dataset(!)', this will export a CSV file with all preprocessed data in the `./out` directory
+    - Based on your system configuration, this might take a while
+3. Run the CVSuiteTestKNN CLI tool:
+```sh
+$ python .\src\helpers\test\knn.py -i .\out\result-(date/time).csv -o .\out\models\model_knn.yaml 
+```
+4. Edit your `config.json` to include the newly created model
+
+---
+
+Arne van Iterson<br>
 Tom Selier
\ No newline at end of file
diff --git a/src/experiments/dataset.py b/src/experiments/dataset.py
index f251d85..731f812 100644
--- a/src/experiments/dataset.py
+++ b/src/experiments/dataset.py
@@ -13,7 +13,7 @@ class Tree(Enum):
     LINDE = 6
     PLATAAN = 7
 
-DIR = "dataset\\input"
+DIR = "./res/dataset"
 SEED = 10
 
 TRAIN_TARGET = 0.7