HueFree is a JavaScript library designed to assist developers in creating accessible web applications for color-blind individuals. The library offers a range of color manipulation methods to simulate different types of color blindness and provide color transformations that enhance accessibility.
- Simulate Color Blindness: Accurately simulate various types of color blindness (e.g., protanopia, deuteranopia, tritanopia).
- Color Transformations: Transform colors based on transformation matrices and color mappings.
- Custom Visions: Create customized vision object with custom color transformation functions.
- Easy Integration: Seamlessly integrate into any JavaScript project with minimal setup.
HueFree empowers developers to create a more inclusive web experience by addressing the needs of color-blind users, ensuring that color is not a barrier to accessing information.
This project is based on research from the following sources:
- "Digital video colourmaps for checking the legibility of displays by dichromats" by Viénot, Brettel, and Mollon (1999).
- "A Physiologically-based Model for Simulation of Color Vision Deficiency" by Machado et al. (2009).
- CVD Simulation by Machado et al.
- Color Blindness Simulation Research by Ixora.io
- Color Blindness Simulation by mk.bcgsc.ca
To install HueFree, follow these steps:
If you prefer to include HueFree directly in your HTML file using a CDN, add the following script tag to your HTML:
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/huefree.min.js"></script>After adding the script tag, you can start using HueFree in your project. For example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>HueFree Example</title>
</head>
<body>
<!-- Adding the HueFree library via CDN -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/huefree.min.js"></script>
<!-- Usage of HueFree APIs -->
<script>
// Example of getting list of supported visions
const { getVisions } = huefree;
const visionList = getVisions();
console.log(visionList);
</script>
</body>
</html>To install HueFree via npm, run the following command in your project directory:
npm install huefreeAfter installation, you can start using HueFree in your Node.js project. For example:
const huefree = require('huefree');
// Example of color transformation
const transformedColor = huefree.changeVision('rgba(255,23,234,23)', 'protanopia');
console.log(transformedColor);
| Method | Parameters | Description |
|---|---|---|
getVisions |
vision object (Object) |
Returns an array containing the list of supported color visions. |
getVisionDetail |
vision (String), vision object (Object) |
Returns an object containing complete details of the specified vision. |
changeVision |
target (String or DOM Element), visionType (String), vision object (Object) |
Modifies and returns the target element (DOM or Color String) with color properties specific to the provided color vision type. |
changeVisionRecursive |
target (String or DOM Element), visionType (String), vision object (Object) |
Modifies the target element and its sub children iteratively and returns back the new target element. |
getCustomVisions |
vision list (String) |
Returns an object containing huefree format of vision object with custom vision types provided as parameters. |
stringToRgb |
color (String) |
Takes an RGB or an RGBA format color string and returns the extracted color values as a numeric array. |
rgbToString |
color (Array number[]) |
Takes a numeric array and based on number of values returns an RGB of an RGBA color string. |
linearize |
color (String or Array number[]) |
Converts the provided standard RGB color string or array into linearized color space RGB string. |
deLinearize |
color (String or Array number[]) |
Converts the provided linear RGB color string or array into standard RGB color string. |
colorTransform |
transMat (Array number[][]), rgbMat (Array number[]) |
Converts the given RGB matrix value by multiplying with the given transformation matrix. |
Get the list of all visions supported in the given vision object. By default it will return the list of in-built visions supported by HueFree.
-
Parameters:
obj(Object): Vision object to be searched through.
-
Returns:
- (Array[Strings]): Array of visions as strings.
const visionList = huefree.getVisions();
console.log(visionList);
Get the complete object definition of the given vision type including its description, transformation matrix, usemap and mapColor. Custom object can be provided as second parameter to be searched through.
-
Parameters:
vision(String): Type of vision to get details.obj(Object): Custom object to be searched for. By default it uses the in-built vision object.
-
Returns:
- (Object): Vision object containing specific definitions to the provided vision type.
const visionDetails = huefree.getVisionDetail("deuteranopia");
console.log(visionDetails);
Modifies the given target (Color string or DOM Element) and changes all the color based properties of this element. The child nodes are not affected.
-
Parameters:
target(String or DOM Element): Color string or DOM Element to be modified.visionType(String): Type of vision to perform color transformation.obj(Object): Custom object to be searched for. By default it uses the in-built vision object.
-
Returns:
- (Object): Modified string or DOM element.
let elementId = document.getElementById("i02");
let visionType = "deuteranopia";
huefree.changeVision(elementId, visionType);
Modifies the given target (Color string or DOM Element) and changes all the color based properties of this element and iteratively changes the properties of all the child nodes of the DOM element.
-
Parameters:
target(String or DOM Element): Color string or DOM Element to be modified.visionType(String): Type of vision to perform color transformation.obj(Object): Custom object to be searched for. By default it uses the in-built vision object.
-
Returns:
- (Object): Modified string or DOM element.
let element = document.documentElement; // Changes the whole document
let visionType = "deuteranopia";
huefree.changeVisionRecursive(element, visionType);
Creates a custom vision object based on the given vision type names and returns the complete object for further customizations.
-
Parameters:
list of vision names(String): Custom vision type names.
-
Returns:
- (Object): Object containing huefree format of vision object.
let myVisions = ['myVision_1', 'myVision_2', 'myVision_3'];
let customObject = huefree.getCustomVisions(...myVisions);
console.log(customObject);
Converts a CSS color string of type RGB or RGBA to an array of numeric values. Supports rgb(x,x,x) and rgba(x,x,x,x) formats. If rgb(x,x,x,x) is provided then input is percieved as rgba type. Similarly if rgba(x,x,x) is provided then input is percieved as rgb type.
-
Parameters:
color(String): CSS color in RGB or RGBA format.
-
Returns:
- (Array number[]): Array containing the RGB components [red, green, blue], or undefined if the input string is invalid, e.g., [255, 23, 45].
let color = "rgba(23,111,68)";
let rgb = huefree.stringToRgb(color);
console.log(rgb);
Converts an array of RGB or RGBA values to a CSS color string. If invalid format is provided then the array is returned without any modifications.
-
Parameters:
color(Array number[]): Array containing the RGB components [red, green, blue] or [red, green, blue, alpha].
-
Returns:
- (String): The CSS color string in the format 'rgb(r, g, b)' or 'rgba(r, g, b, a)'.
let rgb = [23,45,233,50];
let rgbString = huefree.rgbToString(rgb);
console.log(rgbString);
Linearizes an sRGB color array by applying a gamma correction formula.
- Parameters:
color(String or Array number[]): The CSS color string or an array containing the RGB components [red, green, blue, alpha].
- Returns:
- (Array number[]): Array containing the linearized RGB components [red, green, blue, alpha], or undefined if the input is invalid.
let color = "rgba(23,111,68,23)";
let rgbLinear = huefree.linearize(color);
console.log(rgbLinear);
De-linearizes an RGB color array from linear to gamma-corrected sRGB values.
- Parameters:
color(String or Array number[]): The CSS color string or an array containing the linearized RGB components [red, green, blue, alpha].
- Returns:
- (Array number[]): Array containing the de-linearized sRGB components [red, green, blue, alpha], or undefined if the input is invalid.
let rgbLinear = [ 0.008568125618069307, 0.1589608350608804, 0.05780543019106723, 23 ];
let sRGB = huefree.deLinearize(rgbLinear);
console.log(sRGB);
Applies a color transformation matrix to an RGB color array.
- Parameters:
transMat(Array number[][]): The transformation matrix, a 3x3 array of numbers.rgbMat(Array number[]): An array containing the transformed RGB components.
- Returns:
- (Array number[]): An array containing the RGB components [red, green, blue, alpha].
let transform = [
[0.2, 1, 0.3],
[0, 1, 1],
[1.2, -1.1, -0.3]
];
let rgb = [233, 123, 19];
let transRgb = huefree.colorTransform(transform, rgb);
console.log(transRgb);
We welcome contributions to HueFree! If you'd like to contribute, please follow these steps:
-
Fork the Repository:
- Fork the HueFree repository on GitHub.
-
Clone the Fork:
- Clone your forked repository to your local machine.
git clone https://github.com/your-username/huefree.git
cd huefree -
Create a Branch:
- Create a new branch for your feature or bug fix.
git checkout -b your-branch-name
-
Make Your Changes:
- Implement your feature or bug fix in your new branch.
git add . git commit -m "Description of your changes"
-
Commit Your Changes:
- Commit your changes with a descriptive commit message.
git clone https://github.com/your-username/huefree.git
-
Push to Your Fork:
- Push your changes to your forked repository.
git push origin your-branch-name
-
Create a Pull Request:
- Open a pull request from your branch to the main branch of the original repository.
- Provide a clear and descriptive title for your pull request.
- Include a detailed description of your changes and any related issue numbers.
This project is licensed under the GNU General Public License Version 3. See the LICENSE file for more details.