isabella232 / puma-1

Puma is a plugin for Rhino and Grasshopper. It provides a Rhino command and Grasshopper components which enable the execution of CityEngine rules within Rhino.

Puma - CityEngine Plugin for Rhino3D and Grasshopper

Puma is a plugin for Rhino3D and Grasshopper. It provides a Rhino command and Grasshopper components which enable the execution of CityEngine ‘rules’ within a Rhino scene. Therefore, a Rhino artist or designer does not have to leave their familiar Rhino environment anymore to make use of CityEngine’s procedural modeling power. Complicated export-import steps are no longer needed, which also means that the procedural models do not need to be “baked” anymore. The building or street models stay procedural during the entire design or planning workflow. Consequently, the user can change any attributes of the building or street models easily by connecting them to other Grasshopper components.

Puma requires so-called rule packages (RPK) as input, which are authored in CityEngine. An RPK includes assets and a CGA rule file which encodes an architectural style. Comprehensive RPK examples are available below.

Puma is free for personal, educational, and non-commercial use. Commercial use requires at least one commercial license of the latest CityEngine version installed in the organization. Redistribution or web service offerings are not allowed unless expressly permitted.

Quick Start

Download and open the "Street Segment" example or create a scene from scratch:

1. In CityEngine, download e.g. Tutorial 9 and export the "Parthenon" CGA rules to a RPK (see Creating a Rule Package).
2. Install Puma via the Rhino 7 Package Manager in the Tools menu (recommended) or from food4rhino.
3. Start Rhino and open Grasshopper.
4. In Grasshopper go to the "Esri" tab and find the "Puma" section, drag the Puma component into the document.
5. Right-click on the RPK input parameter to select the "Parthenon" RPK created above. Puma will ask you to save the document, so it can store the path to the RPK relative to the document. It is best practice to put RPKs next to the Grasshopper document or in a subdirectory.
6. Create a "Surface" component and use the "Set one surface" context menu entry to draw a surface in Rhino with the "Surface from 3 or 4 corner points" tool.
7. Connect the "Surface" to the "Shapes" input. Now Puma will generate the model in the Rhino viewport.

Table of Contents

• User Manual
• Examples
• Developer Manual
• Release Notes
• Licensing Information

User Manual

Puma technically consists of two plugins, (1) a command for Rhino and (2) components for Grasshopper. We expect Puma to be used mainly through Grasshopper as only there its full potential can be used by connecting it to other Grasshopper components. The lower-level Rhino command ApplyRulePackage is useful to one-off test CityEngine Rule Packages.

Installation

Note: Puma is currently only available for Windows 10 (Intel/AMD 64bit).

Recommended Installation Method: Rhino 7 Package Manager

Open the Package Manager in the Rhino 7 "Tools" menu and search for "Puma".

Food4Rhino App Store

Go to the Puma app store entry on food4rhino and click on Download, this will download the Puma installer file. Double-click to install into your Rhino.

Install from local files

See below in the developer documentation.

Using the Puma Grasshopper components

After starting Grasshopper, the Puma components are located in the Esri section in the Special tab.

The main Puma component is used for generating models, materials and reports out of a CityEngine Rule Package (RPK) and input shapes (polygons, surfaces, meshes). The two helper components Puma Reports Unpacker and Puma Reports Display assist with inspecting and displaying report values generated by the CGA rules.

Connecting the main Puma inputs

The main Puma component has two fixed inputs. The RPK input takes a file path from a CityEngine Rule Package file (.rpk). The second input Shape(s) takes one or more input geometries (Mesh, Rectangle, Brep, Surface).

Any Grasshopper component providing such objects can be connected to the Shape(s) input, for example the Rectangle component. The steps how to define a Rectangle input are:

1. Create a Rectangle component
2. Right-click on the Rectangle component and choose Set one Rectangle or Set Multiple Rectangles.
3. Draw the rectangle(s) in the Rhino viewport using the Rhino Rectangle tool.
4. Select the rectangle.

Note that there are slight differences in these steps based on the geometry type. The Surface component, for example, does not allow you to draw a shape, but only to select a previously existing one. It is needed to draw it first using Rhino tools.

Working with rule attribute inputs

When both main inputs are connected, the component is solved a first time. The default values for the cga rule attributes are used. It is possible to override them by adding input parameters to the Puma component. To do that, zoom on the component until a small + button appears. It opens a dialog window in which new inputs can be selected from the list of available rule attributes, defined in the rule package currently used.

These parameters can then be connected to other components. The context menu also provides an easy way to directly assign a value. Puma will use default values for unconnected inputs which are defined in the rules and in general also depend on the input shapes.

Rule attributes and the corresponding Puma component inputs use four basic data types: (1) Number, (2) String, (3) Boolean (Toggle) and (4) Colour. These can be either single values or lists of values. In case of lists and length mismatches, Puma will either truncate lists or repeat the last value of a list until the length of the shape(s) input is matched.

