flutter_color_models

A wrapper for the color_models plugin that implements Flutter's Color class.

For use without Flutter, see: https://pub.dev/packages/color_models

Check out flutter_palette, a package for creating, generating, and modifying color palettes.

Usage

import 'package:flutter_color_models/flutter_color_models.dart';

Color Spaces

color_models exposes models for the CMYK, HSI, HSL, HSP, HSB, LAB, Oklab, RGB, and XYZ color spaces; represented as CmykColor, HsiColor, HslColor, HspColor, HsbColor, LabColor, OklabColor, RgbColor, and XyzColor respectively.

Creating Colors

Colors can be created by constructing a ColorModel directly, or with the fromList or extrapolate constructors. extrapolate accepts each model's respective values on a 0 to 1 scale, and extrapolates them to their normal scale.

Each model posesses values for each property of their respective acronyms, as well as an optional alpha value.

// Each of the below colors is red at 100% opacity.

// RGB without alpha
RgbColor(255, 0, 0);
RgbColor.fromList(<num>[255, 0, 0]);
RgbColor.extrapolate(<num>[1.0, 0.0, 0.0]);

// RGB with alpha
RgbColor(255, 0, 0, 1.0);
RgbColor.fromList(<num>[255, 0, 0, 255]);
RgbColor.extrapolate(<num>[1.0, 0.0, 0.0, 255]);

// CMYK without alpha
CmykColor(0.0, 100.0, 100.0, 0.0);
CmykColor.fromList(<num>[0.0, 100.0, 100.0, 0.0]);
CmykColor.extrapolate(<num>[0.0, 1.0, 1.0, 0.0]);

// CMYK with alpha
CmykColor(0.0, 100.0, 100.0, 0.0, 1.0);
CmykColor.fromList(<num>[0.0, 100.0, 100.0, 0.0, 255]);
CmykColor.extrapolate(<num>[0.0, 1.0, 1.0, 0.0, 255]);

// HSL without alpha
HslColor(0.0, 100.0, 50.0);
HslColor.fromList(<num>[0.0, 100.0, 50.0]);
HslColor.extrapolate(<num>[0.0, 1.0, 0.5]);

// HSL with alpha
HslColor(0.0, 100.0, 50.0, 1.0);
HslColor.fromList(<num>[0.0, 100.0, 50.0, 255]);
HslColor.extrapolate(<num>[0.0, 1.0, 0.5, 255]);

Casting Color to and from the ColorModels

Each color model has method toColor() a static method fromColor() that will cast a Color to a ColorModel and vice versa, converting the color to desired color space if not called on RgbColor.

Color color = Color(0xFFFFFF00); // yellow

CmykColor cmykColor = CmykColor.fromColor(color);
color = cmykColor.toColor();

HsiColor hsiColor = HsiColor.fromColor(color);
color = hsiColor.toColor();

HslColor hslColor = HslColor.fromColor(color);
color = hslColor.toColor();

HspColor hspColor = HspColor.fromColor(color);
color = hspColor.toColor();

HsvColor hsvColor = HsvColor.fromColor(color);
color = hsvColor.toColor();

LabColor labColor = LabColor.fromColor(color);
color = labColor.toColor();

RgbColor rgbColor = RgbColor.fromColor(color);
color = rgbColor.toColor();

XyzColor xyzColor = XyzColor.fromColor(color);
color = xyzColor.toColor();

Due to the nature of this implementation, the base ColorModel lacks the toColor method. Instead, the global toColor method can be used.

// Cast a [ColorModel] to a [Color].
var color = toColor(color);

Converting Colors Between Spaces

Each color model has methods to convert itself to each of the other color models.

CmykColor toCmykColor();

HsiColor toHsiColor();

HslColor toHslColor();

HspColor toHspColor();

HsbColor toHsbColor();

LabColor toLabColor();

OklabColor toOklabColor();

RgbColor toRgbColor();

XyzColor toXyzColor();

Altenatively, each color model has a constructor ColorModel.from that can accept a color from any color space and returns its own type (T).

// Create a HSB color
HsbColor originalColor = HsbColor(0.3, 0.8, 0.7);

// Convert it to RGB => RgbColor(64, 179, 36)
RgbColor rgbColor = RgbColor.from(originalColor);

// Then to CMYK => CmykColor(64.25, 0, 79.89, 29.8)
CmykColor cmykColor = CmykColor.from(rgbColor);

// Back to HSB => HsbColor(0.3, 0.8, 0.7)
HsbColor hsbColor = HsbColor.from(cmykColor);

Note: All color conversions use the RGB color space as an intermediary. To minimize the loss of precision when converting between other color spaces, RgbColor privately stores the RGB values as nums rather than ints. The num values can be returned as a list with RgbColor's toPreciseList() method.

Color Adjustments

