#!/usr/bin/env python
# coding: utf-8

# # The HFM library - A fast marching solver with adaptive stencils
# 
# # Volume : Fast Marching Methods

# The HamiltonFastMarching (HFM) software is a C++ library designed to find globally optimal paths for a variety of problems. The [source](https://github.com/mirebeau/HamiltonFastMarching) features a number of examples in addition to those presented in the following notebooks, in the Python®, Matlab®, and Mathematica® languages.
# 
# This series of python notebooks are intended as documentation for the [HamiltonFastMarching (HFM) library](https://github.com/mirebeau/HamiltonFastMarching), which also has interfaces to the Matlab® and Mathematica® languages. 
# They are also a companion for the manuscript :
# * Jean-Marie Mirebeau, Jorg Portegies, "Hamiltonian Fast Marching: A numerical solver for anisotropic and non-holonomic eikonal PDEs", 2019, IPOL [(link)](https://hal.archives-ouvertes.fr/hal-01778322)
#     
# 
# Latest version of this summary [(view online)](http://nbviewer.jupyter.org/urls/rawgithub.com/Mirebeau/HFM_Python_Notebooks/master/Summary.ipynb)
# 
# 
# <!---
# * [Metrics arising from seismology](http://nbviewer.jupyter.org/urls/rawgithub.com/Mirebeau/HFM_Python_Notebooks/master/A8_Seismic.ipynb)
# -->
# 
# 
# ## Notes on calling the Hamilton Fast Marching (HFM) library
# 
# There are two ways to install the HFM library.
# * **Use the anaconda package.** 
# A conda environnement containing the packages required to execute all the present notebooks is provided, see the installation instructions in the `README.md` file in the root directory. Thanks to Hugo Leclerc for setting up this solution (and Loic Gouarin on a previous version).
# Alternatively, should you want to install the HFM library alone, type the following in a console:
# ```console
# conda install -c agd-lbr hfm
# ```
# 
# * **Compile from the sources.** You need to download a compile the HamiltonFastMarching library, from the sources : 
# [HamiltonFastMarching](https://github.com/mirebeau/HamiltonFastMarching)
#  and [JMM_CPPLibs](https://github.com/Mirebeau/JMM_CPPLibs).
# Compilation is routinely tested on MacOs, Windows, and Linux. A recent compiler is needed (C++17).
# In addition, you will need to set the path to the HFM library in file `FileHFM_binary_dir.txt`
# 
# 
# 
# 
# <!---
# There are two ways to call the HFM library from python code.
# 
# * (Simple, but non-scalable and a bit ugly)
# Input and output are based on files written on the disk. 
# 
# * (Elegant and fast, when available)
# Input and output uses a direct link based on boost-python.  
# -->
# 
# <!---
# In this series of notebooks, we use the first way.
# Indeed, in my experience (on an Apple&reg; computer), correctly linking boost-python can be non-trivial. This is mainly due to the presence of multiple python distributions on the system.
# -->

