Readme.md 2.96 KB
Newer Older
Olivier Lantsoght's avatar
Olivier Lantsoght committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
# PEGS for Python (PEGSpy?)

This computes the contacts forces inside a granular media from a picture of the photoelastic signal.  
Based on the Matlab implementation of [J. Kollmer](https://github.com/jekollmer/PEGS).  
Theoritical background provided in '_Photoelastic force measurements in granular materials_', by Daniels, K.E., Kollmer, J.E., Puckett, J.G., Review of Scientific Instruments 2017 88:5

## Implementation

All needed functions are defined in the `PEGS.py` file.  
The computation of the stress field is done by a C library, see _StressEngineC/Readme.md_ for compilation.


## Requirements

Tested on Ubuntu 16.04:
 * Python (tested with v2.7.12)
     * Numpy (tested with v1.11.0)
     * Scipy (tested with v1.1.0)
     * Cython (tested with v0.23.4 & v0.28.3)
     * Matplotlib (tested with v2.2.2)
     * OpenCV (tested with v2.4.9.1) `sudo apt-get install python-opencv`
     * Scikit-image (tested with v0.14.0) `sudo apt-get install scikit-image` (may be outdated)
 * Everythink needed to compile C code (simple way : ```sudo apt-get install build-essential```)

## Workflow

 1. Run some part of the original PEGS:
    * Detect grains with the PEGS dedicated script: _PeGSDiskPrep.m_
    * Optionnaly, run a first forces identification : _PeGSDiskSolve.m_
    * Both files have been modified
    * Required:
        * The matlab strucure name is `pres` (like in the output of originale _PeGSDiskSolve_)
        * The following fields of the particles are required (created only int the _PeGSDiskSolve_) but can contains dummy values:
            * forces
            * alphas
            * fitError
            * synthImg
        * The field `gradientImg` is new and containds the gradient image of the particle
 1. Load the resulting _.mat_ file in python : _load\_matlab(options...)_ function
 1. Run a first estimation considering each particle isolated: _forces\_initial\_guess(options...)_ function
 1. Run the force propagation to adjacent particles: _forces\_propagation(options...)_ function
 1. In last hope try a brute force estimation : _forces\_brute\_force(options...)_ function
      * This function is slow and not efficient (few or none force found)
      * A genetic algorithm could be used, but they are far more slower and convergence is not garantee.

 Python steps are illustrated in the _Example.py_ script and use the files in the _Example/_ subfolder.

## Remarks

 1. Pickle file size could be decreased by specifying the parameter _protocol=2_ in the _pickle.dump_ function.

## Sources
Original works from Karen E. Daniels and James G. Puckett, "_Photoelastic force measurements in granular media_" Review of Scientific Instrument, 88 051808 (2017)
Main differences with the source:
 * Programming language.
 * The estimated forces are propagated from particle to the adjacents.
 * Possibility to choose between darkfield or brightfield circular polariscope.
 * The computed photoelastic signal is compared to the picture by the SSIM (structural similarity index) insted of the MSE