IMG2SIXEL(1)

NAME
img2sixel - image converter to DEC SIXEL graphics

SYNOPSIS
img2sixel [ -options ] imagefiles
img2sixel [ -options ] < imagefiles

DESCRIPTION
img2sixel converts various images into high quality DEC SIXEL image format.

COMMAND-LINE OPTIONS
img2sixel has the following command-line options:

-o, --outfile
    specify output file name (default:stdout).

-7, --7bit-mode
    generate a sixel image for 7bit terminals or printers (default).

-8, --8bit-mode
    generate a sixel image for 8bit terminals or printers.

-R, --gri-limit
    limit arguments of DECGRI('!') to 255.

-p COLORS, --colors=COLORS
    specify number of colors to reduce the image to (default=256).

-m FILE, --mapfile=FILE
    transform image colors to match this set of colorsspecify map.

-e, --monochrome
    output monochrome sixel image. this option assumes the terminal background color is black.

-k, --insecure
    allow to connect to SSL sites without certs (enabled only when configured with --with-libcurl)

-i, --invert
    assume the terminal background color is white. make sense only when -e option is given.

-I, --high-color
    output 15bpp sixel image

-u, --use-macro
    use DECDMAC and DEVINVM sequences to optimize GIF animation rendering.

-n MACRONO, --macro-number=MACRONO
    specify an number argument for DECDMAC and make terminal memorize SIXEL image. No image is shown if this option is specified

-C COMPLEXIONSCORE, --complexion-score=COMPLEXIONSCORE
    specify an number argument for the score of complexion correction. COMPLEXIONSCORE must be 1 or more.

-g, --ignore-delay
    render GIF animation without delay.

-S, --static
    render animated GIF as a static image.

-d DIFFUSIONTYPE, --diffusion=DIFFUSIONTYPE
    choose diffusion method which used with color reduction.
    DIFFUSIONTYPE is one of them:
    auto -> choose diffusion type automatically (default)
    none -> do not diffuse
    fs -> Floyd-Steinberg method
    atkinson -> Bill Atkinson's method
    jajuni -> Jarvis, Judice & Ninke
    stucki -> Stucki's method
    burkes -> Burkes' method
    a_dither -> positionally stable arithmetic dither
    x_dither -> positionally stable arithmetic xor based dither

-f FINDTYPE, --find-largest=FINDTYPE
    choose method for finding the largest dimension of median cut boxes for splitting, make sense only when -p option (color reduction) is specified.
    FINDTYPE is one of them:
    auto -> choose finding method automatically (default)
    norm -> simply comparing the range in RGB space
    lum -> transforming into luminosities before the comparison

-s SELECTTYPE, --select-color=SELECTTYPE
    choose the method for selecting representative color from each median-cut box, make sense only when -p option (color reduction) is specified.
    SELECTTYPE is one of them:
    auto -> choose selecting method automatically (default)
    center -> choose the center of the box
    average -> calculate the color average into the box
    histogram -> similar with average but considers color histogram

-c REGION, --crop=REGION
    crop source image to fit the specified geometry.
    REGION should be formatted as '%dx%d+%d+%d'.

-w WIDTH, --width=WIDTH
    resize image to specified width.
    WIDTH is represented by the following syntax:
    auto -> preserving aspect ratio (default)
    <number>% -> scale width with given percentage
    <number> -> scale width with pixel counts
    <number>px -> scale width with pixel counts

-h HEIGHT, --height=HEIGHT
    resize image to specified height.
    HEIGHT is represented by the following syntax
    auto -> preserving aspect ratio (default)
    <number>% -> scale height with given percentage
    <number> -> scale height with pixel counts
    <number>px -> scale height with pixel counts

-r RESAMPLINGTYPE, --resampling=RESAMPLINGTYPE
    choose resampling method used with -w or -h option (scaling).
    RESAMPLINGTYPE is one of them:
    nearest -> Nearest-Neighbor method
    gaussian -> Gaussian filter
    hanning -> Hanning filter
    hamming -> Hamming filter
    bilinear -> Bilinear filter (default)
    welsh -> Welsh filter
    bicubic -> Bicubic filter
    lanczos2 -> Lanczos-2 filter
    lanczos3 -> Lanczos-3 filter
    lanczos4 -> Lanczos-4 filter

-q QUALITYMODE, --quality=QUALITYMODE
    select quality of color quanlization.
    QUALITYMODE is one of them:
    auto -> decide quality mode automatically (default)
    high -> high quality and low speed mode
    low -> low quality and high speed mode
    full -> quality and careful speed mode

