Tutorial 2018-04-27T10:19:44+01:00


0- Installing the Software 2022-04-29T13:47:42+01:00

The tools consist of two main parts. The first part runs in QGIS, the second in Rhino Grasshopper.

The current version (0.3.x) has been tested and runs on Rhino 7 and QGIS 3 on Windows 10 and MacOS.

Step 1:

First you should download Rhino from here, and QGIS 3 from here. We recommend the current the Long Term Release. On Windows, we recommend you choose the Standalone installer.

Mac: Install QGIS by dragging it to your Applications folder. The first time you run it you may need to right click and press open on the dialog to bypass the Mac security measures.

Windows: Install QGIS by running the installer with default options.

Step 2:

Download the QGIS python codes by going to the Tools page and clicking on “Download Triangulation Tools”. Do not unzip the file.

Windows users: If you are running Windows with the default security options, please open QGIS as an administrator in order to install the plugin (right click on QGIS, select ‘run as administrator’).

Windows and Mac: Install the CSV plugin by opening QGIS and going to: ‘Plugins’ menu, ‘Manage and Install Plugins’, ‘Install from ZIP’, and choosing your zip file and clicking ‘Install Plugin’. If QGIS asks to install other plugins, please allow. The installation process should be quick, but if you are running QGIS on MacOS older than Big Sur, it can take up to  5 minutes. Important: Wait for the success message bar to show before closing the plugin manager.

Once installed, we recommend you restart QGIS. The plugin will be available in the Plugins menu bar (DCG CSV), or the Processing Toolbox.

Plugin manager

Step 3:

The second part of the code runs in grasshopper. Download the script from ‘Download Convex Solids Tool’ in the Tools page. Unzip the file you downloaded.

Install Rhino through the usual means for your OS.

Windows users: If you are running Windows with the default security options, please open Rhino as an administrator in order to install the plugin (right click on Rhino, select ‘run as administrator’).

Open Grasshopper (type grasshopper in the Rhino command line) and while in Grasshopper, open the install.gh script inside the folder you just unzipped. Double click on the Install toggle button to begin the installation process. Once it is finished, you can close grasshopper, shut down Rhino, and delete the install.gh file.

You can now open Rhino and Grasshopper, and open the CSV script. The first time you run it, it may ask to install a few plugins. Let it. You can now follow the rest of the tutorial.

1- Preparing the geometry 2018-05-10T21:36:41+01:00

First you need to prepare your geometry in Rhino. If you don’t already have the geometry of the area you will analyze, one way to acquire 3d urban geometry is to import it from GIS files using the Meerkat plugin for grasshopper. Below are the geometry and what you need to pay attention to while creating them:

  • Buildings: these need to be extrusions of flat polygons on the XY plane. Their base should not sit on top of the topography mesh, but the XY plane, at Z=0.
  • Walls: these are boundaries that you usually have to model manually, unless you already have a detailed GIS file or a 3d model. The walls should be extrusions of line geometry sitting on the XY plane, and not the topography mesh, just like the building geometry. This is why, all boundaries will essentially be modeled like walls, may they be hedges, fences, gates, removable parking barriers or in some cases, parking lots. You should decide if the urban space they separate is accessible or not, and accordingly model the barrier or not. Below are several cases of boundaries that may be modeled as walls.


  • The topography mesh: the code only requires topography points (located at their correct elevations). Nevertheless, it is advisable to first create a delaunay mesh and make sure that the top-most vertices of the walls and building geometry remain above the mesh geometry (avoid the case in the image below). Otherwise, the QGIS code will give you an error. If the topography points are not dense enough, you may also get an error in the 3rd QGIS code you are going to run in the next step. If that happens, extrapolate a denser set of topography points. For this, you can project a 10m x 10m grid of points on the delaunay mesh.

2- Creating the Shape Files 2022-04-29T14:54:53+01:00

