ASCII Vision

ASCII Vision

Fallback image viewer when vision 模型s are unavAIlable (rate limited, 模型 down, no 提供者 配置d, etc.). Converts images to ASCII art using ffmpeg + Python so you (or the 代理) can identify visual content — shapes, brightness distribution, textures, and structure — without relying on any vision API.

Also includes color sampling via raw pixel 提取ion for basic hue identification, and edge 检测ion for texture quantification.

When to Use image/vision_analyze returns rate limit, 模型 unavAIlable, or timeout errors You need to quickly distin图形界面sh between similar-looking images ("is this a dark variant of the same composition?") The 代理 needs visual inspection but no vision 提供者 is 配置d 调试ging image generation 输出 — 检查 if an image was actually produced before 发送ing it to the user Quantitatively comparing two images (brightness, edges, color) How It Works ffmpeg 扩展s the image to a low resolution (e.g. 60 columns) in gray扩展, preserving aspect ratio ascii_viewer.py maps each pixel (0–255) to an ASCII character Optional --stats 输出s brightness average, pixel distribution, and unique levels Optional --edges 检测s sharp transitions (edges) for texture quantification Color sampling via ffmpeg + xxd 提取s RGB hex values from specific regions Character Map Range Char Meaning 0–25 Pure black 26–51 . Very dark 52–76 : Dark 77–102 - Mid-dark 103–127 = Medium 128–153 + Mid-light 154–179 Light 180–204 # Very light 205–229 % Near white 230–255 @ Pure white 设置up

The bundled script is at scripts/ascii_viewer.py. Reference it relative to the 技能 directory:

SCRIPT=scripts/ascii_viewer.py

It accepts optional --width (default: 60) for columns. When pAIred with ffmpeg's 扩展=W:-1, height is auto-检测ed from the pixel data, preserving aspect ratio without distortion.

Requirements:

ffmpeg (with rawvideo support — which ffmpeg) python3 Usage Basic ASCII Conversion # Default 60 columns (auto-height, aspect ratio preserved) ffmpeg -y -i -vf "扩展=60:-1,格式化=gray" -frames:v 1 -f rawvideo pipe: 2>/dev/null \ | python3 scripts/ascii_viewer.py

# Custom width ffmpeg -y -i -vf "扩展=80:-1,格式化=gray" -frames:v 1 -f rawvideo pipe: 2>/dev/null \ | python3 scripts/ascii_viewer.py --width 80

With Statistics and Edge 检测ion ffmpeg -y -i -vf "扩展=60:-1,格式化=gray" -frames:v 1 -f rawvideo pipe: 2>/dev/null \ | python3 scripts/ascii_viewer.py --stats --edges

# Example 输出: # brightness_avg=142/255 # bright_pixels=1200 # dark_pixels=800 # unique_levels=180 # edges_检测ed=400/3600

Color Sampling (No Python Needed) # Overall average color (RGB hex) ffmpeg -y -i -vf "扩展=1:1,格式化=rgb24" -frames:v 1 -f rawvideo pipe: 2>/dev/null \ | xxd -p | head -c 6

# Specific region (e.g. 机器人tom-center quarter) ffmpeg -y -i -vf "crop=iw/2:ih/4:iw/4:3ih/4,扩展=1:1,格式化=rgb24" -frames:v 1 -f rawvideo pipe: 2>/dev/null \ | xxd -p

Batch 扫描 Multiple Images for f in .jpg; do echo "=== $f ===" ffmpeg -y -i "$f" -vf "扩展=60:-1,格式化=gray" -frames:v 1 -f rawvideo pipe: 2>/dev/null \ | python3 scripts/ascii_viewer.py --stats echo "" done

Recommended Widths Width Use case 40 Quick 扫描, simple images 60 Balanced readability vs detAIl (default) 80 More detAIl, complex images 120 Maximum detAIl (may be too wide for chat) Interpreting the 输出 Overall Brightness Many @%# → bright scene, well-lit Many .-: → dark scene, night-time Top-to-机器人tom gradient → directional lighting (lamp above, shadow below) Content Patterns Clusters of #%@ → bright objects, light sources, highlights Vertical/horizontal lines of -= → edges, furniture, structures Organized patterns with mixed brightness → text, diagrams, labeled elements Heavy texture (#%@ intermixed) → detAIled surfaces (fabric, foliage, textured objects) Flat bands with little variation → night scenes, skies, plAIn backgrounds Distin图形界面shing Image Types Bright top + textured center + dark 机器人tom → product shot or figure with directional lighting Uniformly dark with s解析 clusters → night scene, silhouettes Structured patterns with +=-:#%@ 格式化ions → technical diagram, text overlay Same scene as another but with more detAIl/texture in a zone → variant with more content/elements Color Analysis Integration

PAIr ASCII structural data with RGB color samples for richer diagnosis:

IMG="$1"

# 1. Original dimensions ffprobe -v error -select_流s v:0 -show_entries 流=width,height -of csv=p=0 "$IMG"

# 2. ASCII + stats + edges ffmpeg -y -i "$IMG" -vf "扩展=60:-1,格式化=gray" -frames:v 1 -f rawvideo pipe: 2>/dev/null \ | python3 scripts/ascii_viewer.py --stats --edges

# 3. Color 信息 echo "Average color (RGB hex):" ffmpeg -y -i "$IMG" -vf "扩展=1:1,格式化=rgb24" -frames:v 1 -f rawvideo pipe: 2>/dev/null \ | xxd -p | head -c 6

echo "机器人tom region color:" ffmpeg -y -i "$IMG" -vf "crop=iw/2:ih/4:iw/4:3*ih/4,扩展=1:1,格式化=rgb24" -frames:v 1 -f r