Please note that string attributes representing assets like .obj or texture files can only refer to files within the current Rule Package (RPK). Puma will interpret the string as a file path (with forward slashes as separator) relative to the RPK root, e.g. assets/my_asset.obj. In case of unexpected behavior, it can be useful to inspect the RPK in question with a tool like 7zip to confirm the presence of asset files.

The inputs are typically created by these built-in Grasshopper components:

• Number(s): Number and Number Slider
• String(s): Panel and Text
• Boolean(s): Bool and Toggle
• Color(s): Colour, Colour Picker and Swatch

To get more information on each rule attribute input, the user can hover with the mouse over each of them. A tooltip is displayed, containing information on the expected data. Puma will read the CGA annotations on the rule attributes and display metadata such as the allowed range for numbers.

If the CGA rule attribute is annotated as an enumeration the tooltips will list the range of values.

Extract parameter

It is possible to automatically create connected input components by using the Extract Parameter feature. Right-click on the input parameter you want to extract and select Extract parameter. The new component will display the same name and description as the input parameter, and have the attribute's default value(s) assigned to it.

Working with the Puma outputs

The Puma component has five outputs:

1. Models: The generated meshes.
2. Materials: The generated materials
3. Reports: The generated cga reports.
4. Prints: The messages defined in the cga rule.
5. Errors: The errors encountered during the generation process.

The Models output will contain for each input shape a list of meshes (one mesh per material). The generated materials can be applied to the meshes by connecting the built-in Custom Preview component. The reports are output as a custom data type which can be displayed and converted with the Puma reports helper components.

Toggle the material generation

Each Grasshopper component has an option menu that can be opened by right-clicking on the component name. The Puma menu contains an additional menu item to toggle the material generation. This is useful to speedup model generation when working with complex scenes.

Using the Puma reports helper components

The Puma Reports Display is designed to help display CGA report values in the Rhino viewport and takes 5 inputs. The first two are typically connected to the respective outputs of the main Puma component. The next three inputs are optional filters:

1. Shape ID Filter: Used to filter the reports by initial shape ID. Accepts a Domain component.
2. Report Key Filter: Filters the reports by key name. Accepts a Panel or Text component, or a list of them. Report keys can be written on multiple lines.
3. Report Value Filter: This input allows to select specific values for each keys selected in the Report Key Filter input.

This component has three outputs, the first two can be connected to a 3D Text Tag component to display the selected reports in the Rhino viewport. The Reports Location output provides the location to position and align the reports text above each generated model. The Reports Display output provides the formatted reports text.

Here is an example of reports displayed in the Rhino viewport using the 3D Text Tag component.

The Reports passes through the selected reports for further processing. For example, to unpack them with the Puma Reports Unpacker.

The Puma Reports Unpacker component unpacks the reports data from Puma into lists of shape index, report name and report value. This is typically used to further process the reports with built-in Grasshopper components, e.g. to write the reports to a text file.

Using the Puma Rhino command

In Rhino, select a shape and type the command ApplyRulePackage in the command line. This will open a file dialog to choose a RPK file. After confirming, the models will be generated on the selected shape.

Please note, this command is only meant to provide a quick way for testing a RPK on a shape and it is currently not possible to change the rule attributes.

Developer Manual

Software Requirements

