'\" t
.\"     Title: chafa
.\"    Author: Hans Petter Jansson
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 11/26/2020
.\"    Manual: User Commands
.\"    Source: chafa
.\"  Language: English
.\"
.TH "CHAFA" "1" "" "chafa" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
chafa \- Character art facsimile generator
.SH "SYNOPSIS"
.HP \w'\fBchafa\fR\ 'u
\fBchafa\fR [OPTION...] [IMAGE...]
.SH "DESCRIPTION"
.PP
\fBchafa\fR
is a utility that converts all kinds of images, including animated GIFs, into (potentially animated) ANSI/Unicode character output that can be displayed in a terminal\&. It supports alpha transparency and multiple color modes and color spaces, and combines a range of Unicode characters for optimal output\&.
.PP
You can specify one or more input files, but the default behavior is slightly different with multiple files \-\- for instance, animations will not loop forever when there is more than one input file\&.
.SH "OPTIONS"
.PP
\fB\-\-bg \fR\fB\fIcolor\fR\fR
.RS 4
Background color of display (color name or hex)\&. Partially transparent input will be blended with this color\&. Color names are based on those provided with X\&.Org\&. Defaults to black\&.
.RE
.PP
\fB\-\-clear\fR
.RS 4
Clear screen before processing each file\&.
.RE
.PP
\fB\-c \fR\fB\fImode\fR\fR\fB, \-\-colors \fR\fB\fImode\fR\fR
.RS 4
Set output color mode; one of [none, 2, 16, 240, 256, full]\&. Defaults to full (24\-bit)\&. The 240\-color mode is recommended over the 256\-color one, since the lower 16 colors are unreliable and tend to differ between terminals\&. 16\-color mode will use aixterm extensions to produce 16 foreground and background colors\&. 2\-color mode will only emit the ANSI codes for reverse color and attribute reset, while "none" will emit no ANSI color codes whatsoever\&.
.sp
In sixel mode, "full" will dynamically generate a 256\-color palette for each image or animation frame\&. The other modes refer to built\-in palettes\&. "none" and "2" are interchangeable and will use the specified foreground/background colors (see \-\-fg and \-\-bg)\&.
.RE
.PP
\fB\-\-color\-extractor \fR\fB\fIextractor\fR\fR
.RS 4
Method for extracting color from an area; one of [average, median]\&. Median normally produces crisper output, while average may perform better on noisy images\&. Defaults to median\&.
.RE
.PP
\fB\-\-color\-space \fR\fB\fIcs\fR\fR
.RS 4
Color space used for quantization; one of [rgb, din99d]\&. Defaults to rgb, which is faster but less accurate\&.
.RE
.PP
\fB\-\-dither \fR\fB\fItype\fR\fR
.RS 4
Type of dithering to apply during quantization\&. One of [none, ordered, diffusion]\&. "Bayer" is a synonym for "ordered", and "fs" (Floyd\-Steinberg) is a synonym for "diffusion"\&.
.RE
.PP
\fB\-\-dither\-grain \fR\fB\fIwidth\fR\fR\fBx\fR\fB\fIheight\fR\fR
.RS 4
Dimensions of grain used when dithering\&. Specified as width x height, where each can be one of [1, 2, 4, 8] pixels\&. One character cell is by definition 8 pixels across in both dimensions\&. Defaults to 4x4 in symbol mode and 1x1 in sixel mode\&.
.RE
.PP
\fB\-\-dither\-intensity \fR\fB\fIintensity\fR\fR
.RS 4
Intensity of dithering pattern\&. Ranges from 0\&.0 to infinity, with 1\&.0 considered neutral\&. Lower values tend to reduce the amount of dithering done, while higher values increase it\&. In practice, values higher than 10\&.0 are unlikely to produce useful results\&.
.RE
.PP
\fB\-d, \-\-duration \fR\fB\fIseconds\fR\fR
.RS 4
Time to show each file, in seconds\&. Defaults to zero for still images and for animations when multiple files are specified\&. If a single animation is specified, defaults to infinite\&. Animations will always be played through at least once, even if duration is e\&.g\&. zero\&.
.RE
.PP
\fB\-\-fg \fR\fB\fIcolor\fR\fR
.RS 4
Foreground color of display (color name or hex)\&. Together with the background color specified by \-\-bg, this specifies the terminal\*(Aqs palette in color modes 2 and none\&. Color names are based on those provided with X\&.Org\&. Defaults to white\&.
.RE
.PP
\fB\-\-fill \fR\fB\fIsymbols\fR\fR
.RS 4
Specify character symbols to use for fill/gradients\&. Defaults to none\&. Usage is similar to that of \-\-symbols; see below\&.
.RE
.PP
\fB\-\-font\-ratio \fR\fB\fIwidth\fR\fR\fB/\fR\fB\fIheight\fR\fR
.RS 4
Target font\*(Aqs width/height ratio\&. Can be specified as a real number or a fraction\&. Defaults to 1/2\&.
.RE
.PP
\fB\-f, \-\-format \fR\fB\fIformat\fR\fR
.RS 4
Set output format; one of [sixels, symbols]\&. The default is sixels if there is a sixel\-capable terminal connected, otherwise symbols will be used\&. Sixels yield much better quality, but support for it is fairly rare\&.
.RE
.PP
\fB\-\-glyph\-file \fR\fB\fIfile\fR\fR
.RS 4
Load glyph information from file, which can be any font file supported by FreeType (TTF, PCF, etc)\&. The glyph outlines will replace any existing outlines, including builtins\&. Useful in symbol mode for custom font support or for improving quality with a specific font\&. Note that this only makes sense if the output terminal is using a matching font\&. Can be specified multiple times\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show a brief help text\&.
.RE
.PP
\fB\-\-invert\fR
.RS 4
Invert video\&. For display with bright backgrounds in color modes 2 and none\&. Swaps \-\-fg and \-\-bg\&.
.RE
.PP
\fB\-p \fR\fB\fIbool\fR\fR\fB, \-\-preprocess \fR\fB\fIbool\fR\fR
.RS 4
Image preprocessing [on, off]\&. Defaults to on with 16 colors or lower, off otherwise\&. This enhances colors and contrast prior to conversion, which can be useful in low\-color modes\&.
.RE
.PP
\fB\-s \fR\fB\fIwidth\fR\fR\fBx\fR\fB\fIheight\fR\fR\fB, \-\-size \fR\fB\fIwidth\fR\fR\fBx\fR\fB\fIheight\fR\fR
.RS 4
Set maximum output dimensions in columns and rows\&. By default this will be the size of your terminal, or 80x25 if size detection fails\&.
.RE
.PP
\fB\-\-speed \fR\fB\fIspeed\fR\fR
.RS 4
Set the speed animations will play at\&. This can be either a unitless multiplier (fractions are allowed), or a real number followed by "fps" to apply a specific framerate\&.
.RE
.PP
\fB\-\-stretch\fR
.RS 4
Stretch image to fit output dimensions; ignore aspect\&. Implies \-\-zoom\&.
.RE
.PP
\fB\-\-symbols \fR\fB\fIsymbols\fR\fR
.RS 4
Specify character symbols to employ in final output\&. See below for full usage and a list of symbol classes\&.
.RE
.PP
\fB\-t \fR\fB\fIthreshold\fR\fR\fB, \-\-threshold \fR\fB\fIthreshold\fR\fR
.RS 4
Threshold above which full transparency will be used [0\&.0 \- 1\&.0]\&. Setting this to 0\&.0 will render a blank image, while a value of 1\&.0 will replace any transparency with the background color (configurable with \-\-bg)\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Show version, feature and copyright information\&.
.RE
.PP
\fB\-\-watch\fR
.RS 4
Watch a single input file, redisplaying it whenever its contents change\&. Will run until manually interrupted or, if \-\-duration is set, until it expires\&.
.RE
.PP
\fB\-w \fR\fB\fInum\fR\fR\fB, \-\-work \fR\fB\fInum\fR\fR
.RS 4
How hard to work in terms of CPU and memory [1\-9]\&. 1 is the cheapest, 9 is the most accurate\&. Defaults to 5\&.
.RE
.PP
\fB\-\-zoom\fR
.RS 4
Allow scaling up beyond one character per pixel\&.
.RE
.SH "SYMBOLS"
.PP
Accepted classes for \-\-symbols are [all, none, space, solid, stipple, block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted, braille, technical, geometric, ascii]\&. Some symbols belong to multiple classes, e\&.g\&. diagonals are also borders\&.
.PP
You can specify a list of classes separated by commas, or prefix them with + and \- to add or remove symbols relative to the existing set\&. The ordering is significant\&.
.PP
The default symbol set is all\-stipple\-braille\-ascii+space\-extra\-inverted for all modes except for "none", which uses all\-stipple\-braille\-ascii+space\-extra\&.
.SH "EXAMPLES"
.PP
chafa in\&.gif
.RS 4
Show a potentially animated GIF image in the terminal\&. If this is an animation, it will run until the user generates an interrupt (typically ctrl\-c)\&. All parameters will be autodetected based on the current environment\&.
.RE
.PP
chafa \-c full \-s 200 in\&.gif
.RS 4
Like the above, but force truecolor output that is 200 characters wide and calculate the height preserving the aspect of the original image\&.
.RE
.PP
chafa \-c 16 \-\-color\-space din99d \-\-symbols \-dot in\&.jpg
.RS 4
Generate 16\-color output with perceptual color picking and avoid using dot symbols\&.
.RE
.PP
chafa \-c none \-\-symbols block+border\-solid in\&.png
.RS 4
Generate uncolored output using block and border symbols, but avoid the solid block symbol\&.
.RE
.SH "FURTHER READING"
.PP
See the
\m[blue]\fBChafa homepage\fR\m[]\&\s-2\u[1]\d\s+2
for more information\&.
.SH "AUTHOR"
.PP
Written by
\m[blue]\fBHans Petter Jansson\fR\m[]\&\s-2\u[2]\d\s+2
<hpj@copyleft\&.no>\&.
.SH "NOTES"
.IP " 1." 4
Chafa homepage
.RS 4
\%https://hpjansson.org/chafa/
.RE
.IP " 2." 4
Hans Petter Jansson
.RS 4
\%https://hpjansson.org/
.RE