There are a LOT of different types of palette files. Like, way too many. But we can solve this.
One library to rule them all,
one library to find them,
One library to load them all
and in the browser bind them.
AnyPalette.js has a single interface for all formats, so you can load any of the supported file types with one call, and it'll choose an appropriate parser to use automatically.
It can even load from files that aren't intended specifically as palettes, but that have CSS-style color values in them (.css, .html, .svg, .js, etc.)
Works in Node.js and in the browser.
Supported palette formats:
File Extension | Name | Programs | Read | Write |
---|---|---|---|---|
.pal | RIFF Palette | MS Paint for Windows 95 and Windows NT 4.0 | ✅ | ✅ |
.gpl | GIMP Palette | Gimp, Inkscape, Krita, KolourPaint, Scribus, CinePaint, MyPaint | ✅ | ✅ |
.aco | Adobe Color Swatch | Adobe Photoshop | ✅ | ✅ |
.ase | Adobe Swatch Exchange | Adobe Photoshop, InDesign, and Illustrator | ✅ | ✅ |
.txt | Paint.NET Palette | Paint.NET | ✅ | ✅ |
.act | Adobe Color Table | Adobe Photoshop and Illustrator | ✅* | ✅ |
.pal, .psppalette | Paint Shop Pro Palette | Paint Shop Pro (Jasc Software / Corel) | ✅ | ✅ |
.hpl | Homesite Palette | Allaire Homesite / Macromedia ColdFusion | ✅ | ✅ |
.cs | ColorSchemer | ColorSchemer Studio | ✅* | |
.pal | Starcraft Palette | Starcraft | ✅ | ✅ |
.wpe | Starcraft Terrain Palette | Starcraft | ✅ | ✅ |
.sketchpalette | Sketch Palette | Sketch | ✅ | ✅ |
.spl | Skencil Palette | Skencil (formerly called Sketch) | ✅ | ✅ |
.soc | StarOffice Colors | StarOffice, OpenOffice, LibreOffice | ✅ | ✅ |
.colors | KolourPaint Color Collection | KolourPaint | ✅ | ✅ |
.colors | Plasma Desktop Color Scheme | KDE Plasma Desktop | ✅ | |
.theme | Windows Theme | Windows Desktop | ✅ | |
.themepack | Windows Theme | Windows Desktop | ✅ | |
.css, .scss, .styl | Cascading StyleSheets | Web browsers / web pages | ✅ | ✅ |
.html, .svg, .js | any text files with CSS colors | Web browsers / web pages | ✅ |
*The ColorSchemer file parser is only enabled when the file extension is known to be .cs
,
provided by passing a File
object, or options.fileName
, or options.fileExt
, or options.filePath
.
The Adobe Color Table loader is only enabled when the file extension is known to be .act
OR the file is exactly 768 or 772 bytes long.
UNSUPPORTED palette formats (for now):
File Extension | Name | Programs | Read | Write |
---|---|---|---|---|
.gpa | Gpick Palette | Gpick | ||
.acb | Adobe Color Book | Adobe InDesign and Illustrator | ✅** | |
.acbl | Adobe Color Book Library / Legacy | Adobe InDesign and Illustrator (?) |
**None of the color spaces are supported (CMYK, CIELAB, CIEXYZ). The code is mostly all there! But I think probably ICC profiles are needed for correct-looking colors.
Picking colors from an image can be done by other libraries, like vibrant.js/node-vibrant
MIT-licensed, see LICENSE
For Node.js / Webpack / Parcel / Rollup / Browserify, install with:
npm i anypalette --save
# or
yarn add anypalette
Then access the library with:
const AnyPalette = require("anypalette");
Alternatively, download build/anypalette-0.7.0.js
and include it as a script:
<script src="https://github.com/1j01/anypalette.js/raw/master/anypalette-0.7.0.js"></script>
This will create a global AnyPalette
This library uses UMD, so you can also load it with AMD or CommonJS (in which case it won't create a global).
See the changelog for upgrading. Properties and methods not documented here may break without notice.
AnyPalette.loadPalette(options, callback)
Load a palette from a palette file. You can pass in the file data in a few different ways.
Knowing the file extension means AnyPalette.js can often pick the correct palette loader right away, which can improve the load speed, and also a few loaders are only enabled if their specific file extension matches because they can't determine if the file is actually in that format or not (for raw data formats without headers).
options.file
- the palette file to load, as a File
options.data
- the palette file data to load, as a binary string or ArrayBuffer
or Node.js Buffer
or Uint8Array
(but not any other TypedArray
or DataView
). In the case of a binary string, Unicode names for colors do not work, so an ArrayBuffer
is preferred.options.filePath
- a path to a palette file, for Node.js usageoptions.fileName
(optional) - the file name, if you have it, including the file extension - can be obtained automatically from options.file
or options.filePath
options.fileExt
(optional) - the file extension, if you have it, with or without the dot, e.g. "pal"
- can be obtained automatically from options.fileName
or options.file
or options.filePath
callback(error, palette, formatUsed, matchedFileExtension)
(required) - called when palette loading is finished, either with an error (in the first argument) or with the remaining arguments in the case of success:
Note: The callback is actually executed synchronously if you pass data directly. It's in an asynchronous style to allow for file loading, but all the palette parsing is currently synchronous. TODO:
setImmediate
at least.
AnyPalette.loadPalette(file, callback)
Shortcut to load from a File
object, equivalent to passing {file: file}
for options
.
AnyPalette.loadPalette(filePath, callback)
Shortcut to load from a file path in Node.js, equivalent to passing {filePath: filePath}
for options
.
AnyPalette.writePalette(palette, format)
Returns string (for text-based formats) or ArrayBuffer
(for binary formats) of the content of a file, in the given Format
.
To save a palette as a GPL file, sending a download in a browser:
var format = AnyPalette.formats.GIMP_PALETTE;
var file_content = AnyPalette.writePalette(palette, format);
var file = new File([file_content], "Saved Colors.gpl");
var url = URL.createObjectURL(file);
var a = document.createElement("a");
a.href = url;
a.download = file.name;
document.body.appendChild(a);
a.click(); // Note: this must happen during a user gesture to work
document.body.removeChild(a);
If you don't know what format to export as, use GIMP_PALETTE
(.gpl
), as it's supported by a wide range of software.
AnyPalette.uniqueColors(palette)
Some palette formats are commonly made variable size by just leaving unused slots a certain color
such as #000
or #00F
.
You can get a Palette
with only unique colors like so:
var withoutDuplicates = AnyPalette.uniqueColors(palette);
Palette
extends Array
(Accessible as AnyPalette.Palette
)
Stores a list of Color
s, and some metadata.
Because Palette
is a subclass of Array
, you can use forEach
, map
, join
and other methods,
or access the colors via indexing e.g. palette[0]
and loop over them using palette.length
Note: I think this was a bad design decision because
map
unintuitively returns an instance of the subclassPalette
, andPalette
is only intended to holdColor
s. I plan to change it to simply use acolors
field.
I could make it an array-like object, but that might introduce other confusions. I don't know, jQuery does it. And a bunch of browser-native objects are array-like instead of proper arrays. Maybe that's the way to go.
palette.numberOfColumns
palette.numberOfColumns
may contain a number of columns for the palette to fit into (with the number of rows being implicit).
You should ignore a numberOfColumns
of zero or undefined
, and MAY want to ignore this property entirely.
Inkscape, for example, ignores the number of columns specified in a palette.
palette.name
palette.name
may contain a name for the palette (as a string), or else undefined
.
This is not populated with the filename, it's only available for palette formats that allow defining a name within the file.
palette.description
palette.description
may contain a description for the palette (as a string), or else undefined
.
Color
(Accessible as AnyPalette.Color
)
Color
has a toString
method that returns a CSS color, which means you can
pass a Color object directly to an element's style or a canvas's context.
var color = palette[0];
div.style.background = color;
ctx.fillStyle = color;
See Using JavaScript's 'toString' Method, which incidentally uses a Color
class as an example.
In some cases you may need to call toString()
explicitly to get a string, for example:
var shortenedColorString = color.toString().replace(/\s/g, "");
Color
objects also have red
, green
, blue
properties, and depending on how they were loaded, might have hue
, saturation
, lightness
, and/or alpha
.
color.name
color.name
may contain a name for the color (as a string), or else undefined
.
Not all palette formats support named colors.
Color.is(colorA, colorB, epsilon=0.0001)
Determines whether two colors are equal in value, or nearly equal.
var firstTwoColorsExactlyEqual = AnyPalette.Color.is(palette[0], palette[1], 0);
var firstTwoColorsBasicallyEqual = AnyPalette.Color.is(palette[0], palette[1], 0.001);
var firstTwoColorsSimilar = AnyPalette.Color.is(palette[0], palette[1], 20);
Note: If you want to find perceptually similar colors, it's better to use CIELAB color space instead of RGB. This function compares in RGB space and is really only meant for finding duplicates.
Format
This class represents a loader and/or writer.
name
: A friendly name for the format, e.g. "Paint Shop Pro palette"
fileExtensions
: An array of associated file extensions, without the dot, e.g. ["pal", "psppalette"]
fileExtensionsPretty
: A textual representation of the file extensions, including the dots, e.g. ".pal, .psppalette"
readFromText
: This exists on text-based readers. Don't use it directly, use AnyPalette.loadPalette
instead.read
: This exists on binary readers. Don't use it directly, use AnyPalette.loadPalette
instead.write
: This exists on writers. Don't use it directly, use AnyPalette.writePalette
instead.AnyPalette.formats
This is an object that contains Format
objects, keyed by format IDs.
To get an array of formats:
const formats = Object.values(AnyPalette.formats);
To get just writers:
const writeFormats = Object.values(AnyPalette.formats).filter((format)=> format.write);
To get just readers:
const readFormats = Object.values(AnyPalette.formats).filter((format)=> format.read || format.readFromText);
Load all the palettes!
.png
) - see MagicaVoxelPalettes for examples.clr
).gpa
).acf
).bcf
).mtl
).acbl
).acb
).qcl
).xml
).skpx
/ .skp
)Guess palette geometries?
More stuff (I have an external TODO list)
Install Node.js, if you don't already have it. (It comes with npm
)
Fork and clone the repository
The repo has a git submodule, so in the repository folder run git submodule update --init
Install dependencies with npm install
npm start
will start a server and open a page in your default browser;
it'll rebuild the library when changes to the source files are detected, and it'll auto-reload the page
Run npm test
to update a regression-data
folder, and then view any changes with git.
*.out.2.*
files are for files that are saved differently when loading a saved file. Ideally we want none of these.Update CHANGELOG.md's [Unreleased] section with any notable changes, following the Keep a Changelog format. Include any information someone upgrading the library might need to know.
When pulling changes (e.g. syncing a fork) you may need to npm install
again to update the dependencies.
The process is currently something like this:
(TODO: use update-changelog (altho it doesn't support links to commit ranges... this does, but it's for a different ecosystem))
npm run build
npm test
git diff tests/ # there shouldn't be changes to the test data at this point, that should ideally happen in earlier commits
git add -A && git commit -m "Update for release"
npm version minor # or major or patch or a specific version number
git push --follow-tags # better than --tags!
npm publish