huefree

v1.0.3

Published

3 months ago

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

352

0High
0Medium
0Low

piyushkatyal

color color-blind color-vision vision-transformation conversion tools javaScript library accessibility color-utilities vision simulation

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.

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

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 getVisions Output

`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

getVisionDetail 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

changeVision 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

changeVisionRecursive Output

After

changeVisionRecursive Output

`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

getCustomVisions 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

stringToRgb 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

rgbToString 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

linearize 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

deLinearize 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

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Description

Key Features:

Table of Contents

References

Research Papers

Websites

Installation

Browser-based Environment

Node.js-based Environment

Examples

Normal Vision:

Protanopia Vision:

Deuteranopia Vision:

Tritanopia Vision:

Protanomaly Vision:

Deuteranomaly Vision:

Tritanomaly Vision:

Achromatopsia Vision:

API Documentation

API Usage

getVisions(obj (Optional))

Example

Output

getVisionDetail(vision, obj (Optional))

Example

Output

changeVision(target, visionType, obj (Optional))

Example

Output

changeVisionRecursive(target, visionType, obj (Optional))

Example

Output

Before

After

getCustomVisions(vision1, vision2, vision3 ...)

Example

Output

stringToRgb(color)

Example

Output

rgbToString(color)

Example

Output

linearize(color)

Example

Output

deLinearize(color)

Example

Output

colorTransform(transMat, rgbMat)

Example

Output

Contributing

How to Contribute

License

`getVisions(obj (Optional))`

`getVisionDetail(vision, obj (Optional))`

`changeVision(target, visionType, obj (Optional))`

`changeVisionRecursive(target, visionType, obj (Optional))`

`getCustomVisions(vision1, vision2, vision3 ...)`

`stringToRgb(color)`

`rgbToString(color)`

`linearize(color)`

`deLinearize(color)`

`colorTransform(transMat, rgbMat)`