Installation¶
As biom3d integrates a Remote Graphical User Interface (GUI), a Local GUI, a package or Application Programming Interface (API) and a source code, this installation tutorial has been divided into four sections. The first section is addressed to remote GUI-users, non programmers with limited computation means. The second section is addressed to non programmer who would like to use Biom3d on their own computer by using an installer/executable. The third section is for programmer that want the API of biom3d. The fourth section is addressed to programmers who would like to configure a Python environment to install the source code of Biom3d and eventually modify it.
Remote graphical interface¶
Biom3d has been deployed for Windows and macOS only. Use the following link to download the latest executable file (end with Remote): link.
To use Biom3d, double-click on the downloaded file. Then you can follow the remote documentation.
This downloadable version is remote only which means that you must connect to a Linux server where biom3d is installed. To install biom3d on a server, follow the server documentation. You won’t need a powerful computer as every computation will be done one server, however, if you use a dataset that is on your computer, a good internet connexion with the server will speed up the dataset transfert.
You may encounter a security warning as it is not recongnized by Microsoft and Apple, you can ignore it (only for Biom3d, don’t ignore security warning)
Hardware requirement¶
OS
Windows 10 and 11
Ubuntu >=18
macOS 14
Other OS or version have not been tested.
Architecture
Biom3d can run on x86_64 processor (most common for Windows and Linux) and on arm64 processor (for macOS).
Memory
Will mostly depends on your dataset. At least 12GB but we recommend 16GB or higher (lower than 12GB can still work).
GPU
A GPU is not necessary but it is recommended as it is significantly slower without. The GPU must be a Nvidia GPU with CUDA 11 or 12 compatibility (other version have not been tested). AMD with RocM is not implemented yet. Apple Silicon with metal has been implemented but however we couldn’t test it, so if you encounter an issue please share it with us on GitHub. At least 10GB of VRAM is advised (Predictions can be done with less but not training), smaller Graphic card might also work but some reconfiguration might be required (such as the patch size). We tested the following graphic cards: T4, RTX 2080Ti, RTX 3090, P100, V100, A100 and Quadro T1000 (with patch size reduction).
Local graphical interface¶
To use the local version of Biom3d, meaning that computations will be executed on local computer, the simpliest way is to use the given zip for Windows or macOS. You can still use remote mode with this version.
Warning: The local mode means that all the computation will be executed on the local computer, where Biom3d is installed. In this case, check the requirement.
Installation
Download the zip for your OS here
Extract the contained folder in your chosen destination
It is installed, you can now use it, on first use it will scan your computer for GPU and auto-update its environment so it may take several minutes
On macOS, the extracted folder is a
.appso you just have to double clic on itOn Windows, open the folder and double click on
Biom3d.bat
You may encounter a security warning as it is not recongnized by Microsoft and Apple, you can ignore it (only for Biom3d, don’t ignore security warning)
Installing the package¶
Check the requirement first.
There are two types of installations:
Conda installation is easier.
Python environment will be lighter and more versatile.
Python >=3.9 is needed, it is recommened to use python 3.11 as it has been tested and is completly compatible with all dependencies.
To know the CUDA version of your GPU, simply use nvidia-smi
> nvidia-smi
Thu Jul 17 11:43:05 2025
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 457.51 Driver Version: 457.51 CUDA Version: 11.1 |
|-------------------------------+----------------------+----------------------+
| GPU Name TCC/WDDM | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|===============================+======================+======================|
| 0 GeForce GTX 106... WDDM | 00000000:01:00.0 On | N/A |
| 43% 39C P2 22W / 120W | 1054MiB / 6144MiB | 3% Default |
| | | N/A |
+-------------------------------+----------------------+----------------------+
If your card use CUDA 11.x or 12.x you can use PyTorch with CUDA 11.8 or 12.8. Recent version of PyTorch (the ones we uses) comes with CUDA and cuDNN so you don’t have to manually install it.
Conda installation¶
Install Anaconda or Miniforge (which is a lighter and free version of Anaconda).
Start an Anaconda (or Miniforge) prompt. For Windows user, look for “Anaconda prompt” (or “Miniforge prompt”) in your Windows search bar.
Create a new environment (here named
b3dbut it is up to you): (type in the prompt and press Enter)
# If you plan to use the GUI
conda create --name b3d python 3.11 tk
# If you plan to use only command lines (or just the API)
conda create --name b3d python 3.11
Activate your new environment: (type + Enter)
conda activate b3d
Install Pytorch. The best is to look on Pytorch website. Conda is not available anymore so we have to pass through pip. We don’t use
torchaudioortorchvisionso you can remove them.
pip install torch --index-url https://download.pytorch.org/whl/cu118
# Or
pip install torch --index-url https://download.pytorch.org/whl/cu128
# Or (cpu only)
pip install torch
Install OMERO (optionnal)
conda install -c conda-forge zeroc-ice omero-py
# It is important to use --no-deps here to avoid breaking other dependencies
pip install --no-deps ezomero
Here you should have a warning/non blocking error about a conflict between ezomero and numpy as ezomero doesn’t support numpy 2.x, however, using a lower version of numpy would break torch and we confirmed that ezomero work with numpy 2.2.6.
Install biom3d:
pip install biom3d
Python virtual environment¶
Install Python 3.11 link for Windows or
sudo apt install python3.11(if it says it doesn’t exist you may have to usedeadsnakerepositorysudo add-apt-repository ppa:deadsnakes/ppa && sudo apt update)If you want to use the GUI, you must install
tkinter, on Windows it should be included in python installation (or restart the installtaion > custom installation > tick tcl/tk and IDLE), on Linuxsudo apt install python3.11 tk.Setup a new Python environment before installing Biom3d. You can do that by opening a new terminal or the Command Prompt in Windows (type ‘cmd’ in the Windows search bar) and type:
python -m venv b3d
If you have several version of python you can make a specific call, you can replace every
pythonwithpython3.11and everypipbypython3.11 -m pipto be sure it use the good version.
python3.11 -m venv b3d
This command will create a folder where the command prompt/terminal is opened (on Windows by default it will be
C:\Users\your_username). If you want to change this path either you can typecd path/to/your/folderor, in Windows, open a Windows folder explorer in the appropriate location and type in the path location barcmd.
If you have an error indicating that Python cannot be found on your system, please make sure that you have tick the box “Add Python to environment variable” during installation, or, add Python to your environment variables How to install Python on Windows.
Activate your new environment:
(for Windows users)
b3d\Scripts\activate
(for Linux users)
source b3d/bin/activate
Install Pytorch. Go to Pytorch website and install Pytorch with Pip and the right OS and CUDA version. Once installed in your virtual environment, please make sure that you have access to your NVidia GPU with the following command:
python -c "import torch; print(torch.cuda.is_available())".
pip install torch --index-url https://download.pytorch.org/whl/cu118
# Or
pip install torch --index-url https://download.pytorch.org/whl/cu128
# Or (cpu only)
pip install torch
If the previous requirements are fulfilled, install the API of biom3d:
pip install biom3d
If would like to use OMERO as well, type the following: On Windows
Warning: On Windows,
omero-pyalways tries to recompile manuallyzeroc-ice. So we preinstallomero-pydependencies mannually before installing it without dependencies.ezomeroalso need to be installed without dependencies or it would break other packages.
On Windows :
pip install zeroc-ice==3.6.5
pip install pillow future portalocker pywin32 requests "urllib3<2"
#Forced to do --no-deps because it would try to reinstall zeroc-ice by compiling it
pip install omero-py --no-deps
pip install ezomero --no-deps
On Linux :
pip install https://github.com/glencoesoftware/zeroc-ice-py-linux-x86_64/releases/download/20240202/zeroc_ice-3.6.5-cp311-cp311-manylinux_2_28_x86_64.whl
pip install omero-py
pip install ezomero --no-deps
(Optionally) You can try to start the GUI:
python -m biom3d.gui
# Or
Biom3d
Source code¶
Please first follow the requirements detailed in the installating as a package.
Once PyTorch installed (eventually tkinter and omero-py too), you can download the source code via GitHub by cloning the Biom3d repository:
git clone https://github.com/GuillaumeMougeot/biom3d.git
Or by forking the repository with your GitHub account and cloning it after.
cd to your newly downloaded biom3d repository and the installation can be completed with the following command (after activating your pip environment):
pip install -e .
Optional: If planning to edit the documentation, please use the following command:
pip install -e .[docs]
We also used pydocstyle for documentation linting so you can add
pip install pydocstyle