Speckle QGIS: The Speckle Connector for QGIS

What is Speckle?

Speckle is the Open Source Data Platform for AEC. Speckle allows you to say goodbye to files: we give you object-level control of what you share, infinite versioning history & changelogs. Read more on our website.

Introduction

This repo contains the QGIS plugin for Speckle 2.0. It is written in python and uses our fantastic Python SDK. The Speckle Server is providing all the web-facing functionality and can be found here.

Try it out!! Although we're still in early development stages, we encourage you to try out the latest stable release. Just follow the instructions on this file, and head to the Releases page to download the necessary files and dependencies.

What can it do?

Currently, the plugin allows to send data from a single layer to a Speckle server using one of the accounts configured on your computer. It will extract all the features of that layer along side their properties and, when possible, geometry too. The following geometry types are supported for now:

• Point
• Multipoint
• Polyline (LineString)
• MultiLineString
• Polygon
• MultiPolygon
• More to come!!

If you have questions, you can always find us at our Community forum

Installation

This plugin is still in early development and should only be used for testing. If you'd like to be an early tester and provide us with feedback and feature requests, forge ahead!

Adding the Plugin

First, you'll need to place the speckle_qgis folder into your plugins folder. To find this folder, go to the "Settings" menu and select "User Profiles" > "Open Active Profile Folder".

Inside this folder, navigate into the python folder then the plugins folder. Once inside the plugins folder, drop your speckle_qgis folder into it.

Speckle Dependencies

Before you can launch the plugin, you'll need to add the Speckle dependencies. To do this, you'll need to head to your QGIS installation folder and find the Python site-packages folder. This is in a different location from your plugins folder.

For QGIS 3.20, you'll find this folder at:

• Windows: C:\Program Files\QGIS 3.20.1\apps\Python39\Lib\site-packages
• MacOS: /Applications/QGIS.app/Contents/Resources/python/site-packages

Drop the contents of the included dependencies folder (not the folder itself) into the site-packages folder to add specklepy and all its dependencies to your QGIS environment.

Launching the Plugin

You should now launch QGIS and you should see SpeckleQGIS in your installed plugins. Click the blue brick in the toolbar to open the plugin.

Developing

Setup

Setup is a bit cumbersome for now. The following is adapted from this tutorial

Qt Creator

To edit the UI of the plugin, you'll want to install Qt creator. You can find the free installers on this page in the "Qt Creator" tab. On Windows, you'll be prompted to create an account during the installation process.

Python Qt Bindings

For Windows, the bindings are already included in the QGIS installation.

For Mac, you can install PyQt using homebrew.

brew install pyqt

Install pb_tool

pb_tool allows you to compile resource files from into something python will understand.

For this plugin we only have one file to convert:

• resources.qrc -> resources.py

To install pb_tool, just run:

pip install pb_tool

or

YOUR_PYTHON_EXECUTABLE -m pip install pb_tool

For convenience, the pre-compiled resources.py file so you don't really have to do anything here.

Installing specklepy

You'll also need to manually install specklepy in the QGIS python environment. This will add specklepy and its dependencies to the QGIS python's site-packages folder.

• Find your interpreter's path:
  • Windows: C:\Program Files\QGIS 3.20.1\apps\Python39\
  • Mac: /Applications/QGIS.app/Contents/MacOS/bin
• Use the command line to install specklepy
  • QGIS_PYTHON_PATH -m pip install specklepy

THIS WILL NOT WORK ON DEPLOYMENT, WE NEED TO COME UP WITH A BETTER STRATEGY BUT FOR DEV PURPOSES ITS FINE FOR NOW

Dev Environment

For a better development experience in your editor, we recommend creating a virtual environment. In the venv, you'll just need to install specklepy. You will also need to copy over the qgis module into the {venv}/Lib/site-packages. You can find the qgis module in your QGIS install directory:

• Windows: C:\Program Files\QGIS 3.20.1\apps\qgis\python
• MacOS: /Applications/QGIS.app/Contents/Resources/python

QGIS Plugins

Though it is not required, we recommend installing these plugins from the QGIS Plugin Manager:

• Plugin Reloader (allows you to reload the plugin without restarting QGIS)
• Remote Debugger (enables interactive debugging)
• First Aid (shows errors before crashing QGIS, sometimes)

Debugging

Visual Studio Code

If running on Windows

In VS Code, you can use the built in python debugger. You'll need to create a debug configuration by creating a launch.json file.

Select the "Python" -> "Attach using Process ID" option. Your launch.json should look like this:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Attach using Process Id",
      "type": "python",
      "request": "attach",
      "processId": "${command:pickProcess}"
    }
  ]
}

To start debugging, you'll need to first launch QGIS. Once it's running, run your debug configuration. You'll see a dropdown where you can search for and select the qgis-bin.exe process.

That's all there is to it! Now any breakpoints you create should be hit.

If running on Mac

The previous instructions don't work on a Mac (at least the ones we tested), as QGIS seems to freeze when attaching to it's process. If you managed to make it work, or we're missing something, do let us know!

First, you'll need to install ptvsd the same way you installed specklepy above, so that QGIS will be able to find and use it.

QGIS_PYTHON_PATH -m pip install ptvsd

In VS Code, you can use the built in python debugger. You'll need to create a debug configuration by creating a launch.json file.

Select the "Python" -> "Remote Attach" option. Your launch.json should look like this:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Remote Attach",
      "type": "python",
      "request": "attach",
      "port": 5678,
      "host": "localhost",
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "${workspaceFolder}"
        }
      ]
    }
  ]
}

To start debugging, you'll need to first launch QGIS. Once it's running, run your debug Python: Remote Attach configuration.

That's all there is to it! Now any breakpoints you create should be hit.

Enjoy!

Deploy

TBD