Added demo!

.gitignore

@@ -11,3 +11,5 @@ desktop.ini
 .DS_Store
 
 .DS
+
+.ipynb_checkpoints*

demos/Pyramid Notebook Example.ipynb

+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Installation:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**1) Install [Anaconda](https://www.anaconda.com/download/)**!\n",
+    "\n",
+    "And (optional) an IDE of your choice (recommended: [PyCharm](https://www.jetbrains.com/pycharm/download/#section=windows) Community Edition)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**2) Clone or download the `pyramid` package!**\n",
+    "\n",
+    "<img src=\"images/pyramid-gitlab.png\">\n",
+    "\n",
+    "Can be found [here](https://iffgit.fz-juelich.de/caron/pyramid), if you have access (ask me!)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**3) Clone or download the `jutil` package!**\n",
+    "\n",
+    "<img src=\"images/jutil-gitlab.png\">\n",
+    "\n",
+    "Can be found [here](https://iffgit.fz-juelich.de/unger/jutil), if you have access (ask me or Jörn!)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**4) Create an environment for pyramid to work in, using the `environment.yml` file in the `pyramid` package by using:**\n",
+    "\n",
+    "`conda env create`\n",
+    "\n",
+    "in a terminal in the folder containing `pyramid`. Tested on Windows, but should also work on Mac/Linux.\n",
+    "\n",
+    "<img src=\"images/environment.png\">"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**5) Activate environment by using:**\n",
+    "\n",
+    "Windows:     `activate pyramid`\n",
+    "\n",
+    "Mac/Linux:   `source activate pyramid`\n",
+    "\n",
+    "Test if the correct environment is active!\n",
+    "\n",
+    "<img src=\"images/activate.png\">\n",
+    "\n",
+    "Deactivate by using:\n",
+    "\n",
+    "Windows:     `deactivate`\n",
+    "\n",
+    "Mac/Linux:   `source deactivate`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**6) Install `jutil` into environment by using **\n",
+    "\n",
+    "`python setup.py install`\n",
+    "\n",
+    "in the folder containing `jutil`.\n",
+    "\n",
+    "Make sure to use the correct python distribution (you can check the currently used one with `which python`). If this does not show the one in your newly created environment, you have to use the absolute path to the correct executable, e.g.:\n",
+    "\n",
+    "`C:\\Users\\Jan\\Anaconda3\\envs\\pyramid\\python setup.py install`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**7) EITHER install `pyramid` OR create a PyCharm project containing the `pyramid` package!**\n",
+    "\n",
+    "The former is simpler, but static.\n",
+    "\n",
+    "The latter makes it easier to update, but requires you to add it to your `PYTHONPATH`, either manually (depends on OS) or through PyCharm directly:\n",
+    "\n",
+    "<img src=\"images/addsource.png\">"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Imports:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:14:59.581355Z",
+     "start_time": "2017-10-05T13:14:59.199470Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "%matplotlib inline"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Matplotlib magic, which causes plots to be part of the notebook (and not to cause pop ups)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:14:59.588353Z",
+     "start_time": "2017-10-05T13:14:59.583354Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Standard imports for plotting and array handling."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:00.524072Z",
+     "start_time": "2017-10-05T13:14:59.592352Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "import pyramid as pr"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Import of the `pyramid` package."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:21.035917Z",
+     "start_time": "2017-10-05T13:15:00.526071Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "WARNING:hyperspy.api:The traitsui GUI elements are not available, probably because the hyperspy_gui_traitui package is not installed.\n"
+     ]
+    }
+   ],
+   "source": [
+    "import hyperspy.api as hs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "(Optional) import of `hyperspy` (which is implicitly imported by pyramid! This line is used so that you can use it too!)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# `PhaseMap` objects:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `PhaseMap` class is the main container for phase image information! It has four main properties:\n",
+    "\n",
+    "<img src='images/phasemap-attributes.png'>\n",
+    "\n",
+    "You can access the class by:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:21.044914Z",
+     "start_time": "2017-10-05T13:15:21.037916Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "pyramid.phasemap.PhaseMap"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "pr.PhaseMap"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can either create it from scratch from an array for the `phase` (optionally add more arrays for `mask` and `confidence`):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:21.090900Z",
+     "start_time": "2017-10-05T13:15:21.047913Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<class 'pyramid.phasemap.PhaseMap'>(a=1.0, phase=array([[ 0.98147649,  0.46252942,  0.41486019],\n",
+       "       [ 0.79813403,  0.57133853,  0.03047334],\n",
+       "       [ 0.99620402,  0.28197351,  0.05998559]], dtype=float32), mask=array([[ True,  True,  True],\n",
+       "       [ True,  True,  True],\n",
+       "       [ True,  True,  True]], dtype=bool), confidence=array([[ 1.,  1.,  1.],\n",
+       "       [ 1.,  1.,  1.],\n",
+       "       [ 1.,  1.,  1.]], dtype=float32))"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "pr.PhaseMap(a=1., phase=np.random.rand(3, 3))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Or you can use a function to load your `PhaseMap` from files:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:21.571756Z",
+     "start_time": "2017-10-05T13:15:21.101897Z"
+    }
+   },
+   "outputs": [
+    {
+     "ename": "FileNotFoundError",
+     "evalue": "[Errno 2] No such file or directory: 'files/mask.png'",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[1;31mFileNotFoundError\u001b[0m                         Traceback (most recent call last)",
+      "\u001b[1;32m<ipython-input-7-e6d1be353b2f>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m()\u001b[0m\n\u001b[0;32m      1\u001b[0m pr.load_phasemap(filename='files/phase.unf',\n\u001b[0;32m      2\u001b[0m                  \u001b[0mmask\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;34m'files/mask.png'\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m----> 3\u001b[1;33m                  confidence='files/confidence.png')\n\u001b[0m",
+      "\u001b[1;32mc:\\users\\caron\\work\\projects\\pyramid\\pyramid\\file_io\\io_phasemap.py\u001b[0m in \u001b[0;36mload_phasemap\u001b[1;34m(filename, mask, confidence, a, threshold, print_mask_limits, **kwargs)\u001b[0m\n\u001b[0;32m     61\u001b[0m     \u001b[1;32mif\u001b[0m \u001b[0mmask\u001b[0m \u001b[1;32mis\u001b[0m \u001b[1;32mnot\u001b[0m \u001b[1;32mNone\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m     62\u001b[0m         \u001b[0mfilemask\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mkwargs_mask\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0m_parse_add_param\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mmask\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m---> 63\u001b[1;33m         \u001b[0mmask_raw\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0m_load\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mfilemask\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs_mask\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m     64\u001b[0m         \u001b[1;32mif\u001b[0m \u001b[0mprint_mask_limits\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m     65\u001b[0m             \u001b[0mprint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m'[Mask] min:'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mmask_raw\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mmin\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m'max:'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mmask_raw\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mmax\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m'threshold:'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mthreshold\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
+      "\u001b[1;32mc:\\users\\caron\\work\\projects\\pyramid\\pyramid\\file_io\\io_phasemap.py\u001b[0m in \u001b[0;36m_load\u001b[1;34m(filename, as_phasemap, a, **kwargs)\u001b[0m\n\u001b[0;32m     81\u001b[0m         \u001b[1;32mreturn\u001b[0m \u001b[0m_load_from_npy\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mfilename\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mas_phasemap\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0ma\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m     82\u001b[0m     \u001b[1;32melif\u001b[0m \u001b[0mextension\u001b[0m \u001b[1;32min\u001b[0m \u001b[1;33m[\u001b[0m\u001b[1;34m'.jpeg'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m'.jpg'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m'.png'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m'.bmp'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m'.tif'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m---> 83\u001b[1;33m         \u001b[1;32mreturn\u001b[0m \u001b[0m_load_from_img\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mfilename\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mas_phasemap\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0ma\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m     84\u001b[0m     \u001b[1;31m# Load with HyperSpy:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m     85\u001b[0m     \u001b[1;32melse\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
+      "\u001b[1;32mc:\\users\\caron\\work\\projects\\pyramid\\pyramid\\file_io\\io_phasemap.py\u001b[0m in \u001b[0;36m_load_from_img\u001b[1;34m(filename, as_phasemap, a, **kwargs)\u001b[0m\n\u001b[0;32m    135\u001b[0m \u001b[1;32mdef\u001b[0m \u001b[0m_load_from_img\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mfilename\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mas_phasemap\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0ma\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    136\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m--> 137\u001b[1;33m     \u001b[0mresult\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mnp\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0masarray\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mImage\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mopen\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mfilename\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mconvert\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m'L'\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m    138\u001b[0m     \u001b[1;32mif\u001b[0m \u001b[0mas_phasemap\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    139\u001b[0m         \u001b[1;32mif\u001b[0m \u001b[0ma\u001b[0m \u001b[1;32mis\u001b[0m \u001b[1;32mNone\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
+      "\u001b[1;32mC:\\Users\\caron\\AppData\\Local\\Continuum\\anaconda3\\envs\\pyramid-legacy\\lib\\site-packages\\PIL\\Image.py\u001b[0m in \u001b[0;36mopen\u001b[1;34m(fp, mode)\u001b[0m\n\u001b[0;32m   2408\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m   2409\u001b[0m     \u001b[1;32mif\u001b[0m \u001b[0mfilename\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m-> 2410\u001b[1;33m         \u001b[0mfp\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mbuiltins\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mopen\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mfilename\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m\"rb\"\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m   2411\u001b[0m         \u001b[0mexclusive_fp\u001b[0m \u001b[1;33m=\u001b[0m \u001b[1;32mTrue\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m   2412\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n",
+      "\u001b[1;31mFileNotFoundError\u001b[0m: [Errno 2] No such file or directory: 'files/mask.png'"
+     ]
+    }
+   ],
+   "source": [
+    "pr.load_phasemap(filename='files/phase.unf',\n",
+    "                 mask='files/mask.png',\n",
+    "                 confidence='files/confidence.png')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The package tries to load the grid spacing `a` from the phase file determined by `filename` and defaults to `1` [nm], if it can not be determined. You can overwrite the grid spacing by adding `a` as a keyword argument to the loading function.\n",
+    "\n",
+    "`mask` and `confidence` are optional parameters and can be skipped (like in the \"by-hand\" example above).\n",
+    "\n",
+    "`pyramid` uses mainly `hyperspy` functionality to load files (and `PIL` for images of all kinds) and thus has the same flexibility concerning different formats.\n",
+    "\n",
+    "After constructing or loading a `PhaseMap`, it can be saved to a file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:21.842675Z",
+     "start_time": "2017-10-05T13:15:21.575755Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "phasemap = pr.load_phasemap(filename='phase.unf', mask='mask.png', confidence='confidence.png')\n",
+    "phasemap.save('phasemap.hdf5', overwrite=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Plot `PhaseMap`:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "First, load or create a `PhaseMap`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:21.948643Z",
+     "start_time": "2017-10-05T13:15:21.844674Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "phasemap = pr.load_phasemap(filename='phase.unf', mask='mask.png', confidence='confidence.png')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To plot the `PhaseMap` (including possibly the mask and the confidence), use:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:22.798388Z",
+     "start_time": "2017-10-05T13:15:21.952642Z"
+    },
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "phasemap.plot_phase()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can use the following (optional) parameters to change the plot to your liking:\n",
+    "\n",
+    "<img src='images/plot-phase-params.png'>\n",
+    "\n",
+    "Furthermore, you can plot the holographic contour map by using:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:23.504176Z",
+     "start_time": "2017-10-05T13:15:22.801387Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "phasemap.plot_holo()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can use the following (optional) parameters to change the plot to your liking:\n",
+    "\n",
+    "<img src='images/plot-holo-params.png'>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# `VectorData` objects:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `VectorData` class is a container for 3D vector fields. It has two \n",
+    "\n",
+    "<img src='images/vectordata-attributes.png'>\n",
+    "\n",
+    "The class can be accessed by:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:23.541165Z",
+     "start_time": "2017-10-05T13:15:23.527169Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pr.VectorData"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can either create it from scratch from an array for the `field`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:23.567157Z",
+     "start_time": "2017-10-05T13:15:23.545164Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pr.VectorData(a=1., field=np.random.rand(3, 2, 2, 2))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Or you can use a function to load your `VectorData` from file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:23.746103Z",
+     "start_time": "2017-10-05T13:15:23.571156Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pr.load_vectordata(filename='magdata.hdf5')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The package tries to load the grid spacing `a` from the vector field file determined by `filename` and defaults to `1` [nm], if it can not be determined. You can overwrite the grid spacing by adding `a` as a keyword argument to the loading function.\n",
+    "\n",
+    "After constructing or loading a `VectorData`, it can be saved to a file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:23.924050Z",
+     "start_time": "2017-10-05T13:15:23.750102Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "magdata = pr.load_vectordata(filename='magdata.hdf5')\n",
+    "magdata.save('magdata.hdf5', overwrite=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Furthermore, the `pr.magcreator` subpackage contains a lot of functions to create custom vector fields. It has a module `examples` with a lot of interesting shapes and geometries.\n",
+    "\n",
+    "A vortex disc with a smooth core can e.g. be created by using (see next section for the plot):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:24.214963Z",
+     "start_time": "2017-10-05T13:15:23.927049Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "magdata = pr.magcreator.examples.smooth_vortex_disc()\n",
+    "magdata.plot_quiver_field()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Or a Halbach disc:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:24.441895Z",
+     "start_time": "2017-10-05T13:15:24.217962Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "magdata = pr.magcreator.examples.source_disc()\n",
+    "magdata.plot_quiver_field()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Each example has a lot of attributes which can be used to adapt them to the users needs.\n",
+    "\n",
+    "For more fine control, the following functions can be used:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:24.451892Z",
+     "start_time": "2017-10-05T13:15:24.444894Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pr.magcreator.create_mag_dist_homog"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:24.464888Z",
+     "start_time": "2017-10-05T13:15:24.455890Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pr.magcreator.create_mag_dist_vortex"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:24.488880Z",
+     "start_time": "2017-10-05T13:15:24.468886Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pr.magcreator.create_mag_dist_smooth_vortex"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:24.522870Z",
+     "start_time": "2017-10-05T13:15:24.495878Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pr.magcreator.create_mag_dist_source"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The first parameter for these functions is always a boolean array `mag_shape`, which determines the magnetised volume in 3D. See the docstrings for more information."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Plot VectorData objects:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "There are several methods to plot slices of a 3D magnetisation distribution, e.g. the color coded field can be plotted with:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:25.064708Z",
+     "start_time": "2017-10-05T13:15:24.527869Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "magdata = pr.load_vectordata(filename='magdata.hdf5')\n",
+    "magdata.plot_field(figsize=(10, 10), colorwheel=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can use the following (optional) parameters to change the plot to your liking (in 3D, take care that you plot the correct slice along the correct axis!):\n",
+    "\n",
+    "<img src='images/plot-field-params.png'>\n",
+    "\n",
+    "Another plot is the quiver plot which plots arrows, whose density can be controlled with the parameter `ar_dens`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:26.206365Z",
+     "start_time": "2017-10-05T13:15:25.091700Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "magdata.plot_quiver(ar_dens=8, figsize=(10, 10), b_0=1, colorwheel=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can use the following (optional) parameters to change the plot to your liking:\n",
+    "\n",
+    "<img src='images/plot-quiver-params.png'>\n",
+    "\n",
+    "By setting the parameter `coloring='amplitude'`, the amplitude of the arrows can be encoded:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:27.334027Z",
+     "start_time": "2017-10-05T13:15:26.210364Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "magdata.plot_quiver(ar_dens=8, figsize=(10, 10), b_0=1, coloring='amplitude')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "It is recommended to combine field and quiver plots by using:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:28.439695Z",
+     "start_time": "2017-10-05T13:15:27.338025Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "magdata.plot_quiver_field(ar_dens=8, figsize=(10, 10), b_0=1, colorwheel=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For 2D reconstructions, sometimes a thickness correction has to be done. This is achieved by using the `b_0` parameter:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:29.893259Z",
+     "start_time": "2017-10-05T13:15:28.441694Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "t = 36  # nm\n",
+    "b_0 = magdata.a / t\n",
+    "magdata.plot_quiver_field(ar_dens=8, figsize=(10, 10), b_0=b_0, colorwheel=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "3D plots are also possible, but are not discussed here, due to problems with displaying them in a notebook!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Forward Model:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A fast way to apply the forward model to a given magnetisation distribution is the convenience function:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:15:32.392509Z",
+     "start_time": "2017-10-05T13:15:29.895258Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "phasemap = pr.utils.pm(magdata)\n",
+    "phasemap.plot_combined()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The function accepts optional parameters:\n",
+    "\n",
+    "<img src='images/pm-params.png'>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Reconstruction:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For a fast reconstruction of the projected in-plane moments from a single `PhaseMap`, you can use a convenient one-liner:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:16:39.730301Z",
+     "start_time": "2017-10-05T13:15:32.394508Z"
+    },
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "phasemap = pr.load_phasemap(filename='phase.unf', mask='mask.png', confidence='confidence.png')\n",
+    "magdata_rec, cost = pr.utils.reconstruction_2d_from_phasemap(phasemap, lam=0.01, plot_results=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "These are the parameters that can be changed to influence the reconstruction:\n",
+    "\n",
+    "<img src='images/rec2d-params.png'>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The one-liner does a lot of stuff under the hood, which can also be done manually to have granular control over the reconstruction process.\n",
+    "\n",
+    "First, a `DataSet` instance has to be constructed, which holds one (like in this exampl) or more `PhaseMap` instances and the according `Projector` instances that determine the projection direction (a simple `z`-projection in this case).\n",
+    "\n",
+    "The `DataSet` needs the grid spacing, the dimension of your 3D distribution and a scaling factor for the saturation induction (just use `b_0=1` if no further scaling is needed):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:16:39.737299Z",
+     "start_time": "2017-10-05T13:16:39.732301Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "dim = (1,) + phasemap.dim_uv\n",
+    "data = pr.DataSet(phasemap.a, dim, b_0=1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now the phase images and projectors have to be added to the `DataSet`. In this example, only one pair is added and the projector (a simple `z`-projection) is created on the fly (it needs the dimensions of the 3D magnetisation volume):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:16:40.476077Z",
+     "start_time": "2017-10-05T13:16:39.741298Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "data.append(phasemap, pr.SimpleProjector(dim))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If the mask, which determines the position of the magnetised volume in 3D space is known, it can be set by using (the mask is `True` everywhere in this example):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:16:40.491073Z",
+     "start_time": "2017-10-05T13:16:40.479077Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "mask = np.ones(dim)\n",
+    "data.mask = mask"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If the mask is not known, it can be calculated. If the `DataSet` contains only one `PhaseMap`, the 2D mask (if available) is used. For tilt series, a simple discrete back-projection algorithm is used. The command is:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:16:40.503069Z",
+     "start_time": "2017-10-05T13:16:40.496071Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "data.set_3d_mask()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A forward model is constructed which uses the `DataSet` and a parameter `ramp_order` as input:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:16:40.517065Z",
+     "start_time": "2017-10-05T13:16:40.507068Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "fwd_model = pr.ForwardModel(data, ramp_order=1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `ramp_order` determines the additional fit of phase polynoms:\n",
+    "\n",
+    "* `ramp_order` = None : No additional polynom is fitted.\n",
+    "* `ramp_order` = 0    : A global phase offset is fitted.\n",
+    "* `ramp_order` = 1    : An offset and ramps are  fitted.\n",
+    "\n",
+    "Next, a `Regularisator` has to be constructed, which constrains the solution of the reconstruction:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:16:40.736999Z",
+     "start_time": "2017-10-05T13:16:40.523063Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "reg = pr.FirstOrderRegularisator(data.mask, lam=0.01, add_params=fwd_model.ramp.n)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `FirstOrderRegularisator` constrains the smoothness of the solution (Thikonov 1. order).\n",
+    "It uses the 3D `mask`, a regularisation parameter `lam` and `add_params`, which has to be set to the number of degrees of freedom of the ramp via `fwd_model.ramp.n`, as input.\n",
+    "\n",
+    "`ForwardModel` and `Regularisator` are then combined in a `Costfunction`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:16:40.751995Z",
+     "start_time": "2017-10-05T13:16:40.738999Z"
+    },
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "cost = pr.Costfunction(fwd_model, reg)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This `Costfunction` is then minimised using the `optimize_linear` function in the `reconstruction` module (all of this is done implicitely by the convenience function `pr.utils.reconstruction_2d_from_phasemap`):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2017-10-05T13:17:34.652820Z",
+     "start_time": "2017-10-05T13:16:40.756993Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "magdata_rec = pr.reconstruction.optimize_linear(cost, max_iter=100, verbose=True)\n",
+    "magdata_rec.plot_quiver_field(ar_dens=8, colorwheel=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To find a good estimate for $\\lambda$, an L-Curve analysis should be done. A dedicated class implementing this feature is currently under development!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "3D reconstructions are not shown here, as they take a long time and plotting in a notebook is not very intuitive at the moment!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "After reconstruction, several diagnostic measures can be calculated. They can be found in the `pr.diagnostics` module and are not further discussed here!"
+   ]
+  }
+ ],
+ "metadata": {
+  "hide_input": false,
+  "kernelspec": {
+   "display_name": "Python [conda env:pyramid-legacy]",
+   "language": "python",
+   "name": "conda-env-pyramid-legacy-py"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.5.4"
+  },
+  "notify_time": "5"
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}