Valid String values for colors include:

• RGB values in hexadecimal (a.k.a. hex) with or without the leading # symbol.
• RGB values as:
  • integer byte values (0—255)
  • percent ratios (0%—100% — ¡be sure to use the percent % symbol with RGB values!)

  Each value may be separated by spaces/commas.  You may wrap() or prefix: the values with rgb( ) or rgb: but that is not necessary.

• various different color-space models including:
  • CMYK
  • CMY
  • HSV / HSB
  • HSL
  • HCG
  • Hue ←  define only a hue-angle-value and see the full-color (fully chromatic) tone of the hue.
  • XYZ →  (Observer = 2°, Illuminant = D65) 0 ≤ X ≤ 95.047, 0 ≤ Y ≤ 100, 0 ≤ Z ≤ 108.883

  Use models by wrapping() or prefixing: their given values.  Values are given as percent ratios (0%—100% with or without the percent sign %); except Hue values are given in angular values using one of the following units: (the default unit used when none is specified is found in an RGB_Calc object’s .config.hueAngleUnit property)

  • in degrees (0°—360° ← post-fixed using the ° symbol or “deg”).
  • in radians (0ᴿ–2πᴿ≈6.2831853ᴿ ← post-fixed using the ᴿ symbol, the ᶜ symbol, or “rad”).
  • in gradians (0ᵍ—400ᵍ ← post-fixed using the ᵍ symbol or “grad”).
  • in % of a turn (0%—100% ← post-fixed using the % symbol).
  • of a turn (0●—1● ← post-fixed using the ● symbol or “turn”).
• Any of the available ▼named “palette” colors.  Colors should be prefixed: or wrapped() with the appropriate color-palette name; except CSS colors do not need to be wrapped or prefixed by default.  (The default color-palette name can be found and changed at SoftMoon.defaultPalette)  “Named color” palettes may have sub-palettes; you may or may not need to include the sub-palette name in your color-spec, depending on the palette.  Generally, if all the colors in the parent palette and its sub-palettes have different names, no sub-palette is required in the spec.  ANSI: 35 ANSI: 8-bit: shades and tones: 35

You may specify opacity (the opposite of transparency) in any of the color space models (RGB, CMYK, CMY, HSV, HSL, HCG, HWB, Hue) by adding an additional factor (0-1) or percent (0%-100% ← you must use the percent % sign).  This is called the “Alpha” channel in technical terms.  The color-space model names may or may not end with an additional “A” (for example, RGB vs. RGBA). Per CSS4 specifications, the opacity value may also be separated with a / symbol that is itself preceded and followed by a space; for example RGBA(0, 153, 255 / 62%)  Note the “loose” interpretation of CSS specs allows commas with the / alpha separator. Hex-RGB values may have an additional 2 hex digits to specify the alpha; for example #ADDCAD80  Named colors may use the same Alpha specification for color space models described above, but it must end with either a semicolon ; or a space followed by opacity;  For examples:

• Green 30%;
• DodgerBlue, 78%;
• ANSI: 35 / .84 opacity;

Note that named colors may already have and Alpha value, and if you “add on” another Alpha value as shown above, it will be multiplied by the color’s existing one.  For example, if a named-color already has an Alpha value of 50%, and you add on another 50% Alpha, the final Alpha value is 25%.  You can forbid this action using myCalc.config.forbidAddOnAlpha=true; (or by using myCalc.config.stack({forbidAddOnAlpha:{value:true}});).

Examples:

• These all give the same red color:
  • 255 0 0
  • rgb (255 0 0)
  • rgb(255, 0 0)
  • #FF000
  • ff0000
  • HCG(0deg, 100, 50)
  • HSL: 0°, 100%, 50%
  • HSV: 0° 100% 100
  • red
  • CSS: red
  • X11( RED )
• These all give the same blueish color:
  • 135, 206, 250
  • RGB (135, 206, 250)
  • RGB: 135, 206, 250
  • #87cefa
  • 87ceFA
  • hcg(202.96deg, 45.098% 96.429%)
  • hsl:56.3768%,92,75.49
  • hsv ( .563768turn 46% 98.039% )
  • lightSkyBlue
  • css (LiGHTSKyBLue)
  • X11:lIghtskYblUE

