cpick

README

Cpick

An extensive color picker for the terminal

Table of Contents

1. About
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About

Cpick is an interactive color picker in the terminal. You can run Cpick in any true color terminal, and you can see thousands of unique colors, either from preset values or gradients. Each color has its own formats in many different forms, including RGB, HSV, CMYK, and more.

(back to top)

Built With

• Golang
• Cview
• Tcell

(back to top)

Getting Started

Cpick depends on Tcell and Colors.

Cpick also uses Cview. However, Cview currently has a feature where the table cells are drawn with a required space in between cells, which ruins the aesthetic of Cpick. In order to fix this, a forked version of Cview is used within the Cpick package that has the required fixes. This may lead to bugs and issues in older versions of Cview that are not able to be readily fixed until Cview adopts required features.

Prerequisites

• Golang is installed
• Git is installed
• Your terminal is true color compatible

Installation

Golang

To include the Cpick package in your own Golang application, include the line import "github.com/ethanbaker/cpick".

To make a command based on the package, run go install in the cmd/cpick directory. Command usage can be found in the documentation. If you have difficulties compiling and installing the application, follow these comprehensive steps in the official Golang documentation.

Cpick also utilizes cmdtab, which offers tab completion for Cpick. If you wish to enable tab completion, add the line complete -C cpick cpick to your ~/.bashrc file.

Arch Linux (Arch User Repository)

Visit the AUR page to download Cpick to your arch system. If you don't know how to download a package from the Arch User Repository, you can follow directions from the Arch wiki.

Ubuntu/Debian

Coming soon!

(back to top)

Usage

