tensorboard_image_extractor/README.md

# Tensorboard Image Extractor
## What is this program and why?

This is short script to extract images and create animated gif from there
using a tensorboard event file. Unfortunatly this feature is not native inside
tensorboard, inside which only the graphing data can downloaded (in `csv` or
`json` format).
The only other program which I found that did a similar thing is
https://github.com/lanpa/tensorboard-dumper/ which I took inspiration from.

## How to use it

The repository can be clone with git and the you will maybe need to install
some dependencies (like tensorboard):

```
pip3 install -r requirements.txt
```

You can then run it:

```
python3 tensorboard_image_extractor.py -i event.db
```

You can get some help by running:

```
python3 tensorboard_image_extractor.py --help 
```

## Tensorboard datastructure

The following diagram describes a tree of the log directory found in all
machine learning experiment with a tensorboard writer.

```
logs/
├── lupo
│   ├── args.txt
│   ├── config.txt
│   ├── model_005000.pth
│   ├── model_010000.pth
│   ├── model_015000.pth
│   ├── model_020000.pth
│   └── model_025000.pth
└── summaries
    └── lupo
        └── events.out.tfevents.1623155921.pop-os
```

The file which contains all data and images is the `event` file in
`logs/summaries/{run name}/events`. It can be fairly large because every image
is stored inside in binary format.

## Example

You can create an animated gif, only keeping images with a certain `tag`:
```
python3 tensorboard_image_extractor.py -i lupo.events -t "train/level_1/rgb" -o train_level_1_rgb_24h.gif --gif
```

## Performance

In order to create a gif from a 900 MB event file, it took me just over an
hour. This is due to the fact that Python has to do the I/O reading from binary
data and converting the whole file, which is remarkably slow.

It can create large gif files. In the experiment described above the images of
a single tag was kept and it created a 52 MB gif file.

## Notes

This program is distributed under GNU GNL v3 or later License, which you can
find a copy of in the repository.
This program comes with ABSOLUTELY NO WARRANTY

Tensorboard Image Extractor - Copyright (C) 2021 - Otthorn