README

# Name

fiso

Fast isocontours

Note: due to historical development and laziness, the returned regions are sometimes referred to as "core," "isocontour," "iso," or "fiso."

# Installation

In a directory on your path:

git clone https://github.com/alwinm/fiso.git

OR 

pip install git+https://github.com/alwinm/fiso.git


# Problem

Compute the largest isocontours around minima of n-D fields such that each isocontour only contains 1 local minimum.

# Solution

Given a numpy n-D array, run:
    from fiso import fiso
    isodict, labels = fiso.find(array)

Note:

All cells are given an index, their final position in:

    array.reshape(-1)

To convert from index to coordinates in original n-D array:

    index = numpy.ravel_multi_index(coord,shape)

    coord = numpy.unravel_index(index,shape)


# Isodict

A dictionary of keys,values. Each key is the integer index of the local minimum cell that seeds the isocontour. Each value is a list of integer indices of the cells belonging to the isocontour.

# Labels

A 1-D array of labels corresponding to each cell

-1: Never touched, higher value cells

-2: Processed without assignment (not part of core)

index>-1: Index of cell of the local minimum this cell belongs to. 

# Advanced

    fiso.verbose = False

Turn off debug messages

    fiso.find(array,cut=value)

Optional parameter cut, stops search when cell value = cut

    fiso.find_minima

Change this function to change the initial definition of local minima.

Example:

    from fiso import fiso
    fiso.find_minima = fiso.find_minima_wrap

To be self consistent with the definition of "neighbors" on the boundary, also set:

   fiso.boundary_mode = 'wrap'
   fiso.corner_bool = True

Only occurrence of scipy.ndimage is in find_minima. 

    fiso.boundary_pcn
    fiso.gbi
    fiso.precompute_neighbor

Change functions related to computing indices of neighboring cells for 
more complicated geometries or boundary conditions.

fiso.gbi gets the boundary indices and gives them to fiso.precompute_neighbor, which then uses

fiso.boundary_pcn to set the neighbor indices of the boundary cells.

Default boundary condition:
fiso.boundary_pcn clips the boundary in numpy.ravel_multi_index, so that the neighbors include itself, but do not extend past the box. Since the algorithm only depends on lesser neighbors, a cell can "neighbor" itself without problems. 
fiso.find_minima also clips the box. The default mode of scipy.ndimage.filters.minimum_filter is "reflect". 


# Other Files

fiso.test_fiso contains an example with 4 point particles with smoothing

fiso.tools.contour contains code for showing contours

test.png is the output of test_core.py