Skip to content

Home

Jump to bottom
Al edited this page Jul 9, 2024 · 18 revisions

PURPOSE

The purpose of PyPalEx is to be a bare-bones tool with the sole task of ONLY extracting colors from images. Nothing more. Nothing less. The extracted colors are organized into color palettes / color schemes / color themes and saved to JSON / YAML files, but this organization of extracted colors is only meant for the ease of use by artists and those in the tech community that decide to use this tool to make their own theme managers. It's up to the people that use this tool to decide how they want to use the data in the extracted file(s). PyPalEx is currently a Command Line tool but should also be importable into Python projects via the import keyword.



TABLE OF CONTENTS



OPTION USAGE EXAMPLES

-f --files

palex -f path/to/image/dir/image.jpeg
palex -f path/to/image/dir/image.jpeg path/to/image/dir/image2.PNG

The -f --files option can be used with a singular image file or with multiple image files. The user must specify the absolute file path to the image they want to use with PyPalEx. However, if the user is already within the directory where the images are located, then a relative file path is also acceptable.

~ > cd path/to
~/path/to >
~/path/to > palex -f image/dir/image.jpeg image/dir/image2.PNG
~ > cd path/to
~/path/to >
~/path/to > palex -f image/dir/image.jpeg
~/path/to > cd image/dir
~/path/to/image/dir >
~/path/to/image/dir > palex -f image.JPEG image2.png

The above examples are meant to show how a user can navigate to a directory with images, or at least relatively close to a directory with images, and then use PyPalEx with the -f --files option and relative file path(s).


-p --path

palex -p path/to/image/dir/
palex -p path/to/ -f image/dir/image.png
palex -p path/to/image/dir/ -f image.png
palex -f image1.png image2.jpg image3.jpeg -p path/to/image/dir/

The -p --path option can be used with a whole directory of images and files or it can be used as a reference point for the -f --files option. When the -f --files option is used with -p --path, the user does not have to specify the absolute path to the images, just the relative image names/filepath(s). The directory that was provided with -p --path will be searched for the image names/filepath(s) specified.


-o --output

palex -f path/to/image/dir/image.jpeg -o path/to/output/dir/ 
palex -o path/to/output/dir/ -p path/to/image/dir/
palex -p path/to/image/dir/ -f image.png -o path/to/output/dir/
palex -f image1.png image2.jpg image3.jpeg -o path/to/output/dir/ -p path/to/image/dir/

The -o --output option can be used with both the -f --files and -p --path options. The sole purpose of the -o --output option is to let the user override the default output directory. Please refer to Environment Variables for details about the default output directory.


--save-check

palex -f path/to/image/dir/image.jpeg -o path/to/output/dir/ --save-check

Asks if the user wants to save the extracted color palettes after the extraction process is completed.


--preview

palex -f path/to/image/dir/image.jpeg -o path/to/output/dir/ --preview

Shows a preview of the extracted color palettes before saving. This option requires that the user's terminal has the capability to show ASCII characters and ANSI colors. A future update may include a GUI variation of this preview option to avoid this issue.


--preview-check

palex -f path/to/image/dir/image.jpeg -o path/to/output/dir/ --preview-check

Shows a preview of, and asks if the user wants to save, the extracted color palettes. This option is a combination of the --preview and --save-check options. This option requires that the user's terminal has the capability to show ASCII characters and ANSI colors. A future update may include a GUI variation of this preview option to avoid this issue.


--pastel

palex --pastel -f path/to/image/dir/image.jpeg -o path/to/output/dir/

Converts all the extracted color types into pastel.


--pastel-light

palex --pastel-light -f path/to/image/dir/image.jpeg -o path/to/output/dir/

Converts light color types into pastel.


--pastel-normal

palex --pastel-normal -f path/to/image/dir/image.jpeg -o path/to/output/dir/

Converts normal color types into pastel.


--pastel-dark

palex --pastel-dark -f path/to/image/dir/image.jpeg -o path/to/output/dir/

Converts dark color types into pastel.


-r --raw-dump

palex -r -f path/to/image/dir/image.jpeg -o path/to/output/dir/
palex --raw-dump -f path/to/image/dir/image.jpeg -o path/to/output/dir/

Exports the extracted colors without organizing them into color palettes.


-g --gen-config

palex -g
palex --gen-config

Generates a configuration file and stores it in the default configuration location for PyPalEx.


-w --where

palex -w
palex --where

The -w --where option is used to print out the default locations of configuration file and extraction directories. It will also tell you if these locations exist or not, as they are optional.


-v --version

palex -v
palex --version

The -v --version option is used to print the PyPalEx version number.



UNDER THE HOOD

This section is just going to explain how the palette extractor works.

Definitions

  • Base Colors: There are 6 base colors that are extracted from every image.
    • [red, yellow, green, cyan, blue, magenta]
  • Color Types: Each base color has 3 color types.
    • [light, normal, dark]
    • Each color type is a combination of the 6 base colors that are of a single color type.
      • light type: [light red, light yellow, light green, light cyan, light blue, light magenta]
      • normal type: [normal red, normal yellow, normal green, normal cyan, normal blue, normal magenta]
      • dark type: [dark red, dark yellow, dark green, dark cyan, dark blue, dark magenta]
  • Palette Types: There are 2 palette types that are available.
    • A light palette type: contains a light background and dark foreground.
    • A dark palette type: contains a dark background and light foreground.

