Merge pull request SCIInstitute#1335 from SCIInstitute/just_conda_act…

…ivate

Add activate/deactivate scripts to conda so executables are available when ShapeWorks is installed

.github/workflows/build-linux.yml

@@ -62,7 +62,7 @@ jobs:
 
     - name: conda installs
       shell: bash -l {0}
-      run: source ./conda_installs.sh
+      run: source ./install_shapeworks.sh
 
     - name: install ccache
       shell: bash -l {0}

.github/workflows/build-mac.yml

@@ -61,7 +61,7 @@ jobs:
 
     - name: conda installs
       shell: bash -l {0}
-      run: source ./conda_installs.sh
+      run: source ./install_shapeworks.sh
 
     - name: install ccache
       shell: bash -l {0}

.github/workflows/build-windows.yml

@@ -60,7 +60,7 @@ jobs:
 
     - name: conda installs
       shell: bash -l {0}
-      run: source ./conda_installs.sh
+      run: source ./install_shapeworks.sh
 
     - name: Cache dependencies
       id: cache-dependencies

Installation/conda_env_setup.bat

@@ -0,0 +1,18 @@
+setlocal EnableDelayedExpansion
+
+:: format windows path into posix path
+set BIN_PATH=%cd%\bin
+set BIN_PATH=%BIN_PATH:\=/%
+set BIN_PATH=/%BIN_PATH::=%
+
+:: Copy the [de]activate scripts to %PREFIX%\etc\conda\[de]activate.d.
+:: This will allow them to be run on environment activation.
+for %%F in (activate deactivate) DO (
+    if not exist "%CONDA_PREFIX%\etc\conda\%%F.d" mkdir "%CONDA_PREFIX%\etc\conda\%%F.d"
+    copy .\Installation\shapeworks-%%F.bat "%CONDA_PREFIX%\etc\conda\%%F.d\shapeworks-%%F.bat"
+    call python .\Installation\replace_strings.py "%CONDA_PREFIX%\etc\conda\%%F.d\shapeworks-%%F.bat" shapeworks_placeholder_string "%cd%\bin"
+
+    :: Copy unix shell activation scripts, needed by Windows Bash users
+    copy .\Installation\shapeworks-%%F.sh "%CONDA_PREFIX%\etc\conda\%%F.d\shapeworks-%%F.sh"
+    call python .\Installation\replace_strings.py "%CONDA_PREFIX%\etc\conda\%%F.d\shapeworks-%%F.sh" shapeworks_placeholder_string "\"%BIN_PATH%\""
+)

Installation/conda_env_setup.sh

@@ -0,0 +1,10 @@
+#!/bin/bash -x
+
+# Copy the [de]activate scripts to $CONDA_PREFIX/etc/conda/[de]activate.d.
+# This will allow them to be run on environment activation.
+for CHANGE in "activate" "deactivate"
+do
+    mkdir -p "${CONDA_PREFIX}/etc/conda/${CHANGE}.d"
+    cp "./Installation/shapeworks-${CHANGE}.sh" "${CONDA_PREFIX}/etc/conda/${CHANGE}.d/shapeworks-${CHANGE}.sh"
+    python ./Installation/replace_strings.py "${CONDA_PREFIX}/etc/conda/${CHANGE}.d/shapeworks-${CHANGE}.sh" shapeworks_placeholder_string "\"`pwd`/bin\""
+done

install_python_module.bat → Installation/install_python_module.bat

@@ -6,4 +6,8 @@ call pip install Python\shapeworks
 
 set CONDA_INSTALL_DIR=%CONDA_PREFIX%\lib\site-packages\shapeworks
 
-call python .\update_installed_python_module_binary_path.py "%CONDA_INSTALL_DIR%\setup_path.py" "%cd%\bin"
+:: format windows path to use forward slashes
+set BIN_PATH=%cd%\bin
+set BIN_PATH=%BIN_PATH:\=/%
+
+call python .\Installation\replace_strings.py "%CONDA_INSTALL_DIR%\setup_path.py" placeholder_string %BIN_PATH%

