1"""
  2
  3# <u>P</u>hoto<u>e</u>lastic <u>P</u>ython <u>E</u>nvironment
  4
  5This is a collection of tools for working with photoelastic particle images, including common analysis methods like particle tracking and community analysis.
  6
  7The vast majority of these methods are either derivative or directly sourced from previous works (see, e.g., [1] for a nice review of techniques); therefore the value of this library, as I see it, is not in novel implementations of methods, but as a single toolbox containing consistent and compatable implementations of a wide selection of tools.
  8
  9## Features
 10
 11- Common analysis techniques (G<sup>2</sup>, D<sup>2</sup><sub>min</sub>, etc.)
 12- Particle position and orientation tracking
 13- Masking and other preprocessing tools
 14- Synthetic photoelastic response generation
 15- Inverse force solving (as in [2])
 16
 17## Installation
 18
 19The library is available on PyPi:
 20```
 21pip install pepe-granular
 22```
 23
 24It can also be installed from the Github repository:
 25
 26```
 27git clone https://github.com/Jfeatherstone/pepe
 28cd pepe
 29pip install .
 30```
 31
 32Theoretically, this should work for any Python >3, but Python 3.7 and 3.11 have been explicitly tested.
 33
 34Dependencies:
 35
 36- [numpy](https://numpy.org/)
 37- [matplotlib](https://matplotlib.org/)
 38- [lmfit](https://lmfit.github.io/lmfit-py/index.html)
 39- [scikit-learn](https://scikit-learn.org/stable/)
 40- [opencv](https://opencv.org/)
 41- [Pillow](https://pillow.readthedocs.io/en/stable/)
 42- [numba](https://numba.pydata.org/)
 43- [tqdm](https://github.com/tqdm/tqdm)
 44
 45These can all be installed (alongside their dependencies) via `pip`:
 46```
 47git clone https://github.com/Jfeatherstone/pepe
 48cd pepe
 49pip install -r requirements.txt
 50```
 51
 52Some of the test notebooks may also make use of the Matlab API to compare against Jonathan Kollmer's code, but this is not required to use any functions in the library itself. Installing the Matlab API requires a local installation of Matlab proper; see [here](https://www.mathworks.com/help/matlab/matlab_external/install-the-matlab-engine-for-python.html) for more information.
 53
 54If you'd rather not install systemwide (say, to run just a simple example), you can also just manually add the package to your path at the top of a Jupyter notebook/python file with (after cloning the repo as above):
 55
 56```
 57import sys
 58sys.path.append('/absolute/path/to/clone/folder/pepe/')
 59```
 60
 61Many of the notebooks in the main directory follow this process, since they are used to test the development versions of the packages.
 62
 63## Usage
 64
 65See the `pepe.examples` submodule for some common uses of the toolbox. Many pseudo-unit-tests can be found in the repo's [`notebooks`](https://github.com/Jfeatherstone/pepe/tree/master/notebooks) folder, which may also help determine how to use a certain function. Note that these latter examples are more made for my own benefit, and won't be as heavily commented as the proper examples.
 66
 67## Further Reading and References
 68
 69[1] Abed Zadeh, A., Barés, J., Brzinski, T. A., Daniels, K. E., Dijksman, J., Docquier, N., Everitt, H. O., Kollmer, J. E., Lantsoght, O., Wang, D., Workamp, M., Zhao, Y., & Zheng, H. (2019). Enlightening force chains: A review of photoelasticimetry in granular matter. Granular Matter, 21(4), 83. https://doi.org/10.1007/s10035-019-0942-2
 70
 71[2] Daniels, K. E., Kollmer, J. E., & Puckett, J. G. (2017). Photoelastic force measurements in granular materials. Review of Scientific Instruments, 88(5), 051808. https://doi.org/10.1063/1.4983049
 72
 73[2a] Jonathan Kollmer's implementation in Matlab: https://github.com/jekollmer/PEGS
 74
 75[2b] Olivier Lantsoght's implementation in Python: https://git.immc.ucl.ac.be/olantsoght/pegs_py
 76
 77[3] Photoelastic methods wiki. https://git-xen.lmgc.univ-montp2.fr/PhotoElasticity/Main/-/wikis/home
 78"""
 79
 80__version__ = '1.2.9'
 81__author__ = 'Jack Featherstone'
 82__credits__ = 'North Carolina State University; Okinawa Institute of Science and Technology' 
 83
 84# The below code was mostly copied from scipy
 85
 86import importlib as _importlib
 87
 88submodules = [
 89    'analysis',
 90    'auto',
 91    'preprocess',
 92    'simulate',
 93    'topology',
 94    'tracking',
 95    'utils',
 96    'visualize',
 97]
 98
 99__all__ = submodules
100
101
102def __dir__():
103    return __all__
104
105
106def __getattr__(name):
107    if name in submodules:
108        return _importlib.import_module(f'pepe.{name}')
109    else:
110        try:
111            return globals()[name]
112        except KeyError:
113            raise AttributeError(
114                f"Module 'pepe' has no attribute '{name}'"
115            )