Skip to content

Installation

Usage of AFMSlicer and the Napari plugin require installation and usage of a Python Virtual Environment. This page details how to setup a Python virtual environment using uv and how to install AFMSlicer and the Napari plugin within this virtual environment.

Virtual Environment

We recommend using uv to install and manage your virtual environments but you do not have to. Other options such virtualenvwrapper and MiniForge also allow you to create and manage virtual environments but are not covered here.

Install uv

uv has excellent instructions on how to install the software on different operating systems.

Create a project folder

You need somewhere to undertake the work of processing images with AFMSlicer. There are two strategies that could be employed here...

  • Create a single directory for installing AFMSlicer virtual environment and have nested directories for each project/set of images.
  • Create a virtual environment in each directory of images you wish to process.

The following instructions assume the former approach and that the directory is called AFMSlicer and is located under the users home directory work/

Create a Virtual Environment

To create a virtual environment you should create a directory for undertaking your work, change directory into it and then us uv venv --python 3.11.

NB Because of a performance regression in one of TopoStats dependencies, the package Topoly, TopoStats only supports Python 3.10 and 3.11. The TopoStats developers are aware and are hoping this will be resolved in the near future. In the mean time you have to explicitly create

cd ~/work/
mkdir AFMSlicer
cd AFMSlicer
uv venv --python 3.11

cd Work
mkdir AFMSlicer
cd AFMSlicer
uv venv --python 3.11

Activate Virtual Environment

You can now activate the environment and check that your are using the python binary from that environment.

source .venv/bin/activate
which python
python --version
You should see output similar to the following although the first line will depend on your operating system and the path where you created the afm_slicing programme.

/home/user/work/AFMSlicer
Python 3.11.13

direnv

GNU/Linux and OSX users may want to consider using dirnev to automate activation of virtual environments on navigation to the AFMSlicer directory. Add the following to .envrc to activate the environment from within the AFMSlicer directory.

echo "#!/bin/bash\nsource .venv/bin/activate" > .envrc


.venv\Scripts\activate
where python
python --version
You should see output similar to the following although the first line will depend on your operating system and the path where you created the afm_slicing programme.

c:\work\AFMSlicer
Python 3.11.13

Installing AFMSlicer

PyPI

Failure

Currently AFMSlicer has not been packaged and released to PyPi. For now the following will not work and you should follow the Development isntructions.

You can install both AFMSlicer and the Napari plugin within the virtual environment using the following command.

Failure

This will currently fail (see above).

uv pip install napari-afmslicer

Development

AFMSlicer is in the early stages of development and as such must be installed from the GitHub repository along with the development versions of its dependency TopoStats. The steps involved in installing the development version are described below and require that you install and use uv to set things up.

Cloning Repositories

The following repositories need cloning.

You can use the following commands to clone these.

mkdir -p ~/work/AFMSlicer
cd ~/work/AFMSlicer
git clone https://github.com/AFM-SPM/AFMSlicer.git
git clone https://github.com/AFM-SPM/napari-afmslicer.git

TopoStats

Unfortunately the TopoStats repository is large and will take a while to clone.

Create a virtual environment and install packages

If you haven't already create a virtual environment using uv and activate it (see above)

NB TopoStats is constrained to using Python >=3.10 and < 3.12 hence why Python 3.11 is explicitly installed.

Install AFMSlicer and napari-afmslicer from the cloned repositories using the following commands.

uv pip install -e AFMSlicer/.
uv pip install -e napari-afmslicer/.

Tip

Cloning and installing will take a few minutes because of the downloads that need to be made, please be patient.

You can now proceed to the usage section to learn how to use AFMSlicer.