'\" t
.\"     Title: chafa
.\"    Author: Hans Petter Jansson
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/09/2019
.\"    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\&.
.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\-d, \-\-duration \fR\fB\fIseconds\fR\fR
.RS 4
Time to show each file\&. If showing a single file, defaults to zero for a still image and infinite for an animation\&. For multiple files, defaults to 3\&.0\&. Animations will always be played through at least once\&.
.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\-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\-\-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 "AUTHOR"
.PP
Written by Hans Petter Jansson
<hpj@copyleft\&.no>\&.