.\" vi:set wm=5
.TH IMG2SIXEL 1 "Aug 2016"
.if n .ds Q \&"
.if n .ds U \&"
.if t .ds Q ``
.if t .ds U ''
.UC 4
.SH NAME
img2sixel \- image converter to DEC SIXEL graphics


.SH SYNOPSIS
.B img2sixel
[ \-\fIoptions\fP ] \fIimagefiles\fP
.br
.B img2sixel
[ \-\fIoptions\fP ] < \fIimagefiles\fP
.ta .5i 1.8i


.SH DESCRIPTION
\fIimg2sixel\fP converts various images into high quality DEC SIXEL image format.


.SH "COMMAND-LINE OPTIONS"
\fIimg2sixel\fP has the following command-line options:
.TP 5
.B \-o, \-\-outfile
specify output file name (default:stdout).
.TP 5
.B \-7, \-\-7bit-mode
generate a sixel image for 7bit terminals or printers (default).
.TP 5
.B \-8, \-\-8bit-mode
generate a sixel image for 8bit terminals or printers.
.TP 5
.B \-R, \-\-gri-limit
limit arguments of DECGRI('!') to 255.
.TP 5
.B \-p \fICOLORS\fP, \-\-colors=\fICOLORS\fP
specify number of colors to reduce the image to (default=256).
.TP 5
.B \-m \fIFILE\fP, \-\-mapfile=\fIFILE\fP
transform image colors to match this set of colorsspecify map.
.TP 5
.B \-e, \-\-monochrome
output monochrome sixel image.
this option assumes the terminal background color is black.
.TP 5
.B \-k, \-\-insecure
allow to connect to SSL sites without certs
(enabled only when configured with --with-libcurl)
.TP 5
.B \-i, \-\-invert
assume the terminal background color is white.
make sense only when -e option is given.
.TP 5
.B \-I, \-\-high-color
output 15bpp sixel image
.TP 5
.B \-u, \-\-use-macro
use DECDMAC and DEVINVM sequences to optimize GIF animation rendering.
.TP 5
.B \-n \fIMACRONO\fP, \-\-macro-number=\fIMACRONO\fP
specify an number argument for DECDMAC and make terminal memorize
SIXEL image. No image is shown if this option is specified
.TP 5
.B \-C \fICOMPLEXIONSCORE\fP, \-\-complexion-score=\fICOMPLEXIONSCORE\fP
specify an number argument for the score of complexion correction.
\fICOMPLEXIONSCORE\fP must be 1 or more.
.TP 5
.B \-g, \-\-ignore-delay
render GIF animation without delay.
.TP 5
.B \-S, \-\-static
render animated GIF as a static image.
.TP 5
.B \-d \fIDIFFUSIONTYPE\fP, \-\-diffusion=\fIDIFFUSIONTYPE\fP
choose diffusion method which used with color reduction.
.br
\fIDIFFUSIONTYPE\fP is one of them:
.br
auto     -> choose diffusion type automatically (default)
.br
none     -> do not diffuse
.br
fs       -> Floyd-Steinberg method
.br
atkinson -> Bill Atkinson's method
.br
jajuni   -> Jarvis, Judice & Ninke
.br
stucki   -> Stucki's method
.br
burkes   -> Burkes' method
.br
a_dither -> positionally stable arithmetic dither
.br
x_dither -> positionally stable arithmetic xor based dither
.TP 5
.B \-f \fIFINDTYPE\fP, \-\-find\-largest=\fIFINDTYPE\fP
choose method for finding the largest dimension of median
cut boxes for splitting, make sense only when -p option
(color reduction) is specified.
.br
\fIFINDTYPE\fP is one of them:
.br
auto -> choose finding method automatically (default)
.br
norm -> simply comparing the range in RGB space
.br
lum  -> transforming into luminosities before the comparison
.TP 5
.B \-s \fISELECTTYPE\fP, \-\-select\-color=\fISELECTTYPE\fP
choose the method for selecting representative color from each
median-cut box, make sense only when -p option (color reduction) is
specified.
.br
\fISELECTTYPE\fP is one of them:
.br
auto     -> choose selecting method automatically (default)
.br
center   -> choose the center of the box
.br
average  -> calculate the color average into the box
.br
histogram -> similar with average but considers color histogram
.TP 5
.B \-c \fIREGION\fP, \-\-crop=\fIREGION\fP
crop source image to fit the specified geometry.
.br
REGION should be formatted as '%dx%d+%d+%d'.
.TP 5
.B \-w \fIWIDTH\fP, \-\-width=\fIWIDTH\fP
resize image to specified width.
.br
\fIWIDTH\fP is represented by the following syntax:
.br
auto       -> preserving aspect ratio (default)
.br
<number>%  -> scale width with given percentage
.br
<number>   -> scale width with pixel counts
.br
<number>px -> scale width with pixel counts
.TP 5
.B \-h \fIHEIGHT\fP, \-\-height=\fIHEIGHT\fP
resize image to specified height.
.br
\fIHEIGHT\fP is represented by the following syntax
.br
auto       -> preserving aspect ratio (default)
.br
<number>%  -> scale height with given percentage
.br
<number>   -> scale height with pixel counts
.br
<number>px -> scale height with pixel counts
.TP 5
.B \-r \fIRESAMPLINGTYPE\fP, \-\-resampling=\fIRESAMPLINGTYPE\fP
choose resampling method used with -w or -h option (scaling).
.br
\fIRESAMPLINGTYPE\fP is one of them:
.br
nearest  -> Nearest-Neighbor method
.br
gaussian -> Gaussian filter
.br
hanning  -> Hanning filter
.br
hamming  -> Hamming filter
.br
bilinear -> Bilinear filter (default)
.br
welsh    -> Welsh filter
.br
bicubic  -> Bicubic filter
.br
lanczos2 -> Lanczos-2 filter
.br
lanczos3 -> Lanczos-3 filter
.br
lanczos4 -> Lanczos-4 filter
.TP 5
.B \-q \fIQUALITYMODE\fP, \-\-quality=\fIQUALITYMODE\fP
select quality of color quanlization.
.br
\fIQUALITYMODE\fP is one of them:
.br
auto -> decide quality mode automatically (default)
.br
high -> high quality and low speed mode
.br
low  -> low quality and high speed mode
.br
full -> quality and careful speed mode
.TP 5
.B \-l \fILOOPMODE\fP, \-\-loop\-control=\fILOOPMODE\fP
select loop control mode for GIF animation.
.br
auto    -> honer the setting of GIF header (default)
.br
force   -> always enable loop
.br
disable -> always disable loop
.TP 5
.B \-t \fIPALETTETYPE\fP, \-\-palette\-type=\fIPALETTETYPE\fP
select palette color space type.
.br
auto -> choose palette type automatically (default)
.br
hls  -> use HLS color space
.br
rgb  -> use RGB color space
.TP 5
.B \-b \fIBUILTINPALETTE\fP, \-\-builtin\-palette=\fIBUILTINPALETTE\fP
select built-in palette type
.br
xterm16    -> X default 16 color map
.br
xterm256   -> X default 256 color map
.br
vt340mono  -> VT340 monochrome map
.br
vt340color -> VT340 color map
.TP 5
.B \-E \fIENCODEPOLICY\fP, \-\-encode\-policy=\fIENCODEPOLICY\fP
select encoding policy
.br
auto -> choose encoding policy automatically (default)
.br
fast -> encode as fast as possible
.br
size -> encode to as small sixel sequence as possible
.TP 5
.B \-B \fIBGCOLOR\fP, \-\-bgcolor=\fIBGCOLOR\fP
.br
specify background color
.br
\fIBGCOLOR\fP is represented by the following syntax
.br
#rgb
.br
#rrggbb
.br
#rrrgggbbb
.br
#rrrrggggbbbb
.br
rgb:r/g/b
.br
rgb:rr/gg/bb
.br
rgb:rrr/ggg/bbb
.br
rgb:rrrr/gggg/bbbb
.TP 5
.B \-P, \-\-penetrate
penetrate GNU Screen using DCS pass-through sequence.
.TP 5
.B \-D, \-\-pipe\-mode
[[deprecated]] read source images from stdin continuously.
.TP 5
.B \-v, \-\-verbose
show debugging info.
.TP 5
.B \-V, \-\-version
show version and license info.
.TP 5
.B \-H, \-\-help
print help.