Once you have your geometry ready, open the grasshopper file. Once it finishes loading you can minimise the grasshopper window and use the Grasshopper panel in Rhino (right click on the panel and select Grasshopper if it’s not active. There are only two options: Calculate and Export. Press on Calculate to open the CSV Solution calculation window.

Grasshopper Remote Panel

The CSV Solution window is where all the options and calculations take place. It is divided into eight tabs:

  • Pj (CRS projection)
  • Ot (geometry out)
  • In (geometry in)
  • CS (calculate convex spaces)
  • CV (calculate convex voids)
  • SV (calculate solid voids)
  • Fc (visualise facades)
  • Fl (visualise flows)

CRS Selection Tab

The window should open with the Pj (Projection) tab active. If not, select it. In this part, you will define the CRS that will be used throughout your project. You can either obtain it by reading from an existing shapefile .prj file, or you can attribute an EPSG code by selecting EPSG override. The script accepts most EPSG codes. In this example we enter 3763, for EPSG:3763 used in Portugal mainland. If successful, the status message will inform you of the CRS selected and you can continue with the next step.

Shapefile output

In this step, we select the Ot (output) tab to convert the rhino geometry to ESRI shapefiles. We need topography points,* building volumes,** other urban limit volumes*** and, if there is a shoreline, a polygon defining the water limit.****

We simply select the output folder to be used to export all the files, and then proceed to select the topography points, walls, and buildings, by clicking on the relevant button to activate the Rhino selection tool. Once all the selections have been made we click on export and wait for the process to finish.

* If the topography points are not sufficiently dense, consider creating more through extrapolation

** 3D polygon breps representing the buildings

*** Vertical planar brep elements that represent all physical barriers such as gates, walls, hedges etc.

**** Water and other horizontal limits are still under development and not available at this time.

3- Running the QGIS Code 2022-04-29T15:09:13+01:00

1- Prepare the QGIS working CRS: Always remember to use the correct CRS for your site. For our tutorial, we will be working will Lisbon data which carries the standard Lisbon CRS known as ETRS89 / Portugal TM06 (EPSG:3763). Please make sure QGIS OTF (on the fly transformation) is activated and set to a CRS of EPSG:3763. Whenever you add a file from grasshopper to the project, take a moment to confirm it has the correct CRS. Likewise, whenever you run a script in QGIS, confirm the resulting file has a CRS attached before exporting it. You can define the project CRS by clicking on the bottom right main window globe or by selecting menu item ‘Project -> Properties’. You can define a layer with a known missing CRS through the Processing Toolbox or by right clicking on the layer and selecting ‘Properties’. Do not change the CRS of a layer with a valid coordinate reference system attached (in this case you should re-project it).

CRS selection

2- Import all shape files generated in the first step to QGIS: volumetric limits, planar limits and topography. The CSV algorithms can be accessed either from the plugins menu, under ‘DCG CSV’, or from the Processing Toolbox, under ‘DCG – Solid Voids’.

Plugin access

3- Run the first code: “Merge Urban Limits.” This code receives volumetric limits and planar limits as input. “There are no horizontal limits” checkbox should be checked at this stage as no horizontal limits are generated in the grasshopper code yet.

Do no assign an output file or directory. Simply let the algorithm save the generated files as temporary layers with their default names for now. We will export them all later. Do the same for all five algorithms.

A tolerance setting of 0.01 is advisable for all five codes.

The output of this code will be “urban limits”.

4- Run the second code: “Construct topology.” This code receives “urban limits” as input and creates “points inside” and “edges” as output.

– If you get the error: “not sufficient topography points” do not run the following codes as the final code will not produce geometry after this error. Instead make sure the following issues are resolved and re-run the third code.

  • If the topography mesh remains above the upper vertices of any of the urban limits or planar limits at any point, this should be corrected.
  • If any geometry extends beyond that of the limits of topography points in plan, the region covered by the topography points should be extended.
  • If the error repeats, the topography points may not be dense enough. In this case, a more dense grid of topography points should be generated though extrapolation.

5- Run the third code: “Construct mesh of topography.” This code receives “topography points”, “edges” and “points inside” as input and creates “mesh for qgis”, “vertices”, “edges with topogrpahy.” It also creates a mesh file to be used in the grasshopper code later. This mesh is a .txt file for Rhino. Please save it in your final output folder with the name rhino_mesh.txt.

6- Run the fourth code: “Find cognitive limits.” This code receives “edges with topography” and “vertices” as input. The parameters advisable for use for this code are as follows:

  • projection parameters:  max(LENGTHx15.0,HEIGHTx1.0,UNITSx5.0);;BEARINGorHEIGHTDIFF
  • significant vertex bearing: 30.000000
  • significant edge height difference per vertex : 3.000000
  • tolerance for vertex proximity: 3.000000

This code defines the implicit limits.

  • Search Space: The maximum distance in which implicit points (vertices) should be searched for.
  • Attribute of significance: The Significance Precondition of explicit limits to get projected as implicit ones, defined through the bearing angle, vertices’ height difference and vertices minimum horizontal distance.
  • When (1) and (2) are satisfied the Explicit limits are projected as Implicit vertices.

7- Run the fifth code: ” Do triangulation.” This code receives “edges with cognitive limits”, “vertices with cognitive limits” and “points inside” as input and creates the “triangular mesh.”

8- Split the mesh: To feed this triangular mesh into the grasshopper definition, it needs to be broken up into smaller meshes. This division needs to be done manually but natural divisible limits of convex spaces should be taken into consideration.

Below is an example demonstrating this division from a different urban context.

9- Bulk export the layers: Once everything is done, you will have a large number of temporary layers in the layers panel. To save them for future reference and for import into Rhino, please use the ‘bulkvectorexport’ plugin that was automatically installed when you installed the CSV plugin (shown underneath on the left). You will find it under the ‘Vector – bulkvectorexport’ menu item. Choose ESRI shapefile as your output format, Layer CRS, and choose your destination directory. If you only need to export a small number of layers, you may prefer to simply right click them and choose export (shown underneath on the right).

Export layers

4- Running the Grasshopper Code 2022-04-29T16:04:04+01:00

1- Back in Rhino, we now load the geometry and data generated in QGIS.

Import cognitive geometry

Switch to the In tab and select the folder where the cognitive geometry generated in QGIS was exported. Next, select the trianged mesh within that folder. If the study area is quite large we recommend selecting a limited number of meshes rather than the entire mesh and run the calculations on particular areas first. Click Import and wait for the process to finish.

Once the files have finished importing, you can preview and assess the geometry through the relevant options in the Visualise section of the tab.

2- We can now move on to calculating the Convex Spaces by switching to the CS tab.

Generate Convex Spaces

The tab opens with the default options. Whilst we prepare a manual of all the different options, their meanings and definitions can be viewed in the papers published so far. Click on Generate CS to perform the calculation (warning: this is a computationally intensive process that may take some time). Once the calculation is finished, the totality of the convex spaces (CS), individual convex spaces, paths, and greatest inscribed circles (GIC) can be previewed by clicking on the relevant options in the Visualisations section of the tab.

3-  The next step involves generating what we term Convex Voids, by switching to the CV tab.

Generate Convex Voids

The tab will open with default options. Information on these options can be viewed in the papers published. Make sure the Height option is selected. Click on Generate CVs to proceed with the calculation. Once it finishes, the totality of the convex voids and specific convex voids can be previewed by selecting the relevant options in the Visualisations section of the tab.

Generate Sky View Factor

The Sky View Factor (SVF) can also be calculated within this tab. Simply click on Calculate SVF and wait for the process to finish. The output can be previewed by selecting the relevant options within the Visualisations section of the tab.

If you wish, you can expand the Bake section of the tab to bake the previews into permanent Rhino geometry in particular layers. This can also be done for all or particular geometries at the very end of the process by opening the CSV Export window of the Grasshopper panel.

3-  The final calculation involves generating what we term Solid Voids (SVs), by switching to the SV tab.

Generate Solid Voids

The tab opens with the default options. Information on these options can be viewed in the papers published. Click on Generate SVs to proceed with the calculation and wait for the process to finish.

The totality of the solid voids, particular solid voids, and particular convex voids and convex spaces can be previewed by selecting the relevant options within the Visualisations section of the tab.

If you wish, you can expand the Bake section of the tab to bake the previews into permanent Rhino geometry in particular layers. This can also be done for all or particular geometries at the very end of the process by opening the CSV Export window of the Grasshopper panel.

4- Facades and their relation to the voids and convex spaces can be visualised in the Fc tab.

Visualise Facades

5- Flows and their relation to the voids and convex spaces can be visualised in the Fl tab.

Visualise Flows

6- Once all the calculations are complete, you can close the CSV Calculate window and open the Export window by clicking on the relevant option in the Grasshopper panel in Rhino.

Stream data

The window is split into four tabs:

  • StData (stream data)
  • ExData (export data)
  • SvGeom (bake solutions)
  • ExGeom (export to ESRI shape files)

StData allows you to stream the data generated by the calculations for external real-time analysis. ExData allows you write the final generated data into csv files to import into Excel. SvGeom allows you to bake all or parts of the geometry into the Rhino file. ExGeom allows you to export the geometry and data attributes into shapefiles for use in GIS software.

Bake Geometry

In the future, we will be providing Jupyter notebooks for real-time analytics and statistical visualisation of the streamed data, as well as integrating a select number of data visualisations within the grasshopper code, allowing you to make changes in any part of the process and have them propagate all the way to the final report building section.

Export final shapefiles

Various additional information can be generated using the CS, CV, SV, Facade and Flow data and geometry. Refer to the about page and publications to learn more about the theory and applications of the method.

5- Known Errors 2022-04-29T16:05:16+01:00

Convex and Solid Voids is in active development. We are aware of certain errors that may occur and will strive to fix them as soon as we can.

1- You may get the following error when running the Topography algorithm in QGIS:

Topography error

It seems to happen more often when the algorithm is ran against a previously exported layer. Simply run the algorithm again, preferably straight after the previous algorithm. We are currently investigating the issue.