install_python_module.sh → Installation/install_python_module.sh

@@ -8,4 +8,4 @@ if ! pip install Python/shapeworks; then exit -1; fi
 
 CONDA_INSTALL_DIR=`pip show shapeworks | grep Location | awk '{print $2}'`/shapeworks
 
-python ./update_installed_python_module_binary_path.py $CONDA_INSTALL_DIR/setup_path.py `pwd`/bin
+python ./Installation/replace_strings.py $CONDA_INSTALL_DIR/setup_path.py placeholder_string `pwd`/bin

Installation/replace_strings.py

@@ -0,0 +1,20 @@
+import sys
+import fileinput
+
+"""
+Replaces strings in a file.
+"""
+def replace_strings(file, search_exp, replace_exp):
+    for line in fileinput.input(file, backup='', inplace=1):
+        if search_exp in line:
+            line = line.replace(search_exp, replace_exp)
+        sys.stdout.write(line)
+
+if __name__ == "__main__":
+    if len(sys.argv[1:]) != 3:
+        print(f'params: <file> <search string> <replace string>')
+        sys.exit(1)
+    FILE = sys.argv[1]
+    FIND = sys.argv[2]
+    REPL = sys.argv[3]
+    replace_strings(FILE, FIND, REPL)

Installation/shapeworks-activate.bat

@@ -0,0 +1,7 @@
+@echo off
+
+REM Store _SHAPEWORKS_BIN_PATH to be removed on conda deactivate.
+set _SHAPEWORKS_BIN_PATH=shapeworks_placeholder_string
+
+REM Add _SHAPEWORKS_BIN_PATH to PATH on conda activate.
+set PATH=%_SHAPEWORKS_BIN_PATH%;%PATH%

Installation/shapeworks-activate.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+# Store _SHAPEWORKS_BIN_PATH to be removed on conda deactivate.
+export _SHAPEWORKS_BIN_PATH=shapeworks_placeholder_string
+
+# Add _SHAPEWORKS_BIN_PATH to PATH on conda activate.
+export PATH=$_SHAPEWORKS_BIN_PATH:$PATH

Installation/shapeworks-deactivate.bat

@@ -0,0 +1,7 @@
+@echo off
+setlocal EnableDelayedExpansion
+
+REM Restore original PATH on conda deactivate.
+if defined _SHAPEWORKS_BIN_PATH (
+    set PATH=!PATH:%_SHAPEWORKS_BIN_PATH%;=!
+)

Installation/shapeworks-deactivate.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# Restore original PATH on conda deactivate.
+if [[ -z "$_SHAPEWORKS_BIN_PATH" ]]; then
+    export PATH=`echo $PATH | sed "s*$_SHAPEWORKS_BIN_PATH:**g"`
+fi

Python/shapeworks/shapeworks/setup_path.py

@@ -1,3 +1,3 @@
 def setup_binary_path():
     import sys
-    sys.path.append("")
+    sys.path.append("placeholder_string")

Support/package.sh

