[](https://travis-ci.org/bennyguitar/Colours)
[](https://gitter.im/bennyguitar/Colours)
## Installation
Drag the included **Colours.h** and **Colours.m** files into your project. They are located in the top-level directory. You can see a demo of how to use these with the included Xcode project as well.
#import "Colours.h" into the classes you want to use this category in and you're all set.
**Cocoapods**
pod 'Colours'
or, for Swift:
pod 'Colours/Swift'
**NSColor**
Colours supports NSColor out of the box! Just make sure you have the AppKit framework installed (it comes that way for a new application) and you will be set. This README uses UIColor for its examples, just substitute NSColor and the methods are all the same.
**Swift**
A Swift version of Colours now exists that contains everything in the Obj-C version except:
* Color Components Dictionary (use the tuples instead)
* Sorting/Comparing Colors
* Distance between Colors
Also, instead of dictionaries and arrays of color components, tuples are used instead. So instead of `[someRedColor rgbaArray]`, you would use `someRedColor.rgba()` which gives you a tuple of four `CGFloats` like `(1.0, 0.0, 0.0, 1.0)`. To get just the red value, you would write `someRedColor.rgba().r`.
## Table of Contents
* [Color Palette](#color-palette)
* [Using Predefined Colors](#using-predefined-colors)
* [Color Helper Methods](#color-helper-methods)
* [Hex String](#hex-string)
* [RGBA](#rgba)
* [HSBA](#hsba)
* [CIELAB](#cielab)
* [CMYK](#cmyk)
* [Color Components](#color-components)
* [Darken/Lighten Components](#darkenlighten-colors)
* [Black or White Contrasting Color](#black-or-white-contrasting-color)
* [Complementary Color](#complementary-color)
* [Distance between 2 Colors](#distance-between-2-colors)
* [Generating Color Schemes](#generating-color-schemes)
* [Android](#android)
* [Xamarin](#xamarin)
* [Reap What I Sow!](#reap-what-i-sow)
## Color Palette
 | infoBlueColor |  | successColor |  | warningColor |
 | dangerColor |  | antiqueWhiteColor |  | oldLaceColor |
 | ivoryColor |  | seashellColor |  | ghostWhiteColor |
 | snowColor |  | linenColor |  | black25PercentColor |
 | black50PercentColor |  | black75PercentColor |  | warmGrayColor |
 | coolGrayColor |  | charcoalColor |  | tealColor |
 | steelBlueColor |  | robinEggColor |  | pastelBlueColor |
 | turquoiseColor |  | skyBlueColor |  | indigoColor |
 | denimColor |  | blueberryColor |  | cornflowerColor |
 | babyBlueColor |  | midnightBlueColor |  | fadedBlueColor |
 | icebergColor |  | waveColor |  | emeraldColor |
 | grassColor |  | pastelGreenColor |  | seafoamColor |
 | paleGreenColor |  | cactusGreenColor |  | chartreuseColor |
 | hollyGreenColor |  | oliveColor |  | oliveDrabColor |
 | moneyGreenColor |  | honeydewColor |  | limeColor |
 | cardTableColor |  | salmonColor |  | brickRedColor |
 | easterPinkColor |  | grapefruitColor |  | pinkColor |
 | indianRedColor |  | strawberryColor |  | coralColor |
 | maroonColor |  | watermelonColor |  | tomatoColor |
 | pinkLipstickColor |  | paleRoseColor |  | crimsonColor |
 | eggplantColor |  | pastelPurpleColor |  | palePurpleColor |
 | coolPurpleColor |  | violetColor |  | plumColor |
 | lavenderColor |  | raspberryColor |  | fuschiaColor |
 | grapeColor |  | periwinkleColor |  | orchidColor |
 | goldenrodColor |  | yellowGreenColor |  | bananaColor |
 | mustardColor |  | buttermilkColor |  | goldColor |
 | creamColor |  | lightCreamColor |  | wheatColor |
 | beigeColor |  | peachColor |  | burntOrangeColor |
 | pastelOrangeColor |  | cantaloupeColor |  | carrotColor |
 | mandarinColor |  | chiliPowderColor |  | burntSiennaColor |
 | chocolateColor |  | coffeeColor |  | cinnamonColor |
 | almondColor |  | eggshellColor |  | sandColor |
 | mudColor |  | siennaColor |  | dustColor |
## Using Predefined Colors
Colours was set up to be exactly like using an Apple predefined system color. For instance, to get a stark red, you type [UIColor redColor]. You don't get a lot of variation on this though without diving into the colorWithRed:green:blue:alpha: method and customizing the heck out of it. Well, I took the liberty of creating 100 colors to use in the same system color way that Apple uses with iOS. So instead of the redColor example earlier, just substitute one of the colors from the giant palette above, like so: [UIColor indigoColor].
## Color Helper Methods
Beyond giving you a list of a ton of colors with no effort, this category also gives you some methods that allow different color manipulations and translations. Here's how you use these:
#### Hex String
You can convert the commonly seen hexadecimal color string (ahh, thank you CSS) to a UIColor, and vice versa, very easily using the following methods:
```objc
UIColor *newColor = [UIColor colorFromHexString:@"#f587e4"];
NSString *hexString = [newColor hexString];
```
#### RGBA
**RGBA Array to and from a UIColor**
The color -> array method creates an array of 4 NSNumbers representing the RGBA values of the color. These are not in the 0-255 range, but rather normalized in the 0-1 range. So if your R is 230, then it will be represented in the array as 0.902.
```objc
NSArray *colorArray = [[UIColor seafoamColor] rgbaArray];
UIColor *newColor = [UIColor colorFromRGBAArray:colorArray];
```
**RGBA Dictionary to and from a UIColor**
Similar to the array method above, this returns an NSDictionary that contains NSNumbers. Static keys are used to access the different color components of the dictionary. This allows you to use autocorrect to use the returned dictionary faster.
* `kColoursRGBA_R`
* `kColoursRGBA_G`
* `kColoursRGBA_B`
* `kColoursRGBA_A`
```objc
NSDictionary *colorDict = [[UIColor seafoamColor] rgbaDictionary];
UIColor *newColor = [UIColor colorFromRGBADictionary:colorDict];
// You can also get a single component like so:
NSNumber *r = colorDict[kColoursRGBA_R];
```
#### HSBA
Like both of the RGBA methods above, you can also get the Hue, Saturation and Brightness values from a UIColor and create an array or dictionary out of them, or vice versa. The colorDictionary returned also uses static keys like the RGBA version of this method. Here are the ones to use:
* `kColoursHSBA_H`
* `kColoursHSBA_S`
* `kColoursHSBA_B`
* `kColoursHSBA_A`
```objc
NSArray *colorArray = [[UIColor seafoamColor] hsbaArray];
NSDictionary *colorDict = [[UIColor seafoamColor] hsbaDictionary];
UIColor *newColor1 = [UIColor colorFromHSBAArray:colorArray];
UIColor *newColor2 = [UIColor colorFromHSBADictionary:colorDictionary];
```
#### CIELAB
Like both of the RGBA methods above, you can also get the CIE\_Lightness, CIE\_a and CIE\_b values from a UIColor and create an array or dictionary out of them, or vice versa. The colorDictionary returned also uses static keys like the RGBA version of this method. Here are the ones to use:
* `kColoursCIE_L`
* `kColoursCIE_A`
* `kColoursCIE_B`
* `kColoursCIE_alpha`
```objc
NSArray *colorArray = [[UIColor seafoamColor] CIE_LabArray];
NSDictionary *colorDict = [[UIColor seafoamColor] CIE_LabDictionary];
UIColor *newColor1 = [UIColor colorFromCIE_LabArray:colorArray];
UIColor *newColor2 = [UIColor colorFromCIE_LabDictionary:colorDictionary];
```
#### CMYK
Like both of the RGBA methods above, you can also get the CMYKY values from a UIColor and create an array or dictionary out of them, or vice versa. The colorDictionary returned also uses static keys like the RGBA version of this method. Here are the ones to use:
* `kColoursCMYK_C`
* `kColoursCMYK_M`
* `kColoursCMYK_Y`
* `kColoursCMYK_K`
```objc
NSArray *colorArray = [[UIColor seafoamColor] cmykArray];
NSDictionary *colorDict = [[UIColor seafoamColor] cmykDictionary];
UIColor *newColor1 = [UIColor colorFromCMYKArray:colorArray];
UIColor *newColor2 = [UIColor colorFromCMYKDictionary:colorDictionary];
```
#### Color Components
This method returns a dictionary containing values for each of the keys (RGBA, HSBA, CIE_LAB, CMYK) from above. This means you can get a hue value and a Lightness value from the same source. Here's how you use this:
```objc
NSDictionary *components = [someColor colorComponents];
CGFloat H = components[kColoursHSBA_H];
CGFloat L = components[kColoursCIE_L];
```
You can also retrieve singular values instead of the entire dictionary by calling any of these methods below on a UIColor. This will be significantly slower at getting all of the values for one color, versus just retrieving one. If you need more than one, call the specific array or dictionary method from above.
```obj
CGFloat R = [[UIColor tomatoColor] red];
CGFloat G = [[UIColor tomatoColor] green];
CGFloat B = [[UIColor tomatoColor] blue];
CGFloat H = [[UIColor tomatoColor] hue];
CGFloat S = [[UIColor tomatoColor] saturation];
CGFloat B = [[UIColor tomatoColor] brightness];
CGFloat CIE_L = [[UIColor tomatoColor] CIE_Lightness];
CGFloat CIE_A = [[UIColor tomatoColor] CIE_a];
CGFloat CIE_B = [[UIColor tomatoColor] CIE_b];
CGFloat alpha = [[UIColor tomatoColor] alpha];
```
#### Darken/Lighten Colors
You can darken or lighten a color by using these methods. The only parameter is a percentage float from 0 -> 1, so a 25% lighter color would use the parameter 0.25.
```objc
UIColor *lighterColor = [[UIColor seafoamColor] lighten:0.25f];
UIColor *darkerColor = [[UIColor seafoamColor] darken:0.25f];
```
#### Black or White Contrasting Color
A lot of times you may want to put text on top of a view that is a certain color, and you want to be sure that it will look good on top of it. With this method you will return either white or black, depending on the how well each of them contrast on top of it. Here's how you use this:
```objc
UIColor *contrastingColor = [[UIColor seafoamColor] blackOrWhiteContrastingColor];
```
#### Complementary Color
This method will create a UIColor instance that is the exact opposite color from another UIColor on the color wheel. The same saturation and brightness are preserved, just the hue is changed.
```objc
UIColor *complementary = [[UIColor seafoamColor] complementaryColor];
```
## Distance between 2 Colors
`5.1.0 +`
Detecting a difference in two colors is not as trivial as it sounds. One's first instinct is to go for a difference in RGB values, leaving you with a sum of the differences of each point. It looks great! Until you actually start comparing colors. Why do these two reds have a different distance than these two blues *in real life* vs computationally? Human visual perception is next in the line of things between a color and your brain. Some colors are just perceived to have larger variants inside of their respective areas than others, so we need a way to model this human variable to colors. Enter CIELAB. This color formulation is supposed to be this model. So now we need to standardize a unit of distance between any two colors that works independent of how humans visually perceive that distance. Enter CIE76,94,2000. These are methods that use user-tested data and other mathematically and statistically significant correlations to output this info. You can read the wiki articles below to get a better understanding historically of how we moved to newer and better color distance formulas, and what their respective pros/cons are.
**Finding Distance**
```objc
CGFloat distance = [someColor distanceFromColor:someOtherColor type:ColorDistanceCIE94];
BOOL isNoticablySimilar = distance < threshold;
```
**References**
* [Color Difference](http://en.wikipedia.org/wiki/Color_difference)
* [Just Noticeable Difference](http://en.wikipedia.org/wiki/Just_noticeable_difference)
* [CIELAB Specification](http://en.wikipedia.org/wiki/CIELAB)
## Generating Color Schemes
You can create a 5-color scheme based off of a UIColor using the following method. It takes in a UIColor and one of the ColorSchemeTypes defined in Colours. It returns an NSArray of 4 new UIColor objects to create a pretty nice color scheme that complements the root color you passed in.
```objc
NSArray *colorScheme = [color colorSchemeOfType:ColorSchemeType];
```
**ColorSchemeTypes**
* ColorSchemeAnalagous
* ColorSchemeMonochromatic
* ColorSchemeTriad
* ColorSchemeComplementary
Here are the different examples starting with a color scheme based off of [UIColor seafoamColor].
**ColorSchemeAnalagous**
**ColorSchemeMonochromatic**
**ColorSchemeTriad**
**ColorSchemeComplementary**
## Android
My friend, [Matt York](https://github.com/MatthewYork) ported a version of this repository over to Android, so you can use these exact same colors and color methods in your Android apps as well. You can find it here: [Colours for Android](https://github.com/MatthewYork/Colours).
## Xamarin
[akamud](https://github.com/akamud/) has graciously ported this library as a Xamarin Android component, which can be found at [https://github.com/akamud/Colours](https://github.com/akamud/Colours). An iOS Xamarin component is in the works as well.
Reap What I Sow!
================
This project is distributed under the standard MIT License. Please use this and twist it in whatever fashion you wish - and recommend any cool changes to help the code.
[](https://bitdeli.com/free "Bitdeli Badge")