In general, only the first 4 listed properties of RGB_Calc (above) are used, and in common use, only the first 3 listed.  There are 2 different color-blind filters currently available for the RGB_Calc Class library.  Both install themselves as RGB_Calc.to.colorblind() methods; but only one can work at a time.  They also install their meta-data in the static RGB_Calc.colorblindProviders property.  You can use RGB_Calc.install('colorblind', 'Rigden') or RGB_Calc.install('colorblind', 'Wickline'), and the filter you choose will become the one that is active, not only in RGB_Calc.to but in all future calculators constructed (using for example myCalc = new RGB_Calc();). If you use, for example myCalc.install('colorblind', 'Rigden') then the colorblind filter you install will only take effect on that individual instance of the RGB_Calc Class.

The RGB_Calc.to and RGB_Calc.from methods are all lowercase, and the RGB_Calc.from methods must be for the “catch-all” String filtering function to recognize them.  You may add to them as you wish.  The format makes programming with them simple & easy to de-localize, allowing, for examples: RGB_Calc.from[model] or myCalc.to[model].

The RGB_Calc.to and RGB_Calc.from objects have as their prototype the calculator they are attached to.  That means that the prototype of RGB_Calc.to or RGB_Calc.from is itself RGB_Calc.  Likewise, when you construct a custom calculator: const myCalc = new RGB_Calc() the objects myCalc.to and myCalc.from have as their prototypes myCalc.  Therefore, any of the methods of RGB_Calc.to or RGB_Calc.from (or similar to newly constructed calculators) can refer to this.config and assess the ConfigStack instance for the given calculator.

The other RGB_Calc methods are all hooks to functions that are used internally.  These hooks are for plug-ins to the RGB_Calc Class to access.  You may use these hooks or hack them as you wish, but generally you need not worry about them.

Finally, the last 3 properties listed above of RGB_Calc are static properties and are not included with class instances.  They are also available for your hacking or other use, but the RGB_Calc.ConfigStack constructor and its .prototype need special attention. 

Every calculator gets its own instance of an RGB_Calc.ConfigStack constructed object for its .config property, and every RGB_Calc.ConfigStack instance is “attached” to its calculator.  Also, every custom Color Object (RGBA_Colors, ColorWheel_Colors, & CMYKA_Colors) gets its own ConfigStack, and those stacks each may have different defaults for each type of custom Color Object.  The “ConfigStack” has in its prototype all the default configuration values and special methods.  You can easily change the values in any individual calculator or Color Object without affecting the others, for example RGB_Calc.config.roundRGB=true;.  But the “ConfigStack” is a prototype-stack with methods to add to and remove from the stack: specifically RGB_Calc.config.stack() and RGB_Calc.config.cull().  When you .stack(), the “Stack” adds another new Object to its own top-level making itself the prototype of this new Object, and re-points its calculator’s .config property to this new Object.  (Remember, when JavaScript™ looks for a property of an object and doesn’t find it there, it looks in that object’s prototype and then recursively the prototype’s prototype until it finds the property; this makes native JavaScript™ Objects an ideal container for configuration values!)  Then you can change the configuration values as you like to temporarily suit your needs, then use .config.cull() to return to the previous configuration values.  To make it even easier, .config.stack() accepts a parameter that is a JavaScript™ Object-Properties-Definer (see a good ►JavaScript™ reference): for example myCalc.config.stack({roundRGB:{value:false}, RGBA_Factory:{value:Array}});.  In this way, you can temporarily modify individual configuration value(s) for an individual calculator and then restore the original value(s), quickly and easily without having to keep track of said original value(s).  You can use .config.stack() multiple times and build the “ConfigStack” to as many levels as you need; the .config.reset() method will remove all the Objects stacked for the given calculator’s configuration. 

For any calculator, you don't need to .stack() the .config to temporarily change the config values if you only use defaults in your calculator instance, as the defaults are in the prototype. However, if you pass a .config descriptor object to the RGB_Calc constructor, those values are stored in the top level of your ConfigStack, and modifying the .config directly modifies them.  Using delete as shown below is faster and convenient if you only want to temporarily change one or maybe two values.  Using it with many values may be slower and clutters your codespace — that’s why .stack() and .cull() were included.

