Gontage v1.5.0

Create spritesheets from multiple folders of sprites/images up to ~48x+ faster than ImageMagicks montage command.

Install

go install github.com/kyle-wannacott/gontage@latest

Features

• Images to Spritesheet: flags(-f or -mf)
• Images to Resized images: flags (-f -ss -sr)
• Single Image Resize: flags (-i -sr)
• Spritesheet cut into images: flags (-f -x)
• Circular/Square Fading: flags (-fade, -fm) - applies to all operations

Help:

gontage -h

Examples:

Single Image Resize:

gontage -i myimage.png -sr 64

This will resize myimage.png to 64x64 pixels and save it as myimage_resized_64px.png

PNG Checksum Fix:

gontage -i corrupted.png -sr 64 -fix-png

This will attempt to fix PNG checksum errors by re-encoding the image if corruption is detected during processing

gontage -f sprites_folder -fix-png

Process an entire folder with PNG checksum fixing enabled - any corrupted PNG files will be automatically re-encoded

gontage -mf parent_folder -fix-png

Process multiple folders with PNG checksum fixing enabled

Note: The -fix-png flag works with all image operations (single image resize, folder processing, and multiple folder processing). When enabled, if a PNG file fails to load due to checksum errors, gontage will:

1. Create a backup of the original file (filename.png.backup)
2. Attempt multiple recovery strategies:
   • Standard PNG decoding (if corruption is minimal)
   • Manual PNG chunk reconstruction with CRC recalculation
   • Complete PNG reconstruction from image data
3. Re-encode the image with valid checksums
4. Continue processing with the fixed image
5. Remove the backup if successful, or restore it if fixing fails

Technical Details:

• Validates PNG signatures and chunk structure
• Recalculates CRC32 checksums for all PNG chunks
• Handles common PNG corruption scenarios (transfer errors, partial writes)
• Preserves original image quality and metadata where possible
• Safe operation with automatic backup/restore on failure

This feature is particularly useful when working with PNG files that have been corrupted during transfer or storage but still contain valid image data.

Single Image Resize with Fading:

gontage -i myimage.png -sr 64 -fade 30

This will resize and apply circular fading with 30% radius fade to transparency

gontage -i myimage.jpg -sr 64 -fade 30 -fm s

This will resize a JPG image, apply square fading, and automatically save as PNG

Note: Fading preserves original colors and only modifies the alpha channel for smooth transparency transitions.

Fade Values:

• 0 = No fading (sharp edges)
• 25 = Light fading (25% of radius fades to transparent)
• 50 = Medium fading (50% of radius fades to transparent)
• 75 = Heavy fading (75% of radius fades to transparent)
• 100 = Full fading (entire radius fades from center to edge)

Fade Modes:

• -fm c = Circular fading (default)
• -fm s = Square fading

Important: JPG images with fading are automatically converted to PNG format to preserve transparency.

Folder Processing with Fading:

gontage -f sprites_folder -hf 4 -sr 32 -fade 25 -fm c

Creates a spritesheet with circular faded edges on each sprite

Individual Resized Sprites with Fading:

gontage -f sprites_folder -ss -sr 64 -fade 40 -fm s

Outputs individual resized sprites with square fading applied (JPG files become PNG)

Spritesheet Creation:

Benchmarking:

Multiple folders containing sprites -mf:

• gontage was up to ~48x faster than montage at creating multiple spritesheets (tested on a 12 core AMD 5900x)

Single folder -f:

• gontage was ~3.5x faster in this instance tested on a 12 core AMD 5900x

• ~2.5x faster on a 2 core 4 thread i5-4210U Skylake CPU.

At around the same level of compression:

vs.

Image comparison:

Reference images 33 - 40 :

Gontage:

Montage 7:

Other Info:

• Using an appImage for ImageMagick adds around 0.8seconds to startup time when running montage...
• Building an equivalent in NodeJS took around ~700ms (800ms with Bun) for one folder 7x slower than Gontage (~90ms) and 2x slower than Montage (~350ms).