User Data

The Rhino SDK allows plug-in developers to store custom data inside of Rhino's 3DM file.  This data is referred to as User Data.  There are two types of user data:

1. Document user data - custom data that is stored at the document level of the 3DM file.

2. Object user data - custom data that is attached to either an object's geometry or an object's attributes.

Important: When storing custom data on an object, the data can be stored on either the object's geometry (e.g. curve, surfaces, etc), or on the object's attributes. An object's attributes maintain it's layer, color and other non-geometric properties. The difference between the two storage methods is that adding or modifying user data that is located on an object's geometry will cause Rhino to place a copy of the object on the Undo stack. Thus, if you are working with large geometric object or lots of user data, it is more efficient to store object user data on an object's attributes.

User Text

Rhino provides a standardized mechanism for users, script writers, and plug-in developers to store and retrieve simple text information on an object and in the document. This mechanism called User Text.  Rhino stores User Text key/value pairs.

User text can be set and retrieved on both objects, and their attributes, and the document using:

• Rhino commands (GetUserText, SetUserText, GetDocumentUserText, SetDocumentUserText).

• Rhino object and document user text panels.

• A plug-in written in C++.

• A plug-in written in .NET using RhinoCommon.

• A Rhino.Python script.

• A RhinoScript script.

Note, user text works on both Rhino for Windows and Rhino for Mac. So it is ideal for cross platform development.

User Text Methods

RhinoScript supports this mechanism with the GetUserText, SetUserText, GetDocumentUserText, and SetDocumentUserText methods.

User text can be stored on layers by using the GetLayerUserText and SetLayerUserText methods.

 User text can be stored on groups using the GetGroupUserText and SetGroupUserText methods.

Runtime User Data

When you declare a variable within a procedure, the variable can only be accessed within that procedure. When the procedure exits, the variable is destroyed. These variables are called local variables.

If you declare a variable outside a procedure, all procedures can access it. These variables are called global variables. The lifetime of these variables starts when they are declared, and ends when Rhino is closed. Note, if the Reinitialize script engine when opening new models option is enabled, all variables and procedures are destroyed when a new model is opened.

RhinoScript maintains a runtime data dictionary that you can use to store data. Runtime data is similar to global variables in that it can be accessed from all procedures. But unlike global variables, the runtime data will not be destroyed if the script engine is re-initialized. Runtime data persists until Rhino is closed.

Runtime data can be stored and retrieved using the GetRuntimeData and SetRuntimeData methods.

Legacy User Data

RhinoScript has it's own, legacy, user data format. This feature is considered obsolete because the only technology that can read and write this type of data is RhinoScript. It is provided only for backwards compatibility with older scripts.

User Data Methods