Introduction to openNURBS and a 15-step guide to a Rhino (.3dm) model

What is openNURBS :

openNURBS is an open source toolkit which reads and writes Rhino (.3DM) files. The full-featured development platform is provided in the Rhino SDK. The openNURBS provides tools for a developer to accurately read and/or write3D geometry between Rhino format  and other platforms or representations. 

The openNURBS toolkit consists of C++ source code for a library that will read and write openNURBS 3D model files (.3dm). The toolkit is currently used by more than 400 software development teams and applications, including Rhinoceros, exchange 3D models using the openNURBS file format. The openNURBS Toolkit has source code for several example programs, NURBS evaluation tools and elementary geometric and 3D view manipulation tools.

The tools provided by openNURBS include:

• C++ source code libraries to read and write the 3DM file format. Currently compilers from Microsoft and Apple are supported.The .NET source code to read and write the 3DM file format.
• Quality assurance and revision control is also provided by openNURBS.

15 Key Points while traversing the Rhino Model:

1. Before calling any openNURBS API you need to call ON::Begin() function to ensure all class definitions are linked. Just before your application exits to clean, then you need to call ON::End() function. After ON::End() function call openNURBS will work correctly.

2. To traverse the Rhino model you first need to open a file containing opennurbs archive using ON::OpenFile() function. After opening the file you need to read the contents of the Rhino file into an ONX_model object using the Read() function and later you can close the file using ON::CloseFile() function.

3. The ONX Model contains data of models like the  embedded images, materials, line patterns, text styles, annotation styles, hatch patterns, layers, group, lights, model geometry object and model settings (like units, tolerance and bounding box etc).

4. Every openNURBS class has a method Dump() which can be used to dump the data on the console window.

5. ONX model has different model components (like the ModelGeometry, RenderMaterial, Layer, InstanceDefinition, etc).Now to iterate the corresponding component we need to pass it to Model Component Iterator (ONX_ModelComponentIterator). For example if you need to traverse model geometry then you need to pass ‘ModelGeometry’ to ONX_ModelComponentIterator.

6. Rhino models also have geometry blocks as instance definitions which can be referred to more than once in the model geometry. So while traversing you will receive instance reference as geometry object type. Instance reference objects have reference to the block present in instance definition and its transformation matrix.

7. As a block present in instance definition can be referred more than once in the original model so to avoid geometry repetition you can first traverse the instance definition component and create its corresponding geometry (store it in some data structure container), you can refer these geometry objects once you get instance reference object while traversing model geometry and apply transformation to it.
Below image showing one of the Rhino 3dm models having the instance definitions. You can see these instance definitions for the model in the Rhino modelar using the ‘BlockManager’ command.

8. Instance definition blocks can also have linked file reference, which means that another Rhino (.3dm) file is referred to as a block in instance definition. There is a flag in instance definition object which tells you if the block is linked file reference, if the flag returns yes then it also has the full path of the linked file. Now to traverse a linked reference file you need to call your traversing code recursively.

9. While traversing model geometry components we get geometry object and attribute object. Geometry objects contain the actual geometry data (geometry types like point, curves, surfaces, B-Rep, Mesh, extrude etc) and attributes objects contain information about the geometry (like name, color, transparency etc).

10. Every geometry object has a ‘Duplicate()’ method which creates a copy of the geometry object. It is an advice that you should always work on the copy object as it will not impact an actual geometry object. It is your responsibility to free the memory of the duplicate object.

11. Every OpenNURBS object in a model is on some layer. The layer definitions in an OpenNURBS model are stored in a layer table. The layer has color, material, linetype and weight associated with it.

12. The color attribute used to display an OpenNURBS object is specified in one of 3 ways. If the color source is the layer then layer color is used, if the color source is the object then the value of m_color variable is used. And if the color source is the material then the diffuse color of the object’s render material is used.

13. Attribute objects have a field which tells us which color is applied on the model (layer or material). While traversing you can also find geometries on which layer color is applied on the geometry object. But on layer, material color is applied. Means if the material is applied on a specific layer then you can retrieve the material from the layer and if the material is applied on the object directly then one can retrieve them directly from the object.

14. The 3dm model geometry attribute also has the name attribute attached with it, you can get the name of the objects/geometries from it. There is also a visibility attribute in openNURBS attributes data. OpenNURBS attributes also have an API which can be used to check if the model is visible or hidden.

15. OpenNURBS also comes with example applications which have sample code for reading/traversing and writing the .3dm file. You can also find a few sample codes regarding traversing in Rhino documents. Also you can post your queries on mcneel forum, they can help you to the maximum possible extent.