Merge pull request #40 from tldr-group/development

merge Development onto main

.github/workflows/tests.yaml

@@ -0,0 +1,40 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python application
+
+on:
+  push:
+    branches: [ "cleanup" ]
+  pull_request:
+    branches: [ "main",  ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install -e .
+    # commented out for now until refactoring of experiments done
+    #- name: Lint with flake8
+    #  run: |
+    #    # stop the build if there are Python syntax errors or undefined names
+    #    flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+    #    # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+    #    flake8 . --count --exit-zero --max-complexity=15 --max-line-length=127 --statistics --ignore=E203
+    - name: Test with unittest
+      run: |
+        python tests/tests.py

.gitignore

@@ -8,7 +8,16 @@ fig2 copy.py
 *tif
 *info
 *mat
-*.json
 *.pdf
 *.png
-*.npy
+*.npy
+
+.vscode
+frontend/node_modules
+frontend/dist
+*.kra
+deploy*/
+deploy.sh
+deploy.zip
+
+tests/tmp.py

CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use this model, please cite it as below."
+authors:
+  - name: Amir Dahari
+    orcid: 0000-0003-0142-8597
+  - name: Ronan Docherty
+    orcid: 0000-0002-7332-0924
+  - name: Samuel J. Cooper
+    orcid: 0000-0003-4055-6903
+title: "Predicting Microstructural Representativity from a Single Image"
+doi: ARXIV_DOI
+url: "https://github.com/tldr-group/Representativity"
+preferred-citation:
+  type: article
+  authors:
+  - name: Amir Dahari
+    orcid: 0000-0003-0142-8597
+  - name: Ronan Docherty
+    orcid: 0000-0002-7332-0924
+  - name: Samuel J. Cooper
+    orcid: 0000-0003-4055-6903
+  doi: ARXIV_DOI
+  journal: "arXiV preprint"
+  month: 8
+  title: "Predicting Microstructural Representativity from a Single Image"
+  year: 2024

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, tldr group
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,7 @@
+include requirements.txt
+include LICENSE
+include README.md
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * *old*

README.md

@@ -0,0 +1,93 @@
+# Representativity
+
+![Tests](https://github.com/tldr-group/Representativity/actions/workflows/tests.yml/badge.svg)
+
+[Try it out!](https://www.imagerep.io/)
+
+You take a micrograph of a material. You segment it, and measure the phase fractions. How sure are you that the phase fraction of the whole material is close to your measurements?  
+Here we define 'representativity' as [1]
+> A microstructure is $(c, d)$-property representative if the measured value of the microstructural property deviates by no more than $d\%$ from the bulk material property, with at least $c\%$ confidence. For example, if $(c,d)=(95,3)$, and the property is phase-fraction, this means we can be $95\%$ confident that the measured phase-fraction is within $3\%$ of the bulk material phase-fraction. 
+
+We introduce the 'ImageRep' model for performing fast phase-fraction representativity estimation from a single microstructural image. This is achieved by estimating the Two-Point Correlation (TPC) function of the image via the FFT. From the TPC the 'Integral Range' can be directly determined - the Integral Range has previously been determined using (slow) statistical methods. We then represent the image as binary squares of length 'Integral Range' which are samples from a Bernoulli distribution with a probability determined by the measured phase fraction. From this we can establish the uncertainty in the phase fraction in the image to a given confidence, **and** the image size that would be needed to meet a given target uncertainty.
+
+If you use this model in your research, [please cite us](CITATION.cff).
+
+## Usage:
+
+This model can be used as python package - see [`example.ipynb`](example.ipynb) or via the [website (imagerep.io)](https://www.imagerep.io/).
+
+<p align="center">
+    <img src="https://sambasegment.blob.core.windows.net/resources/repr_repo_v2.gif">
+</p>
+
+NB: the website may run out of memory for large volumes (>1000x1000x1000) - if this happens run the model locally or contact us
+
+## Limitations:
+- **This is not the only source of uncertainty!** Other sources *i.e,* segmentation uncertainty, also contribute and may be larger
+- For multi-phase materials, this model estimates the uncertainty in phase-fraction of a single (chosen) phase, counting all the others as a single phase (*i.e,* a binary microstructure)
+- Not validated for for images smaller than 200x200 or 200x200x200
+- Not validated for large integral ranges/features sizes (>70 px) 
+- Not designed for periodic structures
+- 'Length needed for target uncertainty' is an intentionally conservative estimate - retry when you have measured the larger sample to see a more accurate estimate of that uncertainty
+
+## Local Installation Instructions
+
+These instructions are for installing and running the model locally. They assume a UNIX enviroment (mac or linux), but adapting for Windows is straightforward. Note you will need 2 terminals, one for the frontend local server and one for the backend local server.
+
+### Preliminaries
+
+Install [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (ideally via a manager like [nvm](https://github.com/nvm-sh/nvm)) if you want to run the website. Clone this repo and change directory:
+```
+git clone https://github.com/tldr-group/Representativity && cd Representativity
+```
+
+
+### Install & run the backend
+
+0. Setup a [virtual environment in Python](https://docs.python.org/3/library/venv.html) and activate it (not necessary but recommended)
+1. Install the repo as a local package:
+
+```
+pip install -e .
+```
+
+**NOTE: this is all you need to do if you wish to use the model via the python package.** To run the website locally, follow the rest of the instructions.
+
+2. With your virtual environment activated, and inside the `representativity/` directory, run
+
+```
+python -m flask --app server run
+```
+
+The server should now be running on `http://127.0.0.1:500` and listening for requests!
+
+
+3. If you want to reproduce (all) the figures, you'll need `pytorch` and some additional dependencies. It may be worth using [conda](https://www.anaconda.com/) to install `pytorch` as this will interact correctly with your GPU. Run
+```
+pip install -r requirements_dev.txt
+```
+
+
+### Install & run the frontend
+
+0. Install the JS libraries needed to build and run the frontend. Install Yarn (and npm first if needed)
+
+```
+npm install --g yarn
+```
+
+1. Build and run:
+
+```
+yarn && yarn start
+```
+
+2. Navigate to [`http://localhost:8080/`](http://localhost:8080/) (the browser should do this automatically).
+
+## Testing Instructions
+
+1. Run (with your virtual enviroment activated!)
+
+```
+python tests/tests.py
+```

frontend/configs/webpack/common.js

@@ -0,0 +1,76 @@
+// From Meta SAM demo
+const { resolve } = require("path");
+const HtmlWebpackPlugin = require("html-webpack-plugin");
+const FriendlyErrorsWebpackPlugin = require("friendly-errors-webpack-plugin");
+const CopyPlugin = require("copy-webpack-plugin");
+const webpack = require("webpack");
+
+module.exports = {
+  entry: "./src/index.tsx",
+  resolve: {
+    extensions: [".js", ".jsx", ".ts", ".tsx"],
+  },
+  output: {
+    path: resolve(__dirname, "dist"),
+    publicPath: "/",
+  },
+  module: {
+    rules: [
+      {
+        test: /\.mjs$/,
+        include: /node_modules/,
+        type: "javascript/auto",
+        resolve: {
+          fullySpecified: false,
+        },
+      },
+      {
+        test: [/\.jsx?$/, /\.tsx?$/],
+        use: ["ts-loader"],
+        exclude: /node_modules/,
+      },
+      {
+        test: /\.css$/,
+        use: ["style-loader", "css-loader"],
+      },
+      {
+        test: /\.(scss|sass)$/,
+        use: ["style-loader", "css-loader", "postcss-loader"],
+      },
+      {
+        test: /\.(jpe?g|png|gif|svg)$/i,
+        use: [
+          "file-loader?hash=sha512&digest=hex&name=img/[contenthash].[ext]",
+          "image-webpack-loader?bypassOnDebug&optipng.optimizationLevel=7&gifsicle.interlaced=false",
+        ],
+      },
+      {
+        test: /\.(woff|woff2|ttf)$/,
+        use: {
+          loader: "url-loader",
+        },
+      },
+    ],
+  },
+  plugins: [
+    new CopyPlugin({
+      patterns: [
+        {
+          from: "src/assets",
+          to: "assets",
+        }
+      ]
+    }),
+    new HtmlWebpackPlugin({
+      template: "./src/assets/index.html",
+      favicon: "./src/assets/favicon.png"
+    }),
+    new FriendlyErrorsWebpackPlugin(),
+    new webpack.ProvidePlugin({
+      process: "process/browser",
+    }),
+  ],
+  experiments: {
+    topLevelAwait: true
+  }
+};