numbacs.extraction.ridges
=========================

.. py:module:: numbacs.extraction.ridges




Module Contents
---------------

.. py:function:: ftle_ridge_pts(f, eigvec_max, x, y, sdd_thresh=0.0, percentile=0)

   Compute FTLE ridge points by finding points (with subpixel accuracy) at which:
   ftle > 0 (or percentile of ftle),
   directional derivaitve of ftle (in eigvec_max direction) is 0,
   second directional derivative of ftle (in eigvec_max direction) is greater than
   sdd_thresh (in magnitude).

   :param f: ftle array.
   :type f: np.ndarray, shape = (nx,ny)
   :param eigvec_max: maximum eigenvector of Cauchy Green tensor.
   :type eigvec_max: np.ndarray, shape = (nx,ny,2)
   :param x: array containing x-values.
   :type x: np.ndarray, shape = (nx,)
   :param y: array containing y-values.
   :type y: np.ndarray, shape = (ny,)
   :param sdd_thresh: threshold for second directional derivative, should be at least 0.
                      The default is 0.
   :type sdd_thresh: float, optional
   :param percentile: percentile of ftle used for min allowed value. The default is 0.
   :type percentile: int, optional

   :returns: **r_pts** -- ridge points.
   :rtype: np.ndarray, shape = (ridge_bool.sum(),2)


.. py:function:: ftle_ridges(f, eigvec_max, x, y, sdd_thresh=0.0, percentile=0, min_ridge_pts=3)

   From ridge points from _ftle_ridges, extract connected ridges where
   a connected ridge is defined by a collection of points having continuous
   neighbors that are ridge points.

   :param f: ftle array.
   :type f: np.ndarray, shape = (nx,ny)
   :param eigvec_max: maximum eigenvector of Cauchy Green tensor.
   :type eigvec_max: np.ndarray, shape = (nx,ny,2)
   :param x: array containing x-values.
   :type x: np.ndarray, shape = (nx,)
   :param y: array containing y-values.
   :type y: np.ndarray, shape = (ny,)
   :param sdd_thresh: threshold for second directional derivative, should be at least 0.
                      The default is 0.
   :type sdd_thresh: float, optional
   :param percentile: percentile of ftle used for min allowed value. The default is 0.
   :type percentile: int, optional
   :param min_ridge_pts: minimum points allowed in ridge. The default is 3.
   :type min_ridge_pts: int

   :returns: list containing each connected ridge.
   :rtype: list


.. py:function:: ftle_ordered_ridges(f, eigvec_max, x, y, dist_tol, ep_tan_ang=pi / 4, min_ridge_pts=5, sdd_thresh=0.0, percentile=0, c=1.0)

   Computes ftle ridge points and links points into ridges. After
   this is done, ridges that should be connected are searched for
   and connected if they meet certain critera. Criteria: if two ridges have
   endpoints that are within dist_tol and the angle between the tangent of
   the ridge at the endpoints and vector connecting the endpoints is less
   than ep_tan_ang, connect ridges.

   :param f: ftle array.
   :type f: np.ndarray, shape = (nx,ny)
   :param eigvec_max: maximum eigenvector of Cauchy Green tensor.
   :type eigvec_max: np.ndarray, shape = (nx,ny,2)
   :param x: array containing x-values.
   :type x: np.ndarray, shape = (nx,)
   :param y: array containing y-values.
   :type y: np.ndarray, shape = (ny,)
   :param dist_tol: tolerance used to consider new endpoint for connection.
   :type dist_tol: float
   :param ep_tan_ang: angle used to confirm endpoints are in line. The default is pi/4.
   :type ep_tan_ang: float
   :param min_ridge_pts: minimum points allowed in ridge after endpoints are connected. The default is 5.
   :type min_ridge_pts: int, optional
   :param sdd_thresh: threshold for second directional derivative, should be at least 0.0.
                      The default is 0.
   :type sdd_thresh: float, optional
   :param percentile: percentile of ftle used for min allowed value. The default is 0.
   :type percentile: int, optional
   :param c: scaling for angle portion of metric used in linking algorithm. The default is 1.0.
   :type c: float, optional

   :returns: **ridges** -- list containing connected, ordered ridges.
   :rtype: list