Skip to content

Latest commit

 

History

History
273 lines (178 loc) · 29.3 KB

README.md

File metadata and controls

273 lines (178 loc) · 29.3 KB

ScreenShot

Build Status

Gitter chat

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

infoBlueColorinfoBlueColorsuccessColorsuccessColorwarningColorwarningColor
dangerColordangerColorantiqueWhiteColorantiqueWhiteColoroldLaceColoroldLaceColor
ivoryColorivoryColorseashellColorseashellColorghostWhiteColorghostWhiteColor
snowColorsnowColorlinenColorlinenColorblack25PercentColorblack25PercentColor
black50PercentColorblack50PercentColorblack75PercentColorblack75PercentColorwarmGrayColorwarmGrayColor
coolGrayColorcoolGrayColorcharcoalColorcharcoalColortealColortealColor
steelBlueColorsteelBlueColorrobinEggColorrobinEggColorpastelBlueColorpastelBlueColor
turquoiseColorturquoiseColorskyBlueColorskyBlueColorindigoColorindigoColor
denimColordenimColorblueberryColorblueberryColorcornflowerColorcornflowerColor
babyBlueColorbabyBlueColormidnightBlueColormidnightBlueColorfadedBlueColorfadedBlueColor
icebergColoricebergColorwaveColorwaveColoremeraldColoremeraldColor
grassColorgrassColorpastelGreenColorpastelGreenColorseafoamColorseafoamColor
paleGreenColorpaleGreenColorcactusGreenColorcactusGreenColorchartreuseColorchartreuseColor
hollyGreenColorhollyGreenColoroliveColoroliveColoroliveDrabColoroliveDrabColor
moneyGreenColormoneyGreenColorhoneydewColorhoneydewColorlimeColorlimeColor
cardTableColorcardTableColorsalmonColorsalmonColorbrickRedColorbrickRedColor
easterPinkColoreasterPinkColorgrapefruitColorgrapefruitColorpinkColorpinkColor
indianRedColorindianRedColorstrawberryColorstrawberryColorcoralColorcoralColor
maroonColormaroonColorwatermelonColorwatermelonColortomatoColortomatoColor
pinkLipstickColorpinkLipstickColorpaleRoseColorpaleRoseColorcrimsonColorcrimsonColor
eggplantColoreggplantColorpastelPurpleColorpastelPurpleColorpalePurpleColorpalePurpleColor
coolPurpleColorcoolPurpleColorvioletColorvioletColorplumColorplumColor
lavenderColorlavenderColorraspberryColorraspberryColorfuschiaColorfuschiaColor
grapeColorgrapeColorperiwinkleColorperiwinkleColororchidColororchidColor
goldenrodColorgoldenrodColoryellowGreenColoryellowGreenColorbananaColorbananaColor
mustardColormustardColorbuttermilkColorbuttermilkColorgoldColorgoldColor
creamColorcreamColorlightCreamColorlightCreamColorwheatColorwheatColor
beigeColorbeigeColorpeachColorpeachColorburntOrangeColorburntOrangeColor
pastelOrangeColorpastelOrangeColorcantaloupeColorcantaloupeColorcarrotColorcarrotColor
mandarinColormandarinColorchiliPowderColorchiliPowderColorburntSiennaColorburntSiennaColor
chocolateColorchocolateColorcoffeeColorcoffeeColorcinnamonColorcinnamonColor
almondColoralmondColoreggshellColoreggshellColorsandColorsandColor
mudColormudColorsiennaColorsiennaColordustColordustColor

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:

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.

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
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
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
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
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:

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.

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.

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:

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.

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

CGFloat distance = [someColor distanceFromColor:someOtherColor type:ColorDistanceCIE94];
BOOL isNoticablySimilar = distance < threshold;

References

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.

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

Analagous

ColorSchemeMonochromatic

Monochromatic

ColorSchemeTriad

Triad

ColorSchemeComplementary

Complementary

Android

My friend, Matt York 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.

Xamarin

akamud has graciously ported this library as a Xamarin Android component, which can be found at 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.

Bitdeli Badge