diff --git a/README.md b/README.md index 1ea992a827f61154ed508207eb6d275e4f09448e..9f32da8ac0395415f481a7f8e8da38e3a9ebbfe4 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,67 @@ # Getting started +To run the different tutorials made by QIM, you will be using Python and Jupyter Notebooks. I you don't have a working installation of Python, you can choose to either: **Option A**: run the tutorials online using binder or **Option B**: create a local installation of Python and Jupyter Notebooks using Miniconda (faster to install), or Anaconda. Follow the instructions below. + +## Option A: Running the tutorials with binder +You can run the tutorials on Jupyter Notebook from Binder by clicking on the Binder link you will find in the README document of the tutorials you are interested in. + +## Option B: Configuring a local setup +If you want to configure a local setup, so that you can also use Python in the future, follow the instructions below. + +### 1. Get the tutorial material +Clone the repository, or just download it as a .zip. + +### 1. Installation of framework for Jupyter Notebooks +We suggest you run Jupyter Notebooks via **Miniconda** if you want a faster installation, you may prefer Anaconda if you plan to continue runing Jupyter Notebooks and Python in the future. + +1. Go to https://docs.conda.io/en/latest/miniconda.html and download the latest version + - Mac: Choose the `.pkg` +2. Install Miniconda + - Windows: + - Execute the `.exe` + - Use default installation location and options. + - Mac: + - Execute the `.pkg` + - Select a location for the installation + - If in MacOS Catalina or later, you have to do some extra steps: + - Open a terminal window + - Run `source <location of installation>/opt/miniconda3/bin/activate` + - Run `conda init zsh` + - Linux: + - Navigate to the folder with the downloaded `.sh` file + - Open the terminal in this folder (right click on the folder and select open terminal) + - Change permissions to install by running `chmod 700 <filename>.sh` + - To install, type `<filename>.sh` + +### 2. Set up environment +You can run the file called environment.yml to install the required packages via the command line. 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-esrf` and press enter. + +Windows +1. Open Anaconda Prompt. +2. `cd <workshop_path>`, where workshop_path is the absolute (full) path to the esrf-um-2021-master folder. +3. Type `conda env create -f environment.yml` and press enter. +4. Type `conda activate qim-esrf` and press enter. + +### 4. Install the tool demonstrated in the tutorial +In the case of the layered surfaces tutorials, install package using `pip install slgbuilder` to get the implementation from this [repository](https://github.com/Skielex/slgbuilder). + +In the case of the structure tensor, the tutorial notebook for structure tensor will automatically clone the repository of the structure tensor tool. If that were to fail, follow the steps below. + +_Option 2_ +1. Download the [repository](https://lab.compute.dtu.dk/QIM/structure-tensor) as a .zip file +2. Extract the .zip file +3. Rename the directory from structure-tensor-master to structure_tensor +4. Place the directory inside esrf-um-2021-master/Structure Tensor/ + +### 5. Open Jupyter Notebooks +In the same terminal window where you activated the environment, type `jupyter notebook`. + +You are ready! You can now navigate to the tutorial of interest =)