HueFree

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.

$3

- 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

- Description
- References
- Installation
- Examples
- API Documentation
- API Usage
- Contributing
- License

References

This project is based on research from the following sources:

$3

1. "Digital video colourmaps for checking the legibility of displays by dichromats" by Viénot, Brettel, and Mollon (1999).
2. "A Physiologically-based Model for Simulation of Color Vision Deficiency" by Machado et al. (2009).

$3

1. CVD Simulation by Machado et al.
2. Color Blindness Simulation Research by Ixora.io
3. Color Blindness Simulation by mk.bcgsc.ca

Installation

To install HueFree, follow these steps:

$3

If you prefer to include HueFree directly in your HTML file using a CDN, add the following script tag to your HTML:
``html

`
After adding the script tag, you can start using HueFree in your project. For example:

`html
















`

$3

To install HueFree via npm, run the following command in your project directory:
`sh
npm install huefree
`
After installation, you can start using HueFree in your Node.js project. For example:

`js
const huefree = require('huefree');

// Example of color transformation
const transformedColor = huefree.changeVision('rgba(255,23,234,23)', 'protanopia');
console.log(transformedColor);
`

Examples

$3

$3

$3

$3

$3

$3

$3

$3

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

$3

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

`javascript
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




$3

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

`javascript
const visionDetails = huefree.getVisionDetail("deuteranopia");
console.log(visionDetails);
`

#### Output

!getVisionDetail Output

$3

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

`javascript
let elementId = document.getElementById("i02");
let visionType = "deuteranopia";
huefree.changeVision(elementId, visionType);
`

#### Output

!changeVision Output

$3

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

`javascript
let element = document.documentElement; // Changes the whole document
let visionType = "deuteranopia";
huefree.changeVisionRecursive(element, visionType);
`

#### Output
##### Before
!changeVisionRecursive Output
##### After
!changeVisionRecursive Output

$3

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

`javascript
let myVisions = ['myVision_1', 'myVision_2', 'myVision_3'];
let customObject = huefree.getCustomVisions(...myVisions);
console.log(customObject);
`

#### Output

!getCustomVisions Output

$3

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

`javascript
let color = "rgba(23,111,68)";
let rgb = huefree.stringToRgb(color);
console.log(rgb);
`

#### Output

!stringToRgb Output

$3

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

`javascript
let rgb = [23,45,233,50];
let rgbString = huefree.rgbToString(rgb);
console.log(rgbString);
`

#### Output

!rgbToString Output

$3

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

`javascript
let color = "rgba(23,111,68,23)";
let rgbLinear = huefree.linearize(color);
console.log(rgbLinear);
`

#### Output

!linearize Output

$3

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

`javascript
let rgbLinear = [ 0.008568125618069307, 0.1589608350608804, 0.05780543019106723, 23 ];
let sRGB = huefree.deLinearize(rgbLinear);
console.log(sRGB);
`

#### Output

!deLinearize Output

$3

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

`javascript
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:

$3

1. Fork the Repository:
- Fork the HueFree repository on GitHub.

2. Clone the Fork:
- Clone your forked repository to your local machine.

`sh
git clone https://github.com/your-username/huefree.git
`
`sh
cd huefree
`

3. Create a Branch:
- Create a new branch for your feature or bug fix.

`sh
git checkout -b your-branch-name
`

4. Make Your Changes:
- Implement your feature or bug fix in your new branch.

`sh
git add .
git commit -m "Description of your changes"
`

5. Commit Your Changes:
- Commit your changes with a descriptive commit message.

`sh
git clone https://github.com/your-username/huefree.git
`

6. Push to Your Fork:
- Push your changes to your forked repository.

`sh
git push origin your-branch-name
``

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