DDB Grasshopper

Full documentation of DDB-GH, which enables use of the DDB API within Grasshopper.

Note for external users - many of the links in the following section refer to internal applications. Please speak to your project team for support.

Prerequisites

• Rhino 7 (opens new window) or Rhino 8 (opens new window)

Note for Arup Staff - if you are not in an office, you must be connected to the VPN to access the Arup software shop.

Installation

You can the DDB-GH plugin in the Rhino Package Manager.

DDB-GH Install - Rhino Package Manager

1. Open Rhino.
   • NOTE: If this is your first time using Rhino on this computer, refer to this Yammer post (opens new window) for setup instructions (Arup staff only).
2. Type PackageManager into the Rhino command line, hit enter.
3. Search for DDB, and select DDBGrasshopper when it loads. Note: this may take several seconds to search.
4. Click Install.
5. Type Grasshopper into the Rhino command line to open GH. You should see a ribbon at the top labelled DDB.
   • 

Developer Information

The DDB-GH repository is located here (opens new window). See how to contribute (opens new window)

DDB-GH Step by step guide

How to guide

This how to guide shows examples of how the DDB Grasshopper components are expected to be used. See the Components section below this.

Note: This procedure assumes the project exists on DDB already.

Set up a project

Connect a job number and Environment component to the Project component to get the project from DDB.

Project assets

Link either a project or asset to a Child Asset component to get all the child assets. Create a chain of these through the project heirachy.

Include an Child Asset Types component to filter which assets get returned. With no search input, this component will return all possible Asset Types.

If a new asset needs to be added, used the Get or Create Asset component which will check if an asset already exists, before creating a new one.

Deconstruct asset or check for sub-types

To explore the properties of an asset, use the Deconstruct Asset component to break it into its properties.

Connect an asset type to the Asset Sub-type component to see if there are existing sub-types for the chosen type. These can be used to create an apropriate child asset.

Get parameters

Connect a Parameter component to a project or asset component to get all the parameters associated with the parent.

Use the Parameter Type component to filter down to the correct parameter. With no search input, this component will return all possible parameter types.

Use this as a 'library' to then chose the apropriate type, and then add in the selected item as a search input to filter the component down to one option.

The Deconstruct Parameter component can then be used to break down the parameter to see it's properties.

Note: all components with dynamic outputs (Child Assets, Child Asset Types, Parameters, etc) show each object as an independent output by default. This can easily be changed to display all outputs as one list, to allow for list/tree operations. See screenshot below.

Update a parameter

To update a parameter use the Add Parameter Revision component, which allows you to update the value, source and units for the selected parameter.

By right-clicking on the component, you can select whether parameters are:

• Automatically sent or manually sent
• If a new revision is posted even if the value hasn't changed

The units selected must by of the same type as the asset, but the actual unit can be changed (e.g. if the parameter is in mm of type length, the new units can be in m)

Chose the units for a parameter

Use the Units component to get all the units for the selected unit type and/or unit system. An optional search input can be used to narrow it down.

Units can also be accessed from the Deconstruct Parameter component which provide the unit, unit type and unit system for the parameter.

Create a source for a parameter

First, use the Source component to see what sources already exist for the project. The Source Type component can be used to filter the sources and will return all the possible types for that DDB environment.

The source output can then be broken down using the Deconstruct Source component to get the extra information about the source.

If the source needed for a parameter doesn't yet exist, use the Get or Create Source component to create a source type object. If the source already exists this component will return the existing soure.

Components

This section contains all the components included in the version 01 release, split into the 5 groups below.

NOTE: Outputs that are generated dynamically change depending on inputs.

1. Project level

Project component

Loads a project from DDB

Inputs:

• JN - Job number: Job number for the project (8 digits as a string or number)
• E - Environment: Output from environment component (Production/Development/Sandbox)

Outputs:

• P - Project: A project object

Environment component

Selects the DDB environment to use (with optional token)

Inputs:

• Token (Optional) - Token to authenticate with if required
• Environment dropdown - Type of DDB environment to use

Outputs:

• Env - Environment - DDB Environment object

2. Assets

Child Assets component

Gets the child assets from a project or parent asset

Inputs:

• P - Parent: Parent project or asset to get asset from
• T - Asset type: Asset type to select

Outputs:

• Asset (dynamic): Asset object based on inputs

Asset Search component

Searches the existing assets of a parent project or asset.

Inputs:

• P - Parent: the parent project or asset to search for assets in
• SN - Search Name: an asset name to search for
• Ex - Exact match: whether the search name needs to be an exact match or not (True = Exact; False = Partial Match)
• SI - Search ID: an asset ID to search for
• ST - Search Type: an asset type to search for
• SS-T - Search Sub-type: an asset sub-type to search for
• A/O - And/Or: whether the search should use and/or for the search criteria (True = And; False = Or)

Outputs:

• Assets (dynamic): The assets that match the search criteria

Right-click menu options:

• Include parent asset level in search
• Show outputs as single list

Child Asset Types component

Gets all the child asset types of a parent asset/project

Inputs:

• P - Parent: The parent environemnt, asset or asset type.

Outputs:

• Asset types (dynamic): The asset types of the parent

Asset Sub-types component

Inputs:

• At - Asset type: The asset type to get the sub-types of

Outputs:

• Asset Sub-Types (dynamic): All available sub-types for selected asset type

Deconstruct Asset

Inputs:

• A - Asset: The asset to deconstruct.

Outputs:

• An - Asset name: The name of the asset
• Ai - Asset ID: The GUID of the asset
• At - Asset type: The type of the asset
• As-t - Asset sub-type: The sub-types of the asset
• Pa - Parent asset: The parent asset (or project) of the asset
• Da - Deleted at: The time when the asset was deleted (if applicable)
• J - Json: The json response for the asset

Get or Create Asset

Inputs:

• P - Parent: The parent of the asset
• An - Asset Name: The name of the asset to get or create
• Ty - Asset Type: The type of teh asset

Outputs:

• A - Asset: The returned asset

3. Parameters

Parameters

Inputs:

• P - Parent: The parent project or asset
• T - Type: Optional parameter type to filter by

Outputs:

• Parameters (dynamic): The list of parameter objects for that parent

Additional menu options (right-click on component):

• Only show used parameters

When all parameters are shown, parameters that are unused have a ~ before them

Parameter Search component

Searches the existing parameters of a project

Inputs:

• P - Project: the project to search for parameters in. Note that this must be the project, and cannot be a different asset (unlike the Asset Search component).
• T - Search Type: a parameter type to search for
• SN - Search Name: a parameter name to search for
• Ex - Exact match: whether the search name needs to be an exact match or not (True = Exact; False = Partial Match)
• SI - Search ID: a parameter ID to search for
• SP - Search Parent Asset: search for the parameters of a parent asset
• A/O - And/Or: whether the search should use and/or for the search criteria (True = And; False = Or)

Outputs:

• Parameters (dynamic): The parameters that match the search criteria

Right-click menu options:

• Include project level parameters in search
• Only show parameters with values
• Show outputs as single list

Parameter Types component

Inputs:

• P - Parent: The parent project or asset
• S - Search: Optional search input to filter by

Outputs:

• Parameter Types (dynamic): List of available parameter types for that parent

Deconstruct Parameter component

Inputs:

• P - Parameter: The parameter to deconstruct

Outputs:

• N - Name: The name of the parameter
• V - Value: The value of the parameter
• Pt - Parameter Type: The parameter type of the parameter
• A - Parent Asset: The parent asset of the parameter
• U - Units: The units of the parameter
• Ut - Unit type: The unit type of the parameter
• Us - Unit system: The unit system of the parameter
• S - Source: The source of the parameter
• T - Data Type: The data type of the parameter
• St - Status: The status of the parameter
• D - Date: The date the parameter was added or updated
• I - ID: The GUID of the parameter
• J - Json: The JSON response for the parameter

Deconstruct Parameter Type component

Inputs:

• P - Parameter Type: The parameter type to deconstruct

Outputs:

• N - Name: The name of the parameter
• Dt - Data Type: The data type of the parameter
• GP - Global parameter: Boolean for whether it's a global parameter
• UT - Unit type: The unit type of the parameter
• US - Unit system: The unit system of the parameter
• ID - ID: The GUID of the parameter type
• J - Json: The JSON response for the parameter type

Add Parameter Revision component

Inputs:

• T - Parameter Type: The parameter type of the parameter to update
• P - Parent Asset: The parent asset of the parameter to update
• V - Value: The value to update the parameter with
• S - Source: The source of the new parameter
• U - Units: Optional unit input, will use default units if not provided

Outputs:

• P - Parameter: The updated parameter object

Right-click menu options:

• Always post revision, even with same value
• Automatically send updates

4. Units

Units component

Inputs:

• E - Environment: The DDB environment to get the units for
• S - Search: A search input to filter the units

Outputs:

• Units (dynamic) - The units based on the DDB environment and search (e.g. mm, cm, m, km)

Unit Types component

Inputs:

• E - Environment: The DDB environment to get the unit types for
• S - Search: A search input to filter the unit types

Outputs:

• Unit types (dynamic) - The unit types based on the DDB environment and search (e.g. length, weight, volume)

Unit Systems component

Inputs:

• E - Environment: The DDB environment to get the unit systems for

Outputs:

• Unit systems (dynamic) - The unit systems based on the DDB environment and search (e.e.g. metric, imperial)

5. Sources

Sources component

Inputs:

• P - Project: The parent project
• T - Type: The source type
• S - Search: Text-based search for source

Outputs:

• Sources (dynamic): Source objects based on inputs

Source Types component

Inputs:

• E - Environment: The DDB environment to get the sources for

Outputs:

• Source types (dynamic) - The available source types for the selected environment

Deconstruct Source component

Inputs:

• S - Source: The source to deconstruct

Outputs:

• Ti - Title: The title of the source
• R - Reference: The reference for the source
• Ty - Type: The source type
• U - URL: The url for the source
• D - Date: The date the source was added
• I - ID: The GUID of the source
• J - Json: The json response for the source

Get or Create Source component

Inputs:

• P - Project: The project for the source
• Ti - Title: The title for the source
• R - Reference: The reference for the source
• Ty - Type: The source type for the source
• U - URL: The url for the source
• D - Date: The date the source was added

Outputs:

• S - Source: The source

99. Old components

This section contains the old components that still work, but are no longer being updated or supported. These components will be completely removed from the DDB-GH plugin in the near future, so we do not recommend using these on project scripts.

General Grasshopper Tutorial

Need some help with Grasshopper?

For general Grasshopper knowledge/tutorials, we recommend that you refer to this Grasshopper Getting Started Guide (opens new window). This is unrelated to DDB-GH, but provides a helpful understanding of the basics of Grasshopper.