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