WaBis

walter.bislins.ch

JSG: JsgColor

Es existiert ein globales Objekt JsgColor, welches diverse Funktionen für Farben zur Verfügung stellt. Diese Farb-Objekte werden im JsGraph3D Modul zur Berechnung von Schattierungen und Beleuchtungen verwendet. In diesem Modul werden Farben im CSS-String Format gespeichert. JsgColor Farbangaben werden mit JsgColor.ToString() ins CSS-String Format konvertiert.

CSS-String Format

Farbangaben in Funktionen wie SetColor() und SetBgColor() usw. können in Form eines Strings angegeben werden, wie er von HTML verwendet wird. Neben einigen Namen für Farben wie 'black', 'white', 'red' usw., können auch RGB-Anteile definiert werden im Format '#RGB' oder '#RRGGBB', wobei R, G und B eine Hexadezimale Zahl von 0-F bzw. 00-FF sein kann:

'#FFF'   oder   '#FFFFFF'   oder   'rgb(255,255,255)'   ist gleich   'white'
'#000'   oder   '#000000'   oder   'rgb(0,0,0)'         ist gleich   'black'
'#F00'   oder   '#FF0000'   oder   'rgb(255,0,0)'       ist gleich   'red'
'#0F0'   oder   '#00FF00'   oder   'rgb(0,255,0)'       ist gleich   'green'
'#00F'   oder   '#0000FF'   oder   'rgb(0,0,255)'       ist gleich   'blue'
'#888'   oder   '#808080'   oder   'rgb(128,128,128)'   ist ein mittleres grau

Bei der Farbangabe per 'rgb()' müssen die einzelnen Farbanteile im Bereich von 0..255 liegen. Bei Zeichenfunktionen kann über 'rgba(r,g,b,transp)' auch eine Halbtransparente Farbe angegeben werden:

jsg.SetColor( 'rgba(255,0,0,0.5)' );

Der letzte Parameter von rgba (hier 0.5) gibt die Transparenz der Farbe an: von 0 → unsichtbar bis 1 → undurchsichtig. Dieser Wert wird mit der globalen Transparenz Alpha multipliziert. Texte werden nicht durch die globale Transparenz beeinflusst. Sie können aber über die rgba-Form der Farbdefinition transparent gezeichnet werden.

JsgColor Klasse

Ein Farb-Objekt im JsgColor Format ist ein Array der Grösse 3 oder 4, welcher die Farbkomponenten [ rot, grün, blau, alpha ] als Werte zwischen 0 und 1 enthält. alpha ist der Transparenz-Kanal. alpha = 1 heisst undurchsichtig, alpha = 0 heisst unsichtbar. Der Alpha-Kanal, also die 4-te Komponente ist optional und wird als 1 angenommen, wenn nicht vorhanden.

JsgColor: Array[4] of Number(0-1) = [ r, g, b, a ]

JsgColor ist eigentlich keine Klasse, sondern ein globales Objekt, welches alle Farb-Funktionen zur Verfügung stellt. Damit können Farben erzeugt und manipuliert werden, siehe JsgColor Funktionen.

Das JsGraph Modul verwendet intern Farben im CSS-String Format. Farben im JsgColor Format werden mit der Funktion JsgColor.ToString() ins CSS-String Format konvertiert.

Hinweis: Obwohl gültige Werte für die Farb-Komponenten und den Alpha-Kanal zwischen 0 und 1 liegen sollen, sind auch Werte ausserhalb dieses Bereiches zulässig. Sie werden beim Umwandeln in einen CSS-String mit JsgColor.ToString() entsprechend auf den gültigen Wertebereich beschnitten.

Das folgende Beispiel zeigt, wie JsgColor Farben erzeugt und manipuliert werden:

var areaColor = JsgColor.RGB( 1, 0, 0 );  // rot
var correction = JsgColor.RGB( 0, 0, 0.2 ); // dunkel blau
JsgColor.Add( areaColor, correction );
g.SetAreaColor( areaColor );
 :

JsgColor Funktionen

