all the docs

Author: kwinkunks

README.md

@@ -24,25 +24,62 @@ Read [the documentation](https://code.agilescientific.com/unmap)
 
 ## Example
 
-We'll grab an image from the web and unmap it:
+We'll grab an image from the web and unmap it. First we'll download the image:
 
 ```python
+from io import BytesIO
+
+import requests
+import numpy as np
+from PIL import Image
+import matplotlib.pyplot as plt
+
+
 def get_image_from_web(uri):
     data = requests.get(uri).content
     img = Image.open(BytesIO(data)).convert('RGB')
     rgb_im = np.asarray(img)[..., :3] / 255.
     return rgb_im
 
-# An image from Matteo Niccoli's blog:
-# https://mycartablog.com/2014/08/24/what-your-brain-does-with-colours-when-you-are-not-looking-part-1/
-img = get_image_from_web('https://i0.wp.com/mycartablog.com/wp-content/uploads/2014/03/spectrogram_jet.png')
+# An image from Hugh Pumprey's blog post Colours for Contours, licensed CC BY
+# https://blogs.ed.ac.uk/hughpumphrey/2017/06/29/colours-for-contours/
+uri = 'https://blogs.ed.ac.uk/hughpumphrey/wp-content/uploads/sites/958/2017/06/jeti.png'
+img = get_image_from_web(uri)
+```
+
+The image looks like this:
 
-import gio
+![Hugh_Pumphrey_CC-BY_original.png](./_static/Hugh_Pumphrey_CC-BY_original.png)
 
-data = gio.unmap(img, cmap='jet')
+Now we'll unmap it:
+
+```python
+import unmap
+
+data = unmap.unmap(img, cmap='jet')
 plt.imshow(data)
 ```
 
+This results in:
+
+![The unmapped data.](./_static/Hugh_Pumphrey_CC-BY_unmapped_1.png)
+
+Notice that the data is there, but so is the colourbar. Also, the new data's colourbar shows that our dataset ranges from 0 to 1, but we can see from the colourbar in the original plot that it should range from about 0.4 to 1.333. So let's add `vrange` and `crop` arguments to deal with these issues:
+
+```python
+data = unmap.unmap(img, cmap='jet', vrange=(0.400, 1.333), crop=(115, 72, 690, 647))
+```
+
+Which gives us:
+
+![The final result, cropped to the data area.](./_static/Hugh_Pumphrey_CC-BY_unmapped_2.png)
+
+We could even plot this side by side with the original data, using the same colourmap, as a rough QC:
+
+![Comparison between input and output.](./_static/Hugh_Pumphrey_CC-BY_compare.png)
+
+The extents of the data area are different. We could pass the `extent` argument to `plt.imshow` to fix this, but an even better idea is to put the data in an `xarray.DataArray`, because then the coordinates are attached to the data in a much more useful way. You could do this on your own, or you can use the Gio library's `unmap_to_dataarray()` function to do it for you.
+
 
 ## Testing
 

docs/Makefile

@@ -15,6 +15,7 @@ help:
 .PHONY: help html
 
 html:
+	python process_ipynb.py $(SOURCEDIR)/notebooks
 	$(SPHINXBUILD) -E -b html $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html 
 	python process_html.py $(BUILDDIR)/html
 	@echo

docs/_static/Hugh_Pumphrey_CC-BY_compare.png

@@ -44,20 +44,12 @@ def setup(app):
 extensions = ['sphinx.ext.githubpages',
               'sphinxcontrib.apidoc',
               'sphinx.ext.napoleon',
-              'myst_parser',
+              'myst_nb',
               'sphinx.ext.viewcode'
 ]
 
 myst_enable_extensions = ["dollarmath", "amsmath"]
-
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build']
+jupyter_execute_notebooks = "force"
 
 # Apidoc automation
 # https://pypi.org/project/sphinxcontrib-apidoc/
@@ -68,6 +60,14 @@ def setup(app):
 apidoc_toc_file = False
 apidoc_separate_modules = False
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'notebooks']
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -105,4 +105,4 @@ def setup(app):
 
 # Branding.
 html_favicon = '_static/favicon.ico'
-html_logo = '_static/unmap_logo.png'
+html_logo = '_static/unmap.png'

docs/_static/Hugh_Pumphrey_CC-BY_original.png

@@ -20,6 +20,7 @@ User guide
     :caption: User guide
 
     readme
+    userguide/Unmap_data_from_an_image.ipynb
 
 
 API reference