ASCII 藝術 是做什麼的?
scripts/ascii.py 製作靜態圖片,scripts/animate.py 製作動畫(請參考「動畫」章節)。兩者僅需 Python 3.9+ 與 Pillow(影片需額外安裝 ffmpeg)。若已安裝 uv,uv run 會自動下載 Pillow。
uv run scripts/ascii.py 圖片 [選項] # 或:python3 scripts/ascii.py(需安裝 pillow)
以下路徑均相對於此技能資料夾。
步驟
- 取得圖片路徑。若是網址,請先使用
curl -L -o /tmp/in.img 網址下載。 - 選擇輸出方式。使用 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 - 復古琥珀色終端機:
-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。 - 所有幀使用相同的色調範圍(以及在 braille 模式中相同的點閾值),因此亮度不會波動。
- 靜止區域不會閃爍:像素會保留其值,直到變化超過
--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 名稱 將一張圖片轉換為 2 到 3.2 秒的開場動畫(25 fps),以完成的藝術圖結尾並停留 1.5 秒。所有特效均可與所有模式搭配使用。
matrix:下降的字形柱,帶有明亮的頭部,在其後留下藝術圖。decode:儲存格隨機變換字形並鎖定,從左向右掃過。scan:一條明亮的 CRT 線條向下掃描並逐行輸入文字,帶有短暫的光暈。glitch:短暫的撕裂行、字形交換與紅/青色帶狀爆發。適合循環播放。wave:行在正弦波上左右搖擺,波幅先擴大再平靜。適合循環播放。
場景
--scene 名稱 以程式碼繪製一個循環動畫,因此無需輸入檔案。每個循環為 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 名稱(請參考「場景」章節)。
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")]