README improvments

README.md

@@ -2,19 +2,31 @@
 
 A python library for identifying bubbles/droplets based on volume of fluid (VOF) simulation data.
 
-For documentation, see [dgaylo.github.io/blobid-python](https://dgaylo.github.io/blobid-python).
+# Installation
 
-# Example
+It is suggested to install the library with [Numba](https://numba.pydata.org/) enabled:
+```
+pip install blobid[numba]
+```
 
-![vof and label field](doc/example.svg)
+# Documentation
+
+For the latest release: [dgaylo.github.io/blobid-python](https://dgaylo.github.io/blobid-python)
 
-Here we use the following code to calculate the labels of the air bubbles in water near the surface,
+# Example
+
+Here we load a 2D slice from a simulation of air bubbles in water near the surface, 
+and then use this library to identify and label all the air bubble.
 ```Python Console
 >>> import numpy as np
 >>> from blobid import get_labels
 >>> vof = 1.0 - np.load("tests/resources/fs_vof.npy")[:, 0, :]
 >>> labels = get_labels(vof, periodic=[True, False])
 ```
-and then render the `vof` field and the `labels` field using Matplotlib (see [doc/example.py](doc/example.py)).
-For illustration we use a 2D slice for the `vof` field, but the library supports 1D, 2D, or 3D.
+
+Below is a rendering of the `vof` field (air is white, water is black) and the `labels` field calculated using `get_labels()`
+
+![vof and label field](doc/example.svg)
+
+The full script, including creating these graphics using [Matplotlib](https://matplotlib.org/), is [doc/example.py](doc/example.py).
 

doc/example.py

@@ -9,10 +9,17 @@
 
 # make the plots
 import matplotlib.pyplot as plt
+from matplotlib.colors import ListedColormap
+
+# create a nice coloring for the labels
+base = plt.colormaps["tab20"]
+colors = [base(i % base.N) for i in np.unique(labels)]
+colors[0] = (0, 0, 0, 1)  # unlabeled cells
+labels_cmap = ListedColormap(colors)
 
 fig, ax = plt.subplots(nrows=2)
 ax[0].pcolormesh(1.0-vof.transpose(), cmap='binary', shading='gouraud', rasterized=True)
-ax[1].pcolormesh(labels.transpose(), cmap='nipy_spectral', shading='nearest', rasterized=True)
+ax[1].pcolormesh(labels.transpose(), cmap=labels_cmap, shading='nearest', rasterized=True)
 
 for a in ax:
     a.set_xticks([])
@@ -23,4 +30,4 @@
 plt.rcParams['svg.hashsalt']="blobid-python"
 
 plt.subplots_adjust(hspace=0)
-plt.savefig("doc/example.svg", transparent=True, bbox_inches='tight', pad_inches=0)
+plt.savefig("doc/example.svg", transparent=True, bbox_inches='tight', pad_inches=0, metadata={'Date': None})