Update README.md

src/README.md

@@ -1,36 +1,3 @@
-# Contrast Measures
-Various function that calculate contrast metrics.
-
-### Example usage
-
-```python
-from stimuli import contrast_metrics as cm
-from stimuli.transparency import CheckerboardFactory
-
-f = CheckerboardFactory()
-f.find_checkerboard(8)
-f.build_image(1, .5)
-img, mask = f.get_checkerboard(return_mask=True)
-```
-Checkerboard (left) and only the masked region (right):
-
-![Checkerboard](example_images/checkerboard.png)
-![Masked Checkerboard](example_images/checkerboard_masked.png)
-
-This computes the average of all pair-wise Michelson Contrasts between unique luminance values in the
-masked region of the image:
-```python
-cm.SAM(img, mask=(mask==1), mode="unique")
-```
-Available Metrics:
-- SAM: Space Average Michelson Contrast
-- SAMLG: SAM of log luminances
-- SDMC: Standard Deviation of pair-wise Michelson Contrasts
-- SAW: Space Average Whittle Contrast
-- SAWLG: SAW of log luminances
-- RMS: Root Mean Sqaure Contrast
-- SD: Standard Deviation of luminances
-- SDLG: SD of log luminances
 
 # Lightness
 This submodule contains functions for creating common stimuli used in
@@ -45,21 +12,28 @@ for details.
 from stimuli import lightness
 import matplotlib.pyplot as plt
 ```
-#### Cornsweet / Todorovic
+#### Cornsweet 
+A rectangular Cornsweet edge stimulus.
 ![Cornsweet](example_images/cornsweet.png)
-![Todorovic](example_images/todorovic.png)
 ```python
 a = lightness.cornsweet((10, 10), 10, .5)
-b = lightness.todorovic(a, 2, 2)
 
 plt.figure()
 plt.imshow(a, vmin=0, vmax=1, cmap='gray')
 plt.show()
+```
+
+#### Todorovic
+![Todorovic](example_images/todorovic.png)
+A checkerboard illusion by appropriately aligning COC stimuli, in the way demonstrated by Todorovic (1987)
+```python
+a = lightness.cornsweet((10, 10), 10, .5)
+
 plt.figure()
 plt.imshow(b, vmin=0, vmax=1, cmap='gray')
 plt.show()
-
 ```
+
 #### Square Wave
 ![Square Wave](example_images/square_wave.png)
 ```python
@@ -70,7 +44,7 @@ plt.imshow(c, vmin=0, vmax=1, cmap='gray')
 plt.show()
 
 ```
-#### White's Illusion BMCC
+#### White's Illusion - Blakeslee and McCourt (1999)
 ![White's Illusion BMCC](example_images/whites_illusion_bmcc.png)
 
 ![Contours dark](example_images/contours_white_bmcc_dark.png)
@@ -90,8 +64,8 @@ plt.imshow(e2, vmin=0, vmax=1, cmap='gray')
 plt.show()
 
 ```
-#### White's Illusion Gil
-![White's Illusion Gil](example_images/whites_illusion_gil.png)
+#### White's Illusion - Gilchrist
+![White's Illusion Gilchrist](example_images/whites_illusion_gil.png)
 ```python
 f = lightness.whites_illusion_gil((10, 10), 10, .5, 2)
 
@@ -110,6 +84,41 @@ plt.imshow(g, vmin=0, vmax=1, cmap='gray')
 plt.show()
 ```
 
+# Contrast Measures
+Various function that calculate contrast metrics.
+
+### Example usage
+
+```python
+from stimuli import contrast_metrics as cm
+from stimuli.transparency import CheckerboardFactory
+
+f = CheckerboardFactory()
+f.find_checkerboard(8)
+f.build_image(1, .5)
+img, mask = f.get_checkerboard(return_mask=True)
+```
+Checkerboard (left) and only the masked region (right):
+
+![Checkerboard](example_images/checkerboard.png)
+![Masked Checkerboard](example_images/checkerboard_masked.png)
+
+This computes the average of all pair-wise Michelson Contrasts between unique luminance values in the
+masked region of the image:
+```python
+cm.SAM(img, mask=(mask==1), mode="unique")
+```
+Available Metrics:
+- SAM: Space Average Michelson Contrast
+- SAMLG: SAM of log luminances
+- SDMC: Standard Deviation of pair-wise Michelson Contrasts
+- SAW: Space Average Whittle Contrast
+- SAWLG: SAW of log luminances
+- RMS: Root Mean Sqaure Contrast
+- SD: Standard Deviation of luminances
+- SDLG: SD of log luminances
+
+
 # Utils
 Helper functions for padding, resizing, computing Munsell values, and
 converting pixel values to degrees of visual angle.