EIDORS: Electrical Impedance Tomography and Diffuse Optical Tomography Reconstruction Software

Hosted by

Frequently Asked Questions

1. What is EIDORS?

   The goal of EIDORS is to promote collaboration between groups working on Electrical Impedance Tomography (EIT) and Diffusion based Optical Tomography, in medical and industrial settings.

2. Where do I get help? OR I have an issue/bug/problem with doing xxx in EIDORS.

   We're happy to help. To do that we need a bit of information and the context in which you are trying to solve your problem. First, please have a look through the eidors3d-help@lists.sourceforge.net mailing list archive. Has your problem been observed before and solved. If this solves your problem, great.

   If not, you may write an email to the mailing list. eidors3d-help@lists.sourceforge.net. Sign up for eidors3d-help here. This way the broader EIDORS community will be able to help you resolve your issue, and when or if others run into the same issue, they'll be able to find your solution. In your email, you must provide
   − 1. Background: What are you trying to achieve? What problem are you working on?
   − 2. A clearly worded question or issue: What is the exact error message? What do you expect versus what you actually see occurring.
   − 3. A script that will reproduce the issue. (file attached) (Is this script based on a tutorial from the EIDORS site? If so which one?)
   − 4. A log of the output from EIDORS. (file attached)
   − 5. What version of EIDORS are you using, and what OS/Matlab version are you using?

3. How is EIDORS pronounced?

   EIDORS is pronounced like eiderdown. It sounds like eye doors.

4. What do I need to run EIDORS

   You will need a modern windows, unix or mac computer, and Matlab (version ≥ 7.0). To be able to do fine 3D meshes you will need at least 2GB RAM (or more). For FEM meshing you will need Netgen. It is possible to use Matlab 6.5 with older versions (EIDORS ≤ 3.4). EIDORS also supports modern versions of Octave (≥ 3.4);

5. Can I use Octave instead of Matlab?

   Partially. Many EIDORS functions work well in Octave; however, there are some missing capabilities. This is especially true of the graphical parts of EIDORS. If you are interested to help, we are actively looking for help with Octave support,

6. What is the logo?

   The logo is a walrus. EIDORS images blobby objects in aqueous media; similarly, the walrus is a fat, blobby animal that lives in water. The original (high resolution) image of the one used here is from the NOAA. See www.photolib.noaa.gov/animals/anim0030.htm. For another great picture of fat waruses see this image.

7. Whom should I blame or thank or contact for more information?

   The current maintainers of EIDORS are Andy Adler and Bill Lionheart. Please contact them with suggestions, contribution of code, and contribution of sample data, meshes, and algorithms.

8. How do I get started with EIDORS?

   Step 1: Download EIDORS
   Step 2: Unzip the file and save it to a directory like /path/to/eidors
   Step 3: Start Matlab. Run this command: >>run /path/to/eidors/startup.m

9. Are there any prebuilt examples?

   Yes, please look at the tutorial.

10. Under what terms is EIDORS licenced

    EIDORS is licenced under the GNU General Public License. Uses are free to use, modify, and distribute their modifications. All modifications must include the source code, or instructions on how to obtain it.

11. May I include EIDORS in a commercial product

    Yes. As long as you make the source code for EIDORS and all modifications you made to it available to your clients.

12. How should I refer to EIDORS in a scientific publication

    Please quote the following paper

    Andy Adler, William R B Lionheart (2006) "Uses and abuses of EIDORS: An extensible software base for EIT", Physiol. Meas. 27:S25-S42, 2006

13. Does EIDORS support 2D algorithms

    Yes. Look at examples/image_2d_algs.m.

14. Does EIDORS actually do diffuse optical tomography?

    Not yet, but we intend it to. Please contact us if you are willing to help with this.

15. Does EIDORS provide sample data

    Yes. Look in the sample_data directory. We would love to have additional contributions of sample data from various experimental and clinical settings.

    There are also many data sets provided in data_contrib, covering many important studies in EIT.

16. May I use EIDORS sample data to test my algorithm

    Yes. However, if you publish your tests, you are generall required to refer to EIDORS in your publication. In general, you may simply list this paper in your references:

    Adler and Lionheart (2005), "Uses and abuses of EIDORS: An extensible software base for EIT" Submitted to Physiol. Meas., Nov. 2005
    However, certain data sets may require reference to a different paper. Please read the documentation for the particular data set.

17. How do I use EIDORS to compare my idea to a published algorithm

    Please remember that this is only a toolkit, and that the demonstration programs are only simple worked examples. They are not intended to be the state of the art in EIT reconstruction. By all means publish your improved reconstruction algorithms and compare them with the simple ones we demonstrate here. But please don't just run the demo code on your own data, using the tiny demo mesh, a randomly chosen regularization parameter and only one iteration of regularized Newton's method then compare this with your own highly optimised code and claim that your code is vastly superior than EIDORS' best shot (Yes, we exagerate, slightly). This is a toolkit of routines for you to build a code which suits your application.

