Skip to content
Snippets Groups Projects
monj's avatar
monj authored
7ad731c7
History

Orientation Analysis via the Structure Tensor

  1. Description of repository content
  2. Local set-up to run the tutorials and the tool
  3. Resources and inspiration
  4. Contributions

1. Description of repository content

The tutorials demonstrate the use of the structure tensor tool for the analysis of orientations in 2D and 3D data. With these tutorials we would like you to 1) learn how to choose the parameters to obtain desirable results, 2) see different options for visualising the output of the structure tensor, and 3) get inspiration for scientific questions that you could answer with the structure tensor tool. The 2D and 3D example tutorials (ST2D_examples and ST3D_examples) come as python scripts (.py) and Jupyter Notebooks (.ipynb). While the 2D script covers many examples, the 3D script dives into one example and thus comes with more details. You can also find a set of guided exercises with solutions, names ST2D_exercise_withSolutions.ipynb. The tutorials come with a set of utils (helper functions), named utilsST_2D.py- and utilsST_3D.py, to inspect the output of the structure tensor in various ways.

These tutorials have been developed for the implementation in https://github.com/Skielex/structure-tensor. This implementation is compatible with the python package cupy. Therefore, if you have large volumes to process and a graphical processing unit (GPU), you can speed up your computations simply by having a working installation of cupy.

To find out more, click on the binder icon to run the tutorials online Binder

2. Local set-up to run the tutorials and the tool

If you want to run the tutorials locally, check our instructions for installing Jupyter Notebooks and then follow the instructions below to install the tool.

Option 1: pip install

If you have pip, you can install the tool with pip install structure-tensor.

Option 2: Set up environment

You can run the file called environment.yml to install the structure tensor tool and other required packages via the command line, as explained below. If using Anaconda, you can also install the packages using its graphical user interface, just check the packages that are required by opening the environment file with a text reader.

Mac/Linux:

  1. Navigate to the tutorial extracted folder.
  2. To open the terminal, right click on the folder and navigate to
    • Mac: Services/New Terminal at Folder
    • Linux: Open in Terminal
  3. Type conda env create -f environment.yml and press enter.
  4. Type conda activate qim-ST and press enter.

Windows:

  1. Open Anaconda Prompt.
  2. cd <tutorials_path>, where tutorials_path is the absolute (full) path to the structure-tensor-master folder.
  3. Type conda env create -f environment.yml and press enter.
  4. Type conda activate qim-ST and press enter.

3. Resources and inspiration

To learn more about the computation of structure tensor, the visualisation of orientation analysis and other examples of using orientation analysis in volumetric data analysis, we recommend you take a look at the notes by Vedrana A. Dahl vand@dtu.dk

For inspiration, check out the following papers on user cases we have solved with the structure tensor tool:

4. Contributions

The development of the tutorials is a combined effort from several researchers in the QIM team. The collection of scripts and exercises is in constant development, and actively used to demonstrate the tool and teach at workshops. We would therefore very much appreciate to hear about your experience.

Please contact Monica J. Emerson monj@dtu.dk with issues and feedback.