Improved documentation: Added image captions, formatted keystroke letters using :kbd:.

Author: victoriousluser

docs/source/_static/css/custom.css

@@ -13,3 +13,36 @@ div.bottomnav p {
     text-align: left;
     font-size: 0.8em;
 }
+
+table.image-grid,
+table.image-grid tr,
+table.image-grid col {
+    border: hidden;
+}
+
+table.caption,
+table.caption tr,
+table.caption col {
+    border: hidden;
+}
+
+table.caption {
+    margin-left: 5%;
+    margin-right: 5%;
+    width: 90%;
+}
+
+table.caption td {
+    text-align: center;
+    font-size: smaller;
+    font-style: italic;
+}
+
+.kbd.docutils.literal {
+    border: solid #CCCCCC 1px;
+    font-family: Arial, Helvetica, sans-serif;
+    font-size: 90%;
+	  font-weight: normal;
+    padding: 1px 5px 3px;
+    white-space: nowrap;
+}

docs/source/quickstart.rst

@@ -6,8 +6,9 @@ Install pptk.
     >>> pip install pptk
 
 .. note::
-   pptk requires 64-bit Python and is currently only :code:`pip install`-able on Python 3.6 and Python 2.7.
-    
+   pptk requires 64-bit Python and is only :code:`pip install`-able on versions of Python
+   that have a corresponding pptk wheel file on PyPI.
+
 In Python, generate 100 random 3-d points, and 
 
 .. code-block:: python

docs/source/tutorial.rst

@@ -6,7 +6,53 @@ Tutorials
 Visualizing 2-d and 3-d point data
 ----------------------------------
 
-:py:func:`pptk.viewer` is able to visualize any point data that can be represented as a 3-column numpy array.
+.. |semantic3d_small_i| image:: tutorials/viewer/images/semantic3d_small_i.jpg
+   :height: 200
+   :width: 275
+   :scale: 80%
+   :align: middle
+
+.. |geolife_utm| image:: tutorials/viewer/images/geolife_utm.png
+   :height: 200
+   :width: 289
+   :scale: 80%
+   :align: middle
+
+.. |footprints_dc| image:: tutorials/viewer/images/footprints_dc.png
+   :height: 200
+   :width: 275
+   :scale: 80%
+   :align: middle
+
+.. |mobius| image:: tutorials/viewer/images/mobius.png
+   :height: 200
+   :width: 200
+   :scale: 80%
+   :align: middle
+
+.. rst-class:: image-grid
+.. table::
+   :widths: 280 294 280 205
+   :align: center
+
+   ==================== ============= =============== ========
+   |semantic3d_small_i| |geolife_utm| |footprints_dc| |mobius|
+   ==================== ============= =============== ========
+
+.. rst-class:: caption
+
+   +---------------------------------------------------------------------------------------------------------------+
+   | Point datasets visualized using :py:meth:`pptk.viewer`.                                                       |
+   | The :file:`bildstein1` Lidar point cloud from `Semantic3D <http://semantic3d.net>`__ (left).                  |
+   | Beijing GPS trajectories from                                                                                 |
+   | `Geolife <https://www.microsoft.com/en-us/research/publication/geolife-gps-trajectory-dataset-user-guide/>`__ |
+   | (middle left).                                                                                                |
+   | :file:`DistrictofColumbia.geojson` 2-d polygons from                                                          |
+   | `US building footprints <https://github.com/Microsoft/USBuildingFootprints>`__ (middle right).                |
+   | A Mobius strip (right).                                                                                       |
+   +---------------------------------------------------------------------------------------------------------------+
+
+:py:func:`pptk.viewer` allows interactive visualization of any point data that can be represented as a 3-column numpy array.
 This includes Lidar point clouds, GPS trajectories, points on a 3-d parametric surface, or even point samplings of 2-d polygons.
 The viewer is not tied to a specific file format.
 As shown in these tutorials,

docs/source/tutorials/viewer/building_footprints.rst

@@ -83,6 +83,7 @@ Visualize.
    :width: 375px
    :align: middle
 
+.. rst-class:: image-grid
 .. table::
    :widths: 390 390
    :align: center