Cpick can be used to select any color and output the corresponding color format. For example, entering the command cpick hex will output a hexadecimal color (ex: #123abc) when a color is selected. Many different color formats exist, such as ansi escape sequences, rgb values, or even color names.

For more examples, please refer to the documentation.

Controls/Keys

If you are looking for a simplified version, check out the docs. Here is a more in-depth explanation.

You can also see a minified help version by pressing backtick (`) while the Cpick application is running.

In Cpick, there are two main screens: the hue screen and the saturation-value screen.

The hue screen is the first screen that pops up. It contains a hue slider present at the top, two color tint previews on the left, and a table of different preset or custom colors at the bottom.

The saturation-value screen is the screen that pops up once you press enter to select a color on the hue screen. It contains one large color gradient in the center and two color tint previews on the right.

On the hue screen, you initially start off on the hue slider. This is where you can select a specific hue by navigating the table, either using h and l (from vim) or the left and right arrow keys. If you press enter, you will be moved to the saturation-value screen with the table representing the hue you chose. You can also press space to move to the listed colors at the bottom of the hue screen.

For the listed color table on the hue screen, you can navigate it using the standard vim keys (h, j, k, l) or the arrow keys. If you press enter on a selected color, you will be taken to the saturation-value screen and the color you selected will automatically be selected on the big color gradient table. You can also switch between color types by pressing c to go forward a page and C to go back.

In addition, you can press ? to open up a search menu. Here you can search for a specific color or keyword. You can press N to go to the next selection and n to go to the previous selection, just like in vim.

On the saturation-value screen, you can move about the screen using the standard vim keys (h, j, k, l) or the arrow keys. Once on a desired color, press enter to select it.

In addition, you can press g to go to the start of the table (top-left most cell) or G to go to the end of the table (bottom-right most cell).

You can press 'q' or Escape to exit the application at any point, except in the search screen (Escape brings you back to the hue screen and 'q' is treated as a normal letter).

Custom Colors

In Cpick, you can add custom colors that can come up on the color pages. You can add JSON files that hold the colors in 3 ways.

1. Local Environment

Wherever you are running Cpick, you can provide a local colors.json file (file would have the path ./colors.json from wherever Cpick is being run). This has the highest priority.

1. ~/.config Directory

In the ~/.config directory, you can create a cpick directory that can contain the colors.json file (file would have the path ~/.config/cpick/colors.json). This has a lower priority than a local file but a higher priority than a ./cpick directory.

1. ~/.cpick Directory

In your home directory, you can create a .cpick directory that can contain the colors.json file (file would have the path ~/.cpick/colors.json). This has the lowest priority.

The colors.json file has a very strict format.

{
  "colorList": [
    {
      "name": "COLOR NAME 1",
      "colors": []
    },

    {	
      "name": "COLOR NAME 2",
      "colors": []
    },

    {	
      "name": "COLOR NAME 3",
      "colors": []
    }

  ]
}

Each color type consists of an object with a name and colors key. The name key consists of what color type the colors provided are, such as CSS, Solarized, or XTERM. The colors key holds all of the colors that will be previewed when Cpick is run. All of the different color types are in the colorList array.

An individual color is an object that consists of two keys: name and value. name is the name of the color and value is the hexadecimal value of the color as a string. The "#" for the hexadecimal value is optional.

"colors": [
  {"name": "Red",   "value": "#FF0000"},
  {"name": "Green", "value": "#00FF00"},
  {"name": "Blue",  "value": "#0000FF"}
]

Cpick comes with three color types as a default: CSS, Solarized, and XTERM. In order to fix complicated import problems, the JSON data is present in the colors.go file as a string. The preset data always has the lowest priority for being used.

Testing

Cpick has a testing mode that can only be enabled by calling Start with testing mode enabled. This automatically happens when you run go test in the cpick directory.

All of the tests can be found in the tests.go file.

(back to top)

Roadmap

• Version 1.2.0
  • Color Searching
• Version 1.3.0
  • Black Box Testing
  • Application Breakpoints

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

For issues and suggestions, please include as much useful information as possible. Review the documentation and make sure the issue is actually present or the suggestion is not included. Please share issues/suggestions on the issue tracker.

For patches and feature additions, please submit them as pull requests. Please adhere to the conventional commits. standard for commit messaging. In addition, please try to name your git branch according to your new patch. These standards are a great guide you can follow.

You can follow these steps below to create a pull request:

1. Fork the Project
2. Create your Feature Branch (git checkout -b branch_name)
3. Commit your Changes (git commit -m "commit_message")
4. Push to the Branch (git push origin branch_name)
5. Open a Pull Request

(back to top)

License

This project uses the Apache 2.0 license.

You can find more information about this license in the LICENSE file.

(back to top)

Contact

Ethan Baker - contact@ethanbaker.dev - LinkedIn

Project Link: https://github.com/ethanbaker/cpick

(back to top)

Documentation

Overview

Package cpick is an interactive color picker in the terminal using cview

Package cpick is a advanced color picker that can be run from the terminal.

Controls

Help screen:

• View help screen: Backtick (`)

For everything:

• Movement: Use the standard vim keys (hjkl) or arrow keys
• Advanced movement: Press g to go to the top left of the table and press G to go to the bottom right of the table.
• Exiting the application: Press q or Escape

For hue screen (the first screen seen when cpick runs; it contains a slider at the top of the screen, and a list of colors at the bottom)

• Creating a new table based on selection: Press Enter
• Switch between slider and preset color table: Press Space
• Switch between color types on preset color table: Press C to go forwards and c to go backwards (same as vim)
• Enter search menu (for preset colors): Press question mark (?)
• Go to next search instance: Press N to go forwards and n to go backwards (same as vim)
• Switch to saturation-value table: Press Tab

For saturation-value screen (the second screen; it contains a large gradient of a single hue and the corresponding color values on the right)

• Select your final color: Press Enter
• Switch to hue screen: Press Tab

For the search menu (What opens when you press the question mark (?))

To search for a color name, type the name of the color into the search bar. Related colors will appear below.
Once a color (or phrase) is desired, press enter. You can press N (forward) and n (reverse) to swap between instances.

Each value type you want to select will have instructions below:

	* Hexadecimal: type the hex value starting with "#" (EX: #ffffff)
	* RGB: type "rgb:" and three RGB values separated by a space (EX: rgb: 255 255 255)
	* HSV: type "hsv:" and three HSV values separated by a space (EX: hsv: 0 100 0)
	* HSL: type "hsl:" and three HSL values separated by a space (EX: hsl: 0 100 50)
	* CMYK: type "cmyk:" and four CMYK values separated by a space (EX: cmyk: 0 0 0 0)
	* Decimal: type "decimal:" and then the decimal value (EX: 16777215)

Once a color is selected, you will be taken to the Saturation-Value table with the specified color selected.

Any errors that you make will appear in red below the search bar.

Return values

Cpick will return a struct (type ReturnValues) that contains all of the following
values:

* RGB
* HSV
* HSL
* CMYK
* Hex
* Decimal
* Ansi
* Name

RGB, HSV, HSL, CMYK, Hex, Decimal, and Ansi all come from the colors package (github.com/ethanbaker/colors).

Name will only be returned if you select a value from the preset color table. Name will be "Custom color" if no preset color is selected.

A "Hello World" for cpick:

An example to start cpick in "normal" mode: cpick.Start(false, false)

Command Usage:

A cpick bash command can be installed by running `go install` in the cmd/cpick/ directory.

Cpick manual:

NAME

cpick - Color picker in the terminal

SYNOPSIS

cpick [TYPE] [OPTION]

DESCRIPTION

Bring up an extensive color picker to select and return many different colors in
various color types.

TYPES

Types: [rgb|hsv|hsl|cmyk|hex|decimal|ansi|escape|name|json|bash [NAME]|css [TAG]]

Default: ansi

Multiple types will result in the first type entered selected to return. For
example, running `cpick rgb ansi` will return rgb values.

rgb: Return rgb values separated by a semi-colon (EX: 255;127;0)

hsv: Return hsv values separated by a semi-colon (EX: 60;100;100)

hsl: Return hsl values separated by a semi-colon (EX: 60;100;50)

cmyk: Return cmyk values separated by a semi-colon (EX: 60;100;50)

hex: Return a hex value with the "#" (EX: #ffff00)

decimal: Return a deciaml value (EX: 13842970)

ansi: Return the value of an ansi escape code (this will be represented as a color)

escape: Return the ansi escape code (EX: \033[38;2;255;127;0m)

name: Return the name of the color (if there is one)

json: Return a json object containing all of the color info

css: Return a css line containing a certain tag with the specified color in
hexadecimal format. Css takes another keyword, [TAG], which is the specified css
tag that will be outputted. By default, [TAG]="color".

bash: Return a readonly statement with the color constant as an ansi escape code.
Bash takes another keyword, [NAME], that is used as the name of the declaration
statement. By default, [NAME]="custom".

Package cpick is an interactive color picker in the terminal using cview

Index

• Constants
• type ColorValues
  • func Start(testing bool) (ColorValues, error)

Constants

const BREAKPOINT_HEIGHT = 30

Breakpoint boundaries

const BREAKPOINT_WIDTH = 110

Types

type ColorValues

type ColorValues struct {
	RGB     color.RGB
	HSV     color.HSV
	HSL     color.HSL
	CMYK    color.CMYK
	Hex     color.Hex
	Decimal color.Decimal
	Ansi    color.Ansi
	Name    string
}

ColorValues type used to hold color values and optional name

func Start

func Start(testing bool) (ColorValues, error)

Start function starts the cpick application. Testing (bool) is used to test all of the functions to make sure they can run properly without a need for user input (testing = true).