hex-to-css-filter-library

A JavaScript library to access a remote database of CSS filters to change HTML elements to any hex color code.

Usage

1. Install the dependency

   • NPM: npm install hex-to-css-filter-library
   • Yarn: yarn add hex-to-css-filter-library

2. Add the dependency into your file

   import HexToCssFilterLibrary from 'hex-to-css-filter-library'

3. Create an account with DBHub.io

4. Generate a new API key on your Settings page

5. Use your API key to fetch a CSS filter or query the database

   const filter = await new HexToCssFilterLibrary(apiKey).fetchFilter('#42dead')

Documentation

Hex Color Input

Hex color codes can be passed in with 3 or 6 digits, case insensitive, and hash insensitive.

For example, all of these are valid and accepted representations:

• 333
• #333
• 333333
• #333333

Constructor

// This is hardcoded but it's standard to set this as an environment variable
// Your key should be kept secret and not committed or made public
const apiKey = '...'
const hexToCssFilterLibrary = new HexToCssFilterLibrary(apiKey)

const options = {...}
const hexToCssFilterLibrary = new HexToCssFilterLibrary(apiKey, options)

| Parameter | Type | Description | | --------- | :----: | --------------------- | | apiKey | String | generated by DBHub.io |

Options

Starting with 2.0.0, this package relies on Node 18's experimental fetch API instead of node-fetch. This makes the package work in the browser and Node.

For Node usage, if not on 18 or not wanting to rely on an experimental feature, feel free to import node-fetch or another dependency and pass in the relevant options.

import fetch, { FormData, Headers, Request } from 'node-fetch'

const options = {
  formDataClass: FormData,
  headersClass: Headers,
  requestClass: Request,
  fetchFunction: fetch,
}
const hexToCssFilterLibrary = new HexToCssFilterLibrary(apiKey, options)

| Name | Type | Default | Description | | --------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | | apiUrl | String | https://api.dbhub.io | URL for the DBHub.io API | | apiEndpoint | String | /v1/query | query endpoint for the DBHub.io API | | dbOwner | String | blakegearin | owner of the database on DBHub.io | | dbName | String | hex-to-css-filter-db.sqlite3 | name of the database on DBHub.io | | formDataClass | Class | FormData of Web API or Node | class used to form the body of the request to the database | | headersClass | Class | Headers of Web API or Node | class used to form the headers of the request to the database | | requestClass | Class | Request of Web API or Node | class used to form the request to the database | | fetchFunction | Function | fetch of Web API or Node | function used to execute the request to the database |

Fetch Filter

const filter = await hexToCssFilterLibrary.fetchFilter('#42dead')
// invert(66%) sepia(56%) saturate(416%) hue-rotate(110deg) brightness(98%) contrast(100%)

const options = {
  filterPrefix: true,
  preBlacken: true
}
const filter = await hexToCssFilterLibrary.fetchFilter('#42dead', options)
// filter: brightness(0) saturate(1) invert(66%) sepia(56%) saturate(416%) hue-rotate(110deg) brightness(98%) contrast(100%)

| Parameter | Type | Description | | ---------- | :----: | --------------------------------------- | | hexColor | String | see Hex Color Input |

Options

| Name | Type | Default | Description | | -------------- | :-----: | ------- | ---------------------------------------------- | | filterPrefix | Boolean | false | flag for filter: inclusion | | preBlacken | Boolean | false | flag for brightness(0) saturate(1) inclusion |

Fetch Color Record

const colorRecord = await hexToCssFilterLibrary.fetchColorRecord('#42dead')
// {
//   id: 4382381,
//   invert: 66,
//   sepia: 56,
//   saturate: 416,
//   'hue-rotate': 110,
//   brightness: 98,
//   contrast: 100,
//   loss: 0.2578769732
// }

