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


0- Installing the Software 2018-07-06T08:21:53+00:00

The tools consist of two main parts. The first part runs in QGIS, for which we will soon provide a Virtual Machine you will be able to download here. When you download the virtual machine, you will not have to do the first step of the installations.

Step 1:

Until the virtual machine is ready, to run the first part of the code you need to install:

  • QGIS 64 bit with GRASS, SAGA and OTB components. Make sure to install the 64 bit unless your computer is 32 bit.  The current code works best in 2.18.0 version of QGIS. If you are running a 64bit windows, you can download it here. Or go to the downloads site and find the appropriate installation.
  • Osgeo4w.If you are running a 64bit windows, you can download it here. Or go to the downloads site and find the appropriate installation. Our system runs on November 2016 installation.
  • Python.

*2.7 64bit      https/://www.python.org/downloads

  • Python plugin pyshp, 2.7 64 bit from the link. Alternatively, launch windows command line and type:
                     pip install pyshp
    • If pip is not installed go to: https://pip.pypa.io/en/latest/installing/
    • Note: If command line does not recognize python or pip, add its directory (such as C:\Python27) as well as pip’s directory (C:\Python27\Scripts) to your environment variables> system variables > as a Path. Go to system>Advanced system settings, Advanced Tab, Environment Variables, System Variables> , then select “Path”,>Edit>New, and add your two paths . If this doesn’t work, navigate to the Python\Scripts directory in the Command Line and enter the code above. For this, you need to type in your windows command line:
                         cd c:\Python27\Scripts


                     pip install pyshp

*** Pyshp installation is necessary for the Grasshopper code as well so make sure you install this even if you are not installing rest of the Qgis plugins.

  • Python plugin Triangle inside Qgis
    • First, test if you already have pip in QGIS by typing:
                           pip list

or if it doesn’t work:

                           python -m pip list

      • Type OSGeo4WShell in command line and run as administrator.
        • Copy curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
        • Then python get-pip.py
        • Upgrade setuptools using pip install setuptools –upgrade
  • Install cython using pip install cython
    • If pip install cython doesn’t work download it from this link if you are running windows 64 bit or go to to the url and download appropriate version: https://pypi.org/project/Cython/#files . Then type this in your Osgeo command line:
        • pip install C:\Users\user_name\Desktop\Cython-0.28.2-cp27-cp27m-win_amd64.whl   
  • Install triangle using  pip install triangle*
            •                    pip install C:\Users\user_name\Desktop\triangle-20160203-cp27-none-win_amd64.whl                                                                                        
          • *Python2.7 amd64 and all it’s compatible packages are needed. You may get this error:
          • error: Microsoft Visual C++ 9.0 is required (Unable to find vcvarsall.bat).  Get it from http://aka.ms/vcpython27  (solution included with error description)
  • You need grass6 files in your OSGeo grass directory. For this, download grass6 folder here. Unzip, and put the folder into your Osgeo directory: C:\OSGeo4W64\apps\grass\
  • Configuration (QGis)
    • Now, we need to make sure the paths for the Grass and OTB plugins are correct within QGis. In QGis, go to Processing > Options. Expand the Providers tab and locate your Grass and OTB (Orfeo Toolbox) tabs. Expand these tabs as well.Make sure your Grass and OTB folders are pointing to the correct locations in the OSGeo4W folder (double click the field).
    • *Notice that within Grass commands tab:

  • Download the 5 QGIS python codes by going to the Tools page and clicking on the “Download Triangulation Tools”. Unzip and put the five python codes in the correct directory:                  C:\Users\user_directory_here\.qgis2\processing\scripts

Step 2:

The second part of the code runs in grasshopper. You can download the code through the same link.

To run the grashopper code, you need to install:

Also, you need the python plugin pyshp. If you have completed the Qgis installation (Step 1), you already have pyshp. If not, to install pyshp, open windows command line, and type:

           pip install pyshp

If it doesn’t work, type:

           python -m pip install pyshp

If it doesn’t work, add C:\Python27 and C:\Python27\Scripts\ to your system paths. For more details on how to do this, refer to the Step 1 of the installation.

1- Preparing the geometry 2018-05-10T21:36:41+00: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 2018-05-10T21:35:33+00:00

Once you have your geometry ready, open the grasshopper definition and go to the first part.

This part of the definition will allow you to convert rhino geometry to shape files. You need topography points, building breps, other urban limit breps and if you have a shoreline, a polygon defining the water limit.

You will see a component that requires the following inputs:

  • File path: This is where you want your shape files to be saved.
  • Topography: Plugin your topography points. If these are not dense enough, consider creating more through extrapolation.
  • Walls: Vertical planar brep elements that represent all physical barriers such as gates, walls, hedges etc.
  • Buildings: 3d polygon breps representing the buildings.
  • Water: A polygon.
  • Horizontal Limit: This feature is in development so please leave this input blank.

Toggle to write the shapes and see the success messages.

3- Running the QGIS Code 2018-05-10T21:36:18+00:00

This requires running 5 custom scripts in QGIS for which you need to have installed the Virtual Machine available here.

1- Import all shape files generated in the first step to QGIS: volumetric limits, planar limits and topography.



2- 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.

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

Make sure to set the file directories and names to be saved for the output fields before running the codes.



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




3- 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.


4- 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 (mesh for Rhino) should be saved as a .txt file.



5- 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.



6- 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.”



7- 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.




4- Running the Grasshopper Code 2018-05-10T21:36:10+00:00

Open the grasshopper definition and go to the second part of the code.

1- Load the shape files and the mesh.txt file to the first component.



You can preview the geometry through the visualization definition below.



2- The third part of the code generates the Convex Spaces (CSs).


Data and geometry generated for each CS can be visualized below the definition.


3-  The fourth part of the code generates the Convex Voids (CVs).


Data and geometry generated for each CV can be visualized below the definition.


3-  The fifth part of the code generates the Solid Voids (SVs). The sixth and seventh parts generate the Facades of the Convex Voids and the Flows respectively. Each part has the data and geometry visualizations below their generator definitions.


4- The eighth part writes the generated data into excel sheets, bakes the geometry for the Rhino file and exports the geometry to shape files.



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 2018-06-05T16:08:22+00:00

If your TT Toolbox plugin is not correctly installed, you may get this error with the “Write to Excel” part of the grasshopper code:

To fix this, open your Grasshopper Components folder, go into the TT Toolbox plugin folder, and in it, find the relevant dll file (in this case, CORE.Library.Office.dll), right click on the folder, and make sure the file is unblocked. Then restart Rhino.

You may get the following error pop up after loading the triangular mesh parts to the Urban Limits component.

Check the “Do not show this message again” box and Close. The code keep working.