Food4Rhino

sDNA_GH is an open source (MIT licensed) plug-in providing components that run the tools from a local sDNA installation from within Grasshopper.  

sDNA is able to calculate Betweenness, Closeness, Angular distance, and many other quantities including custom hybrid metrics, and is able to perform many other advanced functions as well. 

sDNA_GH:

•  Reads a network's polyline Geometry from Rhino or Grasshopper, and Data from any User Text on it.
•  Writes the network polylines (formed by one or more polylines) and user Data to a Shapefile.  
•  Initiates an sDNA tool that processes that shapefile, and e.g. carries out a network preparation or an analysis.
•  Reads the shapefile produced by the sDNA tool.
•  Displays the results from sDNA by colouring new polylines or the original ones.

Installation.

1. Ensure you have an installation of Rhino 3D including Grasshopper (versions 6 and 7 are supported).

2. To use sDNA with sDNA_GH, ensure you have an installation of Python 2.7 or Python 2.7.18  that can run sDNA correctly from the command line, with pip for sDNA Learn.  sDNA_GH runs sDNA from the command line.  Command line use of sDNA has been tested with Python versions 2.6 and 2.7 .  Do not run sDNA with Iron Python 2.7, as invalid shape files may be produced (it is not possible to access the Iron Python shipped with Rhino from the command line, in any case).  

3. sDNA Learn requires numpy.  Numpy can be added after installing Python 2.7.18 by opening a cmd window and typing: "cd C:\Python27\Scripts" and "pip2.7 install numpy".

Optional:  If this Python 2.7.18 installation is also used by other processes, to guarantee there are no dependency conflicts, use a venv to run sDNA, e.g. firstly by entering: "cd C:\Python27\Scripts" followed by "pip2.7 install virtualenv" and "<abs_path_to_sDNA_GH_venv_folder>\Scripts\pip2.7 install numpy" (enter "<abs_path_to_sDNA_GH_venv_folder>\Scripts\activate.bat" to test the venv from the command line) and secondly by setting "python" to "abs_path_to_sDNA_GH_venv_folder>\Scripts" (on a config component or on config.toml) in step 13.3 below.

4. To use sDNA with sDNA_GH, ensure you have an installation of sDNA.  sDNA itself may require the 64 bit (x64) Visual Studio 2008 redistributable (alternative download link).  The closed source "free as in beer" version of sDNA and sDNA+ may also require the 32 bit (x86) Visual Studio 2008 redistributable (alternative download link) in order to unlock sDNA with a serial number.

5. Download sdna-gh.zip from food4rhino or the sDNA_GH releases page on Github. 

6. Ensure sdna-gh.zip is unblocked: Open File Explorer and go to your Downloads folder (or whichever folder you saved it in).  Right click it and select Properties from the bottom of the menu.  Then click on the Unblock check box at the bottom (right of Security), and click OK or Apply.  The check box and _Security_ section should disappear.  This should unblock all the files in the zip archive.  Please do not automatically trust and unblock all software downloaded from anywhere on the internet (the source code and build scripts for sDNA_GH are visible on Github).  

7. Open Rhino and Grasshopper.

8. In Grasshopper's pull down menus (above the tabs ribbon at the top) click File -> Special folders -> User Objects Folder.  The default in Rhino 7 is %appdata%\Grasshopper\UserObjects.  Note, this is not the Components Folder used by many other plug-ins (i.e. not %appdata%\Grasshopper\Libraries).

9. Copy sdna-gh.zip to this folder (it should be at e.g.%appdata%\Grasshopper\UserObjects\sdna-gh.zip). 

10. Unzip sdna-gh.zip to this location (in Windows 10 right click sdna-gh.zip and select Extract All ..., then click Extract to use the suggested location).  In the User Objects folder, a single folder called sdna-gh should have been created, itself containing a subfolder called sDNA_GH.  If necessary, rename the outer parent folder (inside the User Objects folder) to exactly "sdna-gh" (no quotes). E.g. if you previously downloaded an earlier version of sDNA_GH (or any other file called) sdna-gh.zip, your web browser may have renamed a second download to sdna-gh(1).zip.  In this case, you will need to either rename the file or the folder created by unzipping it.

11. Restart Rhino and Grasshopper.

12. The sDNA_GH plug in components should now be available under a new sDNA tab in the ribbon amongst the tabs for any other plug-ins installed (right of Mesh, Intersect, Transform and Display etc).  

13. To use sDNA with sDNA_GH, if no preferences are specified, sDNA_GH will search for sDNA and Python 2.7 installations automatically, using the first one of each it finds.  To ensure sDNA_GH uses a particular version of sDNA and the correct Python 2.7 interpreter it is recommended on first usage to:

    -place a Config component on the canvas (the component with a gear/cog icon in Extra).

    -Specify the file path of the sDNA folder (containing sDNAUISpec.py and runsdnacommand.py) of the sDNA installation you wish to use in the sDNA_folders input.

    -Specify the file path of the Python 2.7 interpreter's main executable in the python input.

    -Specify any other options you wish to save and reuse on all projects, if necessary by adding custom input Params with the option's name.

    -Connect a true boolean toggle to go.  An installation wide user options file (config.toml) will be created if there isn't one already.

To save options to other project specific `config.toml` files, specify the file path in `save_to` and repeat the previous 4 sub steps.

14. If a newer version of sDNA is used in future with tools unknown to sDNA_GH at the time it was built, if a Config component is placed, and the path of the new sDNA specified in sDNA_folders, sDNA_GH will then attempt to automatically build components and user objects for the new sDNA tools, and add them to Grasshopper for you.  Set make_new_comps to false to prevent this.

