Skip to content

ASCII Art Converter

Jump to bottom
Jack Murray edited this page Nov 8, 2025 · 1 revision

🎨 ASCII Art Converter

The ASCII Art Converter is a dedicated utility developed by Jack Murray (Nova Foundry) to transform digital images into customizable text-based art. It provides fine-grained control over the character set, resolution, and pre-processing effects (contrast and inversion) for the resulting ASCII output.

This tool is accessible directly from the Echo Hub.

💻 Application Workflow

The application guides the user through three simple steps:

1. Image Input

This section specifies the source file for the conversion.

  • Browse... Button: Use this to open a file selection dialog. Supported input formats include PNG, JPG, JPEG, BMP, and GIF.
  • File Entry: Displays the file path.
    • Default Image: If the entry field is empty and conversion is initiated, the application will attempt to use the hardcoded DEFAULT_PREVIEW_IMAGE_PATH. A message, [Using Default Image], will appear in the entry field if this fallback is used.
    • Requirement: A valid image must be selected, or the application's default path must be configured and valid, for conversion to proceed.

2. Conversion Settings

These parameters allow you to fine-tune the final appearance of the ASCII art.

Art Style

Selects the character set used to map grayscale values (dark to light) to text characters.

Style Character Set (Darkest → Lightest) Description
Standard .@%#*+=-:. (Reversed) A balanced and widely compatible set.
Blocks █▓▒░ (Reversed) Uses solid block characters for a heavy, abstract look.
Complex $@B%8&WM#*o... (Reversed) A large set offering the highest level of detail.
Simple .:-=+*#%@ A small set for low-detail, high-contrast results.

Width (Chars)

A slider defining the maximum horizontal resolution of the art, ranging from 50 to 250 characters. The resulting height is automatically calculated to preserve the image's aspect ratio, adjusted by a factor of $0.55$ to compensate for the vertical spacing of text characters.

Contrast Multiplier

A slider (range 0.0 to 3.0, default 1.0) that enhances the contrast of the grayscale image before character mapping.

  • Below 1.0: Reduces contrast, resulting in a more uniform, gray output.
  • Above 1.0: Increases contrast, making light areas lighter and dark areas darker, leading to a sharper, more defined output.

Invert Light/Dark Mapping

A switch that reverses the mapping logic.

  • Off (Default): Dark pixels are mapped to dark/dense characters (e.g., @), and light pixels are mapped to light/sparse characters (e.g., . or ). Ideal for light-on-dark displays.
  • On (Invert): Light pixels are mapped to dense characters, and dark pixels are mapped to sparse characters. Ideal for dark-on-light printouts or displays.

3. Result and Output

  • Convert to ASCII (Button): Executes the conversion using multi-threading (run_conversion_thread). This prevents the main UI from locking up during processing. The button text changes to Converting... while active.
  • Output Textbox: Displays the final, fixed-width ASCII art.
  • Save as .txt (Button): Allows the user to export the content of the Output Textbox to a plain text file for external use.
  • Return to Hub (Button): Closes the Converter and attempts to launch the Echo_hub.exe application.

⚠️ Troubleshooting & Conversion Notes

Issue Likely Cause Fix
"Error: The image file does not exist." The path entered in the File Entry box is invalid or the original file was moved/deleted. Re-select the file using Browse... or ensure the file is present.
ASCII art is too short/low-detail. The Width setting is too low. Increase the Width slider (e.g., to 200) for higher character resolution.
Output appears grayscale/muddy. The image is low contrast, or the Contrast Multiplier is set too low (near 0.0). Increase the Contrast Multiplier to sharpen the edges.
Art is inverted (light areas are dark). The input image is dark, or the output is better suited for a different background color. Toggle the Invert Light/Dark Mapping switch.
"Failed to save file..." Permissions error or an invalid character in the file path. Choose a simple save path, like the desktop or a user folder.

Clone this wiki locally