Tidyup jors (#50)

* Fixed EIDORS example. Fixed Typo in usage desc. remove unused test file

* Better comments for Docker usage and run_mesher.m

* changed volume names so not to be confused with existing directories

Dockerfile

@@ -1,10 +1,10 @@
 FROM ubuntu:bionic
 
-# Mount volumes - these are in root to make it easier to type 
-# and to avoid confusion between those included in the Mesher directory
+# Mount volumes - these are in root to make it easier to type (/in/param.txt rather than /Mesher/inputs/param.txt)
+# and to avoid confusion between those included in the Mesher repository 
 
-VOLUME /output
-VOLUME /input
+VOLUME /out
+VOLUME /in
 
 RUN apt-get update \
     && apt-get install -y \
@@ -37,9 +37,9 @@ RUN apt-get clean \
     && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
 ENTRYPOINT [ "./bin/mesher" ]
-# default run with example inputs inside the container to demonstrate its working
+# default run with example inputs inside the container to demonstrate its working. Note these directories are with respect to the current folder /Mesher/ set by WORKDIR 
 CMD ["-i", "inputs/input.inr", "-e", "inputs/Electrodes.txt", "-p", "inputs/params.txt"]
 
 # To run the Mesher, you need to mount the volumes and then direct the mesher to look into the correct directories e.g.:
-# docker run --rm -v ~/Mesher/inputs2:/input -v ~/Mesher/output2:/output  mesher -i /input/input.inr -e /input/Electrodes.txt -p /input/params.txt -d /output/ -o testing
+# docker run --rm -v path/to/inputs:/in -v path/to/outputs:/out  mesher -i /in/input.inr -e /in/Electrodes.txt -p /in/params.txt -d /out/ -o testing
 

MATLAB/runmesher.m

@@ -1,7 +1,33 @@
 function [status,cmdout] = runmesher(inrfile,electrodesfile,parameterfile,outdir,outname,MesherRoot)
-%RUNMESHER Calls Mesher from Command line from MATLAB, uses WSL if using
-%Windows
-%   Detailed explanation goes here
+% RUNMESHER Calls Mesher from Command line from MATLAB, uses WSL if using
+% Windows
+%   Builds the command string and calls the Mesher. If on Windows, it will
+%   call the Mesher using the default WSL distribution.
+%
+% The mesher is called from the command line with the following parameters
+% ./bin/mesher 
+%         -i input image file
+%         -e electrode position file
+%         -p parameter file
+%         -o output mesh name (default = new_mesh)
+%         -d output directory (default = output/)
+%
+% Inputs:
+% inrfile        - path to .inr file with binary volume
+% electrodesfile - path to electrodes.txt with 3D coordinates of electrode positiosn
+% parameterfile  - path to param file e.g. made by writemesherparam()
+%
+% Optional inputs:
+% outdir         - output dir, if blank or missing will use MesherRoot/output
+% outname        - output mesh name, will use new_mesh if not given
+% MesherRoot     - Mesher repository root. By default it assumes the mesher
+%                  is built in the same root directory as this current
+%                  Matlab script. The user can specify a different
+%                  directory. This is useful in some cases using WSL
+%
+% Usage:
+% from run_examples.m assuming pwd is Mesher/examples:
+% runmesher('brain/input.inr','brain/Electrodes.txt','brain/input_idx.txt','brain/output/','brainexample');
 
 %% Mesher location
 
@@ -69,7 +95,8 @@
 
 %% Finally call mesher
 
-% use WSL if we are on PC
+% use WSL if we are on PC. This is the *default* WSL distribution, which
+% can be set by wsl --set-default 
 if ispc
     CMDSTR = ['wsl ' CMDSTR];
 end

README.md

@@ -89,15 +89,16 @@ The docker container can be obtained using two different methods:
 docker build -t mesher .
 ```
 
-* Pull image directly from dockerhub without having to build
+* Pull image directly from dockerhub without having to build, renaming the container to `mesher` (or name of your choice) :
 
 ```bash
 docker pull doctorjimbles/eit-mesher
+docker image tag doctorjimbles/eit-mesher:latest mesher:latest
 ```
 
 ### Running Mesher from container
 
-To test it is working run the container with no inputs, this will call the mesher with defaults which runs the single example included in the container:
+To test if it is working run the container with no inputs, this will call the mesher with defaults which runs the single example included in the container:
 
 ```bash
 docker run --rm mesher
@@ -113,14 +114,36 @@ docker run --rm mesher -i inputs/input.inr -e inputs/Electrodes.txt -p inputs/pa
 
 * Using your own data - mounting volumes
 
-The container has two volumes `/input` and `/output` which can be mounted to a directory on the host using the `-v` flag. So for example with the `MESHER` repository on the home dir:
+The container has two **root** directories `/in` and `/out` which can be mounted as volumes to map to directories on the host using the `-v` flag. So for example, if we had the `MESHER` repository in our home dir we would add the flags:
 
 ```bash
-docker run --rm -v ~/Mesher/inputs:/input -v ~/Mesher/output:/output  mesher
+ -v ~/Mesher/inputs:/in -v ~/Mesher/output:/out
 ```
 
-The mesher can then finally be called by combining the volume definitions and the parameters. **Note** The directories must be with respect to the container file structure
+The mesher can then finally be called by combining the volume definitions and then directing the mesher at the new input location `/in/`. **Note** Parameters given must be with respect to the container file structure. So for example, to make the default mesh but using the inputs files in the repository on the host machine (assuming it is stored in /home/user/Mesher):
 
 ```bash
-docker run --rm  -v ~/Mesher/inputs:/input -v ~/Mesher/output:/output  mesher -i /input/input.inr -e /input/Electrodes.txt -p /input/params.txt -d /output/ -o dockertest
+docker run --rm  -v ~/Mesher/inputs:/in -v ~/Mesher/output:/out  mesher -i /in/input.inr -e /in/Electrodes.txt -p /in/params.txt -d /out/ -o dockertest
 ```
+
+This will result in an output mesh `dockertest` in `/home/user/Mesher/output`.
+
+To run the NN scalp example (still assuming this repository is stored in /home/user/Mesher)
+
+```bash
+docker run --rm  -v ~/Mesher/examples/neonatescalp/:/in -v ~/Mesher/examples/neonatescalp/output:/out  mesher -i /in/NNscalp.inr -e /in/NNscalp_elecINRpos.txt -p /in/NNscalp_param.txt -d /out/ -o dockertestNN
+```
+
+* Improving slow file write on some systems
+
+In some systems (reported on macOS 10.15.6, Docker Desktop 2.3.0.4, Docker Engine 19.03.12) it is much slower writing files into the mapped volume. Therefore to improve performance, it is possible to call the mesher and copy the files out afterwards. To do this we remove the `--rm` flag as we want to keep it, and add the `--name` flag to give it a name that makes more sense to us. We also drop the `-v` flag for the `\out` folder.
+
+```bash
+docker run --name NNmesher  -v ~/Mesher/examples/neonatescalp/:/in mesher -i /in/NNscalp.inr -e /in/NNscalp_elecINRpos.txt -p /in/NNscalp_param.txt -d /out/ -o dockertestNN
+```
+
+The mesher files can then be copied outside of the container
+
+```bash
+docker cp NNmesher:/out ./newoutputdir
+```

examples/solvers/EIDORS/NNEIDORS_param.txt

@@ -1,4 +1,4 @@
-# Mesher parameter file 10-Feb-2020 12:08:44
+# Mesher parameter file 17-Sep-2020 16:02:26
 # Refinement(s) on/off (1 - yes, 0 -no)
 electrode_refinement = 1
 depth_refinement = 0

examples/solvers/EIDORS/eidors_example.m

@@ -97,7 +97,7 @@
 % and contact impedance to be given within a structure. So here we find 
 % nodes on the suface within electrode radius
 
-z_contact = 100; % ohms 
+z_contact = 20e-3; % ohms/m2 
 elec_radius = .008; %in meters
 
 % unique surface node references
@@ -204,4 +204,4 @@
 xlabel('Measurement');
 ylabel('Voltage (V)');
 ylim([-0.15 0.15])
-% saveas(gcf,'figures/EIDORS_Volts.png')
+saveas(gcf,'figures/EIDORS_Volts.png')

src/mesher.cpp

@@ -17,7 +17,7 @@ using namespace std;
  **/
 void printusage(void)
 {
-  printf("Usage:  ./mesher -i INPUT_INR -e INPUT_ELECTRODES -p INPUT_PARAMETERS");
+  printf("Usage:  ./mesher -i INPUT_INR -e INPUT_ELECTRODES -p INPUT_PARAMETERS\n");
   printf("        -i input image file\n");
   printf("        -e electrode position file\n");
   printf("        -p parameter file\n");