For convenience, each ColorModel has 2 getters, inverted and opposite, and 3 methods, cooler, warmer and rotateHue, for generating new colors.

inverted inverts the colors properties within their respective ranges, excluding hue, which is instead rotated 180 degrees.

final orange = RgbColor(255, 144, 0);

print(orange.inverted); // RgbColor(0, 111, 255);

opposite returns the color with the hue opposite this. opposite is shorthand for color.rotateHue(180).

rotateHue rotates the hue of the color by the amount specified in degrees. Colors in the CMYK, LAB, RGB, and XYZ color spaces will be converted to and from the HSL color space where the hue will be rotated.

final orange = RgbColor(255, 144, 0);

print(orange.opposite); // RgbColor(0, 111, 255);

print(orange.rotateHue(30)); // RgbColor(239, 255, 0);

print(orange.rotateHue(-30)); // RgbColor(255, 17, 0);

warmer and cooler will rotate the hue of the color by the amount specified towards 90 degrees and 270 degrees, respectively. The hue's value will be capped at 90 or 270.

final orange = RgbColor(255, 144, 0);

print(orange.warmer(30)); // RgbColor(239, 255, 0);

print(orange.cooler(30)); // RgbColor(255, 17, 0);

Interpolating Between Colors

Each color model has a method, lerpTo, that calculates a specified number of steps between this color and a color provided to the method, returning all of the colors inbetween the two colors in a list. Colors will be returned in the color space of the color the method is called on.

final color1 = RgbColor(255, 0, 0); // red
final color2 = RgbColor(0, 0, 255); // blue

/// Calculate a [List<RgbColor>] of 5 colors: [color1], [color2] and the 3 steps inbetween.
final colors = color1.lerpTo(color2, 3);

// [RgbColor(255, 0, 0, 255), RgbColor(191, 0, 64, 255), RgbColor(128, 0, 128, 255), RgbColor(64, 0, 191, 255), RgbColor(0, 0, 255, 255)]
print(colors);

/// To return only the steps in between [color1] and [color2], the [excludeOriginalColors] parameter can be set to `true`.
final steps = color1.lerpTo(color2, 3, excludeOriginalColors: true);

// [RgbColor(191, 0, 64, 255), RgbColor(128, 0, 128, 255), RgbColor(64, 0, 191, 255)]
print(steps);

Augmenting Palettes

color_models provides an extension on Iterable<ColorModel> for augmenting color palettes. It works by distributing the colors in the iterable across an abstract gradient and calculating new colors based on their positions within the gradient.

final palette = <ColorModel>[
  RgbColor(255, 0, 0),
  RgbColor(0, 255, 0),
  RgbColor(0, 0, 255),
];

// [RgbColor(255, 0, 0), RgbColor(128, 128, 0), RgbColor(0, 255, 0), RgbColor(0, 128, 128), RgbColor(0, 0, 255)]
final newPalette = palette.augment(5);

stops can be provided to map the colors in the list to positions within the abstract gradient.

final palette = <ColorModel>[
  RgbColor(255, 0, 0),
  RgbColor(0, 255, 0),
  RgbColor(0, 0, 255),
];

// [RgbColor(255, 0, 0), RgbColor(170, 85, 0), RgbColor(85, 170, 0), RgbColor(0, 255, 0), RgbColor(0, 0, 255)]
final newPalette = palette.augment(5, stops: [0.0, 0.75, 1.0]);

colorSpace can be provided to specify which color space the colors should be interpolated in. If colorSpace is left null, the colors will be interpolated in the space defined by the starting color in any pairing, unless reverse is set to true, in which case they'll be interpolated in the space defined by the ending color.

final palette = <ColorModel>[
  RgbColor(255, 0, 0),
  RgbColor(0, 255, 0),
  RgbColor(0, 0, 255),
];

// [(RgbColor(255, 0, 0), RgbColor(91, 33, 0), RgbColor(0, 255, 0), RgbColor(0, 34, 59), RgbColor(0, 0, 255))]
final newPalette = palette
    .augment(5, colorSpace: ColorSpace.oklab)
    .map<RgbColor>((color) => color.toRgbColor());

The Chroma Value

The chroma getter returns a value that represents the lightness of a color on a 0 to 1 scale.

The value is derived from the color's lightness value in the Oklab color space by normalizing it to a linear curve.

  print(RgbColor(0, 0, 0).chroma); // 0
  print(RgbColor(127, 127, 127).chroma); // 0.5
  print(RgbColor(255, 255, 255).chroma); // 1.0

The withChroma method will return a modified color by applying the supplied chroma value to the color in the Oklab color space and converting it back to its original color space.

  final color = RgbColor(42, 176, 232);
  print(color.chroma); // 0.534
  print(color.withChroma(0.3)); // RgbColor(21, 101, 135)