Check out my first novel, midnight's simulacra!

Sixel: Difference between revisions

From dankwiki
No edit summary
 
(20 intermediate revisions by the same user not shown)
Line 1: Line 1:
Sixel ("six pixels") does not appear to have any true, up-to-date "standard". It seems to have been introduced on DEC printers, and made its first glass appearance on the VT125, though the [http://www.vt100.net/docs/vt3xx-gp/chapter14.html VT3xx] documentation gets the most play (the VT340 appears to have been the first terminal which could sensibly scroll pixel graphics). A single sixel combines a set of programmable color registers with a vertical stack of six pixels; a sixel sprite (sprixel?) is MxN pixels where N is a multiple of 6. It is probably the most widely implemented method of pixel graphics for terminal emulators ([https://sw.kovidgoyal.net/kitty/graphics-protocol.html kitty] has its own protocol, as does [http://www.asmeurer.com/iterm2-tools/images.html ITerm2]). [https://en.wikipedia.org/wiki/ReGIS ReGIS] is a similar method for vector graphics. A single horizontal strip of sixels is a "band"; a sprixel has one or more bands.
Sixel ("six pixels") does not appear to have any true, up-to-date "standard" (Thomas Dickey's [https://invisible-island.net/xterm/ctlseqs/ctlseqs.html XTerm Control Sequences] document is probably the closest thing). It seems to have been introduced on DEC printers, and made its first glass appearance on the VT125, though the [http://www.vt100.net/docs/vt3xx-gp/chapter14.html VT3xx] documentation gets the most play (the VT340 appears to have been the first terminal which could sensibly scroll pixel graphics). A single sixel combines a set of programmable color registers with a vertical stack of six pixels; a sixel sprite (sprixel?) is MxN pixels where N is a multiple of 6. It is probably the most widely implemented method of pixel graphics for terminal emulators ([https://sw.kovidgoyal.net/kitty/graphics-protocol.html kitty] has its own protocol, as does [http://www.asmeurer.com/iterm2-tools/images.html ITerm2]). [https://en.wikipedia.org/wiki/ReGIS ReGIS] is a similar method for vector graphics. A single horizontal strip of sixels is a "band"; a sprixel has one or more bands.
 
Sixels are specified using only printable ASCII characters, and are thus 7-bit clean.


A sprixel must typically be emitted as a single unit to be rendered as a coherent whole (i.e. without gaps between bands). Sprixels do not annihilate entire cells, but only the pixels covered. A glyph emitted atop a sixel will annihilate all pixels contained within the cell.
A sprixel must typically be emitted as a single unit to be rendered as a coherent whole (i.e. without gaps between bands). Sprixels do not annihilate entire cells, but only the pixels covered. A glyph emitted atop a sixel will annihilate all pixels contained within the cell.


==Color registers==
==Syntax==
Before emitting a sprixel, the terminal must first be put into the appropriate mode via "\ePq" ('''FIXME''' details on 8-bit, start params). Properly exit the mode with "\e\\" ('''FIXME''' again 8-bit). '''FIXME what about \e[?80h?'''
 
The mode switch may be followed by an optional quartet of parameters, separated by semicolons:
 
<tt>AspectX;AspectY;LenX;LenY</tt>
 
I'm not yet completely sure of the effect of these parameters '''FIXME'''.
 
Color registers precede the band data ''en bloc''. Each color register takes the form "#N;T;a;b;c" where N is the register and T is the type (see below).
 
Bands are separated by hyphens ('-'). Return to the start of a band without moving to the next one (i.e. to draw another color) with '$'. The same number of sixels ought be provided for each color used in a band (but they may of course be the empty sixel). For each sixel, determine which of the six pixels 0..5 (0 on the top, 5 on the bottom) match the color, and and for each pixel N, add 2ⁿ. The result will be between 0 and 63, inclusive. Add 63 to this total; the sixel is the corresponding ASCII character (between 63 and 126, inclusive). When a sixel is repeated four or more times in a row, use "!n" to runlength encode the series.
 
If a given pixel is unspecified (i.e. no band includes the pixel), the behavior is dependent on whether the Set Raster Attributes control sequence has been emitted. If it has, unspecified pixels are drawn with Color Register 0. If it has not, they are not touched. For transparency with regards to existing material, then, Set Raster Attributes must not be used.
 
===Color registers===
A terminal supports some number of color registers for each sprixel. For <tt>xterm</tt>, this is controlled by the <tt>numColorRegisters</tt> resource (set to a (low) value based off <tt>decTerminalID</tt> if not explicitly provided):
A terminal supports some number of color registers for each sprixel. For <tt>xterm</tt>, this is controlled by the <tt>numColorRegisters</tt> resource (set to a (low) value based off <tt>decTerminalID</tt> if not explicitly provided):
<pre>XTerm*numColorRegisters: 1024</pre>
<pre>XTerm*numColorRegisters: 1024</pre>


==Support==
Each register is specified with a type ("1" for HSL, "2" for RGB) and three components, each between 0 and 100 inclusive. Assuming 8bpc RGB, every 2.6 bits of component get squashed to 1.
* <tt>xterm</tt> supports scrolling sprixels when compiled with <tt>--enable-sixel-graphics</tt> and launched with at least a <tt>vt340</tt> <tt>decGraphicsID</tt> (or <tt>decTerminalID</tt>).
 
The <tt>privateColorRegisters</tt> resource (default: "true") determines whether each sixel escape sequence controls its own distinct color registers, or whether they're shared by all sprixels.
 
==Complexifiers==
 
* At least on <tt>xterm</tt> (this does not appear to happen with <tt>mlterm</tt>), when a sprixel is emitted to the alternate screen, it will be redrawn upon the next entry to the alternate screen.
 
''scrolling, scrollback, terminal resize, zoom (font change), overlapping, is the color register limit per-sprixel or per-terminal, geometry arguments, background, maximum size'' '''FIXME'''
 
==Detecting support==
<tt>Send Device Attributes</tt> can be used to detect Sixel support. Send <tt>CSI Ps c</tt>. If the VT220-level reply contains a '4', sixel graphics are supported.
===Detecting details===
<tt>XTSMGRAPHICS</tt> can be used to set and retrieve Sixel-related configuration, if Sixel is supported. Send <tt>CSI ? Pi ; Pa ; Pv S</tt> where
* Pi == 1, color registers
* Pi == 2, maximum geometry
* Pa == 1, read
* Pa == 2, reset to default
* Pa == 3, set to Pv
* Pa == 4, read maximum value
For color registers, the maximum value is the absolute maximum supported by the application. For geometry, the current value is affected by current window geometry in addition to configuration.
 
===Known support===
* <tt>xterm</tt> supports scrolling sprixels when compiled with <tt>--enable-sixel-graphics</tt>
** and launched with at least a <tt>vt340</tt> <tt>decGraphicsID</tt> (or <tt>decTerminalID</tt>)
* <tt>mlterm</tt> works
* <tt>mlterm</tt> works
* <tt>alacritty</tt> has a patch outstanding to add support, but it is not yet merged as of 0.8.0-dev
* <tt>alacritty</tt> has a patch outstanding to add support, but it is not yet merged as of 0.8.0-dev
* <tt>VTE</tt> supports sprixels when built with <tt>-Dsixel=true</tt>.
* <tt>VTE</tt> supports sprixels when built with <tt>-Dsixel=true</tt>
* Microsoft's [https://github.com/microsoft/terminal Windows Terminal] is said to support sixel


==See also==
==See also==
* [[Notcurses]] supports sixel intermingled with standard TUI elements
* [[Notcurses]] supports sixel intermingled with standard TUI elements
* [https://github.com/saitoha/libsixel libsixel] is pretty complete
* [https://github.com/saitoha/libsixel libsixel] is pretty complete
* [[Theory and Practice of Sprixels]]
[[CATEGORY: Terminals]]

Latest revision as of 20:48, 25 June 2021

Sixel ("six pixels") does not appear to have any true, up-to-date "standard" (Thomas Dickey's XTerm Control Sequences document is probably the closest thing). It seems to have been introduced on DEC printers, and made its first glass appearance on the VT125, though the VT3xx documentation gets the most play (the VT340 appears to have been the first terminal which could sensibly scroll pixel graphics). A single sixel combines a set of programmable color registers with a vertical stack of six pixels; a sixel sprite (sprixel?) is MxN pixels where N is a multiple of 6. It is probably the most widely implemented method of pixel graphics for terminal emulators (kitty has its own protocol, as does ITerm2). ReGIS is a similar method for vector graphics. A single horizontal strip of sixels is a "band"; a sprixel has one or more bands.

Sixels are specified using only printable ASCII characters, and are thus 7-bit clean.

A sprixel must typically be emitted as a single unit to be rendered as a coherent whole (i.e. without gaps between bands). Sprixels do not annihilate entire cells, but only the pixels covered. A glyph emitted atop a sixel will annihilate all pixels contained within the cell.

Syntax

Before emitting a sprixel, the terminal must first be put into the appropriate mode via "\ePq" (FIXME details on 8-bit, start params). Properly exit the mode with "\e\\" (FIXME again 8-bit). FIXME what about \e[?80h?

The mode switch may be followed by an optional quartet of parameters, separated by semicolons:

AspectX;AspectY;LenX;LenY

I'm not yet completely sure of the effect of these parameters FIXME.

Color registers precede the band data en bloc. Each color register takes the form "#N;T;a;b;c" where N is the register and T is the type (see below).

Bands are separated by hyphens ('-'). Return to the start of a band without moving to the next one (i.e. to draw another color) with '$'. The same number of sixels ought be provided for each color used in a band (but they may of course be the empty sixel). For each sixel, determine which of the six pixels 0..5 (0 on the top, 5 on the bottom) match the color, and and for each pixel N, add 2ⁿ. The result will be between 0 and 63, inclusive. Add 63 to this total; the sixel is the corresponding ASCII character (between 63 and 126, inclusive). When a sixel is repeated four or more times in a row, use "!n" to runlength encode the series.

If a given pixel is unspecified (i.e. no band includes the pixel), the behavior is dependent on whether the Set Raster Attributes control sequence has been emitted. If it has, unspecified pixels are drawn with Color Register 0. If it has not, they are not touched. For transparency with regards to existing material, then, Set Raster Attributes must not be used.

Color registers

A terminal supports some number of color registers for each sprixel. For xterm, this is controlled by the numColorRegisters resource (set to a (low) value based off decTerminalID if not explicitly provided):

XTerm*numColorRegisters: 1024

Each register is specified with a type ("1" for HSL, "2" for RGB) and three components, each between 0 and 100 inclusive. Assuming 8bpc RGB, every 2.6 bits of component get squashed to 1.

The privateColorRegisters resource (default: "true") determines whether each sixel escape sequence controls its own distinct color registers, or whether they're shared by all sprixels.

Complexifiers

  • At least on xterm (this does not appear to happen with mlterm), when a sprixel is emitted to the alternate screen, it will be redrawn upon the next entry to the alternate screen.

scrolling, scrollback, terminal resize, zoom (font change), overlapping, is the color register limit per-sprixel or per-terminal, geometry arguments, background, maximum size FIXME

Detecting support

Send Device Attributes can be used to detect Sixel support. Send CSI Ps c. If the VT220-level reply contains a '4', sixel graphics are supported.

Detecting details

XTSMGRAPHICS can be used to set and retrieve Sixel-related configuration, if Sixel is supported. Send CSI ? Pi ; Pa ; Pv S where

  • Pi == 1, color registers
  • Pi == 2, maximum geometry
  • Pa == 1, read
  • Pa == 2, reset to default
  • Pa == 3, set to Pv
  • Pa == 4, read maximum value

For color registers, the maximum value is the absolute maximum supported by the application. For geometry, the current value is affected by current window geometry in addition to configuration.

Known support

  • xterm supports scrolling sprixels when compiled with --enable-sixel-graphics
    • and launched with at least a vt340 decGraphicsID (or decTerminalID)
  • mlterm works
  • alacritty has a patch outstanding to add support, but it is not yet merged as of 0.8.0-dev
  • VTE supports sprixels when built with -Dsixel=true
  • Microsoft's Windows Terminal is said to support sixel

See also