@@ -91,6 +92,14 @@ Visualize.
    |footprints_dc| |footprints_dc_zoom|
    =============== ====================
 
+.. rst-class:: caption
+
+   +----------------------------------------------------------------------------------------+
+   | :file:`DistrictofColumbia.geojson` polygons from Microsoft's                           |
+   | `US building footprints dataset <https://github.com/Microsoft/USBuildingFootprints>`__ |
+   | converted into a point set and viewed using :py:meth:`pptk.viewer()`                   |
+   +----------------------------------------------------------------------------------------+
+
 The above procedure can be repeated for other .geojson files in the dataset.
 But note that converting polygons into a point set can become memory intensive.
 By the above procedure, the District of Columbia's 58,329 polygons yields 18,465,292 points.

docs/source/tutorials/viewer/geolife.rst

@@ -4,7 +4,7 @@ Geolife dataset
 ===============
 
 Download the dataset from the
-`project website <https://www.microsoft.com/en-us/research/publication/geolife-gps-trajectory-dataset-user-guide/>`_
+`Geolife <https://www.microsoft.com/en-us/research/publication/geolife-gps-trajectory-dataset-user-guide/>`_ project website
 
 Extract the zip file and observe the following directory structure.
 
@@ -224,15 +224,25 @@ Visualize and color each point based on its altitude.
 .. image:: images/geolife_latlon_default.png
    :align: center
    :width: 900px
-    
+
+.. rst-class:: caption
+
+   +-----------------------------------------------------------------------------+
+   | Full view of `Geolife`_ dataset in lat-lon with points colored by altitude. |
+   +-----------------------------------------------------------------------------+
+
 Since we are interested only in the spatial arrangements of points on the x-y plane,
-Press 5 to toggle to an orthographic view, and press 7 to go to a top-down view.
-Pan the viewpoint by pressing the left mouse button while holding the shift key.
-Double click on a point to recenter the view on the point.
+Press :kbd:`5` to toggle to an orthographic view, and press :kbd:`7` to go to a top-down view.
+Pan the viewpoint by pressing the :kbd:`LMB` while holding the :kbd:`Shift` key.
+Double click with the :kbd:`LMB` on a point to recenter the view on that point.
 And use the mouse wheel to zoom in/out.
 To inspect the attribute of a point, which here is altitude,
-left click the point while holding the Ctrl key.
+left click the point while holding the :kbd:`Ctrl` key.
 Deselect by right clicking anywhere.
+See the :doc:`viewer page <../../viewer>` for the full instructions on using the viewer.
+
+.. note::
+   On Mac, use :kbd:`⌘` instead of :kbd:`Ctrl`
 
 The mapping from per-point attribute value to per-point color is determined automatically based on the range of attribute values.
 But the presence of bad attribute values (e.g. unreasonably large or small altitude values) may result in a poor color mapping,
@@ -255,17 +265,43 @@ Improve the color map by manually setting the mapping domain using :py:meth:`vie
    :align: center
    :width: 900px
 
+.. rst-class:: caption
+
+   +----------------------------------------------------------------------------------------------------+
+   | Full view of `Geolife`_ dataset in lat-lon with an improved color map                              |
+   | (i.e. the greater range of colors allows one to better see the changes in altitude across points). |
+   +----------------------------------------------------------------------------------------------------+
+
 Observe that point coverage is world wide,
 as there are points not just in Beijing but also in faraway cities such as Rome and Seattle.
 Observe also the high altitude points (i.e. airplane trajectories) that connect some of these cities.
 A future release of the pptk viewer may include support for overlaying points on map tiles
 (e.g. `HERE Map Tile <https://developer.here.com/documentation/map-tile/topics/introduction.html>`__)
 for better supporting such visualizations.
 
+.. note::
+   You may notice that you cannot zoom in as close as you would like.
+   This is because there is currently a hardcoded limit on zooming in,
+   which a future release of pptk will fix.
+   This is not an issue when viewing data such as Lidar point clouds that are typically specified in meters,
+   but becomes a limitation when viewing lat-lon points
+   (i.e. two points 1m apart translates to a very small difference in lat/lon).
+   Meanwhile, to zoom in further, consider scaling up the lat-lon values,
+   or converting the points to UTM coordinates, as described in the next section.
+
 Visualize using UTM coordinates
 -------------------------------
 