JsgColor.RGB() Erzeugt ein JsgColor Objekt aus drei Farbkomponenten
JsgColor.RGBA() Erzeugt ein JsgColor Objekt aus drei Farbkomponenten und einem Alpha-Kanal
JsgColor.BW() Erzeugt ein JsgColor Objekt mit Grauwert zwischen Schwarz und Weiss
JsgColor.Black() Erzeugt ein schwarzes JsgColor Objekt
JsgColor.White() Erzeugt ein weisses JsgColor Objekt
JsgColor.Ok() Gibt true zurück, wenn das Farb-Objekt definiert und vom richtigen Typ ist
JsgColor.Alpha() Gibt den Wert des Alpha-Kanals zurück
JsgColor.SetAlpha() Setzt den Wert des Alpha-Kanals
JsgColor.SetRGB() Setzt die 3 Farb-Komponenten eines Farb-Objektes auf neue Werte
JsgColor.SetRGBA() Setzt die 3 Farb-Komponenten und den Alpha-Kanal eines Farb-Objektes auf neue Werte
JsgColor.SetBW() Setzt die 3 Farb-Komponenten eines Farb-Objektes auf einen Wert zwischen Schwarz und Weiss
JsgColor.SetBlack() Setzt die 3 Farb-Komponenten eines Farb-Objektes auf den Wert für Schwarz
JsgColor.SetWhite() Setzt die 3 Farb-Komponenten eines Farb-Objektes auf den Wert für Weiss
JsgColor.Copy() Gibt eine Kopie eines Farb-Objektes zurück
JsgColor.CopyTo() Kopiert die Kanäle eines Farb-Objektes in ein anderes
JsgColor.ToString() Wandelt ein Farb-Objekt in einen CSS-String → Farben
JsgColor.HSV() Erzeugt ein Farb-Objekt aus Hue (H), Saturation (S) und Brightness (V)
JsgColor.HL() Erzeugt ein Farb-Objekt aus Hue (H) und Luminance (L)
JsgColor.Scale() Skaliert die Farbwerte mit einem Skalar
JsgColor.Add() Addiert die Farbwerte eines Farb-Objekes zu einem anderen
JsgColor.Mult() Multipliziert die Farbwerte eines Farb-Objektes zu einem anderen

JsgColor.RGB()

global JsgColor.RGB( r, g, b )

r, g, b: Number(0-1)
Farbkomponenten rot, grüen und blau als Werte zwischen 0 und 1
Return: JsgColor

Erzeugt ein JsgColor Objekt mit den drei Grundfarben. Der Alpha-Kanal wird auf 1 (undurchsichtig) gesetzt.

JsgColor.RGBA()

global JsgColor.RGBA( r, g, b, a )

r, g, b: Number(0-1)
Farbkomponenten rot, grüen und blau als Werte zwischen 0 und 1
a: Number(0-1)
Alpha-Kanal
Return: JsgColor

Erzeugt ein JsgColor Objekt mit den drei Grundfarben. a gibt den Wert des Alpha-Kanals an: 0 → unsichtbar, 1 → undurchsichtig. Es sind alle Werte zwischen 0 und 1 erlaubt.

JsgColor.BW()

global JsgColor.BW( v )

v: Number(0-1)
Helligkeit des Graywertes
Return: JsgColor

Erzeugt ein JsgColor Objekt, bei welchem alle drei Farbkanäle den selben Wert haben. Dadurch entstehen Farben von Schwarz (v = 0) über Grau bis Weiss (v = 1). Der Alpha-Kanal wird auf 1 (undurchsichtig) gesetzt.

JsgColor.Black()

global JsgColor.Black( )

Return: JsgColor

Erzeugt ein schwarzes JsgColor Objekt, d.h. alle Farbkanäle sind 0. Der Alpha-Kanal wird auf 1 (undurchsichtig) gesetzt.

JsgColor.White()

global JsgColor.White( )

Return: JsgColor

Erzeugt ein weisses JsgColor Objekt, d.h. alle Farbkanäle sind 1. Der Alpha-Kanal wird auf 1 (undurchsichtig) gesetzt.

JsgColor.Ok()

global JsgColor.Ok( col )

col: JsgColor
Zu überprüfendes Argument
Return: Boolean
false → col ist nicht definiert oder kein JsgColor Objekt

Überprüft, ob einer Variable ein JsgColor Objekt zugewiesen ist. Eigentlich wird nur geprüft, ob col ein Array ist.

var myCol = JsgColor.Ok(col) ? col : JsgColor.Blank();

JsgColor.Alpha()

global JsgColor.Alpha( col )

col: JsgColor
Farbe, dessen Alpha-Kanal abgefragt wird
Return: Number
Wert des Alpha-Kanals von col