Process of Extraction

  1. First, all the base colors are extracted from the image and placed into a dictionary:
    • { 'Red': [2D list of red colors], 'Yellow': [2D list of yellow colors], 'Green': [2D list of green colors],
      'Cyan': [2D list of cyan colors], 'Blue': [2D list of blue colors], 'Magenta': [2D list of magenta colors] }
  2. Each of these 6 base colors is organized by their brightness values into three color types (light, normal, dark):
    • { 'Red': ([2D list of light red colors], [2D list of normal red colors], [2D list of dark red colors]),
      'Yellow': ([2D list of light yellow colors], [2D list of normal yellow colors], [2D list of dark yellow colors]),
      'Green': ([2D list of light green colors], [2D list of normal green colors], [2D list of dark green colors]),
      'Cyan': ([2D list of light cyan colors], [2D list of normal cyan colors], [2D list of dark cyan colors]),
      'Blue': ([2D list of light blue colors], [2D list of normal blue colors], [2D list of dark blue colors]),
      'Magenta': ([2D list of light magenta colors], [2D list of normal magenta colors], [2D list of dark magenta colors]) }
  3. Only ONE color from each of the light/normal/dark color types is selected for each of the 6 base colors.
    • { 'Red': [light red, red, dark red], 'Yellow': [light yellow, yellow, dark yellow],
      'Green': [light green, green, dark green], 'Cyan': [light cyan, cyan, dark cyan],
      'Blue': [light blue, blue, dark blue], 'Magenta': [light magenta, magenta, dark magenta] }
    • A variation of Euclidean Distance is used to select each of these colors.
    • There is a tiny bit of variation that was purposefully left in during this selection process, but the variation is so minor that it is barely noticeable and can be removed in the future if requested by the users.
  4. PyPalEx then checks for any missing colors and borrows them from one of the already-extracted colors.
    • During this color borrowing process, the hue of the borrowed color is shifted slightly so that you don't have two of the same exact color.
  5. The hue of the MOST dominant color in the image, that appears the most, is selected to be used as the black and white color.
  6. The hue of the MOST dominant color in the image and it's complimentary hue is selected to be the background and the foreground.
    • The background is always a shade of the most dominant color.
    • The foreground is always a shade of the complementary color.
  7. The background and foreground saturation and lightness values are hardcoded, to avoid clashing colors and for better contrast.

Organization of Default Color Palettes

  1. The Light color palette:
    • background: "light background" (hardcoded to be light)
    • foreground: "dark foreground" (hardcoded to be dark)
    • standard colors: "normal color type"
    • high-intensity colors: "dark color type"
  2. The Dark color palette:
    • background: "dark background" (hardcoded to be dark)
    • foreground: "light foreground" (hardcoded to be light)
    • standard colors: "normal color type"
    • high-intensity colors: "light color type"


USING PASTEL OPTIONS

As mentioned in the README description, PyPalEx also has pastel options for the user to use that affect the color types. To avoid misunderstandings, color types in this case will only refer to the 6 base colors and not the black, white, background or foreground colors. Below you will find some examples of how the pastel options affect the default color palettes.

--pastel Option

  1. The Light color palettes:
    • background: "light background" (hardcoded to be light)
    • foreground: "dark foreground" (hardcoded to be dark)
    • standard colors: "normal pastel color type"
    • high-intensity colors: "dark pastel color type"
  2. The Dark color scheme:
    • background: "dark background" (hardcoded to be dark)
    • foreground: "light foreground" (hardcoded to be light)
    • standard colors: "normal pastel color type"
    • high-intensity colors: "light pastel color type"

--pastel-light Option

  1. The Light color palettes:
    • background: "light background" (hardcoded to be light)
    • foreground: "dark foreground" (hardcoded to be dark)
    • standard colors: "normal color type"
    • high-intensity colors: "dark color type"
  2. The Dark color scheme:
    • background: "dark background" (hardcoded to be dark)
    • foreground: "light foreground" (hardcoded to be light)
    • standard colors: "normal color type"
    • high-intensity colors: "light pastel color type"

--pastel-normal Option

  1. The Light color scheme:
    • background: "light background" (hardcoded to be light)
    • foreground: "dark foreground" (hardcoded to be dark)
    • standard colors: "normal pastel color type"
    • high-intensity colors: "dark color type"
  2. The Dark color scheme:
    • background: "dark background" (hardcoded to be dark)
    • foreground: "light foreground" (hardcoded to be light)
    • standard colors: "normal pastel color type"
    • high-intensity colors: "light color type"

--pastel-dark Option

  1. The Light color scheme:
    • background: "light background" (hardcoded to be light)
    • foreground: "dark foreground" (hardcoded to be dark)
    • standard colors: "normal color type"
    • high-intensity colors: "dark pastel color type"
  2. The Dark color scheme:
    • background: "dark background" (hardcoded to be dark)
    • foreground: "light foreground" (hardcoded to be light)
    • standard colors: "normal color type"
    • high-intensity colors: "light color type"
Clone this wiki locally