• Windows 10 (Intel/AMD 64bit)
• Rhino 6 or 7 (https://www.rhino3d.com/download)
• Microsoft Visual Studio 2019 with MSVC 14.27, MFC for MSVC 14.27 and C# (.NET Framework 4.5.2)
• Optional: Python 3.7 or later

Build Instructions

1. Install the tools from the Software Requirements section.
2. Follow the instructions from the Rhino documentation to install the Rhino SDK and related tools.
3. Follow the instructions from the Rhino documentation to install the Grasshopper SDK.
4. Checkout this Git repository.
5. Open the Visual Studio solution.
6. Ensure the configuration is set to Release and x64 (the only supported configuration).
7. Build the solution. The result is stored in the build directory, foremost PumaRhino.rhp and PumaGrasshopper.gha.

Installing locally built plugins

After having built the plugins, they have to be installed in Rhino and Grasshopper respectively.

1. Start Rhino. In the menu bar, go to Tools -> Options -> Rhino Options -> Plug-ins.
2. Click on install and select the PumaRhino.rhp file located in path-to-solution/build.
3. To install the Grasshopper plugin, run the command GrasshopperDeveloperSettings in Rhino.
4. In the window that opens, add the folder path-to-solution/build containing PumaGrasshopper.gha. Make sure the Memory load .gha assemblies... box is unticked.
5. Confirm, then restart Rhino and Grasshopper.

Create installation packages (rhi, yak)

Once both plugins (rhp for Rhino, gha for Grasshopper) are built, it is possible to create a rhi (Rhino Installer) package and/or a yak package using the create_package.py python script. A rhi package is simply a zip archive containing all files required to run a plugin. If Rhino is installed, the plugin can be installed by double-clicking the package. It will extract the files and Rhino/Grasshopper will load them when started. The yak package is the archive that can be uploaded to the Rhino marketplace in order to publish the plug-in.

1. Open a console, navigate to the Puma solution directory and run the command python create_package.py <option>. Valid values for <option> are both (default), rhi, or yak to choose which package type to build.
2. The resulting rhi and yak packages will be created in a folder named packages located in the solution root directory.

Install locally built packages

1. Close Rhino if it is open.
2. Run the rhi package by double-clicking it.
3. The package installer will open. Follow the instructions.
4. The plugin will be loaded at the next start of Rhino/Grasshopper.

Note: In case of troubles, try to enable the "Ask to load disabled plug-ins" box located in Rhino's Tools -> Options -> Plug-ins.

Debug the native code

For debugging, keep the Release configuration (we always generate PDBs) and turn off the C++ optimizations in the PumaCodecs and PumaRhino C++ project properties. Rebuild and attach the debugger to Rhino and set breakpoints.

Release Notes

Puma 1.0.0 (2021-12-10)

• Corresponds to v0.9.4 with updated documentation.
• Published "Street Segment" example (for Rhino 7) to show-case the main features of Puma.
• Puma supports Rhino 6 and 7.
• Supports Rule Packages from CityEngine 2021.1 and older.
• Limitation: no support yet for PBR materials in Rhino 7.

Puma 0.9.4 (2021-11-15)

• Public Beta.
• Updated to PRT 2.5: Supports Rule Packages (RPK) from CityEngine 2021.1 and older.
• Fixed use of wrong rule attribute values in a GH document with multiple Puma nodes.
• Fixed group assignment of extracted parameters.
• Supports Rhino 6 and 7.

Puma 0.9.3 (2021-09-22)

• Internal test build.
• Supports Rhino 6 and 7.
• Supports Rule Packages from CityEngine 2021.0 and older.
• Improved portability of Grasshopper documents by storing relative paths to Rule Packages (introduces a "RPK" custom parameter).
• Detect external modification of Rule Packages and potentially reload them when solving the Grasshopper document.
• Correctly keep manually set parameter values when internalizing a parameter.
• Fixed parameter extraction of rule attributes after loading a Grasshopper document.
• Fixed handling of polygons with holes.
• Various code cleanups.

Puma 0.9.2 (2021-08-09)

• Internal test build.
• Supports Rhino 6 and 7.
• Supports Rule Packages from CityEngine 2021.0 and older.
• Improved conversion of non-Mesh input shapes. Rhino Rectangles now have a consistent winding order.
• Optimized loading performance of large Rule Packages with many textures.
• Improved "extract parameter" behavior for rule attributes. This includes support for array attributes and using dedicated components (e.g. toggles and sliders) for single value attributes.

Puma 0.9.1 (2021-07-16)

• Internal test build.
• Supports Rhino 6 and 7.
• Supports Rule Packages from CityEngine 2021.0 and older.
• Optimized model generation to distribute input shapes across all CPU cores.
• Improved attribute sorting in chooser dialog to match the CityEngine inspector as close as possible.

Puma 0.9.0 (2021-07-02)

• Internal test build.
• Supports Rhino 6 and 7.
• Supports Rule Packages from CityEngine 2021.0 and older.
• Supports multiple input shapes with different rule attribute values.
• Switched to dynamic input parameters for the rule attributes on the Puma components. Do not show all possible rule attributes by default to keep the Puma component compact.
• Added support for rule array attributes.
• Added input parameter to control random generator per Puma component.
• Added output parameters for CGA print and asset error/warning outputs.
• Added support for creating yak packages.
• Added initial manual.

Puma 0.6.0 (2020-12-01)

• Internal test build.
• Supports Rhino 6.
• Supports Rule Packages from CityEngine 2020.0 and older.
• Supports multiple input shapes with same rule attributes.
• Added Grasshopper helper components to process and display CGA report values.
• Development: Added support for creating rhi packages.

Puma 0.5.0 (Fall 2020)

• First internal proof of concept.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Licensing Information

Puma is free for personal, educational, and non-commercial use. Commercial use requires at least one commercial license of the latest CityEngine version installed in the organization. Redistribution or web service offerings are not allowed unless expressly permitted.

Puma is under the same license as the included CityEngine SDK. An exception is the Puma source code (without CityEngine SDK, binaries, or object code), which is licensed under the Apache License, Version 2.0 (the “License”); you may not use this work except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.

For questions or enquiries, please contact the Esri CityEngine team ([email protected]).