EV5_Beeldherk_Bomen/README.md

# Tree Recogniser 7000

This repository contains all files for the Image recognition course of HU Electrical Engineering year 3.

---

### 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 export 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/ 
```
4. Edit your `config.json` to include the newly created model

---

Arne van Iterson<br>
Tom Selier