OasysGH 0.4.4-beta

.NET Framework 4.8
This is a prerelease version of OasysGH.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package OasysGH --version 0.4.4-beta
NuGet\Install-Package OasysGH -Version 0.4.4-beta
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OasysGH" Version="0.4.4-beta" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add OasysGH --version 0.4.4-beta
#r "nuget: OasysGH, 0.4.4-beta"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install OasysGH as a Cake Addin
#addin nuget:?package=OasysGH&version=0.4.4-beta&prerelease

// Install OasysGH as a Cake Tool
#tool nuget:?package=OasysGH&version=0.4.4-beta&prerelease

OasysGH

Contents

  1. Introduction
  2. How to use
    1. Shared units
  3. Content overview
    1. Units
    2. Component Attributes
    3. Abstract component classes
    4. Abstract parameter classes
    5. Input helpers
    6. Output helpers

Introduction

OasysGH is a library with shared content for Oasys Grasshopper plugins.

You can use this library for:

  • Units shared by multiple plugins, with form to set defaults.
  • GH_UnitNumber parameter to pass OasysUnits (fork of UnitsNet) based objects around between components.
  • Custom component UI (dropdown, sliders, buttons, etc), also known s "Component Attributes".
  • Abstract classes for parameters to help handle wrapping an object oriented API.
  • Abstract classes for components to help implement custom component UI.
  • Helper methods for input/output of various custom parameters

How to use

Reference this library as a NuGet package in your project.

Setup a OasysPluginInfo PluginInfo singleton like this for your plugin:

internal sealed class PluginInfo
{
  private static readonly Lazy<OasysPluginInfo> lazy =
      new Lazy<OasysPluginInfo>(() => new OasysPluginInfo(
        "Oasys Shared Grasshopper", "OasysGH", "0.1.0.0", true, "phc_alOp3OccDM3D18xJTWDoW44Y1cJvbEScm5LJSX8qnhs"
        ));
   public static OasysPluginInfo Instance { get { return lazy.Value; } }
   private PluginInfo()
  {
  }
}

Shared units

To initialise shared default units along with the Windows Form to allow user to set their default units, simply call the method:

OasysGH.Utility.InitialiseMainMenuAndDefaultUnits();

DefaultUnits This will also automatically download the latest version of the UnitNumber plugin, which is a separate project in this repository.

Content overview

Units

This library contains:

  • A shared class with default units for typical engineering units.
  • Filters to get relevant engineering units (UnitsNet contains many units unrelated to engineering, for instance lengths in lightyears or printer points)
  • Helper methods to get for instance a moment unit from length and force units.
  • A custom grasshopper parameter called GH_UnitNumber which wraps OasysUnits.IQuantity which will allow you to pass numbers with units around between components.
  • Input helpers for GH_UnitNumber which will allow users to input:
    • another GH_UnitNumber,
    • a number (for instance from a slider) which will be converted into a Quantity with the selected unit (can be combined with dropdown UI component to allow users to select the unit)
    • a text string, for instance 15 kNm which will be parsed into a OasysUnits.Moment.

Component Attributes

Attributes for components is a custom way to override the drawing methods creating the UI of a component on the Grasshopper canvas.

It is used to set the m_attributes field in a Grasshopper component:

public override void CreateAttributes()
{
  m_attributes = new UI.DropDownComponentAttributes(this, this.SetSelected, this.DropDownItems, this.SelectedItems, this.SpacerDescriptions);
}

OasysGH contains component Attribute methods to create:

  • Bool6 component (six check boxes)
  • Button component (single button for 'Open' components)
  • Dropdown(s) with check boxes
  • Dropdown(s) component
  • Dropdown(s) with slider (for scaling results)
  • Releases component (12 check boxes)
  • Support component (three buttons with six check boxes)
  • Three button component (for 'Save' components, buttons for 'Save', 'Save As' and 'Open in X')

Feel free to add your own custom components UI.

Abstract component classes

Inherit from GH_OasysComponent, GH_OasysDropDownComponent or GH_OasysTaskCapableComponent<T> to:

  • Track usage with posthog
  • Use simple scaffolding code to create, for instance, complex dropdown menus components. The abstract base classes take care of most things for you.
  • By default, the GH_OasysDropDownComponent will use DropDownComponentAttributes so you do not have to override the CreateAttributes() method unless you want to use one of the other component attributes.
GH_OasysComponent

Inherit from this class if you have a simple, normal component with nothing fancy happening. This will simply add posthog tracking to your components.

GH_OasysDropDownComponent

Inherit from this class to use the custom UI. As mentioned above, the default behaviour is for GH_OasysDropDownComponent to use DropDownComponentAttributes but if you want to use one of the other attributes just override the CreateAttributes() method.

A good example for simple implementation of the abstract/virtual methods in GH_OasysDropDownComponent is shown below, this is taken from the ComposGH repo

This example will create a component with a dropdown menu to set a length unit. It will take the initial unit from the default units, but then afterwards save the selected unit in the component so that the settings is stored when users reopen their Grasshopper document.

First, we need to initialise the dropdown lists

private LengthUnit LengthUnit = DefaultUnits.LengthUnitSection; // get default length unit

public override void InitialiseDropdowns()
{
  this.SpacerDescriptions = new List<string>(new string[] { "Unit" });

  this.DropDownItems = new List<List<string>>();
  this.SelectedItems = new List<string>();

  // add length
  this.DropDownItems.Add(Units.FilteredLengthUnits);
  this.SelectedItems.Add(this.LengthUnit.ToString());

  this.IsInitialised = true;
}

