Installation#

Install QGIS#

You are suggested to install the latest version of QGIS since the plugin has mainly been tested on versions newer than QGIS 3.30 (QGIS 3.28 LTR should also work fine).

Install Python Dependencies#

Some dependencies need to be installed into the Python environment in QGIS beforehand to use Geo-SAM. Pytorch is a fundamental dependency. If you want to install the GPU version of Pytorch, it is recommended to refer to the official website for installation: https://pytorch.org/get-started/locally/#start-locally .

After installing PyTorch, torchgeo and segment-anything need to be installed subsequently. Below are tutorials for installing these dependencies on different operating systems.

For Windows Users#

Open the OSGeo4W Shell OsGeo4WShell application as Administrator from the Start menu, which is a dedicated shell for the QGIS.

CPU version#

If you want to install the CPU version of PyTorch, run the following command in the OSGeo4W Shell directly.

pip3 install torch torchvision torchgeo segment-anything

GPU version#

Geo-SAM Encoder Tool supports using GPU to accelerate the encoding process. If your PC has NVIDIA GPUs, you need to download and install the CUDA Toolkit first.

Then install the gpu-version pytorch using the following command (here CUDA 11.7 as an example):

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117

Note

If you have installed the CPU version of PyTorch before, you may need to add the --force-reinstall option to force the reinstallation of the GPU version.

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117 --force-reinstall

Then install the other dependencies:

pip3 install torchgeo segment-anything

For Mac/Linux Users#

Open your own terminal application, and change the directory to where the QGIS Python binary file locates.

# Mac
cd /Applications/QGIS.app/Contents/MacOS/bin

# Linux
cd /usr/bin

Important

Do not ignore the ./ before python and pip in the following commands to avoid using your default Python/pip in the system

Run the following command to check if the QGIS Python environment is correctly set up.

./python3
>>> import qgis

Then install the Python Dependencies of Geo-SAM.

./pip3 install torch torchvision torchgeo segment-anything

For Linux users, if pip3 is not found in /usr/bin, try the following commands:

sudo apt-get update
sudo apt-get install python3-pip

Note

For Linux users, if your computer got available CUDA GPUs and with CUDA Toolkit installed, the above commands should have helped you install the gpu-version pytorch. You can reach pytorch official website for more information.

Warning

If QGIS 3.34/3.36 crash when you try to run the plugin, you may need to install the rtree package using the system package manager instead of using pip. More details can be found in blog Crash on QGIS 3.34/3.36.

Below is a brief guide for Ubuntu/Debian users:

# Remove the rtree package using pip in QGIS:
./pip3 uninstall rtree

# Install the rtree package using system package manager:
sudo apt-get install python3-rtree

Install the Geo-SAM Plugin#

Download the Plugin#

Download the stable version: plugin zip file or the dev version (more features and capabilities, but not rigorous tested): plugin zip file, unzip it, and rename the folder as Geo-SAM (be aware of undesired nested folders after unzipping).

Locate the QGIS Plugin folder#

In QGIS, go to the menu Settings > User Profiles > Open active profile folder. You’ll be taken straight to the profile directory. Under the profile folder, you may find a python folder; the plugins folder should be right inside the python folder (create the plugins folder if it does not exist). Put the entire Geo-SAM folder inside the plugins folder, then restart QGIS. The directory tree structure should be the same as the following.

python
└── plugins
    └── Geo-SAM
       ├── checkpoint
       ├── docs
       ├── ...
       ├── tools
       └── ui

Below are some general paths of the plugin folder for your reference.

# Windows
%APPDATA%\QGIS\QGIS3\profiles\default\python\plugins

# Mac
~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins

# Linux
~/.local/share/QGIS/QGIS3/profiles/default/python/plugins

Activate the Geo-SAM Plugin#

After restarting QGIS, go to the menu Plugins > Manage and Install Plugins, and under Installed, you may find the Geo SAM plugin; check it to activate the plugin.

After activating the Geo-SAM plugin, you may find the Geo SAM tools under the Plugins menu,

You may also find a new toolbar, including three icons.