-l LOOPMODE, --loop-control=LOOPMODE
    select loop control mode for GIF animation.
    auto -> honer the setting of GIF header (default)
    force -> always enable loop
    disable -> always disable loop

-t PALETTETYPE, --palette-type=PALETTETYPE
    select palette color space type.
    auto -> choose palette type automatically (default)
    hls -> use HLS color space
    rgb -> use RGB color space

-b BUILTINPALETTE, --builtin-palette=BUILTINPALETTE
    select built-in palette type
    xterm16 -> X default 16 color map
    xterm256 -> X default 256 color map
    vt340mono -> VT340 monochrome map
    vt340color -> VT340 color map

-E ENCODEPOLICY, --encode-policy=ENCODEPOLICY
    select encoding policy
    auto -> choose encoding policy automatically (default)
    fast -> encode as fast as possible
    size -> encode to as small sixel sequence as possible

-B BGCOLOR, --bgcolor=BGCOLOR
    specify background color
    BGCOLOR is represented by the following syntax
    #rgb
    #rrggbb
    #rrrgggbbb
    #rrrrggggbbbb
    rgb:r/g/b
    rgb:rr/gg/bb
    rgb:rrr/ggg/bbb
    rgb:rrrr/gggg/bbbb

-P, --penetrate
    penetrate GNU Screen using DCS pass-through sequence.

-D, --pipe-mode
    [[deprecated]] read source images from stdin continuously.

-v, --verbose
    show debugging info.

-V, --version
    show version and license info.

-H, --help
    print help.

ENVIRONMENT VARIABLES
img2sixel has the following command-line options:

SIXEL_BGCOLOR
    specify background color.
    overrided by -B(--bgcolor) option.
    represented by the following syntax:
    #rgb
    #rrggbb
    #rrrgggbbb
    #rrrrggggbbbb
    rgb:r/g/b
    rgb:rr/gg/bb
    rgb:rrr/ggg/bbb
    rgb:rrrr/gggg/bbbb

SIXEL_NCOLORS
    specify number of colors to reduce the image to (default=256).
    overrided by -p(--colors) option.

Image loaders
img2sixel includes two or more image decoder components.

stb_image
    libsixel includes stb_image, a public domain image loader.
    img2sixel 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. 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) Limitations:
       no 12-bit-per-channel JPEG
       no JPEGs with arithmetic coding / JPEG 2000
       no 1-bit BMP

libpng
       If libpng library is linked at compile time, img2sixel uses it for decoding PNG image.

libjpeg
       If libjpeg library is linked at compile time, img2sixel uses it for decoding JPEG image.

gdk-pixbuf2
       If gdk-pixbuf2 library is linked at compile time, img2sixel uses it automatically in some cases.

GD
       If GD library is linked at compile time, img2sixel uses it automatically in some cases.

libsixel
       img2sixel can load SIXEL as source image format, because it uses libsixel as a SIXEL image decoder.

HISTORY
Former SIXEL encoders(such as ppmtosixel) 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. kmiya's sixel(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 libsixel and ImageMagick's sixel coder follow it. Araki Ken, known as the maintainer of mlterm, proposed the method for more compressed SIXEL encoding. Now libsixel adopted that method. Araki Ken describes about the way to generate high quality SIXEL. See http://mlterm.sourceforge.net/libsixel.pdf(in Japanese).

SEE ALSO
sixel(5) sixel2png(1)

AUTHORS
img2sixel is maintained by Hayaki Saito. We imported whole code of stb_image v2.12, written by Sean Barrett and its contributers, for loading various images, and imported some code from pnmquant.c (netpbm library) for image quantization.

COPYRIGHT
Copyright (c) 2014-2016 Hayaki Saito

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:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

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.

THANKS
This software derives from the following implementations.

stb_image-v2.12
    This software includes stb_image-v2.12 (stb_image.h), a public domain JPEG/PNG reader.
    https://github.com/nothings/stb

pnmquant.c (netpbm library)
    The implementation of median cut algorithm for color quantization in quant.c is imported from pnmcolormap included in netpbm library.
    http://netpbm.sourceforge.net/
    pnmcolormap was derived from ppmquant, originally by Jef Poskanzer.
    Copyright (C) 1989, 1991 by Jef Poskanzer.
    Copyright (C) 2001 by Bryan Henderson.
    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.

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

REFERENCES

resize.c (ImageMagick)
    We added some resampling filters in reference to the line-up of filters of MagickCore's resize.c.
    http://www.imagemagick.org/api/MagickCore/resize_8c_source.html

CONTRIBUTORS
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)

BUGS

•   Send bug-reports, fixes, enhancements to saitoha@me.com