Palettes Guide

Palettes define which characters are used to represent different brightness levels in your ASCII art. gummyworm comes with 12 built-in palettes and supports custom palettes via inline strings or files.

How Palettes Work

A palette is an ordered string of characters from lightest (or empty) to darkest. When converting an image:

Each pixel's brightness is calculated using luminance
The brightness (0-255) is mapped to a character index
The corresponding character from the palette is output

Example: With palette .oO@ (5 characters):

Very bright pixels → (space)
Bright pixels → .
Medium pixels → o
Dark pixels → O
Very dark pixels → @

Built-in Palettes

View all available palettes with:

gummyworm --list-palettes

See also: -l, --list-palettes in the CLI Reference.

Palette	Characters	Best For
`standard`	`.:-=+*#%@`	General purpose, good balance
`detailed`	72 ASCII chars	High-detail photos, portraits
`simple`	`.oO@`	Quick previews, small sizes
`blocks`	`░▒▓█`	High contrast, bold images
`binary`	`█`	Silhouettes, logos, line art
`dots`	`⠁⠃⠇⠿⣿`	Braille-style, compact art
`shades`	`░▒▓█`	Block shading
`retro`	`.:░▒▓█`	Retro computing aesthetic
`matrix`	`01`	Matrix/hacker style
`emoji`	🌑🌒🌓🌔🌕	Fun social posts, moon phases
`stars`	`·✦★✷✸✹`	Dreamy, celestial effects
`hearts`	`♡♥❤💖💗`	Love-themed art

Visual Examples

Here's how the same circular shape looks with different palettes:

standard (default)

      .:::.
    .::::::::.
   :::::::::::
  :::::::::::::
  :::::::::::::
   :::::::::::
    '::::::::'
      ':::'

blocks

      ░▒▒░
    ░▒▒▒▒▒▒░
   ▒▒▒▒▒▒▒▒▒
  ▒▒▒▒▒▒▒▒▒▒▒
  ▒▒▒▒▒▒▒▒▒▒▒
   ▒▒▒▒▒▒▒▒▒
    ░▒▒▒▒▒▒░
      ░▒▒░

binary

      ███
    ███████
   █████████
  ███████████
  ███████████
   █████████
    ███████
      ███

emoji (smaller width recommended)

    🌓🌔🌔🌓
  🌔🌕🌕🌕🌕🌔
  🌔🌕🌕🌕🌕🌔
    🌓🌔🌔🌓

Tip: Generate your own comparisons:

for p in standard blocks binary emoji; do
  echo "=== $p ===" && gummyworm -p "$p" -w 40 photo.jpg
done

Usage Examples

# Standard palette (default)
gummyworm photo.jpg

# Block characters for bold output (see -p option in CLI Reference)
gummyworm -p blocks landscape.jpg

# Emoji for fun social sharing
gummyworm -p emoji -w 40 cat.jpg

# High detail for portraits
gummyworm -p detailed -w 150 portrait.png

# Binary for logos and silhouettes
gummyworm -p binary logo.png

# Braille dots for compact art
gummyworm -p dots -w 60 photo.jpg

Custom Palettes

Inline Custom Palettes

Specify a custom character string directly on the command line:

# Simple custom palette
gummyworm -p " .oO0@#" photo.jpg

# Block-based custom
gummyworm -p " ░▒▓█" photo.jpg

# ASCII art style
gummyworm -p " .',:;!|[{#@" photo.jpg

# Minimal
gummyworm -p " *#" photo.jpg

Rules for inline palettes:

Characters go from lightest to darkest
Start with a space for white/bright areas
Minimum 2 characters required
Special characters may need quoting

Palette Files

Create reusable palette files in the palettes/ directory with optional metadata.

File format: palettes/<name>.palette

# Name: My Palette
# Description: A brief description of the palette
# Author: Your Name
# Tags: unicode, artistic, high-contrast

 ~≈≋⌇░▒▓█

Metadata Fields

Palette files support optional metadata headers:

Field	Description
`Name`	Display name shown in `--list-palettes`
`Description`	Brief description of the palette
`Author`	Creator's name
`Tags`	Comma-separated tags for categorization

All metadata is optional. Lines starting with # are comments. The first non-comment, non-empty line is the character set.

Example: Creating a custom palette

Copy the template:

cp palettes/_template.palette palettes/ocean.palette

Edit palettes/ocean.palette:

# Name: Ocean
# Description: Wave-themed palette for water images
# Author: Your Name
# Tags: unicode, water, nature

 ~≈≋⌇░▒▓█

Use it:
```
gummyworm -p ocean beach.jpg
```

More example palettes:

