mColor

Manipulate RGB/HSL colors module.

Getting Started

1. Install mColor via NPM.

npm install mcolor

Optionally: rename mcolor to mColor: npm is unable to handle the complexity of uppercase characters in a module name. Node.js on Windows does not have this problem, so renaming the folder is not required for you to use the module.

2. Require mColor in your project.

var mColor=require("mColor");

3. Create and modify colors using mColor.

var oWhiteRGBA = new mColor.cRGBA("#FFFFFFFF"),
    oWhiteHSLA = new mColor.cHSLA(0, 0, 1, 1),
    oRedRGBA = new mColor.cRGBA(1, 0, 0, 1),
    oRedHSLA = new mColor.cHSLA(0, 1, 0.5, 1),
    oBlueRGBA = new mColor.cRGBA("blue"),
    oNavyHSLA = new mColor.cHSLA("navy"),
    oTransparentGreenRGBA = new mColor.cRGBA(0, 1, 0, 0.5),
    oTransparentGreenHSLA = new mColor.cHSLA(1/3, 1, 0.5, 0.5),
    oPinkRGBA = new mColor.cRGBA(1, 0.75, 1, 1),
    oPinkHSLA = new mColor.cHSLA(5/6, 1, 7/8, 1);

// Create a copy of red and make it white
var oWhiteHSLA = oRedHSLA.foClone().foSetL(1);
// Create a copy of transparent green and have it overlaying opaque pink.
var oGreenMix = oTransparentGreenHSLA.foClone().foOver(oPinkRGBA) 
// Create a copy of transparent green and make it opaque and add red to make
// yellow.
var oYellowRGBA = oTransparentGreenHSLA.foClone().foSetA(1)
                                       .foGetRGBA().foSetR(1);

Notes

This module has two classes, cRGBA and cHSLA, which respectively represent colors based on the intensity values of the red, green, and blue color channels and the hue, saturation and luminosity values. Instances of either class can be converted to the other. Note that this may result in loss of information, eg. converting the color white from cHSLA to cRGBA results in loss of the hue value.

API

class cRGBA

Create color objects based on red, green, and blue color channel intensity values, as well as alpha transparency. Internally the values are stored as floating point numbers in the range [0, 1], resulting in very little risk of rounding errors.

Constructors:

[new] cRGBA(String sRGBA);

Where sRGBA is a hex triplet or quadruplet. If a quadruplet is provided, the last digits provide the alpha transparency value. Otherwise, the color will be fully opaque. Shorthand forms are accepted, so "#FFF", "#FFFF", "#FFFFFF", and "#FFFFFFFF" are all opaque white.

[new] cRGBA(Number nR, Number nG, Number nB [, Number nA]);

Where nR, nG, nB, and nA are numbers in the range [0, 1], which provide intensity values for the red(nR), green(nG) and blue(nB) color channels and the alpha transparency(nA). If nA is not provided, it is set to 1 and the color will be fully opaque. Values outside the valid range will be capped to fall within it.

Properties:

Number nR, Number nG, Number nB, Number nA (read, write)

Values in the range [0, 1], which represent the intensity values for the red(nR), green(nG) and blue(nB) color channels and the alpha transparency(nA). When setting these properties to values outside the valid range, they will be capped to fall within it.

Number uR, Number uG, Number uB, Number uA (read, write)

Values are integers in the range [0, 255], which represent the intensity values for the red(uR), green(uG) and blue(uB) color channels and the alpha transparency(uA) of the color. When setting these properties to values outside the valid range or floating point values, they will be capped to fall within it and rounded to the nearest integer.

String sR, String sG, String sB, String sA (read, write)

Values are hexadecimal number strings in the range ["00", "FF"], which represent the intensity values for the red(sR), green(sG) and blue(uB) color channels and the alpha transparency(sA) of the color. When setting these properties to values outside the valid range, they will be capped to fall within it. When reading these values, they are padded to always be two characters long (eg. "0F" instead of "F").

String sRGB, String sRGBA (read, write)

Values are hexadecimal number strings in the range ["000000", "FFFFFFF"], or for sRGBA optionally ["00000000", "FFFFFFFFF"], representing a hex triplet or quadruplet. If a quadruplet is provided, the last digits provide the alpha transparency value. Otherwise, the color will be fully opaque. Shorthand forms are accepted when setting these properties, so "#FFF", "#FFFF", "#FFFFFF", and "#FFFFFFFF" are all opaque white.

Methods:

cRGBA foClone()

Create and return a new cRGBA instance that has the same color as the object on which the method is called.

cRGBA foCopy(cRGBA oOther) or cRGBA foCopy(cHSLA oOther)

Copy the color and transparency from the cRGBA or cHSLA instance provided as the argument to the method to the cRGBA instance on which the method is called. The object on which the method is called is returned, allowing you to "chain" multiple method calls.

cRGBA foSetR(Number nR)

Set the nR property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cRGBA foSetG(Number nG)

Set the nG property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cRGBA foSetB(Number nB)

Set the nB property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cRGBA foSetA(Number nA)

