Metadata-Version: 2.1
Name: thumby
Version: 0.2.3
Summary: Simple python library for inserting .png thumbnails into gcode files.
Home-page: https://github.com/ThunderFly-aerospace/thumby/
Author: Dusan Jansky
License: MIT
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: LICENSE

# 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. 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/). 

## 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 (recommanded)
--insert-mini	-imini	FILE1	FILE2	mini size	16x16
--insert-normal	-inorm	FILE1	FILE2	normal size	220x124
--insert-large	-ilarge	FILE1	FILE2	large size	240x320
Clear - FILE1=gcode_file - delete current thumbnails from gcode file
--clear		-c	FILE1	(None)	deletes thumbnails from gcode file
```
##### 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`.
##### 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
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
