thumb-py

Table of Content

1. Annotation
2. Example of Usage
   • CLI Script gcode_img_inserter.py
   • Write Your Own Script
3. Install
   • Using pip
   • For developers
4. List of Functions
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. Where the gcodes need to be precisely generated by the Processor3D software suite. Currently supported 3D printer is Prusa MINI+.

2. Example of Usage

CLI Script gcode_img_inserter.py

Requirment: Install thumby. Than you can use 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. If you want to use other functions of thumby.py see 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.

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):

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.

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:

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.

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:

pip install thumby

For developers

For development purposes git-clone this repo and run

pip install .

For dev version

pip install .[dev]

4. List of Functions

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

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

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

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

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

insert_header_to_gcode(header, gcode_filepath)    

Insert given header into gcode. Skips comments and free spaces

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

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

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

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

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

generate_base64(source_path)

returns base64 generated from source path (.png)

wrap_as_thumbnail(img_as_base64, img_w, img_h)

returns wrapped content as str

delete_thumbnail_normal(path_to_gcode)

Delete space between HEADER_BEG and HEADER_END. Delete all thumbnails of size 220x124

delete_thumbnail_mini(path_to_gcode)

Delete space between HEADER_BEG and HEADER_END. Delete all thumbnails of size 16x16

delete_thumbnail_large(path_to_gcode)

Delete space between HEADER_BEG and HEADER_END. Delete all thumbnails of size 240x320

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.

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