inkaterm 2.0.1

Convert PNG images to ASCII colored art

Inkaterm 🔏

Convert images into beautiful colored ASCII art directly in your terminal with a fast, customizable, and lightweight Python library.

---

✨ Features

• 🚀 Fast rendering
• 🎨 ANSI TrueColor and 256-color support
• 🖼️ Convert images into colored ASCII art
• 💾 Smart disk cache with LZ4 compression
• ⚡ Optimized rendering pipeline
• 🔧 Highly customizable output
• 📂 Supports file paths, bytes, bytearray, memoryview and BytesIO
• 🎭 Built-in image filters
• 🐍 Pure Python implementation
• 🔗 Method chaining support

---

📦 Installation

pip install inkaterm

---

🚀 Quick Start

import inkaterm

ink = inkaterm.Ink()

image = ink.image("image.png")
image.resize(75, 75)

print(image)

---

🖼️ Output

ANSI TrueColor

ANSI 256 Colors

All screenshots were captured inside the Termux terminal.

---

⚡ Performance

Inkaterm includes an optimized cache system.

Example:

Image size: 1000 × 1000

First render:
≈ 9 s

From cache:
≈ 200 ms

Cache files are compressed using LZ4.

Example:

Original cache:
12 MB

Compressed:
218 KB

---

⚙️ Basic Usage

Create an Ink instance

import inkaterm

ink = inkaterm.Ink()

---

Load an image

image = ink.image("cat.png")

---

Resize

image.resize(120, 80)

---

Apply filters

image.filter \
    .grayscale() \
    .contrast(1.5) \
    .brightness(15)

print(image)

---

Method chaining

image.resize(80, 80)

image.filter \
    .dreamy() \
    .contrast(1.4) \
    .sharpness(2)

print(image)

---

📚 API Reference

inkaterm.Ink

Main rendering class.

Constructor

Ink(
    root_dir=".",
    char="██",
    fill_background=False,
    cache=False,
    cache_dir="inkaterm_cache",
    true_color=None
)

Parameter	Type	Default	Description
root_dir	str	"."	Base directory for relative image paths.
char	str	"██"	Character(s) used for rendering.
fill_background	bool	False	Uses ANSI background colors instead of foreground text colors.
cache	bool	False	Enables disk cache.
cache_dir	str	"inkaterm_cache"	Cache directory.
true_color	bool | None	None	Enables or disables TrueColor. When None, Inkaterm detects terminal support automatically.

---

Ink.image()

Loads an image.

image = ink.image(
    file,
    char=None,
    fill_background=None,
    cache=None,
    cache_dir=None,
    true_color=None
)

Parameter	Type	Description
file	str, bytes, bytearray, memoryview, BytesIO	Image source.
char	str | None	Overrides the default rendering character.
fill_background	bool | None	Overrides the renderer background mode.
cache	bool | None	Enables or disables cache for this image only.
cache_dir	str | None	Overrides the cache directory.
true_color	bool | None	Overrides color mode for this image.

Returns:

Image

---

🖼️ Image

Represents a loaded image.

---

resize()

image.resize(width, height)

Parameter	Type
width	int
height	int

Returns:

Image

---

Rendering

print(image)

or

str(image)

---

🎨 Filters

Access filters through

image.filter

---

apply()

image.filter.apply(red, green, blue)

Parameter	Type	Description
red	float	Red channel multiplier.
green	float	Green channel multiplier.
blue	float	Blue channel multiplier.

---

Available Filters

Method	Description
brightness(value)	Adjust image brightness.
contrast(factor)	Adjust image contrast.
invert()	Invert image colors.
grayscale()	Convert the image to grayscale.
sharpness(amount)	Increase image sharpness.
blur(radius)	Apply a box blur.
gaussian_blur(radius)	Apply Gaussian blur.
sepia()	Apply a sepia effect.
vintage()	Apply a vintage effect.
cool_blue()	Apply a cool blue effect.
retro_red()	Apply a retro red effect.
neon_green()	Apply a neon green effect.
dreamy()	Apply a dreamy color effect.
dark_mood()	Apply a dark mood effect.

Every filter returns the current Filter object, allowing method chaining.

Example:

image.filter \
    .grayscale() \
    .contrast(1.5) \
    .brightness(20)

---

Rendering

print(image)

or

str(image)

---

save()

Save rendered ASCII art to a text file.

image.save("output.txt")

Parameter	Type	Description
path	str	Output file path.

Returns:

True

Example:

image = ink.image("cat.png")

image.resize(80, 80)

image.save("cat_ascii.txt")

---

📂 Supported Image Sources

Source	Supported
File path (str)	✅
bytes	✅
bytearray	✅
memoryview	✅
BytesIO	✅

---

⚠️ Exceptions

Exception	Description
ImageNotFoundError	Image file does not exist.
InvalidTypeError	Invalid argument type.
InvalidSizeError	Width or height is less than 1.
FilterError	Invalid filter parameter.

---

📝 License

This project is licensed under the MIT License.

---

⭐ Support

If you like Inkaterm, consider giving the repository a ⭐ on GitHub.