# display-colors
`display-colors` is a program to explore the color and display effect capabilities of a terminal emulator
## Compatibility
`display-colors` runs on macOS and Linux.
It requires Python 3.
## Installation and Use
`display-colors` should be installed in a virtual environment.
### How to Create, Use and Destroy a Virtual Environment
```
python -m venv .venv // Create the virtual environment '.venv'
source .venv/bin/activate // Enter .venv
(.venv) ... // While in the virtual environment, your prompt will be prefixed with '(.venv)'
(.venv) deactivate // Exit .venv
rm -rf .venv // Destroy .venv
```
### How to Install and Uninstall `display-colors`
```
(.venv) python -m pip install display-colors // Install
(.venv) python -m pip uninstall display-colors // Uninstall
```
### Use
```
(.venv) display-colors [--help | --version] COMMAND [OPTIONS]
```
COMMAND: 4-bit | 8-bit | effects
OPTIONS vary depending on the command; do `display-colors COMMAND --help` to list them
## Features
Modern terminal emulators support color but the results vary across emulators, let alone across platforms. Three sets of colors are available: 4 bit, 8 bit and 24 bit. They may not be completely supported.
`display-colors` produces test patterns that include all of the 4- and 8-bit colors: all foreground-background combinations of 4-bit colors, which can vary depending on the theme, and swatches of all 8-bit colors. It also demonstrates each Select Graphic Rendition (SGR) code controlling effects like underline and blink. Support for these among emulators is spotty.
The SGR codes also specify four font weights: default, dim, medium and bold. Implementation of these varies. The `--weight` option in 4-bit mode lets you specify what weights you would like to see (8-bit mode text uses the default weight).
One of the widely-supported effects is reverse video. This is not always implemented by swapping foreground and background colors. The `--reverse-video` option displays each line twice, the second with foreground and background colors swapped *and* reverse video turned on. If reverse video is implemented simply by swapping the two lines will appear identical; if not, they won't.
The program has four modes:
- 4-bit -- A color palette in the traditional format, one background color per column (*qv* [iTerm2 Color Schemes](https://iterm2colorschemes.com/))
- 4-bit transpose -- A palette with one foreground color per column
- 8-bit -- A palette of background colors, including the standard 16 and grayscale (*qv* [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit))
- effects -- A test pattern of terminal effects
### 4-bit mode (`display-colors 4-bit`)
Options:
- `--col-width` *`n`* -- Width of the columns in the body of the output table (default: 7)
- `--gutter` *`string`* -- Delimiter between output columns (default: empty string)
- `--reverse-video` -- Displays each row twice, the second time with BG-color on FG-color in reverse video. If your terminal emulator implements reverse video by swapping background and foreground, the two lines will appear identical
- `--stanzas` -- Group output rows by color (default: off)
- `--text` *`string`* -- Specifies the sample text to be displayed in each cell (default: 'gYw')
- `-w` *`string`*, `--weight` *`string`* -- Specifies which weight font to display and in what order (use multiple times). Supported weights are `dim`, `default`, `medium`, `bold` and `all` (default: `default`, `bold`)
This format lists background colors one per column with their SGR codes at top and left. The default background color is the leftmost column and the topmost rows show the default foreground color.
Each row is labeled on the left with its weight. If the row is reverse video, the weight label will appear in reverse video.
### 4-bit transpose mode (`display-colors 4-bit --transpose`)
Options:
- `--col-width` *`n`* -- (see '4-bit mode' above)
- `--gutter` *`string`* -- (see '4-bit mode' above)
- `--reverse-video` -- (see '4-bit mode' above)
- `-w` *`string`*, `--weight` *`string`* -- (see '4-bit mode' above)
This format lists foreground colors one per column, with the default foreground color in the leftmost column and the default background color in the topmost rows. The SGR codes are not shown and the sample text is of the form FG/BG.
### 8-bit mode (`display-colors 8-bit`)
This has three parts:
- 16 standard and bright colors
- The palette of 216 RGB colors
- 24 grayscale colors
These are displayed as background colors. The text in each cell is the hexadecimal value of the color code; for example, the background color of cell D8 in the test pattern is given by the ANSI escape code `\033[48;5;216m`. The foreground colors in the test pattern are (standard) white for the darker cells and black for the lighter ones. Some terminal emulators modify this in an attempt to improve the contrast.
The text in the cells is in hexadecimal by default because it is more readable and to save space.
The sixteen standard colors are presented just above their 4-bit equivalents (sometimes these are different).
The 216 RGB colors are arranged in a 6x6 cube, displayed in 6 slices with the origin at the back upper left corner. We assign codes to them in xyz order, with the x coordinate varying first. The x coordinate moves left to right, the y coordinate top to bottom and the z coordinate back to front. The display shows three views of the cube, one per row: head-on sliced back to front, from above sliced top to bottom and from the left sliced left to right. (The view in the [ANSI escape code illustration](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) is the second of these views).
From these slices you can see that the darker cells occupy the top half of the cube, the greens the back lower left corner, the reds the front upper left corner and the blues the back upper right corner.
### Effects mode (`display-colors effects`)
Options:
- `--pattern` *`string`* -- Specify a string to use as a sample text pattern (default: '|'). Most screens will not be wide enough to accomodate a test pattern string of more than one character. (If the pattern string contains a character that has a special meaning to the shell, like '|', it must be escaped (preceded) by a backslash: `--pattern \|`).
- `--gutter` *`string`* -- (see '4-bit mode' above)
Displays a sample of the effect of each SGR code in all 4-bit foreground and background colors (see [Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters) for the list of SGR codes). Some effects may be more visible in certain colors than in others. The text samples are displayed in groups of three:
1. Without applying the effect
2. After turning the effect on
3. After turning the effect off again
So for a supported effect, you should see that effect applied to the second character only and the first and third characters should be identical.
Practically all of the effects can be individually turned on and off. One code was unwisely assigned to both 'bold off' and 'double underline on', and for emulators that support double underline you can see this in the 'Bold:' row. For those emulators you should substitute a different SGR code, such as the one for 'medium', in place of 'bold off'.
### Color names
The display uses abbreviations for the colors, as follows:
| | |
| :---: | :--- |
| df | Default color |
| bk | Black |
| re | Red |
| gr | Green |
| ye | Yellow |
| bl | Blue |
| ma | Magenta |
| cy | Cyan |
| wh | White |
| BK | Bright black |
| RE | Bright red |
| GR | Bright green |
| YE | Bright yellow |
| BL | Bright blue |
| MA | Bright magenta |
| CY | Bright cyan |
| WH | Bright white |
## Problems
If the terminal somehow gets into a confused state, it will not display colors correctly. If the output of `display-colors` looks incorrect, try one of the following to reset the terminal:
```bash
reset
tput reset
```
## Examples
Traditional 4-bit palette, including all font weights, with reverse-video rows, divided into stanzas by color:
```bash
display-colors 4-bit --weight all --reverse-video --stanzas
```
4-bit palette with one column per foreground color, rows ordered 'dim, medium, bold, medium' and spaces between the columns:
```bash
display-colors 4-bit --transpose -w dim -w medium -w bold -w medium --gutter ' '
```
8-bit display including standard and bright colors, 216-color RGB palette and grayscale background colors:
```bash
display-colors 8-bit
```
Terminal effect test pattern with spaces between the columns:
```bash
display-colors effects --gutter ' '
```
Raw data
{
"_id": null,
"home_page": "https://github.com/JoeRodrigue/display-colors",
"name": "display-colors",
"maintainer": "Joe Rodrigue",
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": "joe.rodrigue@gmail.com",
"keywords": "color, terminal, emulator, SGR, ECMA-48",
"author": "Joe Rodrigue",
"author_email": "joe.rodrigue@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cf/bf/f82076efbefd8fcb466b8f489e0da99c4eca04e4e91f57c4d77dca05d8c2/display_colors-1.0.6.tar.gz",
"platform": null,
"description": "# display-colors\n\n`display-colors` is a program to explore the color and display effect capabilities of a terminal emulator\n\n## Compatibility\n\n`display-colors` runs on macOS and Linux.\nIt requires Python 3.\n\n## Installation and Use\n\n`display-colors` should be installed in a virtual environment.\n\n### How to Create, Use and Destroy a Virtual Environment\n\n```\npython -m venv .venv // Create the virtual environment '.venv'\nsource .venv/bin/activate // Enter .venv\n(.venv) ... // While in the virtual environment, your prompt will be prefixed with '(.venv)'\n(.venv) deactivate // Exit .venv\nrm -rf .venv // Destroy .venv\n```\n\n### How to Install and Uninstall `display-colors`\n\n```\n(.venv) python -m pip install display-colors // Install\n(.venv) python -m pip uninstall display-colors // Uninstall\n```\n\n### Use\n\n```\n(.venv) display-colors [--help | --version] COMMAND [OPTIONS]\n```\n\nCOMMAND: 4-bit | 8-bit | effects\n\nOPTIONS vary depending on the command; do `display-colors COMMAND --help` to list them\n\n## Features\n\nModern terminal emulators support color but the results vary across emulators, let alone across platforms. Three sets of colors are available: 4 bit, 8 bit and 24 bit. They may not be completely supported.\n\n`display-colors` produces test patterns that include all of the 4- and 8-bit colors: all foreground-background combinations of 4-bit colors, which can vary depending on the theme, and swatches of all 8-bit colors. It also demonstrates each Select Graphic Rendition (SGR) code controlling effects like underline and blink. Support for these among emulators is spotty.\n\nThe SGR codes also specify four font weights: default, dim, medium and bold. Implementation of these varies. The `--weight` option in 4-bit mode lets you specify what weights you would like to see (8-bit mode text uses the default weight).\n\nOne of the widely-supported effects is reverse video. This is not always implemented by swapping foreground and background colors. The `--reverse-video` option displays each line twice, the second with foreground and background colors swapped *and* reverse video turned on. If reverse video is implemented simply by swapping the two lines will appear identical; if not, they won't.\n\nThe program has four modes:\n\n - 4-bit -- A color palette in the traditional format, one background color per column (*qv* [iTerm2 Color Schemes](https://iterm2colorschemes.com/))\n - 4-bit transpose -- A palette with one foreground color per column\n - 8-bit -- A palette of background colors, including the standard 16 and grayscale (*qv* [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit))\n - effects -- A test pattern of terminal effects\n\n### 4-bit mode (`display-colors 4-bit`)\n\nOptions:\n\n - `--col-width` *`n`* -- Width of the columns in the body of the output table (default: 7)\n - `--gutter` *`string`* -- Delimiter between output columns (default: empty string)\n - `--reverse-video` -- Displays each row twice, the second time with BG-color on FG-color in reverse video. If your terminal emulator implements reverse video by swapping background and foreground, the two lines will appear identical\n - `--stanzas` -- Group output rows by color (default: off)\n - `--text` *`string`* -- Specifies the sample text to be displayed in each cell (default: 'gYw')\n - `-w` *`string`*, `--weight` *`string`* -- Specifies which weight font to display and in what order (use multiple times). Supported weights are `dim`, `default`, `medium`, `bold` and `all` (default: `default`, `bold`)\n\nThis format lists background colors one per column with their SGR codes at top and left. The default background color is the leftmost column and the topmost rows show the default foreground color.\n\nEach row is labeled on the left with its weight. If the row is reverse video, the weight label will appear in reverse video.\n\n### 4-bit transpose mode (`display-colors 4-bit --transpose`)\n\nOptions:\n\n - `--col-width` *`n`* -- (see '4-bit mode' above)\n - `--gutter` *`string`* -- (see '4-bit mode' above)\n - `--reverse-video` -- (see '4-bit mode' above)\n - `-w` *`string`*, `--weight` *`string`* -- (see '4-bit mode' above)\n\nThis format lists foreground colors one per column, with the default foreground color in the leftmost column and the default background color in the topmost rows. The SGR codes are not shown and the sample text is of the form FG/BG.\n\n### 8-bit mode (`display-colors 8-bit`)\n\nThis has three parts:\n\n - 16 standard and bright colors\n - The palette of 216 RGB colors\n - 24 grayscale colors\n\nThese are displayed as background colors. The text in each cell is the hexadecimal value of the color code; for example, the background color of cell D8 in the test pattern is given by the ANSI escape code `\\033[48;5;216m`. The foreground colors in the test pattern are (standard) white for the darker cells and black for the lighter ones. Some terminal emulators modify this in an attempt to improve the contrast.\n\nThe text in the cells is in hexadecimal by default because it is more readable and to save space.\n\nThe sixteen standard colors are presented just above their 4-bit equivalents (sometimes these are different).\n\nThe 216 RGB colors are arranged in a 6x6 cube, displayed in 6 slices with the origin at the back upper left corner. We assign codes to them in xyz order, with the x coordinate varying first. The x coordinate moves left to right, the y coordinate top to bottom and the z coordinate back to front. The display shows three views of the cube, one per row: head-on sliced back to front, from above sliced top to bottom and from the left sliced left to right. (The view in the [ANSI escape code illustration](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) is the second of these views).\n\nFrom these slices you can see that the darker cells occupy the top half of the cube, the greens the back lower left corner, the reds the front upper left corner and the blues the back upper right corner.\n\n### Effects mode (`display-colors effects`)\n\nOptions:\n\n - `--pattern` *`string`* -- Specify a string to use as a sample text pattern (default: '|'). Most screens will not be wide enough to accomodate a test pattern string of more than one character. (If the pattern string contains a character that has a special meaning to the shell, like '|', it must be escaped (preceded) by a backslash: `--pattern \\|`).\n - `--gutter` *`string`* -- (see '4-bit mode' above)\n\nDisplays a sample of the effect of each SGR code in all 4-bit foreground and background colors (see [Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters) for the list of SGR codes). Some effects may be more visible in certain colors than in others. The text samples are displayed in groups of three:\n\n 1. Without applying the effect\n 2. After turning the effect on\n 3. After turning the effect off again\n\nSo for a supported effect, you should see that effect applied to the second character only and the first and third characters should be identical.\n\nPractically all of the effects can be individually turned on and off. One code was unwisely assigned to both 'bold off' and 'double underline on', and for emulators that support double underline you can see this in the 'Bold:' row. For those emulators you should substitute a different SGR code, such as the one for 'medium', in place of 'bold off'.\n\n### Color names\n\nThe display uses abbreviations for the colors, as follows:\n\n | | |\n | :---: | :--- |\n | df | Default color |\n | bk | Black |\n | re | Red |\n | gr | Green |\n | ye | Yellow |\n | bl | Blue |\n | ma | Magenta |\n | cy | Cyan |\n | wh | White |\n | BK | Bright black |\n | RE | Bright red |\n | GR | Bright green |\n | YE | Bright yellow |\n | BL | Bright blue |\n | MA | Bright magenta |\n | CY | Bright cyan |\n | WH | Bright white |\n\n## Problems\n\nIf the terminal somehow gets into a confused state, it will not display colors correctly. If the output of `display-colors` looks incorrect, try one of the following to reset the terminal:\n\n```bash\nreset\ntput reset\n```\n\n## Examples\n\nTraditional 4-bit palette, including all font weights, with reverse-video rows, divided into stanzas by color:\n```bash\ndisplay-colors 4-bit --weight all --reverse-video --stanzas\n```\n4-bit palette with one column per foreground color, rows ordered 'dim, medium, bold, medium' and spaces between the columns:\n```bash\ndisplay-colors 4-bit --transpose -w dim -w medium -w bold -w medium --gutter ' '\n```\n8-bit display including standard and bright colors, 216-color RGB palette and grayscale background colors:\n```bash\ndisplay-colors 8-bit\n```\nTerminal effect test pattern with spaces between the columns:\n```bash\ndisplay-colors effects --gutter ' '\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Shows the 4-bit color and display effect capabilities of a terminal emulator",
"version": "1.0.6",
"project_urls": {
"Documentation": "https://github.com/JoeRodrigue/display-colors",
"Homepage": "https://github.com/JoeRodrigue/display-colors",
"Repository": "https://github.com/JoeRodrigue/display-colors"
},
"split_keywords": [
"color",
" terminal",
" emulator",
" sgr",
" ecma-48"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "08b54354b74ba1e88c2b3d1c2826a659130edbb6cc8354a66f3a4ca99a0fdea5",
"md5": "9a3ef10df9562280a700a006419d8afc",
"sha256": "0007b4c8f5364eeddcaab7b918157f6bb5c504b4da0a26b0a9b8c089fc5a57dd"
},
"downloads": -1,
"filename": "display_colors-1.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a3ef10df9562280a700a006419d8afc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 17157,
"upload_time": "2024-06-06T23:30:46",
"upload_time_iso_8601": "2024-06-06T23:30:46.995193Z",
"url": "https://files.pythonhosted.org/packages/08/b5/4354b74ba1e88c2b3d1c2826a659130edbb6cc8354a66f3a4ca99a0fdea5/display_colors-1.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cfbff82076efbefd8fcb466b8f489e0da99c4eca04e4e91f57c4d77dca05d8c2",
"md5": "91c3740c36749198a0fb1c7bb11834c9",
"sha256": "a1e7e24fd079f9d314e4865a3b693ff29ce8099589c1db3cdac54bd9c8f0646a"
},
"downloads": -1,
"filename": "display_colors-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "91c3740c36749198a0fb1c7bb11834c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 16930,
"upload_time": "2024-06-06T23:30:48",
"upload_time_iso_8601": "2024-06-06T23:30:48.451716Z",
"url": "https://files.pythonhosted.org/packages/cf/bf/f82076efbefd8fcb466b8f489e0da99c4eca04e4e91f57c4d77dca05d8c2/display_colors-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-06 23:30:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JoeRodrigue",
"github_project": "display-colors",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "display-colors"
}
JSON
