Merge pull request #2 from espdev/refactoring-and-docs

Refactoring and docs

.travis.yml

@@ -9,7 +9,8 @@ matrix:
       env: TOXENV=py37-pytest-coverage
     - python: "3.8"
       env: TOXENV=py38-pytest
-
+    - python: "3.7"
+      env: TOXENV=docs
     - python: "3.7"
       env: TOXENV=flake8
 

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.2.0 (27.05.2020)
+
+- Refactoring the package with changing some low-level API
+- Add documentation
+
 ## v0.1.1
 
 - Fix links

README.md

@@ -61,8 +61,6 @@ plt.show()
 
 The full documentation can be found at [scikit-mpe.readthedocs.io](https://scikit-mpe.readthedocs.io/en/latest)
 
-(The documentation is being written)
-
 ## References
 
 - [Fast Marching Methods: A boundary value formulation](https://math.berkeley.edu/~sethian/2006/Explanations/fast_marching_explain.html)

docs/api.rst

@@ -0,0 +1,97 @@
+.. _api:
+
+*************
+API Reference
+*************
+
+.. currentmodule:: skmpe
+
+API Summary
+===========
+
+.. autosummary::
+    :nosignatures:
+
+    InitialInfo
+    PathInfo
+    PathInfoResult
+
+    TravelTimeOrder
+    OdeSolverMethod
+    Parameters
+    parameters
+    default_parameters
+
+    MPEError
+    ComputeTravelTimeError
+    PathExtractionError
+    EndPointNotReachedError
+
+    PathExtractionResult
+    MinimalPathExtractor
+    mpe
+
+|
+
+Data and Models
+===============
+
+.. autoclass:: InitialInfo
+    :members:
+
+.. autoclass:: PathInfo
+    :show-inheritance:
+
+.. autoclass:: PathInfoResult
+    :show-inheritance:
+
+Parameters
+==========
+
+.. autoclass:: TravelTimeOrder
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: OdeSolverMethod
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: Parameters
+    :members:
+    :undoc-members:
+
+.. autofunction:: parameters
+.. autofunction:: default_parameters
+
+Exceptions
+==========
+
+.. autoclass:: MPEError
+    :show-inheritance:
+
+.. autoclass:: ComputeTravelTimeError
+    :show-inheritance:
+
+.. autoclass:: PathExtractionError
+    :members:
+    :show-inheritance:
+
+.. autoclass:: EndPointNotReachedError
+    :members:
+    :inherited-members: PathExtractionError
+    :exclude-members: with_traceback
+    :show-inheritance:
+
+Path Extraction
+===============
+
+.. autoclass:: PathExtractionResult
+    :show-inheritance:
+
+.. autoclass:: MinimalPathExtractor
+    :members:
+    :special-members: __call__
+
+.. autofunction:: mpe

docs/conf.py

@@ -65,7 +65,6 @@ def get_author():
 plot_apply_rcparams = True
 plot_rcparams = {
     'figure.autolayout': 'True',
-    'figure.figsize': '5, 3.5',
     'savefig.bbox': 'tight',
     'savefig.facecolor': "None",
 }

docs/examples.rst

@@ -0,0 +1,77 @@
+.. _examples:
+
+********
+Examples
+********
+
+Retina Vessels
+==============
+
+Extracting the minimal path through the retina vessels with additional way points.
+
+.. plot::
+
+    from skimage.data import retina
+    from skimage.color import rgb2gray
+    from skimage.transform import rescale
+    from skimage.filters import sato
+
+    from skmpe import mpe
+
+    image = rescale(rgb2gray(retina()), 0.5)
+    speed_image = sato(image)
+
+    start_point = (76, 388)
+    end_point = (611, 442)
+    way_points = [(330, 98), (554, 203)]
+
+    path_info = mpe(speed_image, start_point, end_point, way_points)
+
+    px, py = path_info.path[:, 1], path_info.path[:, 0]
+
+    plt.imshow(image, cmap='gray')
+    plt.plot(px, py, '-r')
+    plt.plot(*start_point[::-1], 'oy')
+    plt.plot(*end_point[::-1], 'og')
+    for p in way_points:
+        plt.plot(*p[::-1], 'ob')
+    plt.axis('off')
+
+
+Bricks
+======
+
+Extracting the shortest paths through "bricks" image.
+
+.. plot::
+
+    from skimage.data import brick
+    from skimage.transform import rescale
+    from skimage.exposure import rescale_intensity, adjust_sigmoid
+
+    from skmpe import parameters, mpe
+
+    image = rescale(brick(), 0.5)
+    speed_image = rescale_intensity(
+        adjust_sigmoid(image, cutoff=0.5, gain=10).astype(np.float_), out_range=(0., 1.))
+
+    start_point = (44, 13)
+    end_point = (233, 230)
+    way_points = [(211, 59), (17, 164)]
+
+    with parameters(integrate_max_step=1.0):
+        path_info1 = mpe(speed_image, start_point, end_point)
+        path_info2 = mpe(speed_image, start_point, end_point, way_points)
+
+    px1, py1 = path_info1.path[:, 1], path_info1.path[:, 0]
+    px2, py2 = path_info2.path[:, 1], path_info2.path[:, 0]
+
+    plt.imshow(image, cmap='gray')
+    plt.plot(px1, py1, '-r', linewidth=2)
+    plt.plot(px2, py2, '--r', linewidth=2)
+
+    plt.plot(*start_point[::-1], 'oy')
+    plt.plot(*end_point[::-1], 'og')
+    for p in way_points:
+        plt.plot(*p[::-1], 'ob')
+    plt.axis('off')

docs/index.rst

@@ -6,11 +6,47 @@ scikit-mpe
 **scikit-mpe** is a package for extracting a minimal path in n-dimensional Euclidean space (on regular Cartesian grids)
 using `the fast marching method <https://math.berkeley.edu/~sethian/2006/Explanations/fast_marching_explain.html>`_.
 
+The package can be used in various engineering and image processing tasks.
+For example, it can be used for extracting paths through tubular structures on 2-d and 3-d images,
+or shortest paths on terrain maps.
+
+Installing
+----------
+
+Python 3.6 or above is supported. You can install the package using pip::
+
+    pip install -U scikit-mpe
+
+
+A Simple Example
+----------------
+
+Here is the simple example: how to extract 2-d minimal path using some speed data.
+
+.. code-block:: python
+    :linenos:
+
+    from skmpe import mpe
+
+    # Somehow speed data is calculating
+    speed_data = get_speed_data()
+
+    # Extracting minimal path from the starting point to the ending point
+    path_info = mpe(speed_data, start_point=(10, 20), end_point=(120, 45))
+
+    # Getting the path data in numpy ndarray
+    path = path_info.path
+
+
+Contents
+--------
 
 .. toctree::
     :maxdepth: 2
-    :caption: Contents:
 
+    tutorial
+    examples
+    api
     changelog