.SH "ENVIRONMENT VARIABLES"
\fIimg2sixel\fP has the following command-line options:
.TP 5
.B SIXEL_BGCOLOR
.br
specify background color.
.br
overrided by -B(--bgcolor) option.
.br
represented by the following syntax:
.br
#rgb
.br
#rrggbb
.br
#rrrgggbbb
.br
#rrrrggggbbbb
.br
rgb:r/g/b
.br
rgb:rr/gg/bb
.br
rgb:rrr/ggg/bbb
.br
rgb:rrrr/gggg/bbbb
.br
.TP 5
.B SIXEL_NCOLORS
.br
specify number of colors to reduce the image to (default=256).
.br
overrided by -p(--colors) option.
.br


.SH Image loaders

\fIimg2sixel\fP includes two or more image decoder components.

.TP 5
.B stb_image

\fIlibsixel\fP includes \fIstb_image\fP, a public domain image loader.
.br
\fIimg2sixel\fP uses it as default built-in image decoder.
It can decode almost all images. but a few images can not be decoded by its limitations.

.B Supported source formats:
   JPEG baseline & progressive (12 bpc/arithmetic not supported, same as stock IJG lib)
   PNG 1/2/4/8/16-bit-per-channel
   TGA (not sure what subset, if a subset)
   BMP non-1bpp, non-RLE
   PSD (composited view only, no extra channels)
   PIC (Softimage PIC)
   PNM (PPM and PGM binary only)

.B Limitations:
   no 12-bit-per-channel JPEG
   no JPEGs with arithmetic coding / JPEG 2000
   no 1-bit BMP