const myCalc=new SoftMoon.WebWare.RGB_Calc({hueAngleUnit:'grad'}); myCalc.from.hsv("34, 95, 45"); // input as gradians & percents by this calc’s current default myCalc.config.inputAsFactor=true; myCalc.from.hsv("34grad, .95, .45"); // input as gradians & factors by this calc’s current default delete myCalc.config.inputAsFactor; // now the .config value goes back to the old default, faster than .stack() & .cull() myCalc.config.hueAngleUnit='rad'; // we can never go back to "grad" - if we delete this value, the prototype value is used myCalc.config.stack(); // if we did this first (after we created the calculator) all values could be preserved using delete

There is also a flag to .config.resetConfigStackOnThrownError when using the standard .config.onError() handler. However, now-a-days it is considered best practice to use a try {…} finally {…} code-block (this config option was developed for legacy dinosaur browsers, but it still may simplify your complex coding schemes).  Note using try {…} finally {…} also covers your script’s butt if a native JavaScript™ Error occurs (none now known to exist) in the RGB_Calc code itself.

const myCalc=new SoftMoon.WebWare.RGB_Calc; document.querySelector('input#userColor').attachEventListener('change', function() { myCalc.config.stack({throwErrors: {value:true}}); try {doItAgainAndAgain(this.value);} // if the user-input is in error, an Error is thrown and console outputs once here … catch(e) {console.error('we had an error with the color:',e);} // … … … and a second time here //we ALWAYS want to clean up the stack, but since any Errors are caught above, we really don’t need “finally” below finally {myCalc.config.cull();} } ); function doItAgainAndAgain(userInput) { const c1=myCalc.to.hsl('RGB: 234,127,35'); console.log(c1); //outputs from the standard HSLA_Color object: HSL(27.74deg, 82.57261%, 52.7451%) myCalc.config.stack({HSLA_Factory: {value:Array}}); try { const c2=myCalc.to.hsl(userInput); console.log(c2); //outputs from the Array object, or “null.” (“red” is): Array(3) [ 0, 0.5, 1 ] } //we ALWAYS want to clean up the stack, or if an error is thrown in the above calculator, //the stack will still have the HSLA_Factory as an Array next time we use this function or this calculator. finally {myCalc.config.cull();} } doItAgainAndAgain('red'); // no errors here - console outputs twice doItAgainAndAgain('foo-bar'); // an error but it is not thrown - console outputs twice, second is "null"

There is no reason you can’t also change the ConfigStack.prototype itself.  As is with JavaScript™, this will modify the default configuration values for all calculators: the basic RGB_Calc itself, as well any constructed in the past or future.

The 7 “Factory” pointers of a ConfigStack instance (above) control the output of the functions of RGB_Calc and its instances.  You can set any the default configuration values for your new calculator by passing an Object with corresponding key/value pairs to the constructor as the 1st parameter.  You can also set default configuration values for the custom Color Objects (RGBA_Color, etc.) by passing to their constructors the configuration options object as the final (5th or 6th) value.  Note that unlike the .config.stack() method, this configuration Object is not a JavaScript™ “properties descriptor.”

/* * this example provides a calculator that returns * RGB output as a simple array of values, * instead of the default RGBA_Color object instance: */ myCalc=new SoftMoon.WebWare.RGB_Calc({RGBA_Factory:Array}); /* * this example provides a calculator that returns * an RGBA_Color object instance that outputs * hex using the # symbol, regardless of the universal default: */ myCalc=new SoftMoon.WebWare.RGB_Calc; myCalc.config.RGBA_Factory=function(r,g,b,a) { return new SoftMoon.WebWare.RGBA_Color(r,g,b,a,{useHexSymbol:true}); };

“audit”, “quick”, & “mini” calculators

When you create your own new calculator, it can be either an “audit” or “quick” type.  This is controlled by passing true for a “quick” calculator, or false (the default) for an “auditing” calculator, as the 2nd parameter to the constructor.  You can even make your own custom “mini” calculators that only have the conversion function(s) you specifically need.  The “mini” calculator descriptor Object (passed into the constructor as the 3rd parameter) can have “to” and/or “from” options (property keys), and their values should be an Array listing the conversion functions as individual String values.  You can have any combination of these options, such as a “quick-mini” calculator that returns native Arrays.

// This is the calculator that the “Rigden-colorblind_websafe-table_interpolator” // plug-in for this RGB_Calc class uses in its own internal workings. // It is a “quick” calculator that only has RGB to HCG functionality, and it returns an Array. const rgb_calc=new SoftMoon.WebWare.RGB_Calc( {HCGA_Factory: Array, defaultAlpha: undefined}, true, {to:['hcg']} );

using the named-color palettes

The RGB_Calc Class can interpret named colors, as well as color-models, when using an “auditing” calculator.  It comes packaged with nine named-color database files included: ANSI, Brewer, common, Crayola, CSS, Material Design, OpenOffice, universal, & X11.  The palette file format can come in two formatting flavors: JavaScript™ & JSON. The JavaScript™-formatted palette-files can be hard-loaded using an HTML <script> tag in your web-page; while the JSON-formatted palette-files can be loaded from a server using HTTP.  The RGB_Calc package comes with a basic JavaScript™ function (SoftMoon.WebWare.loadPalettes()) to load JSON palettes from a server as well as a basic PHP file for the server’s color_palettes/ folder “index” that are designed to work together.  (Note that the name of this folder can be changed but it must end with a folder-separator / — see: SoftMoon.colorPalettes_defaultPath)  (Note also that the PHP “index” file may be replaced with one in any programming language, or even a static text file!) You can simply add/remove palette files (they must have the extension: .palette.json) from the server’s color_palettes/ folder without having to modify any HTML, JavaScript™, or PHP code (if you use a static text file for the “index”, you will have to keep it manually updated); the “qualifying” palette files in the folder will be loaded.  Without a server, the palette files must be loaded via HTML <script> tags in the JavaScript™ flavor.

You can also create your own named-color palettes, and an instructional file to do so is included in the color_palettes/ folder.  As a special note, your palettes can have their own .config values for the calculator that interprets them, and this should be a simple object containing the properties and their settings you desire, the same as you pass into the calculator or custom-color-objects constructors (not an object-properties-descriptor formatted for ▲ .config.stack()).  You may want to pay attention to them if you use a “non-standard” configuration.  All palettes use inputAsFactor=false and hueAngleUnit='deg' by default, regardless of whatever the current calculator’s .config values are.  Remember, simply using unit-qualifiers in your palette’s color specs may alleviate the need for any .config values.  In particular, your individual palettes may want to control the default Hue-angle-unit, input-as-factors, input-as-short-hex, default Alpha values, or whether to allow add-on Alpha values.  Configuration values for palettes are by default limited to the above list of properties, since normally the other calculator configuration settings are not Palette-specific, but your implementation may add (or remove) properties from this list.  There is no reason you couldn’t, for example, create a system that uses your own custom Color-objects as return-data from the calculator, and your individual Palettes may want to specify which “Factory” to choose.  You can control which .config properties are allowed in a Palette through the array at SoftMoon.WebWare.Palette.configProps by adding/removing string-names of the specific properties.

Palette files may have extraneous meta-data in them.  The supplied files come with meta-data that the ►MasterColorPicker project uses.  You may also put any meta-data in the palettes you create, but when they are loaded and processed, the final SoftMoon.WebWare.Palette object that gets saved in SoftMoon.palettes will not, by default, include said meta-data.  If you want your meta-data included in the processed palette, you need to tell the SoftMoon.WebWare.Palette constructor to include it.  To do so, add string values for the meta-data property names to the SoftMoon.WebWare.Palette.properties array.  If your custom palette uses the meta-data property “foobar,” then use the code: SoftMoon.WebWare.Palette.properties.push('foobar');

Palette files are supplied in the JavaScript™ flavor.  To use them with a server requires that they are converted to JSON.  This is simple and easy; there is an instructional file to do so manually, as well as a PHP file to do so automatically.  Find both in the color_palettes/ folder.

To use a JavaScript™ flavored palette, you must first create a property of the SoftMoon namespace: SoftMoon.loaded_palettes=new Array; then load the file using a <script> tag.  The palette will place itself in the SoftMoon.loaded_palettes array.  You must then use a JavaScript™ Event-handler to add the palette to the “processed” palettes (found in SoftMoon.palettes).  You use the function SoftMoon.WebWare.addPalette() to process the palette.  You can use an “onload” property of the <script> tag as shown in the example at the top of this page, or wait until all palettes are loaded and use an “onload” event on the window and then add all palettes found in the SoftMoon.loaded_palettes array.

To use a JSON flavored palette, the SoftMoon.WebWare.loadPalettes() function contacts the server, requesting the index for the palette files.  The index returned contains the names of all palette files in the color_palettes/ folder & its sub-folders.  Once the loadPalettes() function gets the index, it “qualifies” each file for loading.  Any file in a “trash” folder or its sub-folders is ignored.  Any file in a “users” folder or its sub-folders is ignored, unless it is in an “autoload” folder or its sub-folders.  The names of these folders (“trash”, “users”, “autoload”) can be modified, but it is a bit trickier and requires knowing how to use JavaScript™ Regular Expressions; see the loadPalettes() function code in the RGB_Calc.js file for more details.  Once a palette file is deemed “qualified” for loading, it is loaded, processed, and added to SoftMoon.palettes

The SoftMoon.WebWare.loadPalettes() function requires no parameters to work, but it can take many, to customize the palette loading process.  These are no light-duty customizations.  The details of these customizing options are beyond this text, require that you fully understand JavaScript™ and asynchronous communications, and are fairly self-explanatory if you read the loadPalettes() function code in the RGB_Calc.js file.  The loadPalettes() function relies on the external file HTTP.js to handle communications, and some of the parameters you pass are for customizing that Class’ functionality so see its file also.

Palettes may also be loaded from a browser’s internal database.  The SoftMoon.WebWare.loadDBPalettes() function handles this.  However, no functionality is supplied to store a palette in the database; this may change in the future.  (The ►MasterColorPicker project can create them, if you are interested; but remember: browser databases only work with the website domain (when using a server) or the individual HTML file (when working from your home filesystem) that created the database.) Palettes in the database should be JSON formatted.  You can also customize the functionality of the loading process as you can when loading from a server — see the code.

RGB_Calc’s custom color Objects

The RGB_Calc package comes with constructors for custom color Objects and these are used as the default output from conversion functions.  They are meant to be relatively “universal” in usage with other software packages.  They are designed internally so if you change one value in the color-object, it reflects throughout the entire object.  For example, in an RGBA_Color object, if you change the property of .red, the other properties .r .rgb[0] .rgba[0] & .hex all change in accordance.  The RGBA_Color objects also have within themselves conversion properties to other color-models, as well as properties that provide “contrast” and “shade.”  These other custom objects have within them a conversion property to RGB, and HSBA_Color & HSVA_Color objects also provide a conversion property to CMYK, since this is a near-parallel mapping.  You can find this latter conversion service as a static function at: SoftMoon.WebWare.HSVA_Color.to_CMYK()

const myRGB=new SoftMoon.WebWare.RGBA_Color(245, 191, 46); console.log(myRGB.to.hcg); //this is a property, not a method. console.log(myRGB.to.cmyk); //this is a property, not a method. console.log(myRGB.contrast); //this is a property, not a method. const myHSV=new SoftMoon.WebWare.HSVA_Color(0.4, 0.9, 0.67); console.log(myHSV.to.rgb); //this is a property, not a method. console.log(myHSV.to.cmyk); //this is a property, not a method. const myHSV_array=[0.4, 0.9, 0.67]; console.log(SoftMoon.WebWare.HSVA_Color.to_CMYK(myHSV_array)); // this is a simple function, not a method.

These custom color Objects also provide .toString() methods that provide user-friendly reading.  These methods are highly customizable with ease, on-the-fly as necessary.  To control their output, you use the ConfigStack configuration object of the custom color Object (e.g. myColor.config.stringFormat) or pass in the formatting info directly to the .toString() method.  For ColorWheel_Colors, the .config.useAngleUnitSymbol option is valid also.  See the ▲details in the section on ConfigStacks above.

You should note that the HSB and HSV color-models are actually one-in-the-same.  RGB_Calc’s custom underlying Color-Object is therefore the same.  You can access “.brightness” from an HSVA_Color instance, and “.value” from an HSBA_Color instance.  The only difference is in the constructor and name values:

const hsv=new SoftMoon.WebWare.HSVA_Color(0.3, 0.5, 0.7); const hsb=new SoftMoon.WebWare.HSBA_Color(0.3, 0.5, 0.7); console.log(hsv instanceof HSBA_Color); //false console.log(hsb instanceof HSVA_Color); //false console.log(hsv instanceof ColorWheel_Color); //true console.log(hsb instanceof ColorWheel_Color); //true console.log(hsv.name) //HSVA_Color console.log(hsb.name) //HSBA_Color console.log(hsv.brightness) //0.7 console.log(hsb.value) //0.7