AnyPalette.js

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. 

Check out the demo!

Features

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

License

MIT-licensed, see LICENSE

Install

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.6.0.js and include it as a script:

<script src="https://github.com/1j01/anypalette.js/raw/v0.6.0/anypalette-0.6.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).

API

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 usage
• options.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, excluding 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:
  • palette: a Palette
  • formatUsed: a Format object representing the file format, or more generic loader, that was used to parse the palette
  • matchedFileExtension: whether the format matched one of the file extensions its known for (Boolean)

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);

class Palette extends Array

(Accessible as AnyPalette.Palette)

Stores a list of Colors, 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 subclass Palette, and Palette is only intended to hold Colors. I plan to change it to simply use a colors 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.

class 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.

`Col