flutter_d3_color_port 0.1.2
flutter_d3_color_port: ^0.1.2 copied to clipboard
A native Dart port of d3-color 3.1.0: CSS color parsing and the RGB, HSL, CIELAB, HCL and Cubehelix color spaces of D3, with Flutter Color conversions.
flutter_d3_color_port #
A native Dart port of d3-color 3.1.0, the color module of D3, for Dart and Flutter. Each color is
a Dart class with double channels. The package runs no JavaScript and uses no WebView. It
converts to and from the Flutter Color.
Even though Flutter understands a lot about colors, it doesn’t offer much help in manipulating colors in other color spaces. The d3-color module therefore provides representations for various color spaces, allowing specification, conversion and manipulation.
For example, take the color named “steelblue”:
final c = d3.color('steelblue'); // Rgb: r 70, g 130, b 180, opacity 1
Let’s try converting it to HSL:
final c = d3.Hsl.parse('steelblue'); // h 207.27…, s 0.44, l 0.4902…, opacity 1
Now rotate the hue by 90°, bump up the saturation, and format as a string for CSS:
c.h += 90;
c.s += 0.2;
c.toString(); // rgb(198, 45, 205)
To fade the color slightly:
c.opacity = 0.8;
c.toString(); // rgba(198, 45, 205, 0.8)
In addition to the ubiquitous and machine-friendly RGB and HSL color space, d3-color supports color spaces that are designed for humans:
- CIELAB (a.k.a. “Lab”)
- CIELChab (a.k.a. “LCh” or “HCL”)
- Dave Green’s Cubehelix
Cubehelix features monotonic lightness, while CIELAB and its polar form CIELChab are perceptually uniform.
Installing #
flutter pub add flutter_d3_color_port
import 'package:flutter_d3_color_port/flutter_d3_color_port.dart' as d3;
package:flutter_d3_color_port/d3_color.dart has the same API with no Flutter import, for code
that runs without the Flutter engine.
API Reference #
d3.color(specifier) #
Parses the specified CSS Color Module Level 3 specifier string, returning an RGB or HSL color, along with CSS Color Module Level 4 hex specifier strings. If the specifier was not valid, null is returned. Some examples:
rgb(255, 255, 255)rgb(10%, 20%, 30%)rgba(255, 255, 255, 0.4)rgba(10%, 20%, 30%, 0.4)hsl(120, 50%, 20%)hsla(120, 50%, 20%, 0.4)#ffeeaa#fea#ffeeaa22#fea2steelblue
The list of supported named colors is specified by CSS.
d3.Color is the base class of each color: x is d3.Color tests if an object is a color
instance. The same is true of the color subclasses, for example x is d3.Hsl, allowing you to
test whether a color is in a particular color space.
color.opacity #
This color’s opacity, typically in the range [0, 1].
color.rgb() #
Returns the RGB equivalent of this color. For RGB colors, that’s this.
color.copy({…}) #
Returns a copy of this color. Each channel that is given as a named argument replaces that channel in the new returned color. For example, to derive a copy of a color with opacity 0.5, say
color.copy(opacity: 0.5)
color.brighter([k]) #
Returns a brighter copy of this color. If k is specified, it controls how much brighter the returned color should be. If k is not specified, it defaults to 1. The behavior of this method is dependent on the implementing color space.
color.darker([k]) #
Returns a darker copy of this color. If k is specified, it controls how much darker the returned color should be. If k is not specified, it defaults to 1. The behavior of this method is dependent on the implementing color space.
color.displayable() #
Returns true if and only if the color is displayable on standard hardware. For example, this returns false for an RGB color if any channel value is less than zero or greater than 255 when rounded, or if the opacity is not in the range [0, 1].
color.formatHex() #
Returns a hexadecimal string representing this color in RGB space, such as #f7eaba. If this
color is not displayable, a suitable displayable color is returned instead. For example, RGB
channel values greater than 255 are clamped to 255.
color.formatHex8() #
Returns a hexadecimal string representing this color in RGB space with its opacity, such as
#f7eaba90.
color.formatHsl() #
Returns a string representing this color according to the CSS Color Module Level 3
specification, such as hsl(257, 50%, 80%) or hsla(257, 50%, 80%, 0.2). If this color is not
displayable, a suitable displayable color is returned instead by clamping S and L channel values
to the interval [0, 100].
color.formatRgb() #
Returns a string representing this color according to the CSS Object Model specification, such
as rgb(247, 234, 186) or rgba(247, 234, 186, 0.2). If this color is not displayable, a
suitable displayable color is returned instead by clamping RGB channel values to the interval
[0, 255].
color.toString() #
An alias for color.formatRgb.
d3.Rgb(r, g, b[, opacity]), d3.Rgb.parse(specifier), d3.Rgb.from(color) #
Constructs a new RGB color. The channel values are exposed as r, g and b properties on the
returned instance.
d3.Rgb(r, g, b) takes the channel values of the returned color; an opacity may also be
specified. d3.Rgb.parse(specifier) parses a CSS Color Module Level 3 specifier string and then
converts it to the RGB color space. See d3.color for examples. d3.Rgb.from(color) converts a
color instance to the RGB color space using color.rgb. Note that unlike color.rgb this
method always returns a new instance, even if color is already an RGB color.
rgb.clamp() #
Returns a new RGB color where the r, g, and b channels are clamped to the range [0, 255]
and rounded to the nearest integer value, and the opacity is clamped to the range [0, 1].
d3.Hsl(h, s, l[, opacity]), d3.Hsl.parse(specifier), d3.Hsl.from(color) #
Constructs a new HSL color. The channel values are exposed as h, s and l properties on the
returned instance.
d3.Hsl(h, s, l) takes the channel values of the returned color; an opacity may also be
specified. d3.Hsl.parse(specifier) parses a CSS Color Module Level 3 specifier string and then
converts it to the HSL color space. See d3.color for examples. d3.Hsl.from(color) converts a
color instance to the RGB color space using color.rgb and then to HSL. (Colors already in the
HSL color space skip the conversion to RGB.)
hsl.clamp() #
Returns a new HSL color where the h channel is clamped to the range [0, 360), and the s, l,
and opacity channels are clamped to the range [0, 1].
d3.Lab(l, a, b[, opacity]), d3.Lab.parse(specifier), d3.Lab.from(color) #
Constructs a new CIELAB color. The channel values are exposed as l, a and b properties on
the returned instance. The value of l is typically in the range [0, 100], while a and b are
typically in [-160, +160].
d3.Lab(l, a, b) takes the channel values of the returned color; an opacity may also be
specified. d3.Lab.parse(specifier) parses a CSS Color Module Level 3 specifier string and then
converts it to the CIELAB color space. See d3.color for examples. d3.Lab.from(color) converts a
color instance to the RGB color space using color.rgb and then to CIELAB. (Colors already in
the CIELAB color space skip the conversion to RGB, and colors in the HCL color space are converted
directly to CIELAB.)
d3.gray(l[, opacity]) #
Constructs a new CIELAB color with the specified l value and a = b = 0.
d3.Hcl(h, c, l[, opacity]), d3.Hcl.parse(specifier), d3.Hcl.from(color) #
Equivalent to d3.lch, but with reversed argument order. d3.Hcl.parse and d3.Hcl.from are also
the forms of d3.lch(specifier) and d3.lch(color) of d3-color.
d3.lch(l, c, h[, opacity]) #
Constructs a new CIELChab color. The channel values are exposed as l, c and h
properties on the returned instance. The value of l is typically in the range [0, 100], c is
typically in [0, 230], and h is typically in [0, 360).
A color instance is converted to the RGB color space using color.rgb and then to CIELChab. (Colors already in CIELChab color space skip the conversion to RGB, and colors in CIELAB color space are converted directly to CIELChab.)
d3.Cubehelix(h, s, l[, opacity]), d3.Cubehelix.parse(specifier), d3.Cubehelix.from(color) #
Constructs a new Cubehelix color. The channel values are exposed as h, s and l properties
on the returned instance.
d3.Cubehelix(h, s, l) takes the channel values of the returned color; an opacity may also be
specified. d3.Cubehelix.parse(specifier) parses a CSS Color Module Level 3 specifier string
and then converts it to the Cubehelix color space. See d3.color for examples.
d3.Cubehelix.from(color) converts a color instance to the RGB color space using color.rgb
and then to Cubehelix. (Colors already in the Cubehelix color space skip the conversion to RGB.)
Flutter #
toUiColor() gives the Flutter Color of a color, and toD3Rgb() gives the d3.Rgb of a
Flutter Color:
import 'package:flutter/painting.dart';
import 'package:flutter_d3_color_port/flutter_d3_color_port.dart' as d3;
final Color paint = d3.Hcl.parse('steelblue').brighter().toUiColor();
final d3.Rgb rgb = const Color(0xff4682b4).toD3Rgb();
toUiColor() clamps the channels to the sRGB range and keeps their fractions. An undefined (NaN)
channel is 0, and an undefined opacity is 1, as formatRgb() reads them.
Differences from d3-color #
- The d3-color factories
rgb,hsl,lab,hcl,lchandcubehelixchange with their argument count. In Dart, each form has its own constructor:d3.Rgb(70, 130, 180),d3.Rgb.parse('steelblue')andd3.Rgb.from(color). - A channel is a
double. A string channel, for examplergb("12", "34", "56"), does not compile. An omitted opacity is 1. NaN is an undefined channel, as in d3-color. copytakes named arguments:color.copy(opacity: 0.5).- The CIELAB and HCL conversions use
atan2,sinandcosofdart:math. On a native platform, their last bit can differ from the browser. A channel exactly on a .5 boundary can then round to the other integer informatRgb().
Performance #
The figures are the time of one operation in nanoseconds, the mean of two runs. A lower number is faster. The benchmark runs the same 26 cases on d3-color 3.1.0 and on this package, with the same inputs. "AOT" is a compiled Dart executable or a release build of a Flutter app. "dart2js" and "dart2wasm" are the JavaScript and WebAssembly builds of this package.
Apple M3 Max, macOS 27. d3-color, dart2js and dart2wasm run in Node.js v24.22.1.
| Case | d3-color in Node.js | Port, AOT | Port, dart2js | Port, dart2wasm |
|---|---|---|---|---|
parse.hex6 |
75 | 32 | 28 | 48 |
parse.hex3 |
65 | 25 | 25 | 37 |
parse.named |
145 | 42 | 46 | 65 |
parse.rgb |
147 | 47 | 71 | 78 |
parse.rgbaPercent |
279 | 60 | 122 | 102 |
parse.hsl |
221 | 44 | 76 | 71 |
parse.invalid |
117 | 24 | 40 | 36 |
parse.mixed |
173 | 45 | 76 | 72 |
rgb.parse |
180 | 47 | 80 | 66 |
format.hex |
45 | 13 | 16 | 31 |
format.hex8 |
59 | 20 | 23 | 40 |
format.rgb |
54 | 25 | 33 | 31 |
format.hsl |
200 | 97 | 105 | 115 |
format.rgbOfHsl |
33 | 31 | 47 | 50 |
convert.rgbToHsl |
20 | 10 | 25 | 9 |
convert.hslToRgb |
20 | 11 | 23 | 18 |
convert.rgbToLab |
88 | 79 | 88 | 64 |
convert.labToRgb |
43 | 37 | 52 | 49 |
convert.rgbToHcl |
129 | 108 | 122 | 115 |
convert.hclToRgb |
72 | 55 | 78 | 75 |
convert.rgbToCubehelix |
43 | 17 | 38 | 9 |
convert.cubehelixToRgb |
38 | 20 | 41 | 32 |
op.brighterRgb |
9 | 6 | 13 | 9 |
op.darkerHcl |
9 | 6 | 13 | 9 |
pipe.hclTick |
174 | 82 | 109 | 108 |
pipe.parseHex |
220 | 61 | 84 | 97 |
Pixel 8a (Android 17) and iPhone 17 Pro (iOS 27). The browser builds run in Chrome 157 on the Pixel.
| Case | Pixel 8a: d3-color in Chrome | Pixel 8a: port, AOT | Pixel 8a: port, dart2js in Chrome | Pixel 8a: port, dart2wasm in Chrome | iPhone 17 Pro: port, AOT |
|---|---|---|---|---|---|
parse.hex6 |
112 | 48 | 44 | 56 | 19 |
parse.hex3 |
98 | 44 | 39 | 48 | 19 |
parse.named |
122 | 65 | 53 | 95 | 29 |
parse.rgb |
190 | 71 | 93 | 119 | 34 |
parse.rgbaPercent |
418 | 90 | 160 | 166 | 43 |
parse.hsl |
269 | 67 | 108 | 112 | 32 |
parse.invalid |
122 | 36 | 51 | 56 | 17 |
parse.mixed |
217 | 66 | 99 | 109 | 31 |
rgb.parse |
226 | 69 | 105 | 107 | 33 |
format.hex |
73 | 33 | 31 | 57 | 13 |
format.hex8 |
94 | 41 | 36 | 68 | 18 |
format.rgb |
69 | 42 | 48 | 46 | 18 |
format.hsl |
197 | 152 | 115 | 156 | 77 |
format.rgbOfHsl |
46 | 56 | 63 | 69 | 22 |
convert.rgbToHsl |
35 | 21 | 34 | 17 | 9 |
convert.hslToRgb |
28 | 19 | 32 | 30 | 9 |
convert.rgbToLab |
148 | 129 | 144 | 100 | 58 |
convert.labToRgb |
70 | 65 | 79 | 80 | 29 |
convert.rgbToHcl |
204 | 168 | 185 | 176 | 88 |
convert.hclToRgb |
105 | 87 | 110 | 109 | 42 |
convert.rgbToCubehelix |
74 | 51 | 68 | 19 | 15 |
convert.cubehelixToRgb |
45 | 37 | 54 | 41 | 20 |
op.brighterRgb |
19 | 14 | 22 | 16 | 8 |
op.darkerHcl |
17 | 14 | 23 | 16 | 8 |
pipe.hclTick |
247 | 128 | 146 | 154 | 54 |
pipe.parseHex |
278 | 93 | 117 | 158 | 47 |
The cases:
parse.*:d3.color(text)with hexadecimal texts of 6 and 3 digits, color names,rgb(),rgba()with percents,hsl(), texts that are not colors, and a mix of all of them.rgb.parse:d3.Rgb.parse(text)with the mix of texts.format.*:formatHex(),formatHex8(),formatRgb()andformatHsl(), andtoString()of an HSL color (format.rgbOfHsl).convert.*: the conversions between RGB and HSL, CIELAB, HCL and Cubehelix.op.*:brighter()of an RGB color anddarker()of an HCL color.pipe.hclTick: one step of an HCL color animation: a new hue, thentoString().pipe.parseHex:d3.Rgb.parse(text).formatHex().
License #
ISC, the license of d3-color. The LICENSE file keeps the notice of Mike Bostock. This project is
not affiliated with the D3 project.