-Remove points that are outside the UTM zone 50 (Beijing's UTM zone).
+Directly mapping lon-lat to x-y (i.e. x <- lon, y <- lat),
+as in the previous section,
+causes points to appear stretched apart near the north and south poles.
+Alternatively, the `UTM projection <https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>`__
+is able to convert lat-lon coordinates into units of meters
+while only introducing a relatively small amount of stretching/shrinking between points in the same UTM zone.
+In this section, we show how to apply the UTM projection on GPS points in UTM zone 50 (Beijing's UTM zone),
+which we then visualize using :py:meth:`pptk.viewer`.
+
+First remove points that are outside the UTM zone 50.
 This is to remove any invalid points that may later convert to unreasonably large UTM coordinates
 (the dataset contains a point with invalid latitude of 400.17)
 
@@ -296,7 +332,7 @@ Optionally, one may use :py:meth:`viewer.color_map <pptk.viewer.color_map>` to m
     >>> v = pptk.viewer(p[mask_labelled])
     >>> v.attributes(df_50[mask_labelled]['label'])
 
-Again Ctrl + left click on a point to examine its mode of transportation attribute.
+Again :kbd:`Ctrl` + left click on a point to examine its mode of transportation attribute.
 
 .. |geolife_utm| image:: images/geolife_utm.png
    :width: 390px
@@ -310,10 +346,18 @@ Again Ctrl + left click on a point to examine its mode of transportation attribu
    :width: 110px
    :align: middle
 
+.. rst-class:: image-grid
 .. table::
    :widths: 400 400 120
    :align: center
 
    ============= ==================== ================
    |geolife_utm| |geolife_utm_zoomed| |geolife_legend|
    ============= ==================== ================
+
+.. rst-class:: caption
+
+   +------------------------------------------------------------------------------------+
+   | `Geolife`_ GPS points in UTM coordinates visualized using :py:meth:`pptk.viewer`.  |
+   | Points are from around the Beijing area and are colored by mode of transportation. |
+   +------------------------------------------------------------------------------------+

docs/source/tutorials/viewer/mobius.rst

@@ -53,11 +53,19 @@ Visualize.
    :width: 256px
    :align: middle
 
-
+.. rst-class:: image-grid
 .. table::
    :align: center
    :widths: 270 270 270 270
 
    ======== ========== ========== ==========
    |mobius| |mobius_x| |mobius_y| |mobius_z|
    ======== ========== ========== ==========
+
+.. rst-class:: caption
+
+   +---------------------------------------------------------------------------+
+   | Visualization of a mobius strip using :py:meth:`pptk.viewer`.             |
+   | Points are colored by normal directions.                                  |
+   | And the latter three images are views along the -x, +y and -z directions. |
+   +---------------------------------------------------------------------------+

docs/source/tutorials/viewer/saddle.rst

@@ -58,7 +58,7 @@ One can also calculate and visualize additional per-point attributes.
     >>> # set per-point attributes
     >>> v.attributes(P[:, 2], mag, 0.5 * (N + 1))
 
-Toggle between attributes using the [ and ] keys.
+Toggle between attributes using the :kbd:`[` and :kbd:`]` keys.
 
 .. |saddle_z| image:: images/saddle_z.png
    :width: 256px
@@ -72,10 +72,18 @@ Toggle between attributes using the [ and ] keys.
    :width: 256px
    :align: middle
 
+.. rst-class:: image-grid
 .. table::
    :widths: 275 275 275
    :align: center
 
    ========== ============ ==========
    |saddle_z| |saddle_mag| |saddle_n|
    ========== ============ ==========
+
+.. rst-class:: caption
+
+   +------------------------------------------------------------------------------------------------------+
+   | Visualization of :math:`f(x,y)=x^2-y^2`.                                                             |
+   | Points are colored by :math:`f` (left), :math:`|\nabla f|` (middle), and normal directions (right)   |
+   +------------------------------------------------------------------------------------------------------+