Secondly, we need to implement what happens when users make a selection in the dropdown:

public override void SetSelected(int i, int j)
{
  // change selected item
  this.SelectedItems[i] = this.DropDownItems[i][j];
  if (this.LengthUnit.ToString() == this.SelectedItems[i])
    return;

  this.LengthUnit = (LengthUnit)Enum.Parse(typeof(LengthUnit), this.SelectedItems[i]);

  base.UpdateUI();
}

Then we need to handle what happens when the component is recreated when a saved document is opened again (or when the component is copied). The contents of SelectedItems and DropDownItems are both stored and recreated automatically by GH_OasysDropDownComponent base.

public override void UpdateUIFromSelectedItems()
{
  this.LengthUnit = (LengthUnit)Enum.Parse(typeof(LengthUnit), this.SelectedItems[0]);

  base.UpdateUIFromSelectedItems();
}

Finally, and optionally, we may want to change the name of the input parameters to display the selected unit on for instance sliders:

public override void VariableParameterMaintenance()
{
  string unitAbbreviation = Length.GetAbbreviation(this.LengthUnit);
  Params.Input[0].Name = "Pos x [" + unitAbbreviation + "]";
  Params.Input[3].Name = "Spacing [" + unitAbbreviation + "]";
}

ChangeDropdown

Abstract parameter classes

The abstract parameter classes makes it easy to implement a custom Grasshopper parameter by wrapping another API object.

GH_OasysGoo

An example of how easy it is to inherit from GH_OasysGoo<T> is the GH_UnitNumber Goo wrapper class, that makes sure s OasysUnits IQuantity can be used in Grasshopper and passed around between components.

public class GH_UnitNumber : GH_OasysGoo<IQuantity>
{
  public static string Name => "UnitNumber";
  public static string NickName => "UN";
  public static string Description => "A value with a unit measure";
  public override OasysPluginInfo PluginInfo => GH_UnitNumberPluginInfo.Instance;

  public GH_UnitNumber(IQuantity item) : base(item) { }
  public override IGH_Goo Duplicate() => new GH_UnitNumber(this.Value);  
}
GH_OasysGeometryGoo

This class is still to be implemented, but is in the making...

Input helpers

OasysGH provides helper methods to get generic input parameters. This enables a single line of code in SolveInstance to retreive custom input parameters in a coherent way that will act similar to how Grasshopper acts to build-in parameters (same type of errors/warnings). For instance a UnitNumber length input can be retrieved like this:

Length inputLength = (Length)Input.UnitNumber(this, DA, 0, this.LengthUnit);

The helpers include methods for getting:

  • GenericGoo<T> (item input)
  • List<GenericGoo<T>> (list input)
  • UnitNumber (item input)
  • List<UnitNumber> (list input)

The UnitNumber inputs are special in the sense that they include additional helpers to cast from string (text) and double (number) inputs, allowing users to input IQuanity as either a:

  • UnitNumber
  • Number (unit will be taken from the dropdown or you can implement a static unit like Hertz for FrequencyUnit)
  • Text (for instance 15 kNm or 130mm)

image

In the image above, the unit for the Height input (cm) is taken from dropdown. Note that the text inputs can be either with or without space between value and unit. Not shown is the example of inputting another UnitNumber.

Output helpers

In order to prevent the dropdown components to continuously expire downstream components, OasysGH provides helper functions to set outputs as item, list or tree which will only expire the output if the output has actually been changed. This allows the user to toggle the dropdown lists without the entire Grasshopper script having to recalculate.

Product Versions
.NET Framework net48 net481
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on OasysGH:

Package Downloads
GsaGH

Official Oasys GSA Grasshopper Plugin GsaGH is pre-release and under active development, including further testing to be undertaken. It is provided "as-is" and you bear the risk of using it. Future versions may contain breaking changes. Any files, results, or other types of output information created using GsaGH should not be relied upon without thorough and independent checking. The plugin requires a licensed version of Gsa to load. Contact oasys@arup.com to request a free trial version. Copyright © Oasys 1985 - 2022

ComposGH

Official Oasys Compos Grasshopper Plugin ComposGH is pre-release and under active development, including further testing to be undertaken. It is provided "as-is" and you bear the risk of using it. Future versions may contain breaking changes. Any files, results, or other types of output information created using ComposGH should not be relied upon without thorough and independent checking. The plugin requires a licensed version of Compos to load. Contact oasys@arup.com to request a free trial version. Copyright © Oasys 1985 - 2022

AdSecGH

Official Oasys AdSec Grasshopper Plugin AdSecGH is pre-release and under active development, including further testing to be undertaken. It is provided "as-is" and you bear the risk of using it. Future versions may contain breaking changes. Any files, results, or other types of output information created using AdSecGH should not be relied upon without thorough and independent checking. The plugin requires a licensed version of AdSec to load. Contact oasys@arup.com to request a free trial version. Copyright © Oasys 1985 - 2022

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.5.2-beta 48 1/26/2023
0.5.1-beta 52 1/25/2023
0.5.0-beta 55 1/11/2023
0.4.5-beta 53 12/14/2022
0.4.4-beta 56 11/23/2022

This is a release of OasysGH 0.4.4-beta.