18. Compiling Netgen under Linux

    Over the years there have been a number of people who have asked for help compiling and installing Netgen. I had a script or two from years back that I have, at various times, suggested people use as a starting point for compiling under linux. It is, generally, not easy to successfully compile as there are a number of patches and the build options and dependencies can be a bit tricky to work through. I've recently gone back through my notes and those build scripts and got them fully operational again. There are now scripts available in my dev/a_boyle directory for three versions of netgen: 4.9.13, 5.3.1 and 6.0_beta.

    All versions apply necessary patches, compile, install to a designated location (either local or system wide), and provide a netgen wrapper which sets necessary environment variables to allow netgen to run under Matlab/EIDORS. The builds have been tested on Gentoo (2017-04-25), Ubuntu (16.04) and will most likely work on other gnu/linux distributions. These are not for Mac or Windows.

    1. install-netgen-4.9.13
    2. install-netgen-5.3.1
    3. install-netgen-6.0-beta

    Note that under Ubuntu, you need dependencies:
    

    $ sudo apt-get install libxmu-dev mesa-common-dev libglu1-mesa-dev libx11-dev
    

    If you happen to be using Gentoo, there is an ebuild which automates the compile from source and installs into the system; these are the builds that I use (and maintain) in production.
    Netgen ebuilds for Gentoo Linux

    Warning: The 4.9.13 version of netgen will crash when it is executed due to a buffer overflow that is detected by modern compilers when meshing simple geometries. Versions 5.3.1 and 6.0_beta seem to work correctly for me.

    Good luck!

19. I'm struggling to use the EIDORS Netgen functions?

    Netgen is a lovely tool, but it can be sensitive to many of it's parameters, especially those related to the placement of many electrodes. If you're having troubles, try these ideas:

    • Try building a model without electrodes (for example, instead of ng_mk_extruded_model({300,a,[3,10],25},[16,1,150],[1]);, set the underlined field to [0 0] (0 electrodes and 0 planes) ).
    • If building without electrodes works, try modifying the placement parameter (e.g. set the underlined field to [16,1.05,150]). This will move the electrodes slightly.
    • Alternatively, you can make the boundary smoother/nicer by interpolating, e.g.

      		trunk = [x1 y1; ...; xn yn];
      		pp= fourier_fit(trunk); 
      		sp = linspace(0,1,51);sp(end)=[]; 
      		smoother_trunk = fourier_fit(pp, sp);

      Changing the starting point (0) in the linspace call will shift the points along the contour, worth trying.
    • Netgen seems to have a problem with electrodes that almost exactly point at each other. This is usually manifested by a number of "Intersection" messages followed by "Error in surface generation" or hang up during surface generation. In the worst case it will hang up or crash already at the "Find Points" stage. The solution is to make the offending electrodes point exactly at each other. In the ng_mk_extruded_model function, the electrodes are perpendicular to the side on which their center lies. However, you can discretise the angle into N possible values by specifying a 5th parameter to the elec_shape (3rd) input, as in:
      

      fmdl = ng_mk_extruded_model({300,a,[3,10],25},[16,1,150],[1,0,0,0,N]);

      Values of N between 6 and 67 have proven useful at times. You should settle for the highest number that works for your shape, as discretization in general distorts electrode shape.
    • Try building your model without internal structures, e.g.
      

      fmdl = ng_mk_extruded_model({2,trunk ,[4,50],.1},[electh,1+0*electh],[0.1 0 0.05]);

      instead of
      

      fmdl = ng_mk_extruded_model({2,{trunk,lung} ,[4,50],.1},[electh,1+0*electh],[0.1 0 0.05]);

      If that works, refine the internal shapes.
    • Try a smaller mesh density (larger last parameter in the underlined field above).
    • Try a smaller electrode density (larger, or none, last parameter in the [0.1 0 0.05] electrode shape field above)
    • If all else fails, locate the .geo file created by the function you called and examine it with Netgen GUI. Location of the .geo file is one of the first things Netgen prints out. On Windows, this will be something like:
      Load geometry file C:\DOCUME~1\Username\LOCALS~1\Temp\tp054957.geo
      Corresponding to the path C:\Documents and Settings\Username\Local Settings\Temp\tp054957.geo

20. What if I notice a bug?

    You may write an email to the maintainers.

21. I need some features that are missing in EIDORS?

    Please note that EIDORS is a volunteer project by some very busy people. You are welcome to make suggestions for new features, but we may not be able to find the time to implement them.

    Good options are: 1) implement new features yourself, and contribute them to EIDORS3D, or 2) find a source of funds to pay for the features you need. In either case, you are welcome to contact the maintainers to discuss.

Errors and Solutions

1. "??? Undefined command/function 'eidors_msg'."

   This error occurs because the functions are not part of the Matlab path. Use the command:

     >>run path/to/eidors/startup.m
   