Wenn bei der Farbe col der Alpha-Kanal nicht definiert ist (der Array hat weniger als 4 Einträge), so wird 1 zurückgegeben.

JsgColor.SetAlpha()

global JsgColor.SetAlpha( col, a )

col: JsgColor
Farbe, dess Alpha-Kanal verändert werden soll
a: Number(0-1)
Wert für den Alpha-Kanal: 0 → unsichtbar, 1 → undurchsichtig
Return: JsgColor
gibt col zurück

Ändert den Wert des Alpha-Kanals von col auf a. Das Farb-Objekt col wird als Returnwert zurückgegeben, damit mehrere Funktionen verkettet werden können:

var col = JsgColor.Scale( 
  JsgColor.SetAlpha( 
    JsgColor.Black(), 0.5 
  ), 0.8 
);

JsgColor.Copy()

global JsgColor.Copy( col )

col: JsgColor
Zu kopierendes Farb-Objekt
Return: JsgColor
Kopie von col

Erzeugt ein neues Farb-Objekt und kopiert alle Komponenten von col in dieses.

JsgColor.CopyTo()

global JsgColor.CopyTo( src, dest )

src: JsgColor
Zu kopierendes Farb-Objekt
dest: JsgColor
Ziel-Objekt
Return: JsgColor
gibt src zurück

Kopiert alle Komponenten des Farb-Objektes src in das bestehende Objekt dest.

JsgColor.SetRGB()

global JsgColor.SetRGB( col, r, g, b )

col: JsgColor
Zu veränderndes Farb-Objekt
r, g, b: Number(0-1)
Farbkomponenten rot, grüen und blau als Werte zwischen 0 und 1
Return: JsgColor
Gibt col zurück.

Setzt die drei Grundfarben eines bestehenden JsgColor Objektes auf neue Werte. Der Alpha-Kanal wird auf 1 (undurchsichtig) gesetzt.

JsgColor.SetRGBA()

global JsgColor.SetRGBA( col, r, g, b, a )

col: JsgColor
Zu veränderndes Farb-Objekt
r, g, b: Number(0-1)
Farbkomponenten rot, grüen und blau als Werte zwischen 0 und 1
a: Number(0-1)
Alpha-Kanal
Return: JsgColor
Gibt col zurück.

Setzt die drei Grundfarben und den Alpha-Kanal eines bestehenden JsgColor Objektes auf neue Werte.

JsgColor.SetBW()

global JsgColor.SetBW( col, v )

col: JsgColor
Zu veränderndes Farb-Objekt
v: Number(0-1)
Helligkeit des Graywertes
Return: JsgColor
Gibt col zurück.

Setzt die drei Grundfarben eines bestehenden JsgColor Objektes auf den Wert v, womit eine Farbe zwischen schwarz (v=0) und weiss (v=1) entsteht. Der Alpha-Kanal wird auf 1 (undurchsichtig) gesetzt.

JsgColor.SetBlack()

global JsgColor.SetBlack( col )

col: JsgColor
Zu veränderndes Farb-Objekt
Return: JsgColor
Gibt col zurück.

Setzt die drei Grundfarben eines bestehenden JsgColor Objektes auf 0, womit die Farbe Schwarz entsteht. Der Alpha-Kanal wird auf 1 (undurchsichtig) gesetzt.

JsgColor.SetWhite()

global JsgColor.SetWhite( col )

col: JsgColor
Zu veränderndes Farb-Objekt
Return: JsgColor
Gibt col zurück.

Setzt die drei Grundfarben eines bestehenden JsgColor Objektes auf 1, womit die Farbe Weiss entsteht. Der Alpha-Kanal wird auf 1 (undurchsichtig) gesetzt.

JsgColor.ToString()

global JsgColor.ToString( col )

col: JsgColor
Return: String
Farbe im CSS-Format

Mit dieser Funktion können Farben, welche in RGB-Komponenten vorliegen, d.h. im JsgColor Format, in einen CSS-String verwandelt werden, wie er bei Attribut Funktionen benötigt wird. Der String hat das Format:

'#ff8000'                 → Orange
'rgba( 255, 128, 0, 0.5)' → Orange halbtransparent
var col = JsgColor.RGB( 1, 0.5, 0 );
g.SetColor( JsgColor.ToString( col ) );

JsgColor.HSV()

global JsgColor.HSV( H, S, V, A )