palettes/arrows.palette:

# Name: Arrows
# Description: Directional arrow characters
# Tags: unicode, artistic
 ·→⇒▸▶►

palettes/boxes.palette:

# Name: Box Drawing
# Description: Box drawing and shade characters
# Tags: unicode, retro
 ╌╎┆┊░▒▓█

palettes/currency.palette:

# Name: Currency
# Description: Money-themed with currency symbols
# Tags: unicode, fun
 ·¢$€£¥₿

See palettes/README.md for more examples and the complete format specification.

Unicode and Emoji Considerations

Terminal Support

Not all terminals render Unicode characters equally:

Character Type	Support Level
Basic ASCII	Universal
Extended ASCII (░▒▓)	Most terminals
Unicode symbols (✦★●)	Modern terminals
Emoji (🌕❤️🔥)	Varies widely
Braille (⠁⠃⠇)	Good in modern terminals

Recommendation: Test your palette in your target terminal before batch processing.

Character Width

Some Unicode characters are "wide" (take 2 columns) while others are narrow (1 column). gummyworm handles this automatically when Python 3 is available.

Characters that may cause alignment issues:

Most emoji (2 columns wide)
CJK characters
Some symbols

Tip: The emoji palette works best at smaller widths (-w 40) due to wide characters.

Font Requirements

For best results with special characters:

Palette Type	Recommended Fonts
Block characters	Any monospace
Braille	DejaVu Sans Mono, Consolas
Emoji	Noto Color Emoji, Apple Color Emoji
Stars/Symbols	Fira Code, JetBrains Mono

Palette Selection Guide

By Image Type

Image Type	Recommended Palette
Portraits	`detailed`, `standard`
Landscapes	`blocks`, `shades`
Logos/Icons	`binary`, `simple`
Photos (general)	`standard`, `detailed`
Dark images	`blocks` + `-i` (invert)
Artistic/stylized	`emoji`, `stars`, `matrix`

By Output Purpose

Purpose	Recommended Palette
Terminal display	`standard`, `blocks`
Text file	`standard`, `detailed`
HTML/Web	Any (colors preserved)
Social media	`emoji`, `blocks`
Print	`detailed`, `standard`
Code comments	`simple`, `binary`

By Size

Output Width	Recommended Palette
Small (< 40)	`simple`, `blocks`, `emoji`
Medium (40-100)	`standard`, `blocks`
Large (> 100)	`detailed`, `standard`

Advanced: Creating Effective Palettes

Design Principles

Start with space: White/bright areas should be empty or near-empty
Gradual progression: Characters should increase in "visual density"
Consistent width: Stick to single-width or double-width characters (don't mix)
Test visually: What looks dense to humans matters more than technical measurements

Visual Density Order

Common characters ordered by visual density:

Lightest: (space) . · ' ` , - ~ _
Light:    : ; ! i l | / \ ( )
Medium:   o O 0 c C { } [ ] + = *
Dark:     # % @ & $ X W M
Darkest:  █ ▓ ▒ (solid blocks)

Testing Your Palette

# Quick test with a gradient image
gummyworm -p "your palette here" -w 60 gradient.png

# Test with color to see mapping
gummyworm -p "your palette" -c photo.jpg

# Compare palettes
for p in standard blocks detailed; do
  echo "=== $p ==="
  gummyworm -p "$p" -w 40 photo.jpg
done

Troubleshooting

Characters not displaying correctly

Check terminal Unicode support: echo "░▒▓█"
Try a different font
Fall back to ASCII-only palettes: standard, detailed, simple

Emoji showing as boxes or ?

Install an emoji font (Noto Color Emoji)
Use a terminal with emoji support (iTerm2, Windows Terminal, Kitty)
Fall back to non-emoji palettes

Output looks wrong / not enough contrast

Try -i (invert) flag for dark images
Use blocks palette for more contrast
Adjust width: smaller = more detail sometimes

Palette file not found

Ensure file is in palettes/ directory
File must end with .palette extension
Check filename matches exactly (case-sensitive)

How Palettes Work​

Built-in Palettes​

Visual Examples​

Usage Examples​

Custom Palettes​

Inline Custom Palettes​

Palette Files​

Metadata Fields​

Unicode and Emoji Considerations​

Terminal Support​

Character Width​

Font Requirements​

Palette Selection Guide​

By Image Type​

By Output Purpose​

By Size​

Advanced: Creating Effective Palettes​

Design Principles​

Visual Density Order​

Testing Your Palette​

Troubleshooting​

Characters not displaying correctly​

Emoji showing as boxes or ?​

Output looks wrong / not enough contrast​

Palette file not found​