thumby 0.4.1
Simple python library for inserting .png thumbnails into gcode files.
License: MIT

# thumb-py
## Table of Content
1. [Annotation](#1-annotation)
2. [Example of Usage](#2-example-of-usage)
    + [CLI Script `gcode_img_inserter.py`](#cli-script-gcode_img_inserterpy)
    + [Write Your Own Script](#write-your-own-script)
3. [Install](#3-install)
    + [Using pip](#using-pip)
    + [For developers](#for-developers)
4. [List of Functions](#4-list-of-functions)
5. [Technical Details of Implementations](#5-technical-details-of-implementations)

## 1. Annotation
Python library for inserting custom image thumbnails into gcode files (extraction from gcode to png is also supported). The original purpose of this library is to increase user experience during the printing of parts of ThunderFly's autogyros like [TF-G2](https://github.com/ThunderFly-aerospace/TF-G2).  Where the gcodes need to be precisely generated by the Processor3D software suite. 
Currently supported 3D printer is [Prusa MINI+](https://www.prusa3d.com/product/original-prusa-mini-semi-assembled-3d-printer-4/). 

<img src="https://user-images.githubusercontent.com/33667517/162848648-6af1fe94-2e7a-4367-9366-320031575016.jpg" width="300">


## 2. Example of Usage
### CLI Script `gcode_img_inserter.py`
Requirment: [Install thumby](#3-install).
Than you can use [`gcode_img_inserter.py`](https://github.com/ThunderFly-aerospace/thumby/tree/master/executable_scripts/gcode_img_inserter.py) script.
#### How to use
##### Help of The Script
```
Usage: gcode_img_inserter.py OPTION FILE1 [FILE2]
Options:
Insert - FILE1=png_file, FILE2=gcode_file - png file to gcode file:
--insert-all    -iall   FILE1   FILE2   all size (recommended)
--insert-mini   -imini  FILE1   FILE2   mini size 16x16
--insert-normal -inorm  FILE1   FILE2   normal size 220x124
--insert-large  -ilarge FILE1   FILE2   large size 240x320
Extract - FILE1=png_file, FILE2=gcode_file - extract png from gcode file:
--extract-any   -eany   FILE1   FILE2   any recommended size
--extract-mini  -emini  FILE1   FILE2   mini size 16x16
--extract-normal-enorm  FILE1   FILE2   normal size 220x124
--extract-large -elarge FILE1   FILE2   large size 240x320
Clear - FILE1=gcode_file - delete current thumbnails from gcode
```
##### Examples
###### Insertion of Thumbnail
Insert thumbnails to your gcode from pngfile.
- My example files:
  
  `model_of_vader_mask.gcode`, `thumbnail_of_my_model.png`.
- Command to run:
  
  `python3 gcode_img_inserter.py --insert-all thumbnail_of_model.png model_of_vader_mask.gcode`
  
If error didn't appear your thumbnail should be inserted to the gcode file.


###### Differences Between Inserts
3D printers supportes three sizes of thumbnails. I recommand insert via option `--insert-all`.
If you want for example use different thumbnails for different sizes, you can insert thumbnails one by one with options: `--insert-mini`, `--insert-normal` and `--insert-large`.
###### Extraction of Thumbnail
Extract thumbnails from your gcode to specified png file.
- My example files:
  
  `model_of_vader_mask.gcode`, `vader_mask_thumbnail.png`.
- Command to run:
  
  `python3 gcode_img_inserter.py --extract-any vader_mask_thumbnail.png model_of_vader_mask.gcode`
  
Note:
If png file doesn't exist: will be created.
If **png file does exist**: content of file **will be replaced** by thumbnail.
If error didn't appear your thumbnail should be placed at specified png file.


###### Differences Between Extractions
3D printers supportes three sizes of thumbnails.
If you are not sure which size of thumbnail is present in your gcode file, use `--extract-any` option. Thumbnail of 1 size is extracted by following priority:
1. normal   220x124
2. mini     16x16
3. large    240x320
##### Clear of Thumbnail
Delete thumbnails from your gcode file. Thumbnails in gcode have to be formated correctly. Script doesn't remove comments or empty lines.
- My example gcode file:
  
  `model_of_vader_mask.gcode`
- Command to run:
  
  `python3 gcode_img_inserter.py --clear model_of_vader_mask.gcode`
  
If error didn't appear your thumbnails should be removed from the gcode file.


### Write Your Own Script
Example of combinig more functions together is [this code block](#recommanded-usage). If you want to use other functions of `thumby.py` see [List of Functions](#4-list-of-functions).
There are 3 recommanded size of thumbnails (width x height):
- normal   220x124
- mini     16x16
- large    240x320
Other formats may not display on 3D printers.

#### Insert Thumbnails
To insert all tree sizes use script bellow.
```python
import thumby

# image you want insert into gcode
pathToPng = "path/to/png/file.png"
# gcode file into which you want to insert the image
pathToGcode = "path/to/gcodeFile.gcode"

insert_png_to_gcode_normal(pathToPng, pathToGcode)
insert_png_to_gcode_large(pathToPng, pathToGcode)
insert_png_to_gcode_mini(pathToPng, pathToGcode)
```
You can also insert thumbnail of other size for advanced purposes (not recommanded):
```python
import thumby

pathToPng = "path/to/png/file.png"
pathToGcode = "path/to/gcodeFile.gcode"

insert_png_to_gcode_custom(pathToPng, pathToGcode, width, height)
```
#### Delete Thumbnails
To delete all tree sizes use script bellow. Functions `delete thumbnail_*()` will delete all thumbnails of set size found in given gcode.
```python
import thumby

# gcode file where thumbnails will be deleted
pathToGcode = "path/to/gcodeFile.gcode"

delete_thumbnail_normal(path_to_gcode)
delete_thumbnail_large(path_to_gcode)
delete_thumbnail_mini(path_to_gcode)
```
To delete thumbnail of other size:
```python
import thumby

pathToGcode = "path/to/gcodeFile.gcode"
delete_thumbnail_custom(path_to_gcode, width, height)
```
#### Combine More Functions Together
A script for inserting and replacing thumbnails into your gcodes.
```python
import thumby

pathToPng = "path/to/png/file.png"
pathToGcode = "path/to/gcodeFile.gcode"

# this makes sure there are no thumbnails in gcode file
delete_thumbnail_normal(path_to_gcode)
delete_thumbnail_large(path_to_gcode)
delete_thumbnail_mini(path_to_gcode)

# than insert thumbnail of all 3 recommanded sizes
insert_png_to_gcode_normal(pathToPng, pathToGcode)
insert_png_to_gcode_large(pathToPng, pathToGcode)
insert_png_to_gcode_mini(pathToPng, pathToGcode)
```

## 3. Install
### Using pip
If you use pip, you can install thumby with:
```python
pip install thumby
```
### For developers
For development purposes git-clone this repo and run
```python
pip install .
```
For dev version
```python
pip install .[dev]
```

## 4. List of Functions

```python
insert_png_to_gcode_normal(path_to_png, path_to_gcode)
```
Makes temp file from given png file and inserts it as thumbnail to given gcode.
size of thumbnail: 220x124


```python
insert_png_to_gcode_mini(path_to_png, path_to_gcode)
```
Makes temp file from given png file and inserts it as thumbnail to given gcode.
size of thumbnail: 16x16

```python
insert_png_to_gcode_large(path_to_png, path_to_gcode)
```
Makes temp file from given png file and inserts it as thumbnail to given gcode.
size of thumbnail: 240x320

```python
insert_png_to_gcode_custom(path_to_png, path_to_gcode, width=WIDTH_NORMAL, height=HEIGHT_NORMAL)
```
Makes temp file from given png file and inserts it as thumbnail to given gcode.
-> default size of thumbnail: 220x124
recomanded sizes:
-> normal   220x124
-> mini     16x16
-> large    240x320

```python
resize_and_save_image(png_filepath, target_width=WIDTH_NORMAL, target_height=HEIGHT_NORMAL, tmpFile="tmp.png")
```
Saves resized file as tmpFile. Default name 'tmp.png'.
Return value is 'tmpFile path'
-> default size of thumbnail: 220x124
recomanded sizes:
-> normal   220x124
-> mini     16x16
-> large    240x320

```python
insert_header_to_gcode(header, gcode_filepath)    
````
Insert given header into gcode.
Skips comments and free spaces 

```python
extract_png_from_gcode_any_recommended(path_to_png: str, path_to_gcode: str)
```
Search for thumbnail of recommended size in gcode file and extract it to given path_to_png.
Args:
- path_to_png: str - creates or overides file at given path
- path_to_gcode: str - source of thumbnail

recommended sizes (ordered by priority):
-> normal   220x124
-> mini     16x16
-> large    240x320

```python
extract_png_from_gcode_normal(path_to_png, path_to_gcode)
```
Search for thumbnail (of size "normal") in gcode file and extract it to given path_to_png.
recommended size "normal": 220x124

```python
extract_png_from_gcode_mini(path_to_png, path_to_gcode)
```
Search for thumbnail (of size "normal") in gcode file and extract it to given path_to_png.
recommended size "mini": 16x16

```python
extract_png_from_gcode_large(path_to_png, path_to_gcode)
```
Search for thumbnail (of size "normal") in gcode file and extract it to given path_to_png.
recommended size "large": 240x320

```python
extract_png_from_gcode_custom(path_to_png, path_to_gcode, width=WIDTH_NORMAL, height=HEIGHT_NORMAL)
```
Search for thumbnail in gcode file and extract it to given path_to_png.
-> default size of thumbnail: 220x124  
    
```python
generate_base64(source_path)
```
returns base64 generated from source path (.png)

```python
wrap_as_thumbnail(img_as_base64, img_w, img_h)
```
returns wrapped content as str

```python
delete_thumbnail_normal(path_to_gcode)
```
Delete space between HEADER_BEG and HEADER_END.
Delete all thumbnails of size 220x124

```python
delete_thumbnail_mini(path_to_gcode)
```
Delete space between HEADER_BEG and HEADER_END.
Delete all thumbnails of size 16x16


```python
delete_thumbnail_large(path_to_gcode)
```
Delete space between HEADER_BEG and HEADER_END.
Delete all thumbnails of size 240x320

```python
delete_thumbnail_custom(path_to_gcode, width=WIDTH_NORMAL, height=WIDTH_NORMAL)
```
Delete space between HEADER_BEG and HEADER_END.
Delete all thumbnails of given size.

```python
remove_file(filepath)
```
Delete file with given filepath

## 5. Technical Details of Implementations
1. PNG to Base64: The chosen PNG thumbnail is encoded into a Base64 string
2. Embedding in GCode: The encoded Base64 string is inserted into the GCode using special comment lines that denote the beginning and the end of the thumbnail data:

```
; thumbnail begin 'width'x'height' 'len'
; 'Base64 encoded PNG data line 1, up to 78 characters long'
; ...
; 'Base64 encoded PNG data last line, up to 78 characters long'
; thumbnail end
```

## 6. Limitations and Future Improvements
- when resizing images, temporary file is created, which is not necessary
- "clearing" the gcode does not remove empty comments
- support for specified printers only
- better CLI tool (messages for user, errors)
- error handling in general is not ideal
- unit testing can be added