@@ -48,9 +48,8 @@ cp -a $INSTALL_DEP_DIR/* "package/${VERSION}"
 cp -a $INSTALL_DIR/* "package/${VERSION}"
 cp -a Examples "package/${VERSION}"
 cp -a Python "package/${VERSION}"
-cp conda_installs.sh package/${VERSION}
-cp install_python_module.sh package/${VERSION}
-cp update_installed_python_module_binary_path.py package/${VERSION}
+cp -a Installation "package/${VERSION}"
+cp install_shapeworks.sh package/${VERSION}
 cp docs/about/release-notes.md package/${VERSION}
 
 if [[ "$OSTYPE" == "darwin"* ]]; then

Support/shapeworks.nsi

@@ -64,14 +64,13 @@ Section "ShapeWorks (required)"
   SetOutPath $INSTDIR
 
   ; Put file there
-  File "conda_installs.bat"
-  File "install_python_module.bat"
-  File "update_installed_python_module_binary_path.py"
+  File "install_shapeworks.bat"
   File "Windows_README.txt"
   File /r "bin"
   File /r "Examples"
   File /r "Python"
   File /r "Documentation"
+  File /r "Installation"
 
 
   ; Write the installation path into the registry

docs/deep-learning/data-augmentation.md

@@ -4,7 +4,7 @@ ShapeWorks includes a Python package, `DataAugmentationUtils`, that supports mod
 
 ## Using the Data Augmentation Package
 
-The ShapeWorks data augmentation package, `DataAugmentationUtils`, is installed to the ShapeWorks anaconda environment when `conda_installs.sh` is run. 
+The ShapeWorks data augmentation package, `DataAugmentationUtils`, is installed with the rest of the ShapeWorks Anaconda environment using `install_shapeworks`.
 
 
 !!! danger "Activate shapeworks environment"

docs/deep-learning/deep-ssm.md

@@ -60,7 +60,7 @@ We then compare the original mesh to the predicted mesh via surface-to-surface d
 
 ## Using the DeepSSM Python Package
 
-The ShapeWorks DeepSSM package, `DeepSSMUtils`, is installed to the ShapeWorks anaconda environment when `conda_installs.sh` is run. 
+The ShapeWorks DeepSSM package, `DeepSSMUtils`, is installed with the rest of the ShapeWorks Anaconda environment using `install_shapeworks`.
 
 !!! danger "Activate shapeworks environment"
     Each time you use ShapeWorks and/or its Python packages, you must first activate its environment using the `conda activate shapeworks` command on the terminal.

docs/deep-learning/pytorch-gpu.md

@@ -1,12 +1,10 @@
 # PyTorch GPU Support for ShapeWorks
 
 ShapeWorks deep learning tools, such as the `DeepSSMUtils` package, requires PyTorch with GPU support. 
-This is installed to the `shapeworks` conda environment when `conda_installs.sh` is run. 
+This is installed with the rest of the ShapeWorks Anaconda environment using `install_shapeworks`. 
+It selects the most recent stable release of PyTorch which can be found at [pytorch.org](https://pytorch.org/).  
 
-Currently `conda_installs.sh` installs the most recent stable release of PyTorch which can be found at [pytorch.org](https://pytorch.org/).  
-When installing, `conda_installs.sh` checks which CUDA driver version is installed on the system and if it finds teh CUDA version is supported by the most recent 
-PyTorch version, the PyTorch with GPU support is installed.
-If an incompatible version of the CUDA driver is found, then `conda_installs.sh` installs CPU PyTorch instead. 
+When the Anaconda enironment is created using `install_shapeworks`, PyTorch with GPU support is installed if the system's current CUDA driver version is supported. Otherwise it selects the CPU version of PyTorch.
 
 ## Checking if PyTorch installation has GPU support
 To check if your `shapeworks` environment has PyTorch with GPU support, run the following:
@@ -21,12 +19,13 @@ If `torch.cuda.is_available()` is True then PyTorch has GPU support, otherwise t
 If `torch` cannot be imported than PyTorch was not installed to the `shapeworks` environment. 
 
 ## Reinstalling the Correct Pytorch Version
-The following steps explain how to include a different PyTorch version in the `shapeworks` conda environment if you find that your system requires an older version 
-of PyTorch or `conda_installs.sh` does not correcty find your CUDA version.
+
+If you find that your system requires an older version of PyTorch or `install_shapeworks` did not correcty find your CUDA version, 
+the following steps explain how to install a different PyTorch version in the `shapeworks` conda environment.
 
 Deltailed instructions about the different ways to install PyTorch can be found here: [PyTorch Getting Started](https://pytorch.org/get-started/locally/).
 
-1. If `conda_installs.sh` has already been run and the CPU version of PyTorch was installed, first that needs to be uninstalled. To uninstall run:
+1. If the CPU version of PyTorch was installed, that first needs to be uninstalled. To uninstall run:
 ```
 conda activate shapeworks
 conda uninstall pytorch

docs/dev/build.md

@@ -41,8 +41,9 @@ We use Anaconda (conda) to install many dependencies required for both building
 
 To install conda and the dependencies it provides (currently requires either bash or zsh shell), run:
 ```
-$ source conda_installs.sh
+$ source install_shapeworks.sh [environment name]`  
 ```
+**Note:** By default this creates an environment named **shapeworks**, but you can specify a different name and it's okay to have multiple environments.  
 
 ShapeWorks uses *[git-lfs](https://github.com/git-lfs/git-lfs/)* to store image data for testing.  If git-lfs was not already installed before cloning ShapeWorks, please use the following commands to get this data:  
 ```
@@ -93,7 +94,9 @@ Download and install [[Anaconda]](https://www.anaconda.com/).
 !!! important
     It is recommended **not** to add Anaconda to your PATH and **not** to register Anaconda as your default Python.  
 
-Using the *Anaconda Prompt*, run `conda_installs.bat`  
+Using the *Anaconda Prompt*, run `install_shapeworks.bat [environment name]`  
+**Note:** By default this creates an environment named **shapeworks**, but you can specify a different name and it's okay to have multiple environments.  
+
 
 #### Qt5  
 Download and install the latest version of [Qt5](https://download.qt.io/archive/qt/), selecting the LGPL (free) license (at least version 5.10 required).   

docs/dev/markdown.md

@@ -8,7 +8,7 @@ ShapeWorks documentation is written using [Markdown](#markdown-basics), a text l
 
 ## Grip
 
-To edit your Markdown, it helps to have a convenient viewer. The `grip` instant preview application is beneficial, and is installed by the conda_installs script (see [How to Build ShapeWorks from Source?](build.md). From the ShapeWorks directory, just run `grip` (be sure to `conda activate shapeworks` beforehand), and then navigate to `http://localhost:6419` in your favorite browser. It will load and display markdown files just like GitHub, showing README.md by default. You can also specify relative paths to any markdown file below the directory from which it was run. Happy editing!
+To edit your Markdown, it helps to have a convenient viewer. The `grip` instant preview application is beneficial, and is installed by the install_shapeworks script (see [How to Build ShapeWorks from Source?](build.md). From the ShapeWorks directory, just run `grip` (be sure to `conda activate shapeworks` beforehand), and then navigate to `http://localhost:6419` in your favorite browser. It will load and display markdown files just like GitHub, showing README.md by default. You can also specify relative paths to any markdown file below the directory from which it was run. Happy editing!
 
 ## Markdown Basics
 

docs/use-cases/deep-ssm-femur.md

@@ -34,7 +34,7 @@ This calls `deep_ssm.py` (in `Examples/Python/`) to perform the following.
 * Creates a DeepSSM model as described in [SSMs Directly from Images](../deep-learning/deep-ssm.md) and uses it to make predictions on unseen images.
 
 !!! danger "On CUDA"
-    This use case uses Pytorch and requires a GPU to run in a timely manner. When you run `conda_installs.sh`, it detects if you have a GPU and and installs the version of Pytorch compatible with your version of CUDA. 
+    This use case uses Pytorch and requires a GPU to run in a timely manner. When you source `install_shapeworks.sh`, it detects if you have a GPU and and installs the version of Pytorch compatible with your version of CUDA. 
 
     Note we only support the three most recent versions of CUDA. If your GPU requires an older CUDA version, you will need to update the Pytorch install in your shapeworks conda environment to the correct CUDA version. For more information on doing so, see [pytorch.org](https://pytorch.org/). 
 

docs/users/Linux_README.txt

@@ -1,41 +1,72 @@
+==========================================
+ ShapeWorks   v6.1.0 - Released June 2021
+==========================================
+
+The ShapeWorks software is an open-source distribution of a new method for
+constructing compact statistical point-based models of ensembles of similar
+shapes that does not rely on any specific surface parameterization. The method
+requires very little preprocessing or parameter tuning and applies to a wide
+range of shape analysis problems, including nonmanifold surfaces and objects of
+arbitrary topology. The proposed correspondence point optimization uses an
+entropy-based minimization that balances the simplicity of the model
+(compactness) with the accuracy of the surface representations. The ShapeWorks
+software includes tools for preprocessing data, computing point-based shape
+models, and visualizing the results.
 
-=====================
-Shapeworks
 =====================
 
-The ShapeWorks software is an open-source distribution of a new method for constructing compact statistical point-based models of ensembles of similar shapes that does not rely on any specific surface parameterization. The method requires very little preprocessing or parameter tuning and applies to a wide range of shape analysis problems, including nonmanifold surfaces and objects of arbitrary topology. The proposed correspondence point optimization uses an entropy-based 
-minimization that balances the simplicity of the model (compactness) with the accuracy of the surface representations. The ShapeWorks software includes tools for preprocessing data, computing point-based shape models, and visualizing the results.
+You have downloaded a binary distribution of ShapeWorks.
 
-=====================
+### Installation instructions.
 
-You have downloaded a binary distribution of ShapeWorks.
+1. Open a terminal and change directory to the installation path (where you unzipped the downloaded file).
+`cd /path/to/shapeworks`
+
+2. Create a protected conda environment that installs everything necessary to run.
+`source install_shapeworks.sh`
 
-1. Open a terminal and change directory to the installation path (where you unzipped the downloaded file): `cd /path/to/shapeworks`
+  **Note:** You can pass a different name for the environment, enabling multiple installations.
+  `source install_shapeworks.sh shapeworks_61`
 
-2. Add the path to the shapeworks executables to your PATH: `export PATH=`pwd`/bin:$PATH`
+**Important:** Your shapeworks conda environment must always be activated before using ShapeWorks.
 
 
-ShapeWorks comes with Python examples to get you started. To run them:
+### ShapeWorks comes with Python examples to get you started.
 
-1. Open a terminal and change directory to the installation path (where you unzipped the downloaded file): `cd /path/to/shapeworks`
+1. Open a terminal and activate the shapeworks conda environment (use the environment name passed to `install_shapeworks` above).
+`conda activate shapeworks`
 
-2. type `source conda_installs.sh` to install necessary Python packages into a protected environment.
+2. Copy the Examples folder to another location of your choosing.
+`cp -r Examples $HOME/ShapeWorks-Examples`
 
-3. Copy the Examples folder to another location (ex: `cp -r Examples $HOME/ShapeWorks-Examples`).
+3. Change to the Python folder of the Examples directory you copied.
+`cd $HOME/ShapeWorks-Examples/Python`
 
-4. Activate the shapeworks conda environment: `conda activate shapeworks`
+4. Run one of the included use cases. To list them all, run: `python RunUseCase.py --help`.
+`python RunUseCase.py --use_case ellipsoid_fd`
 
-5. With the shapeworks conda environment activated, `cd` to your copied Examples\Python location.
 
-6. Run `python RunUseCase.py --use_case <insert name of use case here>`. To list the use cases that are currently released, run: `python RunUseCase.py --help`.
+### ShapeWorks also includes interactive Jupyter Python notebook examples.
 
-**Note:** For subsequent usage, the shapeworks conda environment must be activated using `conda activate shapeworks`.
+1. Open a terminal and activate the shapeworks conda environment (use the environment name passed to `install_shapeworks` above).
+`conda activate shapeworks`
 
+2. Change to the notebook tutorials folder of the Examples directory you copied.
+`cd $HOME/ShapeWorks-Examples/Python/notebooks/tutorials`
 
-To see the interactive Jupyter notebook examples:
+3. Start the Jupyter notebook server. This will open a new tab in your web brower.
+`jupyter notebook`
 
-1. Open a terminal and change directory to your copied Examples\Python\notebooks\tutorials location.
+4. Click on a notebook to get started.
 
-2. Activate the shapeworks conda environment: `conda activate shapeworks`
 
-3. Run `jupyter notebook` to open the notebooks in your web brower. Click on a notebook to get started.
+=====================
+
+Please contact us with any questions or ideas.
+
+Website    sciinstitute.github.io/ShapeWorks
+Email      [email protected]
+Discourse  shapeworks.discourse.group
+Twitter    @ShapeWorksSuite
+
+=====================