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 and clear 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 ThunderFly˙s Processor3D software suite. But could be also used stand-alone see the example below. The currently supported 3D printer is Prusa MINI+.

2. Example of Usage

CLI Script gcode_img_inserter.py

Requirement: Install thumby. Then 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 the error didn't appear your thumbnail should be inserted into the gcode file.

Differences Between Inserts

Prusa MINI 3D printers support three sizes of thumbnails. I recommend inserting via the 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 the 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 the png file doesn't exist: will be created. If png file does exist: content of file will be replaced by thumbnail. If an error doesn't appear your thumbnail should be placed at a specified png file.

Differences Between Extractions

3D printers support three sizes of thumbnails. If you are not sure which size of the thumbnail is present in your gcode file, use --extract-any option. The thumbnail of 1 size is extracted by the 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 formatted correctly. The 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 an error didn't appear your thumbnails should be removed from the gcode file.

Write Your Own Script

An example of combining more functions together is this code block. If you want to use other functions of thumby.py see List of Functions. There are 3 recommended sizes 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 the script below.

import thumby

# image you want to 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 thumbnails of other sizes for advanced purposes (not recommended, the thumbnail will be deformed on the 3D printer display):

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 the script below. Functions delete thumbnail_*() will delete all thumbnails of the set size found in the 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 another 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)

# Then insert a thumbnail of all 3 recommended 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 the 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 the 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 the 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 the thumbnail to given gcode. -> default size of thumbnail: 220x124 recommended 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'. The return value is 'tmpFile path' -> default size of thumbnail: 220x124 recommended sizes: -> normal 220x124 -> mini 16x16 -> large 240x320

insert_header_to_gcode(header, gcode_filepath)    

Insert the 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 the thumbnail of the recommended size in gcode file and extract it to the given path_to_png. Args:

• path_to_png: str - creates or overrides file at the 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 a thumbnail (of size "normal") in gcode file and extract it to the given path_to_png. recommended size "normal": 220x124

extract_png_from_gcode_mini(path_to_png, path_to_gcode)

Search for a thumbnail (of size "normal") in gcode file and extract it to the given path_to_png. Recommended size "mini": 16x16

extract_png_from_gcode_large(path_to_png, path_to_gcode)

Search for a thumbnail (of size "normal") in gcode file and extract it to the 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 the thumbnail in gcode file and extract it to the 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, the 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