Grasshopper File Format

Summary: Basic information about Grasshopper file format flavors and utilities

When it was first released, Grasshopper (then called Explicit History) used the *.wrm format. Although the format was extensible and supported versioning, it was difficult – to the point of being impossible – for third party developers to parse. It was also extremely sensitive to corruption since the content was sequential.

As of Grasshopper 0.5 and later, the WRM format is now obsolete and it can no longer be written (though *.wrm files can still be opened). Instead, Grasshopper data is now stored in *.gh or *.ghx files. These are, respectively, Binary and XML representations of non-sequential, nested dictionaries. We have also provided a standalone DotNET assembly which can read and write *.gh and *.ghx files.

EHC and GHA files are DotNET dll assemblies which reference the Rhino DotNET SDK and the Grasshopper plug-in. As of Version 0.5, the GHA format superseded the EHC format, though EHC files will still load. These assemblies are parsed using Reflection. All defined non-abstract types which implement certain interfaces, derive from certain base classes, or adhere to certain rules will be merged into the Grasshopper runtime. At this time, GHA files can contain Components, Parameters, Custom Objects and Graph Mapper definitions. They can of course define as many custom types, dialogs, and resources as needed.

WRM is a binary, sequential format that is a direct representation of runtime objects in the Grasshopper definition. This format has been marked Obsolete in Grasshopper 0.5+. Support for reading WRM files is still available, but WRM files can no longer be written.

These are two new flavors of file format that were first included in Grasshopper 0.5. GHX files are human-readable text files that conform with the XML1.0 specification (at least, I hope they do). GHX files are direct representations of the nested dictionary structure defined by GH_IO.dll. As is typical, the XML flavor can be easily read and adjusted by third party code or even by hand. No schema is available yet, but if you have questions you can always contact the developer.

GH files are binary representations of the exact same dictionary structure. GH and GHX files are completely interchangeable. Both deserialize to an identical runtime structure. The only difference is that *.gh files do not store comments which are present in the dictionary structure. Since the format is not humanly readable, and since comments are never deserialized, this was not deemed a useful feature.

The File IO code is no longer part of the Grasshopper kernel. If you're using a DotNET language and wish to read/write/translate Grasshopper files you can reference the file format library (GH_IO.dll), which provides ways to read and write both Binary and XML files into dictionary structures. An up-to-date version of GH_IO.dll ships with every Grasshopper 0.5+ release.

	Download the latest Grasshopper release which includes the most recent GH_IO.dll library. You can reference this library from any DotNET assembly since it only depends on standard System namespaces. Library is fully documented.
	Request GH_IO source. GH_IO.dll is an open source project (written in Microsoft Visual Studio 2005 C#). To avoid versioning hell, the source is not available for download yet. GH_IO is distributed under the GNU General Public License.

A standalone file viewer application which can read and write both *.gh and *.ghx flavors. It displays the content of a Grasshopper dictionary archive as a standard tree-view.

	Download the latest Grasshopper release which includes the most recent GH_IO_Viewer.exe runtime. You can run this application on any Windows computer that has the DotNET Framework 2.0 or later installed.
	Request GH_IO_Viewer source. GH_IO_Viewer.exe is an open source project (written in Microsoft Visual Studio 2005 C#). To avoid versioning hell, the source is not available for download yet. GH_IO is distributed under the GNU General Public License.

(This page was last updated on October 10th, 2008.)