AsciiLoom, bir görseli GitHub README dosyasında sorunsuz görünen ASCII çizime dönüştürmek için geliştirdiğim bir araç. Tarayıcı stüdyosu ve komut satırı aracı aynı TypeScript dönüşüm çekirdeğini kullanıyor; görsel tarayıcı sekmesinden hiç çıkmıyor.
Problem
Terminal odaklı ASCII paketlerinin çoğu ANSI renklerine ve konsol düzenine göre tasarlanmış. README ise farklı kısıtlar getiriyor:
- ANSI kaçış kodları README’de taşınabilir bir görsel üretmiyor.
- Karakter rampası ters tırnak veya tilde içerse bile çıktı geçerli Markdown kalmalı.
- Eş aralıklı karakter hücreleri genişliğinden uzun olduğu için görseli doğrudan küçültmek konuyu basık gösteriyor.
- Fotoğrafların bu kadar küçültmeden sağ çıkması için algısal parlaklık, yerel ayrıntı kurtarma ve kontrollü dithering gerekiyor.
- Düz Markdown, okuyucunun GitHub temasına uyuyor; renklerin sabit kalması gerekiyorsa ayrı bir SVG çıktısı gerekiyor.
AsciiLoom bu kısıtları sonradan uyarlanmış bir terminal çizicisiyle değil, baştan README için tasarlanmış bir dönüşüm hattıyla ele alıyor.
Bu projede odaklandığım noktalar
- Tarayıcıda yerel işleme: sürükle-bırak, yapıştır veya dosya seç; görsel hiçbir sunucuya yüklenmiyor
- Tarayıcı ve CLI için tek, test edilebilir dönüşüm çekirdeği
- Varsayılan olarak katı ASCII; Unicode stillerini yalnız kullanıcı seçerse kullanmak
- Ne kadar ters tırnak veya tilde içerirse içersin kapanmayan, güvenli Markdown kod bloğu
- Aynı girdiden her zaman aynı çıktıyı üreten deterministik dönüşüm
Öne çıkan özellikler
Dönüşüm hattı
Görsel önce yönüne göre düzeltiliyor ve karakter hücresinin en-boy oranına göre yeniden ölçekleniyor. Ardından son ızgaranın üzerinde örnekleniyor, saydam pikseller seçilen arka planla birleştiriliyor ve sRGB kanalları doğrusallaştırılıp algısal parlaklığa çevriliyor. Hücre ortalamaları CIE L* açıklığına dönüştürülüyor; böylece rampadaki seviyeler görünür tonlara eşit dağılıyor. Yüzdelik otomatik seviye, yerel ayrıntı güçlendirme, gama, kontrast ve parlaklık ayarları ton kontrolünü tamamlıyor.
Stiller ve ön ayarlar
- On yedi karakter stili: katı ASCII ton rampaları, hücredeki karanlık dağılımını glif şekilleriyle eşleştiren
shape, gerçek 2×4 alt hücreli Braille ve köşe, kesişim ve çaprazları izleyen yapısal Unicode readme,portrait,logo,ultraveunicodeön ayarları; her biri yalnızca bir başlangıç noktası- Atkinson, Floyd–Steinberg, sıralı Bayer 4×4 dithering veya dithering olmadan çizim
- Tarayıcıda kaydedilen, JSON olarak dışa ve içe aktarılabilen kişisel ön ayarlar
Üç çıktı biçimi
- Düz ASCII: metin dosyası, terminal veya issue yorumu için
- Markdown: içerikteki en uzun ters tırnak ve tilde dizisine göre sınırlayıcısı seçilen, yapıştırmaya hazır kod bloğu; büyük çizimler için isteğe bağlı açılır
<details>bloğu - SVG: sabit arka plan ve ön plan rengi, erişilebilir
<title>ve geniş glifleri kırpmayan hücre genişlikleriyle temadan bağımsız çıktı
Kullanım
Kurulum gerekmeden asciiloom.aliyilmaz.co adresinden kullanılabiliyor. CLI, npm’de asciiloom adıyla yayımlanıyor:
npm install --global asciiloom
asciiloom ./photo.jpg --preset readme --output ./ascii-photo.md
Metin, Markdown ve SVG çıktısını birlikte üretmek için:
asciiloom ./logo.png --preset logo --format all --output ./docs/logo-ascii
Teknik mimari
Dönüşüm çekirdeği DOM, Canvas, Node veya Sharp’a bağımlı değil; ham RGB/RGBA piksel verisi alıyor. Bu yüzden tarayıcı ve CLI aynı sonucu üretiyor ve birim testleri hızlı çalışıyor. Tarayıcıda dönüşüm ayrı bir worker’da yürüyor. CLI ise görseli Sharp ile çözüyor, piksel işlemeden önce bütün hedef dosyaları doğruluyor ve her dosyayı atomik bir yeniden adlandırmayla yazıyor. Web arayüzü bir çatıya bağlı olmadan statik olarak derleniyor ve Cloudflare Workers üzerinde yayımlanıyor.
Doğrulama
Yayın kontrolü sıkı TypeScript denetimini, kapsam eşiklerini, Chromium üzerinde uçtan uca tarayıcı testini ve 390 piksel mobil yerleşim kontrolünü çalıştırıyor. Gerçek npm paketini boş bir projeye kurup kurulu CLI’nin depodaki bütün metin, Markdown ve SVG örneklerini bayt bayt aynı ürettiğini de doğruluyor.
Sınırlar
- Çok geniş kod blokları mobilde yatay kayabiliyor; genel bir README için 70–96 sütun iyi bir başlangıç.
- Markdown kod bloğunun renkleri okuyucunun GitHub temasına bağlı; sabit renk için SVG kullanılmalı.
- Unicode stillerinin görünümü seçilen eş aralıklı yazı tipine ve platforma göre değişiyor; en taşınabilir seçenek katı ASCII.
- Tarayıcıda kaynak görsel 32 MiB ve 40 megapikselle, çıktı yüksekliği 400 satırla sınırlı.
Bağlantılar
- Canlı uygulama: asciiloom.aliyilmaz.co
- GitHub deposu: github.com/aliyilmazco/asciiloom
- npm paketi: asciiloom (yalnız CLI)
- Son sürüm: v1.0.0
- Lisans: MIT