palPal - palette manager library

[HydroNitrogen]

About

palPal (Palette Pal) is a simple but powerful library that aims to be easy to use and can be implemented by other software.
palPal allows you to store the entire current palette of a given terminal object into a table which you can manipulate, save and load again to any given terminal object.

Downloading

palPal is available on GitHub here. You can check out its repo, or download the library file directly by executing the following in your terminal:

Code Select Expand

wget https://raw.githubusercontent.com/Wendelstein7/palPal-CC/master/palPal.lua palPal.lua
Related

palPal can be used in combination with my other library palCollection.
palCollection provides a collection of new, popular, historic and beautiful palettes that can be used.

Please see this forum post to inquire more information about working with palCollection.

Documentation

palPal has a few functions you can use. To harness palPal's power, we must first load it into our environment by doing the following:

Code Select Expand

local palPal = require("palPal")
Now we can access palPal's
Functions:

Code Select Expand

-- storing and loading palettes:
 palPal.storePalette(terminal) -- returns palette table
 palPal.loadPalette(terminal, palette) -- returns nil

 -- setting and getting palette colours:
 palPal.getPaletteColour(palette, colour) -- returns red, green, blue
 palPal.setPaletteColour(palette, colour, red, green, blue) -- returns (updated) palette table

 -- note: en-us users can replace colour with color
Reference:

• terminal refers to a terminal object here, which for example can be a wrapped monitor or just term for the default terminal.
• palette refers to a palette table here as created by the palPal lib. A palPal stored table has 16 keys representing the numeric colour ids with their respective values representing an red green blue colour ranged from 0 to 1, similar to term.getPaletteColour.
• colour refers to a numerical colour index. This must be a power of 2, being at least 1 and at most 32768.
• red, green and blue refer to numbers ranging from 0 to 1.

Example

palPal's simpleness can be demonstrated using the following brief example to show the concept of storing a terminals palette, modifying it and loading it into another terminal.

Code Select Expand

-- First we load palPal into our environment
 local palPal = require("palPal")
 
 -- Now we store the current palette of 'term' (the default terminal) into a variable 'p'
 local p = palPal.storePalette(term)
 
 -- Then we change the default red to being pure red, by giving it new RGB values.
 p = palPal.setPaletteColour(p, colours.red, 1, 0, 0)
 -- For demonstration, I will show that you can also use hexadecimal. We will set blue to being pure blue.
 p = palPal.setPaletteColour(p, colours.blue, 0x0000FF)

 -- Let's wrap an adjecent advanced monitor so we can use it.
 local monitor = peripheral.find("monitor")

 -- Finally now that we made our adjustments, we load our modified palette 'p' into the monitor.
 palPal.loadPalette(monitor, p)

 -- We should use our new blue and red!
 monitor.setTextColour(colours.blue)
 monitor.setBackgroundColour(colours.red)
 monitor.write("Thank you for using palPal. Have a nice day!")
Executing the example will result in the following:

Spoiler

Format

palPal stores its palettes in a table which has 16 keys representing the numeric colour ids with their respective values representing an red green blue colour ranged from 0 to 1, similar to term.getPaletteColour.
These tables allow for easy serialisation and therefore storing to disk, loading and unserialisation.
For example, the default computercraft palette looks like this when serialized:

Code Select Expand

{
  [ 1 ] = { b = 0.94117647409439, g = 0.94117647409439, r = 0.94117647409439 },
  [ 2 ] = { b = 0.20000000298023, g = 0.69803923368454, r = 0.94901961088181 },
  [ 4 ] = { b = 0.84705883264542, g = 0.49803921580315, r = 0.89803922176361 },
  [ 256 ] = { b = 0.60000002384186, g = 0.60000002384186, r = 0.60000002384186 },
  [ 32 ] = { b = 0.098039217293262, g = 0.80000001192093, r = 0.49803921580315 },
  [ 64 ] = { b = 0.80000001192093, g = 0.69803923368454, r = 0.94901961088181 },
  [ 32768 ] = { b = 0.066666670143604, g = 0.066666670143604, r = 0.066666670143604 },
  [ 16384 ] = { b = 0.29803922772408, g = 0.29803922772408, r = 0.80000001192093 },
  [ 128 ] = { b = 0.29803922772408, g = 0.29803922772408, r = 0.29803922772408 },
  [ 8192 ] = { b = 0.30588236451149, g = 0.65098041296005, r = 0.34117648005486 },
  [ 4096 ] = { b = 0.29803922772408, g = 0.40000000596046, r = 0.49803921580315 },
  [ 2048 ] = { b = 0.80000001192093, g = 0.40000000596046, r = 0.20000000298023 },
  [ 1024 ] = { b = 0.89803922176361, g = 0.40000000596046, r = 0.69803923368454 },
  [ 8 ] = { b = 0.94901961088181, g = 0.69803923368454, r = 0.60000002384186 },
  [ 16 ] = { b = 0.42352941632271, g = 0.87058824300766, r = 0.87058824300766 },
  [ 512 ] = { b = 0.69803923368454, g = 0.60000002384186, r = 0.29803922772408 }
}Note: The strange order of colour indexes and rgb is caused by the way textutils.serialise works. The order does not harm the data in any way.

Licence

palPal is licenced under the MIT licence, Copyright (c) 2018 Wendelstein7 (a.k.a. HydroNitrogen)

You can definetely use this in your programs, I really recommend everyone doing so! You should make your programs that require it download the library from the raw GitHub link.
You are allowed to distribute this library yourself along with your other software that requires it (giving proper credit), but I strongly recommend downloading it from GitHub dynamically.