2. Matlab prints ugly bitmapped figures rather than vector graphics

   Matlab seems to try to guess what the user wants. At any rate, it often gets the choice wrong. To force vector graphics, use the '-painters' option. One useful trick to control the size of generated figures is to use the 'PaperPosition' property. Another useful trick to crop postscript figures is to use the imagemagick convert utility.

     >> set(gcf, 'PaperPosition', [0.25,2.5, width, height]);
     >> print( gcf, '-depsc2','-painters', 'temp.eps')
     >> system('convert -crop 0x0 temp.eps output.eps');
   

3. "Warning: RGB color data not yet supported in Painter's mode."

   This is a limitation of Matlab. RGB data cannot be exported to postscript files. This can be solved by using colourmaps instead. Try this:

     >>calc_colours('mapped_colour',256);
   

4. "??? Invalid MEX-file ..." error on Linux

   Sometimes one can get linux errors of the form
   ??? Invalid MEX-file '/home/andy/work/eidors3d/eidors_var_id.mexglx': libstdc++.so.6: cannot open shared object file: No such file or directory. or
   ??? Invalid MEX-file '/home/andy/work/eidors3d/eidors_var_id.mexglx': [...]/../sys/os/ glnx86/libgcc_s.so.1: version `GCC_3.3' not found (required by /usr/lib/libstdc++.so.6). These errors are can occur when the linux version on which EIDORS is run is different from that on which the mex file was built. The easiest solution is to recompile the mex file, as follows:

     >> mex eidors_var_id.cpp
   

5. Using Netgen

   EIDORS can use netgen to create some fairly impressive 3D meshes. See the examples. Netgen usage with EIDORS is fairly easy under windows. You need to

   1. Download and install the windows binary from http://sourceforge.net/projects/netgen-mesher/
   2. Run an example which calls netgen (ie call_netgen.m)
   3. Enter a path to the netgen binary without spaces (ie for C:\Program Files\netgen write C:/Progra~1/netgen)

6. mk_stim_patterns question

   is the code

   stim= mk_stim_patterns(16, 1, '{ad}','{ad}', {}, 10); equivalent to stim= mk_stim_patterns(8, 2, '{ad}','{ad}', {}, 10); No, each ring is treated separately, so that, for example

   >> stim= mk_stim_patterns(4, 2, '{ad}','{ad}', {}, 10);
   >> full([stim(:).stim_pattern])
   ans = -10     0     0    10     0     0     0     0
          10   -10     0     0     0     0     0     0
           0    10   -10     0     0     0     0     0
           0     0    10   -10     0     0     0     0
           0     0     0     0   -10     0     0    10
           0     0     0     0    10   -10     0     0
           0     0     0     0     0    10   -10     0
           0     0     0     0     0     0    10   -10
   
   >> stim= mk_stim_patterns(8, 1, '{ad}','{ad}', {}, 10);
   >> full([stim(:).stim_pattern])
   ans = -10     0     0     0     0     0     0    10
          10   -10     0     0     0     0     0     0
           0    10   -10     0     0     0     0     0
           0     0    10   -10     0     0     0     0
           0     0     0    10   -10     0     0     0
           0     0     0     0    10   -10     0     0
           0     0     0     0     0    10   -10     0
           0     0     0     0     0     0    10   -10
   

7. Errors with print_convert

   print_convert gives the error:

    EIDORS:[This function requires the ImageMagick convert program  be
    installed and on the path. On windows, we recommend you install it as
    part of cygwin (www.cygwin.com)]
   

   This may be a path issue. Try

   >> !convert -help
   

   if you get Invalid drive specification., then you need to edit the path so that C:\cygwin\bin is before C:\windows\system32.

8. Compiling Netgen under linux

   The following script describes how to compile netgen and its dependencies under linux:

   # Ubuntu/Debian sudo apt-get install tk-dev tcl-dev libglu1-mesa-dev libtogl-dev (cd /usr/lib/x86_64-linux-gnu/ && sudo ln -s libXmu.so.6 libXmu.so ) # Create a src dir cd $HOME && mkdir -p src && cd src # Download the latest Netgen wget http://downloads.sf.net/project/netgen-mesher/netgen-mesher/5.0/netgen-5.0.0.tar.gz # Unzip tar xfz netgen-5,0.0.tar.gz && cd netgen-5.0.0 # Configure and Make ./configure make sudo make install # That should work and install netgen to /opt/netgen/bin # Set the environment variable to NETGENDIR=/opt/netgen/bin # if you don't have root permissions on the machine, then use ./configure --prefix=$HOME/local # then add the directory to your path export PATH=$PATH:$HOME/local

9. Printing (including print_convert) gives tiny fonts on Ubuntu

   This is similar to the issue discussed here.

   # Install these fonts sudo apt-get install xfonts-75dpi xfonts-100dpi # Restart the x server. # Or, if you're using vncserver, kill and restart the vncserver