# **Github repository** to run and modify the examples on your computer.
# [AdaptiveGridDiscretizations](https://github.com/Mirebeau/AdaptiveGridDiscretizations)
# 
# 
# # Table of contents
# [**Main summary**](../Summary.ipynb), including the other volumes of this work. 
# ### A. Isotropic and anisotropic metrics
# 
#  * I. [Classical isotropic fast marching](Isotropic.ipynb)
#   1. Description of the problem
#   2. Calling the solver
#   3. Displaying the results.
#   4. Introducing obstacles, and position dependent speed
#   5. Termination criteria
#   6. Side products of the fast marching algorithm
#   7. Using a time dependent speed function
#   8. Three dimensional fast marching
#   9. A variant : diagonal metrics
# 
# 
#  * II. [Riemannian metrics](Riemannian.ipynb)
#   1. Two dimensional examples
#   2. Three dimensional examples
#   3. Sensitivity analysis
#   4. Voronoi regions
#   5. Contruction of the Riemannian tensors
# 
# 
#  * III. [Rander metrics](Rander.ipynb)
#   1. Zermelo's navigation problem
#   2. The Chan-Vese model
# 
# 
#  * IV. [Asymmetric quadratic metrics](AsymmetricQuadratic.ipynb)
#   1. Case of a constant metric
#   2. Application to vessel segmentation
#   3. Asymmetric Rander metrics
# 
# 
# ### B. Non holonomic metrics and curvature penalization
# 
#  * I. [Curvature penalized planar paths.](Curvature.ipynb)
#   1. Defining the domain
#   2. Specifying the metric
#   3. Calling the software, and displaying the results.
#   4. Comparison of the different models.
#   5. Varying the cost function
#   6. Generalized models with non-uniform curvature penalization
#   7. Additional functionality
# 
# 
#  * II. [Five dimensional Reeds-Shepp models.](Curvature3.ipynb)
#   1. The orientation space
#   2. Two paths to Rome
#   3. A motion planning example
# 
# 
#  * III. [Customized curvature penalization](DeviationHorizontality.ipynb)
#   1. Re-creating the Reeds-Shepp model.
#   2. A synthetic tubular segmentation problem
#   3. Tubular structure extraction - cost based methods
#   4. Data-driven customization of the Reeds-Shepp model
#   5. Other curvature penalization models
# 
# 
#  * IV. [Vehicles with trailers](Trailers.ipynb)
#   1. Mathematical framework
#   2. One trailer
#   3. Two trailers
# 
# 
# ### C. Algorithmic enhancements to the fast marching method
# 
#  * I. [Geodesic computation](Geodesics.ipynb)
#   1. Theoretical tools
#   2. Isotropic metrics and the Brachistochrone problem
#   3. Riemannian metrics, and the fastest slide on a landscape
# 
# 
#  * II. [Achieving high accuracy](HighAccuracy.ipynb)
#   1. Poincare model of the hyperbolic plane
#   2. A Riemannian metric
#   3. A Rander metric
#   4. Metric arising from seismology.
#   5. Additional discussion
# 
# 
#  * III. [Sensitivity analysis](Sensitivity.ipynb)
#   1. Setting up the problem
#   2. Forward differentiation
#   3. Reverse differentiation
#   4. Gradient of the value function
#   5. An optimization problem : finding the cost function which maximizes distance
#   6. Sensitivity at multiple points, possibly weighted
# 
# 
#  * IV. [Sensitivity in semi-Lagrangian schemes](SensitivitySL.ipynb)
#   1. Forward differentiation
#   2. Reverse differentiation
#   3. Geodesic flow and gradient of the value function
# 
# 
#  * V. [Accurate distance from a boundary](DistanceFromBoundary.ipynb)
#   1. Local approximate geodesic distance to a piecewise smooth boundary
#   2. Validation with constant metrics
#   3. An example with a non-constant metric
# 
# 
# ### D. Motion planning
# 
#  * I. [Closed path through a keypoint](ClosedPaths.ipynb)
#   1. With obstacles
#   2. Evading surveillance
#   3 Optimization of the surveillance system
# 
# 
#  * II. [The Dubins-Zermelo problem](DubinsZermelo.ipynb)
#   1. Dubins' problem
#   2. Adding a constant drift
#   3. Non-constant drift
# 
# 
#  * III. [Optimal routing of a boat](BoatRouting.ipynb)
#   1. Constant medium
#   2. Space-varying medium
# 
# 
#  * IV. [Radar detection models](RadarModels.ipynb)
#   1. Position dependent detection
#   2. Orientation dependent cost
# 
# 
#  * V. [Minimal paths with curvature penalization and obstacles (Interactive)](Interactive_CurvatureObstacles.ipynb)
#   1. Demo
# 
# 
# ### E. Seismology and crystallography
# 
#  * I. [Metrics defined by a Hooke tensor](Seismic.ipynb)
#   1. A constant medium, with tilted and anelliptic anisotropy
#   2. Varying medium
#   3. Taking into account the topography
#   4. Testing reproduction
#   5. Three dimensional example
# 
# 
#  * II. [Tilted transversally isotropic metrics](TTI.ipynb)
#   1. Two dimensions
#   2 Three dimensions
#   3 Building a model from an array of Thomsen parameters
# 
# 
# ### F. Image models and segmentation
# 
#  * I. [A mathematical model for Poggendorff's visual illusions](Illusion.ipynb)
#   1. Sub-Riemannian extrapolation
#   2. First Poggendorff illusion
#   3. Poggendorff's round illusion
# 
# 
#  * II. [Tubular structure segmentation](Tubular.ipynb)
#   1. Preliminary image filtering
#   2. Isotropic models
#   3. Curvature penalized models
#   4. Other models
# 
# 
#  * III. [Geodesic models with convexity shape prior (Interactive)](Interactive_ConvexRegionSegmentation.ipynb)
#   1. Preliminary : Convex geodesics in free space
#   2. Image pre-processing
#   3. Geometric input
#   4. Run the eikonal solver
# 
# 
# ### G. Other applications
# 
#  * I. [Fisher-Rao distances (statistics)](FisherRao.ipynb)
#   1. The univariate Gaussian
# 
# 
#  * II. [The medial axis, and an application to curve denoising](MedialAxis.ipynb)
#   1. Computation of the medial axis
#   2. Planar curve extraction and smoothing
#   3. Three dimensional curves
# 
# 
# ### H. Custom optimal control models, discrete states
# 
#  * I. [Dubins car with a state and additional controls](DubinsState.ipynb)
#   1. One dimensional models
#   2. The Dubins model
#   3. Staying away from the walls
# 
# 
#  * II. [Elastica variants](ElasticaVariants.ipynb)
#   1. Re-implementing the Euler elastica model
#   2. Bounded curvature
#   3. Introducing states
#   4. Penalization of curvature variation

# In[1]:


#import sys; sys.path.append("..") # Allow imports from parent directory
#from Miscellaneous import TocTools; print(TocTools.displayTOCs('FMM'))


# In[2]:


#%%javascript
#IPython.OutputArea.auto_scroll_threshold = 9999;