Contrast - now working and documented!

MinchinWeb · Dec 12, 2014 · 9880804 · 9880804
1 parent 960383c
commit 9880804
Show file tree

Hide file tree

Showing 4 changed files with 104 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -67,4 +67,45 @@ to say:
 ~~~python
 >>> c3.luminance()
 0.2641668488934239
+>>> colourettu.luminance(c4)
 ~~~
+
+## Contrast
+
+Contrast the difference in (precieved) brightness between colours.
+Values vary between 1:1 (a given colour on itself) and 21:1 (white on black).
+
+To compute contrast, two colours are required.
+
+~~~python
+>>> colourettu.contrast("#FFF", "#FFF")	# white on white
+1.0
+>>> colourettu.contrast(c1, "#000")	# black on white
+20.999999999999996
+>>> colourettu.contrast(c4, c5)
+4.363552233203198
+~~~
+
+`contrast` can also be called on an already existing colour, but a second
+colour needs to be provided:
+
+~~~python
+>>> c4.contrast(c5)
+4.363552233203198
+~~~
+
+### Use of Contrast
+
+For Basic readability, the ANSI standard is a contrast of 3:1 between the text
+and it's background. The W3C proposes this as a minimum acceissibilty standard
+for regular text under 18pt and bold text under 14pt. This is referred to as the
+*A* standard. The W3C defines a higher *AA* standard with a mimimum contrast of
+4.5:1. This is approximately equivalent to 20/40 vision, and is common for
+those over 80. The W3C define an even higher *AAA* standard with a 7:1 minimum
+contrast. This would be equivalent to 20/80 vision. Generally, it is assumed
+that those with vision beyond this would access the web with the use of
+assistive technologies.
+
+Also mentioned (and confirmed by personal experience), if the contrast is *too*
+great, this can also cause readability problems when reading longer passages,
+but I have been unable to find any quantitative research to this effect.
diff --git a/colourettu/__init__.py b/colourettu/__init__.py
@@ -3,6 +3,7 @@
 # from ._luminance import luminance
 from ._colour import colour
 from ._colour import _luminance as luminance
+from ._colour import _contrast as contrast
 
 color = colour
 

diff --git a/colourettu/_colour.py b/colourettu/_colour.py
@@ -70,6 +70,9 @@ def normalized_rgb(self):
     def luminance(self):
         return _luminance(self)
 
+    def contrast(self, myothercolour):
+        return _contrast(self, myothercolour)
+
 
 def _luminance(mycolour):
     '''Determine relative luminance of colours'''
@@ -88,3 +91,33 @@ def _luminance(mycolour):
     (r1, g1, b1) = mycolour2.normalized_rgb()
 
     return sqrt(0.299*pow(r1, 2) + 0.587*pow(g1, 2) + 0.114*pow(b1, 2))
+
+
+def _contrast(colour1, colour2):
+    '''Determines the contrast between two colours'''
+
+    '''Used the formula (L1 + 0.05) : (L2 + 0.05)'''
+
+    if type(colour1) is colour:
+        mycolour1 = colour1
+    else:
+        try:
+            mycolour1 = colour(colour1)
+        except:
+            raise TypeError("colour1 must be a colourettu.colour")
+
+    if type(colour2) is colour:
+        mycolour2 = colour2
+    else:
+        try:
+            mycolour2 = colour(colour2)
+        except:
+            raise TypeError("colour2 must be a colourettu.colour")
+
+    lum1 = mycolour1.luminance()
+    lum2 = mycolour2.luminance()
+
+    minlum = min(lum1, lum2)
+    maxlum = max(lum1, lum2)
+
+    return (maxlum + 0.05) / (minlum + 0.05)
diff --git a/tests/test_contrast.py b/tests/test_contrast.py
@@ -0,0 +1,29 @@
+import unittest
+import colourettu
+
+
+class Test_Contrast(unittest.TestCase):
+
+    def test_contrast_white_white(self):
+        '''The Contrast of White and White should be 1'''
+        self.assertAlmostEqual(colourettu.contrast('#FFF', '#FFF'), 1)
+
+    def test_contrast_black_black(self):
+        '''The Contrast of Black and Black should be 1'''
+        self.assertAlmostEqual(colourettu.contrast('#000', '#000'), 1)
+
+    def test_contrast_white_black(self):
+        '''The Contrast of White and Black should be 21'''
+        self.assertAlmostEqual(colourettu.contrast('#FFF', '#000'), 21)
+
+    def test_contrast_from_colour(self):
+        '''The Contrast of a provided colour against White'''
+        colour1 = colourettu.colour("#cde")
+        self.assertTrue(colour1.contrast("#FFF"))
+
+
+def main():
+    unittest.main()
+
+if __name__ == '__main__':
+    unittest.main()