const options = { raw: true }
const rawColorRecord = await hexToCssFilterLibrary.fetchColorRecord('#42dead', options)
// [
//   [
//     { Name: 'id', Type: 4, Value: '4382381' },
//     { Name: 'invert', Type: 4, Value: '66' },
//     { Name: 'sepia', Type: 4, Value: '56' },
//     { Name: 'saturate', Type: 4, Value: '416' },
//     { Name: 'hue-rotate', Type: 4, Value: '110' },
//     { Name: 'brightness', Type: 4, Value: '98' },
//     { Name: 'contrast', Type: 4, Value: '100' },
//     { Name: 'loss', Type: 5, Value: '0.2578769732' }
//   ]
// ]

| Parameter | Type | Description | | ---------- | :----: | --------------------------------------- | | hexColor | String | see Hex Color Input |

Options

| Name | Type | Default | Description | | ----- | :-----: | ------- | ------------------------------------------------------- | | raw | Boolean | false | flag for getting the raw response from the DBHub.io API |

Query DB

const sql = 'SELECT COUNT() FROM color'
const response = await hexToCssFilterLibrary.queryDb(sql)
// [ [ { Name: 'COUNT()', Type: 4, Value: '16777216' } ] ]

const options = { getFirstValue: true }
const response = await hexToCssFilterLibrary.queryDb(sql, options)
// 16777216

| Parameter | Type | Description | | --------- | :----: | ------------ | | sql | String | query to run |

Options

| Name | Type | Default | Description | | --------------- | :-----: | ------- | -------------------------------------------------------------- | | getFirstValue | Boolean | false | flag for getting the value of the first record in the response |

FAQ

• A filter isn't working/accurate, what's going on?

  • The filters in the database assume a starting color of black (#000000). If your HTML element isn't black, you'll need to use the preBlacken option.

• What if I'm not using JavaScript?

  • DBHub.io has Python and Go libraries which can also be used to access the database.

• What if I don't want to rely on your DBHub.io database?

  • There's a few options...

    • Use the sister package, hex-to-css-filter-library-with-db, which calls a local copy of the database.

    • The database has a CC-BY-4.0 license so feel free to fork it on DBHub.io or host elsewhere. It's approximately 524 MB and you can use the constructor options to change the DBHub.io default values.

About Problem Domain

The current leading method to convert a hex color to a CSS filter is through trial & error with loss minimization.

• Search using SPSA by MultiplyByZer0 on Stack Overflow

• NPM package: hex-to-css-filter

• Brute force with partial color coverage by Dave on Stack Overflow

Instead of spending your own time & resources doing this, you can use this library to lookup already calculated low loss values. Currently all colors have less than 1% loss.

I don't have plans to process lower values due to diminishing returns. If you are interested in doing this though, please get in touch and I can share my code.

Database

There are 16,777,216 RGB hex colors. This is equal to 2563, with 256 values for red, green, and blue.

Field|Type|Description -----|----|----------- id|INTEGER|primary key, represents the hex color sepia|INTEGER|percentage value for the sepia filter function saturate|INTEGER|percentage value for the saturate filter function hue-rotate|INTEGER|degree value for the hue-rotate filter function brightness|INTEGER|percentage value for the brightness filter function contrast|INTEGER|percentage value for the contrast filter function loss|REAL|percentage value of the filter's loss (lower is better)

For reference: SQLite datatypes

Loss Statistics

Average|Max|Min|0%|0.0%|0.1%|0.2%|0.3%|0.4%|0.5%|0.6%|0.7%|0.8%|0.9%|Total -------|---|---|--|----|----|----|----|----|----|----|----|----|----|----- 0.40267|0.99999|0|8|1,233,492|2,944,170|3,259,251|2,388,299|1,716,667|1,323,179|1,106,540|987,981|920,722|896,907|16,777,216

pie showData
  "0% loss" : 8
  "0.0% loss" : 1233492
  "0.1% loss" : 2944170
  "0.2% loss" : 3259251
  "0.3% loss" : 2388299
  "0.4% loss" : 1716667
  "0.5% loss" : 1323179
  "0.6% loss" : 1106540
  "0.7% loss" : 987981
  "0.8% loss" : 920722
  "0.9% loss" : 896907