.TP 5
.B libpng

   If \fIlibpng\fP library is linked at compile time, \fIimg2sixel\fP uses it for decoding PNG image.

.TP 5
.B libjpeg

   If \fIlibjpeg\fP library is linked at compile time, \fIimg2sixel\fP uses it for decoding JPEG image.

.TP 5
.B gdk-pixbuf2

   If \fIgdk-pixbuf2\fP library is linked at compile time, \fIimg2sixel\fP uses it automatically in some cases.

.TP 5
.B GD

   If \fIGD\fP library is linked at compile time, \fIimg2sixel\fP uses it automatically in some cases.

.TP 5
.B libsixel

   \fIimg2sixel\fP can load SIXEL as source image format, because it uses \fIlibsixel\fP as a SIXEL image decoder.


.SH HISTORY

Former SIXEL encoders(such as \fIppmtosixel\fP) are mainly designed for dot-matrix printers.
They minimize the amount of printer-head movement distance.
But nowadays this method did not represent the best performance for displaying sixel data on terminal emulators.
Encoded SIXEL data for VT-2xx/VT-3xx terminals were found in 80's Usenet,
But the technology of how to create them seems to be lost.

\fBkmiya's sixel\fP(kmiya,2014) introduces an efficient encoding method which is re-designed for terminal emulators to
optimize the overhead of transporting SIXEL with keeping compatibility with former SIXEL terminal.
Now \fIlibsixel\fP and \fIImageMagick\fP's sixel coder follow it.

\fBAraki Ken\fP, known as the maintainer of mlterm, proposed the method for more compressed SIXEL encoding.
Now \fIlibsixel\fP adopted that method.
\fBAraki Ken\fP describes about the way to generate high quality SIXEL.

See http://mlterm.sourceforge.net/libsixel.pdf(in Japanese).


.SH "SEE ALSO"
sixel(5) sixel2png(1)


.SH AUTHORS
\fIimg2sixel\fP is maintained by Hayaki Saito.
We imported whole code of \fIstb_image v2.12\fP, written by Sean Barrett and its contributers, for loading various images,
and imported some code from \fIpnmquant.c (netpbm library)\fP for image quantization.


.SH COPYRIGHT
Copyright (c) 2014-2016 Hayaki Saito
.PP
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
.PP
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
.PP
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

.SH THANKS
This software derives from the following implementations.
.br
.TP 5
.B stb_image-v2.12
This software includes \fIstb_image-v2.12\fP (stb_image.h),
a public domain JPEG/PNG reader.
.br
.B https://github.com/nothings/stb

.TP 5
.B pnmquant.c (netpbm library)
The implementation of median cut algorithm for color quantization in quant.c
is imported from \fIpnmcolormap\fP included in \fInetpbm library\fP.
.br
http://netpbm.sourceforge.net/
.br
\fIpnmcolormap\fP was derived from \fIppmquant\fP, originally by Jef Poskanzer.
.br
\fB
.br
Copyright (C) 1989, 1991 by Jef Poskanzer.
.br
.br
Copyright (C) 2001 by Bryan Henderson.
.br
.br
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation.  This software is provided "as is" without express or
implied warranty.
\fP

.TP 5
.B sixel 2014-3-2

some part of converters/loader.c are
derived from kmiya's "sixel" original version (2014-3-2).
.br
.br
http://nanno.dip.jp/softlib/man/rlogin/sixel.tar.gz
.br
.br
It is written by kmiya@culti.
.br
.br
He distributes it under very permissive license which permits
useing, copying, modification, redistribution, and all other
public activities without any restrictions.
.br
.br
He declares this is compatible with MIT/BSD/GPL.


.SH REFERENCES
.TP 5
.B resize.c (ImageMagick)

We added some resampling filters in reference to the line-up of filters of
MagickCore's resize.c.

.br
.B http://www.imagemagick.org/api/MagickCore/resize_8c_source.html


.SH CONTRIBUTORS
.nf
Araki Ken (@arakiken)
Markus Elfring (@elfring)
Akinori Hattori (@hattya)
isaki (@isaki68k)
NOKUBI Takatsugu (@knok)
Yasuhiro MATSUMOTO (@mattn)
Masami HIRATA(@msmhrt)
OBATA Akio (@obache)
Izumi Tsutsui (@tsutsui)
Iwamoto Kouichi (@ttdoda)
haru (@uobikiemukot)
Vertis Sidus (@vrtsds)
Bruce Mitchener (@waywardmonkeys)
Kazuhiro YOSHIKAWA (@yoshikaw)
Turenar <sora@turenar.xyz>
Yusuke Endoh <mame@ruby-lang.org>
mattn <mattn.jp@gmail.com>
Akinori Hattori <hattya@gentoo.org>
Øyvind Kolås <pippin@gimp.org>
Henri Salo (@fgeek)
hongxu (@HongxuChen)
pwd (@YourButterfly)
Nicholas Luedtke (@nluedtke)
cool-tomato (@cool-tomato)
.fi


.SH BUGS
.PD
.IP \(bu
Send bug-reports, fixes, enhancements to
.BR saitoha@me.com

.\" end of man page