1CHAFA(1)                         User Commands                        CHAFA(1)
2
3
4

NAME

6       chafa - Character art facsimile generator
7

SYNOPSIS

9       chafa [OPTION...] [IMAGE...]
10

DESCRIPTION

12       chafa is a utility that converts all kinds of images, including
13       animated GIFs, into (potentially animated) ANSI/Unicode character
14       output that can be displayed in a terminal. It supports alpha
15       transparency and multiple color modes and color spaces, and combines a
16       range of Unicode characters for optimal output.
17
18       You can specify one or more input files, but the default behavior is
19       slightly different with multiple files -- for instance, animations will
20       not loop forever when there is more than one input file.
21

OPTIONS

23       --bg color
24           Background color of display (color name or hex). Partially
25           transparent input will be blended with this color. Color names are
26           based on those provided with X.Org. Defaults to black.
27
28       --clear
29           Clear screen before processing each file.
30
31       -c mode, --colors mode
32           Set output color mode; one of [none, 2, 16, 240, 256, full].
33           Defaults to full (24-bit). The 240-color mode is recommended over
34           the 256-color one, since the lower 16 colors are unreliable and
35           tend to differ between terminals. 16-color mode will use aixterm
36           extensions to produce 16 foreground and background colors. 2-color
37           mode will only emit the ANSI codes for reverse color and attribute
38           reset, while "none" will emit no ANSI color codes whatsoever.
39
40       --color-space cs
41           Color space used for quantization; one of [rgb, din99d]. Defaults
42           to rgb, which is faster but less accurate.
43
44       --dither type
45           Type of dithering to apply during quantization. One of [none,
46           ordered, diffusion]. "Bayer" is a synonym for "ordered", and "fs"
47           (Floyd-Steinberg) is a synonym for "diffusion".
48
49       --dither-grain widthxheight
50           Dimensions of grain used when dithering. Specified as width x
51           height, where each can be one of [1, 2, 4, 8] pixels. One character
52           cell is by definition 8 pixels across in both dimensions. Defaults
53           to 4x4.
54
55       --dither-intensity intensity
56           Intensity of dithering pattern. Ranges from 0.0 to infinity, with
57           1.0 considered neutral. Lower values tend to reduce the amount of
58           dithering done, while higher values increase it. In practice,
59           values higher than 10.0 are unlikely to produce useful results.
60
61       -d, --duration seconds
62           Time to show each file. If showing a single file, defaults to zero
63           for a still image and infinite for an animation. For multiple
64           files, defaults to 3.0. Animations will always be played through at
65           least once.
66
67       --fg color
68           Foreground color of display (color name or hex). Together with the
69           background color specified by --bg, this specifies the terminal's
70           palette in color modes 2 and none. Color names are based on those
71           provided with X.Org. Defaults to white.
72
73       --fill symbols
74           Specify character symbols to use for fill/gradients. Defaults to
75           none. Usage is similar to that of --symbols; see below.
76
77       --font-ratio width/height
78           Target font's width/height ratio. Can be specified as a real number
79           or a fraction. Defaults to 1/2.
80
81       -h, --help
82           Show a brief help text.
83
84       --invert
85           Invert video. For display with bright backgrounds in color modes 2
86           and none. Swaps --fg and --bg.
87
88       -p bool, --preprocess bool
89           Image preprocessing [on, off]. Defaults to on with 16 colors or
90           lower, off otherwise. This enhances colors and contrast prior to
91           conversion, which can be useful in low-color modes.
92
93       -s widthxheight, --size widthxheight
94           Set maximum output dimensions in columns and rows. By default this
95           will be the size of your terminal, or 80x25 if size detection
96           fails.
97
98       --stretch
99           Stretch image to fit output dimensions; ignore aspect. Implies
100           --zoom.
101
102       --symbols symbols
103           Specify character symbols to employ in final output. See below for
104           full usage and a list of symbol classes.
105
106       -t threshold, --threshold threshold
107           Threshold above which full transparency will be used [0.0 - 1.0].
108           Setting this to 0.0 will render a blank image, while a value of 1.0
109           will replace any transparency with the background color
110           (configurable with --bg).
111
112       --version
113           Show version, feature and copyright information.
114
115       --watch
116           Watch a single input file, redisplaying it whenever its contents
117           change. Will run until manually interrupted or, if --duration is
118           set, until it expires.
119
120       -w num, --work num
121           How hard to work in terms of CPU and memory [1-9]. 1 is the
122           cheapest, 9 is the most accurate. Defaults to 5.
123
124       --zoom
125           Allow scaling up beyond one character per pixel.
126

SYMBOLS

128       Accepted classes for --symbols are [all, none, space, solid, stipple,
129       block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted,
130       braille, technical, geometric, ascii]. Some symbols belong to multiple
131       classes, e.g. diagonals are also borders.
132
133       You can specify a list of classes separated by commas, or prefix them
134       with + and - to add or remove symbols relative to the existing set. The
135       ordering is significant.
136
137       The default symbol set is
138       all-stipple-braille-ascii+space-extra-inverted for all modes except for
139       "none", which uses all-stipple-braille-ascii+space-extra.
140

EXAMPLES

142       chafa in.gif
143           Show a potentially animated GIF image in the terminal. If this is
144           an animation, it will run until the user generates an interrupt
145           (typically ctrl-c). All parameters will be autodetected based on
146           the current environment.
147
148       chafa -c full -s 200 in.gif
149           Like the above, but force truecolor output that is 200 characters
150           wide and calculate the height preserving the aspect of the original
151           image.
152
153       chafa -c 16 --color-space din99d --symbols -dot in.jpg
154           Generate 16-color output with perceptual color picking and avoid
155           using dot symbols.
156
157       chafa -c none --symbols block+border-solid in.png
158           Generate uncolored output using block and border symbols, but avoid
159           the solid block symbol.
160

AUTHOR

162       Written by Hans Petter Jansson <hpj@copyleft.no>.
163
164
165
166chafa                                                                 CHAFA(1)
Impressum