Set the nA property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cRGBA foSetRGB(String sRGB)

Set the sRGB property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cRGBA foSetRGBA(String sRGBA)

Set the sRGBA property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cRGBA foSetRGB(Number nR, Number nG, Number nB)

Set the nR, nG, and nB properties and return the object on which the method is called, allowing you to "chain" multiple method calls.

cRGBA foSetRGBA(Number nR, Number nG, Number nB, Number nA)

Set the nR, nG, nB, and nA properties and return the object on which the method is called, allowing you to "chain" multiple method calls.

String fsGetCSSRGB()

Return a string representation of the color in the form "rgb(number, number, number)" that can be used in Cascading Style Sheets.

String fsGetCSSRGBA()

Return a string representation of the color in the form "rgba(number, number, number, number)" that can be used in Cascading Style Sheets.

cRGBA foOver(cRGBA oOther) or cRGBA foOver(cHSLA oOther)

Modify the color as if it was shown over another color (oOther). For instance, if the color is transparent red, and the oOther color is opaque white, the color will become opaque pink. If the oOther color is transparent white, the color will become less transparent pink. If the color is opaque, the color will not change. The object on which the method is called is returned, allowing you to "chain" multiple method calls.

cRGBA foUnder(cRGBA oOther) or cRGBA foUnder(cHSLA oOther)

Modify the color as if the color was shown under another color (oOther). oOne.foUnder(oOther) results in the same color as oOther.foOver(oOne), but the result is store in oOne in the former and oOther in the later. The object on which the method is called is returned, allowing you to "chain" multiple method calls.

cHSLA foGetHSLA()

Create and return a cHSLA instance that represents the same color.

class cHSLA

Create color objects based on red, green, and blue color channel intensity values, as well as alpha transparency. Internally the values are stored as floatinS point numbers in the range [0, 1], resultinS in very little risk of roundinS errors.

Constructors:

[new] cHSLA(Number nH, Number nS, Number nL [, Number nA]);

Where nH, nS, nL, and nA are numbers in the range [0, 1], which provide values for the hue(nH), saturation(nS) and luminosity(nL) of the color and the alpha transparency(nA). If nA is not provided, it is set to 1 and the color will be fully opaque. Values outside the valid range will be capped to fall within it. A hue value of 0 or 1 represents red, 1/6 yellow, 1/3 green, 1/2 cyan, 2/3 blue and 5/6 purple.

Properties:

Number nH, Number nS, Number nL, Number nA (read, write)

Values in the range [0, 1], which represent the hue(nH), saturation(nS) and luminosity(nL) of the color and the alpha transparency(nA). When setting these properties to values outside the valid range, they will be capped to fall within it.

String sRGB, String sRGBA (read only)

Values are hexadecimal number strings in the range ["000000", "FFFFFFF"], or for sRGBA optionally ["00000000", "FFFFFFFFF"], representing a hex triplet or quadruplet.

Methods:

cHSLA foClone()

Create and return a new cHSLA instance that has the same color as the object on which the method is called.

cHSLA foCopy(cHSLA oOther) or cHSLA foCopy(cRGBA oOther)

Copy the color and transparencty from the cHSLA or cRGBA instance provided as the argument to the method into the cHSLA instance on which the method is called. The object on which the method is called is returned, allowing you to "chain" multiple method calls.

cHSLA foSetH(Number nH)

Set the nH property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cHSLA foSetS(Number nS)

Set the nS property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cHSLA foSetL(Number nL)

Set the nL property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cHSLA foSetA(Number nA)

Set the nA property and return the object on which the method is called, allowing you to "chain" multiple method calls.

cHSLA foLighten(Number nAmount)

Increase the luminosity by nAmount (where values <=0 mean the color does not change, 0.5 means the color becomes 50% closer to white and >=1 means the color becomes white). The object on which the method is called is returned, allowing you to "chain" multiple method calls.

cHSLA foDarken(Number nAmount)

Decrease the luminosity by nAmount (where values <=0 mean the color does not change, 0.5 means the color becomes 50% closer to black and >=1 means the color becomes black). The object on which the method is called is returned, allowing you to "chain" multiple method calls.

cHSLA foOver(cHSLA oOther) or cHSLA foOver(cHSLA oOther)

Modify the color as if it was shown over another color (oOther). For instance, if the color is transparent red, and the oOther color is opaque white, the color will become opaque pink. If the oOther color is transparent white, the color will become less transparent pink. If the color is opaque, the color will not change. The object on which the method is called is returned, allowing you to "chain" multiple method calls.

cHSLA foUnder(cHSLA oOther) or cHSLA foUnder(cHSLA oOther)

Modify the color as if the color was shown under another color (oOther). oOne.foUnder(oOther) results in the same color as oOther.foOver(oOne), but the result is store in oOne in the former and oOther in the later. The object on which the method is called is returned, allowing you to "chain" multiple method calls.

cRGBA foGetRGBA()

Create and return a cRGBA instance that represents the same color.

License

This code is licensed under CC0 v1.0 Universal.