Skip to content

Latest commit

 

History

History
160 lines (122 loc) · 6 KB

snippets.md

File metadata and controls

160 lines (122 loc) · 6 KB

Code Snippets

It is a part of kch-rgbw-lib. See README.md for general information.

Ex01 : Import everything

In TypeScript/ES2015 you can lazily load and use everything by:

import * as foo from 'kch-rgbw-lib';
const c = new foo.CSpace('xyY', [0.3, 0.4, 1]);

But you need to use foo. everywhere. In the later snippets we import necessary staff only.

Ex02 : Populate an LEDChip

LEDChip class represents a physical LED. You can populate an LEDChip by:

import { LEDChip } from 'kch-rgbw-lib';
const rLED = new LEDChip('LED_R', { x: 0.6857, y: 0.3143, maxLuminance: 30.6, name: 'Red' });

If you don't know maxLuminance, you can set 1 to all LEDs.

Ex03 : Populate a RGBWLED

RGBWLED class represents a composite LED that has 3 or more component LEDChip. You can populate a RGBWLED by:

import { LEDChip, RGBWLED } from 'kch-rgbw-lib';
const rLED = new LEDChip('LED_R', { x: 0.6857, y: 0.3143, maxLuminance: 30.6, name: 'Red' });
const gLED = new LEDChip('LED_G', { x: 0.2002, y: 0.6976, maxLuminance: 67.2, name: 'Green' });
const bLED = new LEDChip('LED_B', { x: 0.1417, y: 0.0618, maxLuminance: 8.2,  name: 'Blue' });
const rgb = new RGBWLED('sample', [rLED, gLED, bLED]);

Ex04 : Instantiate from a JSON file

You can instantiate RGBWLED class object it much easier by preparing a JSON file and read it by:

import { parseRGBWLEDfromJSONFileAsync, RGBWLED } from 'kch-rgbw-lib';
try {
    const rgb: RGBWLED = await parseRGBWLEDfromJSONFileAsync('./foo.json');
} catch (e) {
    console.log(e);
}

You can also instantiate LEDChip array by parseLEDChipArrayfromJSONFileAsync(). For the JSON format, please refer to 'JSON file/string format'. You can also instantiate RGBWLED from a string variable by parseRGBWLEDfromJSONStringAsync():

import { parseRGBWLEDfromJSONFileAsync, RGBWLED } from 'kch-rgbw-lib';
let json_str = `{
  "LEDChip": [
    ...
  ],
  "RGBWLED": {
    ...
  }
}`;
try {
    const rgb: RGBWLED = await parseRGBWLEDfromJSONStringAsync(json_str);
} catch (e) {
    console.log(e);
}

Ex05 Compute brightness of LEDs for composite color

After populating a RGBWLED you can use it to compute array of brightness of LEDs to represent a composite color. This example follows the snippet of Ex03.

// (after instantiating rgb in Ex03)
const c = new CSpace('xyY', [0.32, 0.4, 20]);
const brightness: number[] = await rgb.color2AlphaAsync(c);

It's an asynchronous process because it can be a heavy computation involving a linear programming solution.

Note it does not update rgb itself. To do so, you use setColorAsync().

// (after instantiating rgb in Ex03)
const c = new CSpace('xyY', [0.32, 0.4, 20]);
await rgb.setColorAsync(c); // rgb updated

Ex06 Compute brightness of component LEDs

If you compute array of brightness of LEDs from RGB color, you need to specify luminance independently. This example follows the snippet of Ex03.

// (after instantiating rgb in Ex03)
const c = new CSpace('rgb', [0.3, 0.4, 0.5]);
const c1 = c.xyY();   // Convert to xyY space.
c1.Y = 20;            // Set luminance.
const brightness: number[] = await rgb.color2AlphaAsync(c1);

It is also the case for HSV color space, even it has brightness in V.

Why setting luminance?

You may wonder why we don't use brightness property of RGB or HSV space. It's because the brightness of these color spaces is relative to full brightness, but it's unclear what is full brightness for these color spaces when luminance distribution of component LEDs is not uniform across the gamut. Please refer to 'Luminance and brightness'.

Not giving luminance is equivalent to compute it using luminance between 0 and 1. It will still give you correct color, but it can be very dark if your component LEDs have larger luminance (e.g. maxLuminance = 100).

When this happens, you may magnify brightness array. It usually gives the same result as doing so like Ex06. It can be different under situation where one or more component LEDs reach to saturation (brightness = 1). In such case, linear programming of RGBWLED tries to avoid saturation using redundant LEDs if there are.

Ex07 Compute color from brightness of component LEDs

You can compute composite color from brightness of component LEDs. Assume you have an array brightness as brightness of component LEDs :

// (after instantiating rgb in Ex03)
import { CSpace } from 'kch-rgbw-lib';
const brightness = [0.003, 0.004, 0.008];
const c: CSpace = rgb.alpha2Color(brightness);
const hsv: CSpace = c.hsv();

This example gives an answer [ 222.6, 0.39, 0.94 ] in HSV space. Again, obtained brightness (V = 0.94) is calculated for luminance between 0 and 1.

Note it does not update rgb itself. To update rgb, you use setAlpha().

License

The MIT License (MIT) Copyright (c) K. Chinzei ([email protected]) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.