ascii-view - GitLite

KO | EN

gitlite — search

#javascript #llm #android #machine-learning #linux #docker #macos #windows #awesome #kubernetes #awesome-list #pytorch #ios #openai

ascii-view

(★ 443)

A command-line tool that displays images as colorized ASCII art in the terminal.

파일 탐색기

최종 버전 다운로드 (.zip)

- coverphoto-1.jpg
- coverphoto-2.jpg
- black-and-white.jpg
- cacti.jpg
- contrast.jpg
- pedestrians.jpg
- puffin.jpg
- true-grayscale.jpg
- waterfall.jpg
- argparse.h
- image.h
- print_image.h
- stb_image.h
- argparse.c
- image.c
- main.c
- print_image.c
.gitattributes
.gitignore
LICENSE
makefile
README.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/gouwsxander/ascii-view

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd ascii-view

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Make

보통 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Make Linux/macOS는 보통 기본 설치되어 있습니다. Windows는 별도 설치(예: MSYS2, WSL)가 필요합니다.

make

생성된 빌드 설정을 바탕으로 실제 컴파일을 진행해 실행 파일을 만듭니다.

make release

생성된 빌드 설정을 바탕으로 실제 컴파일을 진행해 실행 파일을 만듭니다.

make clean

생성된 빌드 설정을 바탕으로 실제 컴파일을 진행해 실행 파일을 만듭니다.

✅ 에러 없이 끝나면 성공입니다. 생성된 실행 파일을 직접 실행해보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ASCII View

A command-line tool that displays images as colorized ASCII art in the terminal.

![Cover photo](https://raw.githubusercontent.com/gouwsxander/ascii-view/main/cover-photos/coverphoto-1.jpg)

## Features
- **Multi-format support**: Supports JPEG, PNG, BMP, and other common image formats via [stb_image](https://github.com/nothings/stb)
- **Color terminal output**: Uses ANSI color codes for colors
- **Intelligent resizing**: Scales images to fit the terminal's constrained dimensions while maintaining aspect ratio
- **Terminal-optimized**: Adjusts for typical terminal font aspect ratios (characters are taller than they are wide)
- **Edge enhancement**: Uses Sobel filtering to enhance edges

## Building

This project can be built with Make:
```bash
# Development version
make

# Release version compiled with optimizations
make release
```

To clean build artifacts:
```bash
make clean
```

Requirements:
- C99-compatible compiler (GCC, Clang)
- Make build system

## Usage

```bash
./ascii-view <path/to/image> [OPTIONS]
```

### Options

- `-mw <width>`: Maximum width in characters (default: terminal width OR 64)
- `-mh <height>`: Maximum height in characters (default: terminal height OR 48)
- `-et <threshold>`: Edge detection threshold, range: 0.0 - 4.0 (default 4.0, disabled)
- `-cr <ratio>`: Height-to-width ratio for characters (default 2.0)
- `--retro-colors`: Uses 3-bit colors for pixels.

### Examples

```bash
# Basic usage with default dimensions
./ascii-view examples/puffin.jpg

# Specify custom dimensions
./ascii-view examples/waterfall.jpg -mw 120 -mh 60

# Specify edge threshold
./ascii-view examples/black-and-white.jpg -et 2.5

# Specify character aspect ratio
./ascii-view examples/cacti.jpg -cr 1.7
```

The images in the `examples` directory are via [Unsplash](https://unsplash.com)

### Suggestions for getting good looking results
1. If you make your font size smaller, you can make the pictures larger
2. The results are limited by your terminal's colour scheme
3. If you squint your eyes the images look great!

![Cover photo](https://raw.githubusercontent.com/gouwsxander/ascii-view/main/cover-photos/coverphoto-2.jpg)

## How It Works

1. **Image loading**: Uses stb_image to load various image formats
2. **Aspect ratio correction**: Accounts for terminal character dimensions (typically ~2:1 height to width ratio[^1])
3. **Area averaging**: When downsampling, averages pixel values in rectangular regions for smooth results
4. **Color analysis**: Converts RGB pixels to HSV color space to determine:
   - **Hue**: Maps to ANSI terminal colors (red, green, blue, cyan, magenta, yellow)
   - **Saturation**: Low saturation pixels display as white
   - **Value**: Used to calculate brightness for ASCII character selection
5. **ASCII mapping**: Maps brightness levels to ASCII characters: ` .-=+*x#$&X@`
6. **Edge enhancement**: Finds edges and angles with a Sobel filter, enhances edges with `_/|\`

[^1]: Some terminals support the ability to extract the exact font ratio, but others don't. For the time being we assume a 2:1 ratio, with ability to change it through the `-cr` option.