huefree
v1.0.3
Published
HueFree provides a suite of utility functions specifically designed to facilitate color manipulation and transformation, particularly with an emphasis on accommodating color blindness. It includes methods for converting color representations, applying col
Downloads
11
Maintainers
Readme
Description
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.
Key Features:
- 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.
Table of Contents
References
This project is based on research from the following sources:
Research Papers
- "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).
Websites
- CVD Simulation by Machado et al.
- Color Blindness Simulation Research by Ixora.io
- Color Blindness Simulation by mk.bcgsc.ca
Installation
To install HueFree, follow these steps:
Browser-based Environment
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>
Node.js-based Environment
To install HueFree via npm, run the following command in your project directory:
npm install huefree
After 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);
Examples
Normal Vision:
Protanopia Vision:
Deuteranopia Vision:
Tritanopia Vision:
Protanomaly Vision:
Deuteranomaly Vision:
Tritanomaly Vision:
Achromatopsia Vision:
API Documentation
| 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. |
API Usage
getVisions(obj (Optional))
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.
Example
const visionList = huefree.getVisions();
console.log(visionList);
Output
https://github.com/piyushk77/HueFree/blob/main/resources/images/method_outputs/getVisions.png?raw=true
getVisionDetail(vision, obj (Optional))
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.
Example
const visionDetails = huefree.getVisionDetail("deuteranopia");
console.log(visionDetails);
Output
changeVision(target, visionType, obj (Optional))
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.
Example
let elementId = document.getElementById("i02");
let visionType = "deuteranopia";
huefree.changeVision(elementId, visionType);
Output
changeVisionRecursive(target, visionType, obj (Optional))
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.
Example
let element = document.documentElement; // Changes the whole document
let visionType = "deuteranopia";
huefree.changeVisionRecursive(element, visionType);
Output
Before
After
getCustomVisions(vision1, vision2, vision3 ...)
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.
Example
let myVisions = ['myVision_1', 'myVision_2', 'myVision_3'];
let customObject = huefree.getCustomVisions(...myVisions);
console.log(customObject);
Output
stringToRgb(color)
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].
Example
let color = "rgba(23,111,68)";
let rgb = huefree.stringToRgb(color);
console.log(rgb);
Output
rgbToString(color)
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)'.
Example
let rgb = [23,45,233,50];
let rgbString = huefree.rgbToString(rgb);
console.log(rgbString);
Output
linearize(color)
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.
Example
let color = "rgba(23,111,68,23)";
let rgbLinear = huefree.linearize(color);
console.log(rgbLinear);
Output
deLinearize(color)
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.
Example
let rgbLinear = [ 0.008568125618069307, 0.1589608350608804, 0.05780543019106723, 23 ];
let sRGB = huefree.deLinearize(rgbLinear);
console.log(sRGB);
Output
colorTransform(transMat, rgbMat)
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].
Example
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);
Output
Contributing
We welcome contributions to HueFree! If you'd like to contribute, please follow these steps:
How to Contribute
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.
License
This project is licensed under the GNU General Public License Version 3. See the LICENSE file for more details.