H, S, V: Number(0..1); Optional; Default = 1
Farbkanäle im HSV-Farbraum (H = Hue = Farbwert, S = Saturation = Sättigung, V = Value = Helligkeit).
A: Number(0..1); Optional; Default = 1
Transparenz der Farbe: 0 → durchsichtig, 1 → undurchsichtig.
Return: JsgColor

Mit dieser Funktion lässt sich eine Farbe über den HSV-Farbraum definieren.

  • H = Hue = Farbwert: 0 = red; 1/6 = yellow; 2/6 = green; 3/6 = cyan; 4/6 = blue; 5/6 = magenta
  • S = Saturation = Sättigung: 0 = gray; 1 = reine Farbe
  • V = Value/Luminosity = Helligkeit: 0 = schwarz; 1 = hellste Farbe
var col = JsgColor.HSV( 0, 1, 0.5 ); // dunkles rot
g.SetColor( JsgColor.ToString( col ) );

JsgColor.HL()

global JsgColor.HL( H, L, A )

H, L: Number(0..1); Optional; Default = 1
Farbkanäle im HSV-Farbraum (H = Farbwert, L = Sättigung und Helligkeit).
A: Number(0..1); Optional; Default = 1
Transparenz der Farbe: 0 → durchsichtig, 1 → undurchsichtig.
Return: JsgColor

Mit dieser Funktion lässt sich eine Farbe im HSV-Farbraum definieren. Aus dem Parameter L werden Werte für Saturation S und Value V generiert und zwar wiefolgt:

  • H = Hue = Farbwert: 0 = red; 1/6 = yellow; 2/6 = green; 3/6 = cyan; 4/6 = blue; 5/6 = magenta
  • L = 0 bis 0.5 → S = Sättigung = 1; V = Helligkeit = 2 * L
  • L = 0.5 bis 1 → S = Sättigung = 1 - 2 * (L - 0.5); V = 1

Das heisst: Für Werte von L = 0 bis 0.5 ist die Farbsättigung = 1 (satte Farben) und die Helligkeit geht von 0 (schwarz) bis 1 (satte Farben). Für Werte von L = 0.5 bis 1 ist die Helligkeit = 1 und die Sättigung geht von 1 (satte Farbe) bis 0 (weiss).

var col = JsgColor.HL( 0, 0.7 ); // helles rot
g.SetColor( JsgColor.ToString( col ) );

JsgColor.Scale()

global JsgColor.Scale( col, s )

col: JsgColor
Zu skalierenden Farb-Objekt
s: Number
Skalierungsfaktor
Return: JsgColor
Gibt col zurück

Multipliziert alle Farb-Komponenten von col mit s. Der Alpha-Kanal wird nicht verändert. Gibt col zurück, damit mehrere Funktionsaufrufe verkettet werden können.

Durch Scale können Farbwerte ausserhalb des Bereiches 0-1 entstehen. Beim Umwandeln mit JsgColor.ToString werden die Werte auf den Bereich 0-1 beschnitten.

JsgColor.Add()

global JsgColor.Add( col, add )

col: JsgColor
Zu veränderndes Farb-Objekt
add: JsgColor
Zu addierendes Farb-Objekt
Return: JsgColor
Gibt col zurück

Addiert alle Farb-Komponenten von add zu den Farb-Komponenten von col. Der Alpha-Kanal wird nicht verändert. Gibt col zurück, damit mehrere Funktionsaufrufe verkettet werden können.

Durch Add können Farbwerte ausserhalb des Bereiches 0-1 entstehen. Beim Umwandeln mit JsgColor.ToString werden die Werte auf den Bereich 0-1 beschnitten.

JsgColor.Mult()

global JsgColor.Mult( col, mul )

col: JsgColor
Zu veränderndes Farb-Objekt
mul: JsgColor
Zu multiplizierendes Farb-Objekt
Return: JsgColor
Gibt col zurück

Multipliziert alle Farb-Komponenten von mult zu den Farb-Komponenten von col. Der Alpha-Kanal wird nicht verändert. Gibt col zurück, damit mehrere Funktionsaufrufe verkettet werden können.

Durch Mult können Farbwerte ausserhalb des Bereiches 0-1 entstehen. Beim Umwandeln mit JsgColor.ToString() werden die Werte auf den Bereich 0-1 beschnitten.

Weitere Infos zur Seite
Erzeugt Dienstag, 2. Februar 2016
von wabis
Zum Seitenanfang
Geändert Dienstag, 24. Mai 2016
von wabis