Folder and file preparation

The files for analysis should be placed in the input folder, which for now we request you create yourself. This should be place in a folder named input at $HOME/uvoids, where $HOME is your user folder.

The script requires two additional folders which will be created automatically if they do not exist. The log folder at $HOME/uvoids/logs and the data folder at $HOME/uvoids/data.

  • First, please confirm that your files are saved in Shapefile format with the correct EPSG / CRS projection (we will be adding more file formats in the future and moving to GeoPackage as default).
    • You can check this in any GIS program by comparing the geometry to satellite imagery.
  • You can name your input files anything you want, but the default names are:
    • horizontal_limits.shp
    • planar_limits.shp
    • volumetric_limits.shp
  • Place all your files for analysis in the input folder.
  • Make sure Docker is running and you’ve installed all pre-requisites as per the installation instructions
  • Launch a new terminal console.
    • Press cmd + space and type terminal in MacOS.
    • Press Windows + R and type cmd in Windows.
    • Press Alt + F2 and type terminal in Ubuntu.
  • Launch the uvoids docker: docker start -a -i uvoids

Usage

There is only one command, uvoids. This is the main uvoids command line entry point. All user-configurable variables are declared here, with sensible defaults.

  • If you wish, you can simply type uvoids, press return, and the script will do the entire analysis with sensible defaults.
  • If you prepared the files properly, the script will recognise the correct EPSG projection. If not, it will attribute a default projection of 4326 to mimic how the original algorithm worked.
  • Once it’s finished processing, the results will be in the data folder.
  • You can now exit the terminal by typing exit.
  • If you think the script is hanging, you can press ctrl + c to force exit.

Advanced Usage

  • There are several options you can provide. These are the same as the options in the original QGIS scripts, except that they are all provided at the start.
  • The usage is simply uvoids [options].

Main file options

Input file paths

  • --input

    Full path to input directory (default: ~/uvoids/data/input/).

  • --horizontal_limits, -hi: Full path to horizontal limits input shapefile (default: <input>/horizontal_limits.shp).

    A set of polylines, that represent horizontal limits such as overhangs, bridges, tunnels, arches, etc. Each polyline has height and thickness value. The same polyline can represent both a tunnel and a bridge at the same time.

    The attribute table must consist of:

    • id (int)
    • height(decimal)
    • thickness (decimal)
    • bridge (bool)

  • planar_limits, -pi:

    Full path to planar limits input shapefile (default: <input>/planar_limits.shp).

    A set of polylines, that represent vertical planar urban features such as fences and retaining walls. Each polyline can have its own separate height.

    The attribute table must consist of:

    • id (int)
    • height (decimal)
    • category (varchar)

  • volumetric_limits, -vi:

    Full path to volumetric limits input shapefile (default: <input>/volumetric_limits.shp).

    It is a set of polygons, that represent urban features enclosing som volume or area, e.g. water features, buildings, etc. Each segment of the polygon boundary will have the same height.

    The attribute table must consist of:

    • id (int)
    • height (decimal)
    • category (varchar)

Output file paths

  • output

    Full path to output directory (default: $HOME/uvoids/data/output/).

Hardcoded output filenames:

  • urban_limits: <output>/urban_limits.shp
  • triangular_mesh: <output>/tri_mesh.shp
  • topography_f: <output>/topography.shp
  • edges: <output>/edges.shp
  • interior_points: <output>/interior_points.shp
  • rhino_mesh: <output>/rhino_mesh.txt
  • qgis_mesh: <output>/qgs_mesh.shp
  • triangular_mesh: <output>/triangular_mesh.shp
  • rhino_tri_mesh: <output>/rhino_tri_mesh.txt
  • vertices: <output>/vertices.shp
  • edges_w_topography: <output>/edges_w_top.shp
  • cognitive_vertices: <output>/vertices_w_cog.shp
  • cognitive_edges: <output>/edges_w_cog.shp
  • impact_zones: <output>/impact_zones.shp

General options:

  • --use_grass

    Grass can be used instead of Shapely for more complex geometry simplification and validation.

  • --tolerance

    Tolerance refers to precision tolerance.

  • --tolerance_s

    Tolerance_s refers to tolerance used during geometry simplification.

Calculation options

If needed, only parts of the calculation can be performed. You can also choose what limits to include in the calculation.

  • --all_calculations (default) / --explicit_calculations (specify)
  • --limits / --no_limits
  • --topology / --no_topology
  • --topography / --no_topography
  • --additional / --no_additional

  • --triangulation / --no_triangulation

  • --horizontal_limits / --no_horizontal_limits
  • --planar_limits / --no_planar_limits
  • --volumetric_limits / --no_volumetric_limits

Vertex Projection Parameters (VPP)

These are used in Vertex projection for finding the congnitive vertical limits. They define the distance each edge is offset by to look for influential vertices.

  • The maximum or minimum values of up to three measures can be used:
    • Edge length * multiplier.
    • Average edge height * multiplier.
    • Map unit * multiplier.

  • i.e. For an edge of length 8m, average height 5m, map unit in metres, all multipliers set at 1, the algorithm would consider max(8, 5, 1) and derive 8m as a projection distance.

  • At least one measure must be used.
    • --vpp_edge_length / --no_vpp_edge_length
    • --vpp_edge_height / --no_vpp_edge_height
    • --vpp_map_unit / --no_vpp_map_unit
    • --vpp_quantifier_max / --vpp_quantifier_min
    • --vpp_edge_length_multipler
    • --vpp_edge_height_multiplier
    • --vpp_map_unit_multiplier

Maximum Vertex Projection

The maximum distance each vertex can be projected by. The value is based on Vertex height * multiplier. Vertices at ground level are never projected.

  • --vpp_vertex_height / --no_vpp_vertex_height
  • --vpp_vertex_height_multipler

Factor of vertex significance

A vertex is significant if the Vertex ‘bearing’ is above the significant value or if the ‘height difference’ between connected edges is above the significant value.

  • There are four possible options:
    1. Bearing AND HeightDifference
    2. Bearing OR HeightDifference
    3. Bearing
    4. HeightDifference

Usage:

  • --vpp_vertex_significance (1/2/3/4)

Vertex Projection Tolerances

  • --significant_vertex_bearing
  • --significant_edge_height_difference_per_vertex
  • --tolerance_for_vertex_proximity