Overview.

sDNA_GH components all have an associated tool (apart from a few special ones, e.g. Config).  As one would expect, sDNA components run those sDNA tools of the same name.  But components can run any number of tools, and other components' tools (*).  These tools are callable class instances, abstractions of ordinary Python functions.

sDNA tools expect to receive a raw input shape file, and output a shapefile, exactly as if they were used on the command line.

To run sDNA with Grasshopper geometry, other tools must be run before and afterwards.  For convenience, by default two special options, auto_write_Shp and auto_read_Shp are true.  With these settings, sDNA components will accept Grasshopper Geometry and output Grasshopper Geometry, and the two extra support tools Write_Shp and Read_Shp handle the writing and reading of the shapefiles.

To work directly with a shapefile in sDNA_GH, auto_write_Shp should be set to false, so that the sDNA component doesn't first try to write a shapefile for sDNA when a shapefile is already available.  Only automatically generated temporary shapefiles are deleted after a tool using it has finished.

Rhino polylines should be imported into Grasshopper with Read_Geom.  This is necessary to get the actual UUIDs of the Rhino objects in the object table (not just Grasshopper references). 

Text and weights can be stored on Rhino objects as User Text.  Using the real references to Rhino polylines from Read_Geom, the Read_Usertext tool can read the Geom and output the Usertext keys and values as a Data Tree in Data.  If compute_vals is true, substrings in User Text values such as `%<CurveLength( ... )>%` are expanded.

As expected, Write_Shp writes polylines to shapefiles.  But to allow round tripping of GIS networks, it is now also able to write Degree 1 Nurbs curves to POLYLINEZ shapefiles.  To write weights and text to a Shapefile attribute table, e.g. for sDNA, Data must be supplied to a Write_Shp tool, either in its own component or in an sDNA one with auto_write_Shp set to True.  Data is automatically in the correct format from Read_Usertext.  Read_Usertext will read everything it can find into a Data Tree, but Write_Shp will only write data associated with Usertext keys to a shapefile that match input_key_str.  By default this ("{name}") matches everything.  But different values can be useful for filtering or using longer Usertext key names than the 10 ascii character maximum length of shapefile field names.

Adding a separate Read_Usertext component can be avoided, by setting auto_read_User_Text to true.  The Read_Usertext *tool* must still be run to achieve this, as that tool is where the code to do this task lives.  However that tool (or any other tool) does not have to be run using its *component* of the same name, if there is an *auto* rule that will run it for them as part of another component (or if they add that tool to a name_map workflow themselves).

sDNA results, or any POLYLINE shapefile's geometry and associated data, can be read using the Read_Shp tool (either via its own component, or from an sDNA component with auto_read_Shp = true).  Shapes can be baked into Rhino straight away by setting bake to true.  Otherwise if no Geom was inputted to associate with the shapefile data, Grasshopper Polylines are outputted in Geom.  

Rhino has particular rules for what counts as a valid Polyline.  Many line-strings from GIS sources, e.g. OSM are invalid by these rules.  If attempts to add a polyline from a shapefile of polylines fails, Read_Shp then adds a Degree 1 Nurbs Curve (which Rhino is more lenient towards than Polylines).  If the attempt to add a Degree 1 Nurbs Curve fails, an error is raised.  If ignore_invalid is set to True, this error is stopped, and data about the curve in the shapefile, including its number in the file, and why it is invalid is outputted in invalid. 

Data associated with the (new or old) shapes can be automatically plotted from Read_Shp component by setting auto_plot_data to true.  This runs the Recolour_Objects tool, which itself if given raw data will run Parse_Data on it first.  To pick custom colours, e.g. a gradient component can be placed between a Parse Data Component and a Recolour Object component.  This also allows tinkering with the plotting settings, without having to rerun a large sDNA analysis or reparse the Data Tree for each setting.  Parse Data accepts overrides for class boundaries and legend tag names.  The Grasshopper Legend component accepts overrides for the tags, rectangular legend frame and even the colours too.  

Results and other shapefile data can be saved as Usertext on Rhino objects, using the Write_Usertext tool.  Object references from Read_Geom or from Read_Shp with bake = True are required to get references to the actual Rhino objects.  Write_Usertext avoids overwriting previous Usertext by time stamping the keys using the template defined in output_key_str (by default 'sDNA output={name} run time={datetime}').  overwrite_UserText can also be set to false to stop this, which will append a suffix to the keys. 
 

(*) By adding a nick name to the name map, it's straightforward to create a custom component to run any sequence of sDNA_GH tools desired.  Any standard sDNA_GH component given that name map in its options, that is renamed to that nick name, will run that sequence.  This is faster and more efficient overall than using separate components, as the geometry and data trees don't have to be reconverted and reparsed to go from one Iron Python process, to Grasshopper and back to a second Iron Python process, between each component.  Every tool in the same component can just use the same data and geometry in RAM.  But all the tools in the same component will be rerun each time a solution for it is recomputed.

A detailed manual can be viewed online here, and is also included in sdna-gh.zip (in a text panel component, and in .md & .pdf forms).  Numerous test cases showing example use are available on the Github releases page.

Dependencies: 

• IronPyshp (https://github.com/JamesParrott/IronPyShp)
• toml_tools (https://github.com/JamesParrott/toml_tools)

(both MIT licensed).  Static copies of both are included in sdna-gh.zip

Copyright (c) 2022 Cardiff University, a body incorporated by Royal Charter and a registered charity (number: 1136855) whose administrative offices are at 7th floor 30 - 36 Newport Road, University CF24 0DE, Wales, UK