ASCII艺术 是做什么的?
scripts/ascii.py 制作静态图像,scripts/animate.py 制作动画(见“动画”)。两者仅需 Python 3.9+ 和 Pillow(视频需 ffmpeg)。安装了 uv 后,uv run 会自动安装 Pillow。
uv run scripts/ascii.py IMAGE [options] # 或:python3 scripts/ascii.py(需要 pillow)
以下路径均相对于该技能所在文件夹。
步骤
- 获取图像路径。如果是 URL,先用
curl -L -o /tmp/in.img URL下载。 - 选择输出方式。使用 stdout 文本可在聊天中显示。用户需要可分享的文件时,使用
-o file.png或-o file.html。 - 运行脚本,然后检查结果。对于 PNG,打开图像查看。
- 如果主体难以辨认,调整参数并重新运行(见“修正不佳结果”)。
选项
| 选项 | 功能说明 |
|---|---|
-w 100 | 字符宽度(1–1000)。聊天用 60–80,PNG/HTML 用 120–200,文字截图用 120+。 |
-c standard | 字符梯度:standard、detailed、blocks、terminal、minimal、binary、dots,或自定义从密到空的字符串,如 -c "#*. "。 |
-o out.png | 根据扩展名输出:.txt、.html、.png、.jpg、.webp。若不提供 -o,则纯文本输出到 stdout。 |
--bg black | 背景色:black(默认)、white、none(透明 PNG/HTML),或任意颜色。深色背景下明亮像素会选用密集字形;浅色背景下则相反。 |
--fg matrix | 单一墨色:matrix、amber、cyan、magenta、mint,或任意 CSS 颜色/十六进制值。不设置时,PNG/HTML 使用照片自身颜色。 |
--color | 在文本输出(stdout 或 .txt)中使用真彩色 ANSI 转义码。若提供了 --fg 则使用它,否则使用照片颜色。 |
--invert | 交换明暗。 |
--contrast 1.0 --brightness 1.0 | 在自动对比度拉伸基础上的调整系数。1.0 表示无变化。 |
--dither | Floyd-Steinberg 抖动。适用于平滑渐变和短字符梯度,如 blocks 或 minimal。 |
--mode ramp | ramp(默认):每个像素根据亮度选择一个字形。shape:类似 ramp,但边缘使用相同形状的符号(`/ \ |
--sharpen | 在缩小前锐化边缘。有助于面部和细节,尤其对 braille 模式效果最佳。 |
--aspect 0.5 | 字符宽度与高度之比。如果艺术图看起来被压扁,可增大此值。 |
--font-size 12 | PNG/HTML 中字形大小(像素)。 |
--glow 0.8 | PNG、HTML 和动画中字形周围的柔和辉光(0-1),类似老式屏幕的光晕。深色背景上效果最佳。 |
修正不佳结果
脚本会自动将每张图像的色调范围拉伸至最大,因此大多数图像无需调整即可获得良好效果。
- 照片:
-c blocks --dither可生成最易识别的面部和动物。 - 深色主体(黑狗、夜景)在黑色背景上难以辨认:使用
--bg white。提高--brightness 1.5也有帮助。提高对比度会使深色场景更糟。 - 白色背景上的深色 Logo 会显示为实心块:添加
--bg white(或对终端输出使用--invert)。 - 希望在相同宽度下获得更多细节:
--mode braille --dither --sharpen适合线条艺术风格,--mode halfblock适合彩色照片。 - 噪声过多:减少列数或使用更短的字符梯度(
-c minimal)。 - 渐变中出现条带:添加
--dither。 - 聊天输出:切勿使用
--color,因为转义码会显示为乱码。将文本包裹在代码块中。 - 不支持 SVG。请先将其转换为 PNG(
rsvg-convert -w 800 logo.svg -o logo.png)。
模式简述
braille忽略-c。对于照片,与--dither配合使用;对于 Logo,不使用。颜色跟随照片或--fg。halfblock忽略-c、--dither和--fg,因为颜色本身就是图像。纯文本(无--color)没有颜色,因此每个单元格会根据亮度变为一个色块█▓▒░。--bg none不会使其透明:透明像素变为黑色。- 终端绘制的盲文点很小,因此盲文在终端中看起来比在 PNG 中更暗。
瓦片海报
--mode tiles 制作海报:由若干平静颜色的方形瓦片组成的网格,每个瓦片包含一个字形,背景为炭色。在图像颜色接近页面颜色的区域,单元格不作为瓦片显示:它们显示一个淡化的字形,因此网格无处不在。
uv run scripts/ascii.py photo.jpg --mode tiles -w 36 -o poster.png
- 瓦片模式的默认设置:方形单元格(
--aspect 1)、--font-size 80(48 像素瓦片)、--gap 1、--bg "#1d1f22"。文本输出保持--aspect 0.5。 --palette 8:瓦片颜色数量,从主体中一次性选取。使用 4–6 可获得更平坦、更平静的外观。- 字形是随机的。
--seed N可更换另一组。使用-c可改用梯度字形。 - 浅色背景的照片:使用浅色页面,如
--bg "#ecebe6"。这样深色部分会成为瓦片。 - 也适用于
animate.py。字形和颜色在帧之间保持不变。
文字海报
--mode words 用大写单词填充画布,单词之间间隔一个空格。每行从自己的偏移量开始,并向两侧延伸出边缘。图像仅通过每个单词的亮度显现:每个单词一个级别,取决于其下方图像的平均亮度。深色部分产生淡色单词,主体产生亮色单词。
--words "A B C"设置词汇表(以空格或逗号分隔)。默认是类型和像素相关词汇的简短列表。--accent "#f28c28"在色彩最鲜艳的单词后面放置一个实心框,文字为深色。--accent-level 0.5(0-1)是单词所需的最低鲜艳度。灰度照片不会产生任何框;全彩 Logo 会产生很多框,因此可提高该级别。- 背景默认为
#1d1f22。--gap设置堆叠行中框之间的像素距离。--seed可更换另一种布局。--fg被忽略。 - 它在深色背景上的明亮、简单主体上效果最佳。对于浅色照片上的深色主体,添加
--invert。 - 在
animate.py中,每一帧的布局保持不变;只有亮度会变化。
预设:--mode words -w 110 --font-size 16 --accent "#f28c28" -o poster.png
预设
- 矩阵风格:
-c binary --fg matrix --glow 0.8 -o out.png - Retro 琥珀色终端:
-c terminal --fg amber -o out.png - 彩色照片马赛克:
-c detailed -w 160 -o out.html - 终端中最佳彩色照片:
--mode halfblock --color - 精细点画:
--mode braille --dither --sharpen -o out.png - 黑色电影风格:
--fg "#e8e6df" --contrast 1.35 --bg "#050505" --glow 0.7 -o out.png - 适合打印:
--bg white -o out.png - 瓦片海报:
--mode tiles -w 36 -o poster.png
动画
scripts/animate.py 制作 ASCII 动画。它接受与 ascii.py 相同的视觉选项(-w、-c、--mode、--sharpen、--bg、--fg、--invert、--contrast、--brightness、--font-size、--aspect、--gap、--glow,以及文字和瓦片海报选项)。视频输入和 .mp4 输出需要 ffmpeg。GIF 和 WebP 则不需要。
uv run scripts/animate.py cat.gif # 在终端播放,Ctrl-C 停止
uv run scripts/animate.py cat.gif -o out.gif # 也支持 .webp、.mp4 或 .html(单个文件,内含播放/暂停控制)
uv run scripts/animate.py clip.mp4 -o out.html --start 2 --duration 4 --fps 12
uv run scripts/animate.py photo.jpg --effect matrix -o intro.gif # 为静态图像制作动画
- 输入:动画 GIF、WebP 或 APNG、ffmpeg 可读取的任何视频,或带有
--effect的静态图像。 - 帧时序来自源文件。
--fps可重新采样。--start和--duration以秒为单位选择片段。 - 默认在 300 帧后停止并给出提示。对于较长的剪辑,提高
--max-frames或降低--fps。 - 所有帧使用同一个色调范围(盲文模式下使用同一个点阈值),因此亮度不会跳动。
- 静止区域不会闪烁:像素值在变化超过
--steady(默认 6,范围 0-255)之前保持不变。对于颗粒感胶片,可将其提高到 16 或更高。--steady 0关闭此功能。 - 隔行视频会被去隔行处理,非方形像素的视频会保持其实际形状。
- 避免对动画使用
--dither:它会导致字形在帧之间爬动。 - GIF 的播放速度无法超过约 50 fps,因此快速视频在
.gif中会丢失部分帧。使用.mp4或.webp可获得流畅的 60 fps。
纯色背景上的主体
对于浅色背景上的深色主体,如迈布里奇的奔跑的马,使用 --bg white。这样主体获得墨色,页面保持干净。--mode braille 可获得最锐利的运动主体,而 --mode halfblock 可保留照片的色调。
uv run scripts/animate.py horse.gif --mode braille --bg white -o horse.gif
uv run scripts/animate.py juggler.webm --start 17 --duration 4 --mode braille --subject -o juggler.gif
--subject 仅保留移动的部分,并将其余部分绘制为空白页面(背景为浅色时是白色,除非设置了 --bg)。它需要固定相机:从最多 25 帧的中位数获取背景。注意:
- 在大部分剪辑中保持静止的部分(如头部)会被视为背景并淡出。
- 如果图片边缘不断变化,表示相机在移动:脚本会给出提示并保持帧原样。慢速平移有时无法被检测到,会留下轮廓。
- 在每一帧都是不同照片的剪辑中(如迈布里奇的马和水牛),改用
--bg white。 --subject-cut(默认 40,范围 0-255)是像素与背景差异达到多少才被视为主体。对于模糊主体降低此值,对于噪声视频则提高。
静态图像特效
--effect NAME 将单张图像转换为 2 到 3.2 秒的片头动画(25 fps),最终展示完成的艺术品并保持 1.5 秒。每种特效都适用于所有模式。
matrix:随着明亮头部下落,字符列慢慢显现成最终艺术图。decode:单元格随机闪烁后,从左到右逐步锁定。scan:明亮的 CRT 行向下扫描,逐行输入,带有短时辉光。glitch:短暂的撕裂行、字符交换和红/青色彩带。适合循环播放。wave:行在正弦波上左右摆动,摆动幅度先增强后减弱。适合循环播放。
纯代码场景
--scene NAME 通过代码绘制循环动画,无需输入文件。每个循环持续 2 到 3.2 秒,最后一帧平滑过渡到第一帧。所有模式、颜色选项和输出格式均支持。--seed N 提供变体(火、波浪、星星、雨),--fps 改变流畅度但保持循环长度。
uv run scripts/animate.py --scene fire -o fire.gif # 上升的火焰,暖色调
uv run scripts/animate.py --scene donut -o donut.gif # 旋转、发光、撒糖霜的甜甜圈
uv run scripts/animate.py --scene cube --mode braille -o cube.gif # 翻滚的立方体,明亮边缘
uv run scripts/animate.py --scene waves --mode halfblock -o waves.gif # 月光下的海浪
uv run scripts/animate.py --scene stars -o stars.gif # 飞越星空
uv run scripts/animate.py --scene walker --mode braille -o run.gif # 原地跑步的火柴人
uv run scripts/animate.py --scene rain --mode braille -o rain.gif # 雨和飞溅
uv run scripts/animate.py --scene bounce --mode halfblock -o ball.gif # 弹跳时会变形的球
uv run scripts/animate.py --scene text --mode halfblock -o text.gif # 单词 "ASCII" 在彩虹波浪上骑行
- 使用
-w 60到-w 100。--mode halfblock提供最佳色彩;--mode braille提供最清晰的线条。 - 不使用
-o时,场景在终端中播放。 - 场景是
scripts/scenes.py中的一个普通函数:scene(w, h, n, seed)返回n张可循环的图像。要添加新场景,编写函数并为其添加@scene(width, height, frames, fps)装饰行。
由文字描述生成
当用户描述一个运动物体(如“奔跑的马”)而未提供文件时,首先查找免费素材。scripts/fetch.py 在维基共享资源中搜索动画 GIF 和短视频,选择最佳匹配并下载。
- 获取素材:
uv run scripts/fetch.py "running horse" -o /tmp/clip。它会自动添加正确的扩展名(.gif、.webm),然后打印保存路径和署名信息。如需自行选择,先使用--list,然后使用--pick N。 - 转换打印出的路径:
uv run scripts/animate.py /tmp/clip.gif --mode braille -w 80 --bg white -o out.gif。任何预设都适用。对于长视频,添加--duration 5。 - 查看结果的一帧。如果主体难以辨认,尝试使用
--pick选择其他结果。 - 将署名信息和结果一起提供给用户。大多数许可证(CC BY、CC BY-SA)要求署名。
使用简短、纯英语的词语描述主体和动作。线条画、剪影和纯色背景上的素材最容易被 ASCII 化。杂乱的真实世界视频效果通常不佳。
如果未找到合适的素材,则改用代码绘制的场景:animate.py --scene NAME(见“纯代码场景”)。
Python 使用
import sys; sys.path.insert(0, "scripts")
from PIL import Image
from ascii import convert, to_text, to_png
grid = convert(Image.open("cat.jpg"), width=80, charset="blocks", dither=True)
# 单元格为 (char, (r, g, b))。使用 mode="halfblock" 时为 (char, top_rgb, bottom_rgb)。
# 使用 mode="tiles" 时,瓦片单元格为 (char, ink_rgb, tile_rgb)。
print(to_text(grid))
to_png(grid).save("cat_ascii.png")
from effects import frames # 网格列表;最后一个就是 `grid`
intro = [to_png(g) for g in frames(grid, "decode")]