From ad73eb3dbbefbbb37024a4408691ba6f081b3540 Mon Sep 17 00:00:00 2001 From: Constantin Pape Date: Sat, 21 Dec 2024 18:48:10 +0100 Subject: [PATCH] Update conda environments and CI (#814) Simplify installation and update installation instructions --- .github/doc_env.yaml | 1 - .github/workflows/build_installers.yaml | 2 +- .github/workflows/test.yaml | 2 +- doc/annotation_tools.md | 4 +- doc/contributing.md | 8 +-- doc/faq.md | 8 +-- doc/installation.md | 66 +++++++++++-------- doc/start_page.md | 4 +- environment.yaml | 30 +++++++++ ...nment_cpu.yaml => environment_cpu_win.yaml | 0 ...nment_gpu.yaml => environment_gpu_win.yaml | 0 11 files changed, 82 insertions(+), 43 deletions(-) create mode 100644 environment.yaml rename environment_cpu.yaml => environment_cpu_win.yaml (100%) rename environment_gpu.yaml => environment_gpu_win.yaml (100%) diff --git a/.github/doc_env.yaml b/.github/doc_env.yaml index 0e3769b4d..bf830c57f 100644 --- a/.github/doc_env.yaml +++ b/.github/doc_env.yaml @@ -1,5 +1,4 @@ channels: - - pytorch - conda-forge name: sam diff --git a/.github/workflows/build_installers.yaml b/.github/workflows/build_installers.yaml index 0ca5c18f4..699c3c489 100644 --- a/.github/workflows/build_installers.yaml +++ b/.github/workflows/build_installers.yaml @@ -24,7 +24,7 @@ jobs: RUN_SCRIPT: | python version_getter.py mkdir ./${{ matrix.os }}_x86_64 - constructor --output-dir ./${{ matrix.os }}_x86_64 --config-filename construct_${{ matrix.os }}.yaml . + constructor --output-dir ./${{ matrix.os }}_x86_64 --config-filename construct_${{ matrix.os }}.yaml . steps: - name: checkout diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 779dbbbb8..412e19b79 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -31,7 +31,7 @@ jobs: - name: Setup micromamba uses: mamba-org/setup-micromamba@v1 with: - environment-file: environment_cpu.yaml + environment-file: ${{ runner.os == 'Windows' && 'environment_cpu_win.yaml' || 'environment.yaml' }} create-args: >- python=${{ matrix.python-version }} diff --git a/doc/annotation_tools.md b/doc/annotation_tools.md index 4692ed1a2..8527e2dfb 100644 --- a/doc/annotation_tools.md +++ b/doc/annotation_tools.md @@ -22,8 +22,8 @@ You can find additional information on the annotation tools [in the FAQ section] HINT: If you would like to start napari to use `micro-sam` from the plugin menu, you must start it by activating the environment where `micro-sam` has been installed using: ```bash -$ mamba activate -$ napari +conda activate +napari ``` diff --git a/doc/contributing.md b/doc/contributing.md index 0be1717e3..a7069dbd1 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -37,10 +37,10 @@ We use [conda](https://docs.conda.io/en/latest/) to [manage our environments](ht Now you can create the environment, install user and developer dependencies, and micro-sam as an editable installation: ```bash -$ mamba env create environment_gpu.yaml -$ mamba activate sam -$ python -m pip install requirements-dev.txt -$ python -m pip install -e . +conda env create environment.yaml +conda activate sam +python -m pip install requirements-dev.txt +python -m pip install -e . ``` ### Make your changes diff --git a/doc/faq.md b/doc/faq.md index 3661fefb5..9100a29ad 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -7,12 +7,12 @@ If you encounter a problem or question not addressed here feel free to [open an ### 1. How to install `micro_sam`? -The [installation](https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#installation) for `micro_sam` is supported in three ways: [from mamba](https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#from-mamba) (recommended), [from source](https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#from-source) and [from installers](https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#from-installer). Check out our [tutorial video](https://youtu.be/gcv0fa84mCc) to get started with `micro_sam`, briefly walking you through the installation process and how to start the tool. +The [installation](https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#installation) for `micro_sam` is supported in three ways: [from conda](https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#from-conda) (recommended), [from source](https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#from-source) and [from installers](https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#from-installer). Check out our [tutorial video](https://youtu.be/gcv0fa84mCc) to get started with `micro_sam`, briefly walking you through the installation process and how to start the tool. ### 2. I cannot install `micro_sam` using the installer, I am getting some errors. The installer should work out-of-the-box on Windows and Linux platforms. Please open an issue to report the error you encounter. ->NOTE: The installers enable using `micro_sam` without mamba or conda. However, we recommend the installation from mamba / from source to use all its features seamlessly. Specifically, the installers currently only support the CPU and won't enable you to use the GPU (if you have one). +>NOTE: The installers enable using `micro_sam` without conda. However, we recommend the installation from conda or from source to use all its features seamlessly. Specifically, the installers currently only support the CPU and won't enable you to use the GPU (if you have one). ### 3. What is the minimum system requirement for `micro_sam`? @@ -40,7 +40,7 @@ Having a GPU will significantly speed up the annotation tools and especially the ### 5. I am missing a few packages (eg. `ModuleNotFoundError: No module named 'elf.io`). What should I do? -With the latest release 1.0.0, the installation from mamba and source should take care of this and install all the relevant packages for you. +With the latest release 1.0.0, the installation from conda and source should take care of this and install all the relevant packages for you. So please reinstall `micro_sam`, following [the installation guide](#installation). ### 6. Can I install `micro_sam` using pip? @@ -132,7 +132,7 @@ We want to remove these errors, so we would be very grateful if you can [open an ### 10. The objects are not segmented in my 3d data using the interactive annotation tool. -The first thing to check is: a) make sure you are using the latest version of `micro_sam` (pull the latest commit from master if your installation is from source, or update the installation from conda / mamba using `mamba update micro_sam`), and b) try out the steps from the [3d annotation tutorial video](https://youtu.be/nqpyNQSyu74) to verify if this shows the same behaviour (or the same errors) as you faced. For 3d images, it's important to pass the inputs in the python axis convention, ZYX. +The first thing to check is: a) make sure you are using the latest version of `micro_sam` (pull the latest commit from master if your installation is from source, or update the installation from conda using `conda update micro_sam`), and b) try out the steps from the [3d annotation tutorial video](https://youtu.be/nqpyNQSyu74) to verify if this shows the same behaviour (or the same errors) as you faced. For 3d images, it's important to pass the inputs in the python axis convention, ZYX. c) try using a different model and change the projection mode for 3d segmentation. This is also explained in the video. diff --git a/doc/installation.md b/doc/installation.md index c155f02c1..ccef6097f 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,77 +1,87 @@ # Installation There are three ways to install `micro_sam`: -- [From mamba](#from-mamba) is the recommended way if you want to use all functionality. +- [From conda](#from-conda) is the recommended way if you want to use all functionality. - [From source](#from-source) for setting up a development environment to use the latest version and to change and contribute to our software. -- [From installer](#from-installer) to install it without having to use mamba (supported platforms: Windows and Linux, supports only CPU). +- [From installer](#from-installer) to install it without having to use conda (supported platforms: Windows and Linux, supports only CPU). You can find more information on the installation and how to troubleshoot it in [the FAQ section](#installation-questions). -We do **not** recommend installing `micro-sam` with pip. +We do **not support** installing `micro_sam` with pip. -## From mamba +## From conda -[mamba](https://mamba.readthedocs.io/en/latest/) is a drop-in replacement for conda, but much faster. -The steps below may also work with `conda`, but we recommend using `mamba`, especially if the installation does not work with `conda`. -You can follow the instructions [here](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html) to install `mamba`. +`conda` is a python package manager. If you don't have it installed yet you can follow the instructions [here](https://conda-forge.org/download/) to set it up on your system. +Please make sure that you are using an up-to-date version of conda to install `micro_sam`. +You can also use [mamba](https://mamba.readthedocs.io/en/latest/), which is a drop-in replacement for conda, to install it. In this case, just replace the `conda` command below with `mamba`. -**IMPORTANT**: Make sure to avoid installing anything in the base environment. +**IMPORTANT**: Do not install `micro_sam` in the base conda environment. + +**Installation on Linux and Mac OS:** `micro_sam` can be installed in an existing environment via: ```bash -$ mamba install -c pytorch -c conda-forge micro_sam +conda install -c conda-forge micro_sam ``` -or you can create a new environment (here called `micro-sam`) via: - +or you can create a new environment with it (here called `micro-sam`) via: ```bash -$ mamba create -c pytorch -c conda-forge -n micro-sam micro_sam +conda create -c conda-forge -n micro-sam micro_sam ``` - -if you want to use the GPU you need to install PyTorch from the `pytorch` channel instead of `conda-forge`. For example: - +and then activate it via ```bash -$ mamba create -c pytorch -c nvidia -c conda-forge -n micro-sam micro_sam pytorch pytorch-cuda=12.1 +conda activate micro-sam ``` -NOTE: If you create a new enviroment (eg. here called `micro-sam`), you must activate the environment using - +This will also install `pytorch` from the `conda-forge` channel. If you have a recent enough operating system, it will automatically install the best suitable `pytorch` version on your system. +This means it will install the CPU version if you don't have a nVidia GPU, and will install a GPU version if you have. +However, if you have an older operating system, or a CUDA version older than 12, than it may not install the correct version. In this case you will have to specify you're CUDA version, for example for CUDA 11, like this: ```bash -$ mamba activate micro-sam +conda install -c conda-forge micro_sam "libtorch=*=cuda11*" ``` -You may need to change this command to install the correct CUDA version for your system, see [https://pytorch.org/](https://pytorch.org/) for details. +**Installation on Windows:** +`pytorch` is currently not available on conda-forge for windows. Thus, you have to install it from the `pytorch` conda channel. In addition, you have to specify two specific dependencies to avoid incompatibilities. +This can be done with the following commands: +```bash +conda install -c pytorch -c conda-forge micro_sam "nifty=1.2.1=*_4" "protobuf<5" +``` +to install `micro_sam` in an existing environment and +```bash +conda create -c conda-forge -n micro-sam micro_sam "nifty=1.2.1=*_4" "protobuf<5" +``` ## From source To install `micro_sam` from source, we recommend to first set up an environment with the necessary requirements: -- [environment_gpu.yaml](https://github.com/computational-cell-analytics/micro-sam/blob/master/environment_gpu.yaml): sets up an environment with GPU support. -- [environment_cpu.yaml](https://github.com/computational-cell-analytics/micro-sam/blob/master/environment_cpu.yaml): sets up an environment with CPU support. +- [environment.yaml](https://github.com/computational-cell-analytics/micro-sam/blob/master/environment.yaml): to set up an environment on Linux or Mac OS. +- [environment_cpu_win.yaml](https://github.com/computational-cell-analytics/micro-sam/blob/master/environment_cpu_win.yaml): to set up an environment on windows with CPU support. +- [environment_gpu_win.yaml](https://github.com/computational-cell-analytics/micro-sam/blob/master/environment_gpu_win.yaml): to set up an environment on windows with GPU support. To create one of these environments and install `micro_sam` into it follow these steps 1. Clone the repository: ```bash -$ git clone https://github.com/computational-cell-analytics/micro-sam +git clone https://github.com/computational-cell-analytics/micro-sam ``` 2. Enter it: ```bash -$ cd micro-sam +cd micro-sam ``` -3. Create the GPU or CPU environment: +3. Create the respective environment: ```bash -$ mamba env create -f .yaml +conda env create -f .yaml ``` 4. Activate the environment: ```bash -$ mamba activate sam +conda activate sam ``` 5. Install `micro_sam`: @@ -89,7 +99,7 @@ We also provide installers for Linux and Windows: - [Mac](https://owncloud.gwdg.de/index.php/s/7YupGgACw9SHy2P) --> -The installers will not enable you to use a GPU, so if you have one then please consider installing `micro_sam` via [mamba](#from-mamba) instead. They will also not enable using the python library. +The installers will not enable you to use a GPU, so if you have one then please consider installing `micro_sam` via [conda](#from-conda) instead. They will also not enable using the python library. ### Linux Installer: diff --git a/doc/start_page.md b/doc/start_page.md index 9364b20b7..a416a7325 100644 --- a/doc/start_page.md +++ b/doc/start_page.md @@ -21,9 +21,9 @@ If you run into any problems or have questions please [open an issue](https://gi ## Quickstart -You can install `micro_sam` via mamba: +You can install `micro_sam` via conda: ```bash -$ mamba install -c conda-forge micro_sam +conda install -c conda-forge micro_sam ``` We also provide installers for Windows and Linux. For more details on the available installation options, check out [the installation section](#installation). diff --git a/environment.yaml b/environment.yaml new file mode 100644 index 000000000..26c61f526 --- /dev/null +++ b/environment.yaml @@ -0,0 +1,30 @@ +name: sam +channels: + - conda-forge +dependencies: + - nifty >=1.2.1 + - imagecodecs + - magicgui + - napari >=0.5.0 + - natsort + - pip + - pooch + - pyqt + - python-xxhash + - python-elf >=0.4.8 + # Note: installing the pytorch package from conda-forge will generally + # give you the most optmized version for your system, if you have a modern + # enough OS and CUDA version (CUDA >= 12). For older versions, you can + # specify the CUDA version by pinning libtorch. + # For example, add this line for a CUDA 11 version: + # - libtorch=*=cuda11* + # or, to enforce a CPU installation, change to + # - "pytorch=*=cpu*" + - pytorch >=2.4 + - segment-anything + - torchvision + - torch_em >=0.7.0 + - tqdm + - timm + - pip: + - git+https://github.com/ChaoningZhang/MobileSAM.git diff --git a/environment_cpu.yaml b/environment_cpu_win.yaml similarity index 100% rename from environment_cpu.yaml rename to environment_cpu_win.yaml diff --git a/environment_gpu.yaml b/environment_gpu_win.yaml similarity index 100% rename from environment_gpu.yaml rename to environment_gpu_win.yaml