update docs tutorial

docs/tutorial.rst

@@ -4,6 +4,8 @@
 Tutorial
 ********
 
+.. currentmodule:: skmpe
+
 Overview
 ========
 
@@ -23,7 +25,7 @@ The package uses `the fast marching method <https://scikit-fmm.readthedocs.io/en
 `ODE solver <https://docs.scipy.org/doc/scipy/reference/integrate.html#solving-initial-value-problems-for-ode-systems>`_ for extracting minimal paths.
 
 Algorithm
-=========
+---------
 
 The algorithm contains two main steps:
 
@@ -112,3 +114,154 @@ using **scikit-mpe** package and plot it. Also we can plot travel time contours.
 
 Advanced Usage
 ==============
+
+Initial Data
+------------
+
+The initial data is storing and validating in :class:`InitialInfo` class which inherited from
+`Pydantic BaseModel <https://pydantic-docs.helpmanual.io/usage/models/#basic-model-usage>`_. The class checks speed data and points dimensions, boundaries and values.
+
+Therefore, we cannot set an invalid data:
+
+.. code-block:: python
+
+    import numpy as np
+    from skmpe import InitialInfo
+
+    speed_data = np.zeros((100, 200))
+    start_point = (10, 300)  # out of bounds
+    end_point = (50, 60)
+
+    init_data = InitialInfo(
+        speed_data=speed_data,
+        start_point=start_point,
+        end_point=end_point,
+    )
+
+The code above is raising an exception::
+
+    Traceback (most recent call last):
+      ...
+        raise validation_error
+    pydantic.error_wrappers.ValidationError: 1 validation error for InitialInfo
+    start_point
+      'start_point' (10, 300) coordinate 1 is out of 'speed_data' bounds [0, 200). (type=value_error)
+
+
+We can use :class:`InitialInfo` explicity in :func:`mpe` function:
+
+.. code-block:: python
+
+    from skmpe import InitialInfo, mpe
+
+    init_data = InitialInfo(...)
+    result = mpe(init_data)
+
+
+Also in most cases we can use the second :func:`mpe` function signature without using `InitialInfo` explicity:
+
+.. code-block:: python
+
+    from skmpe import mpe
+
+    ...
+
+    result = mpe(speed_data, start_point, end_point)
+
+
+Parameters
+----------
+
+The algorithm parameters are storing and validating in :class:`Parameters` class.
+We can use this class directly, or we can use :func:`parameters` context manager for manage parameters.
+
+Also :func:`default_parameters` function returns the instance with default parameters:
+
+.. code-block:: python
+
+    >>> from skmpe import default_parameters
+    >>> print(default_parameters())
+
+    travel_time_spacing=1.0
+    travel_time_order=<TravelTimeOrder.first: 1>
+    travel_time_cache=False
+    ode_solver_method=<OdeSolverMethod.RK45: 'RK45'>
+    integrate_time_bound=10000.0
+    integrate_min_step=0.0
+    integrate_max_step=4.0
+    dist_tol=0.001
+    max_small_dist_steps=100
+
+
+Important Parameters
+~~~~~~~~~~~~~~~~~~~~
+
+The following parameters may be important in some cases:
+
+    - **travel_time_order** -- the order of the fast-marching computation method.
+      2 is more accurate, but it is slower. By default it is 1. Use :class:`TravelTimeOrder` enum for
+      this parameter
+    - **travel_time_cache** -- if we set way points we can use cached travel time.
+      For example if we set one way point we can compute travel time once for this way point as
+      source point. By default it is False.
+    - **ode_solver_method** -- we can use some ODE methods for extracting path.
+      Some methods may be work faster or more accurate on some speed data.
+      Use :class:`OdeSolverMethod` enum for this parameter. By default it is Runge-Kutta 4/5 (`RK45`)
+    - **integrate_time_bound** -- if we want to extract a long path we need to set a greater
+      value for time bound. By default it is 10000
+    - **dist_tol** -- distance tolerance between steps for control path evolution.
+      By default it is 0.001
+    - **max_small_dist_steps** -- the maximum number of small distance steps while path evolution.
+      Too small steps will be ignore N-times by this parameter.
+
+Using Parameters
+~~~~~~~~~~~~~~~~
+
+We can set the custom parameter values by :class:`Parameters` class or :func:`parameters` context manager.
+
+Using class:
+
+.. code-block:: python
+
+    from skmpe import Parameters, mpe
+
+    my_parameters = Parameters(travel_time_cache=True, travel_time_order=1)
+    result = mpe(..., parameters=my_parameters)
+
+
+Using context manager:
+
+.. code-block:: python
+
+    from skmpe import parameters, mpe
+
+    with parameters(travel_time_cache=True, travel_time_order=1):
+        # the custom parameters will be used automatically
+        result = mpe(...)
+
+
+Results
+-------
+
+The whole extracted path results are storing in :class:`PathInfoResult` class (named tuple).
+The instance of this class is returning from :func:`mpe` function. The pieces of the path
+(in the case with way points) are storing in :class:`PathInfo` class.
+
+:class:`PathInfoResult` object contains:
+
+    - **path** -- the whole extracted path in numpy array MxN where M is the number of points and N is dimension
+    - **pieces** -- the list of extracted path pieces between start/end or way points in `PathInfo` instances.
+      If we do not use way points, **pieces** list will be contain one piece.
+
+:class:`PathInfo` object contains:
+
+    - **path** -- the extracted path piece in numpy array MxN where M is the number of points and N is dimension
+    - **start_point** -- the starting point
+    - **end_point** -- the ending point
+    - **travel_time** -- the computed travel time data for given speed data
+    - **extraction_result** -- the raw extraction result in :class:`PathExtractionResult` instance.
+      This data is returning from :class:`MinimalPathExtractor` class (low-level API). The data
+      contains additional info about extracted path and info about extracting process.
+      This data may be useful for debugging.
+    - **reversed** -- The flag indicates that the path piece is reversed.
+      This is relevant when using ``travel_time_cache == True`` parameter.