:orphan:

##############
Rhino3D Reader
##############

.. rst-class:: format-title-block

+----------------------------------------------------------------------+
|                        **Rhino3D**                                   |
+-----------------------------------------+----------------------------+
| **File Extension**                      | 3DM                        |
+-----------------------------------------+----------------------------+
| **Supported Versions**                  | From 4 to 8                |
+-----------------------------------------+----------------------------+
| **Platforms**                           | |wy| |ly| |my| |an| |iy|   | 
+-----------------------------------------+----------------------------+
| :ref:`rhino3d_rd_assembly`              | |c_green|                  | 
+-----------------------------------------+----------------------------+
| :ref:`rhino3d_rd_brep`                  | |c_green|                  | 
+-----------------------------------------+----------------------------+
| :ref:`rhino3d_rd_pmi`                   | |c_grey| N/A               | 
+-----------------------------------------+----------------------------+
| :ref:`rhino3d_rd_tess`                  | |c_green|                  | 
+-----------------------------------------+----------------------------+
| **Visualization**                       | |c_green|                  |
+-----------------------------------------+----------------------------+

Rhino3D is a file format created by Robert McNeel & Associates. It is used in the proprietary Rhinoceros ecosystem.

Our Rhino3D Reader provides full access to the assembly, B-rep, view, and PMI data stored within a Rhino file. The most common file extension you can expect is **.3DM**.

HOOPS Exchange geometry access for Rhino3D includes:

* **B-rep:** Access to exact geometry where present in the source file.
* **Tessellation:** Can be generated by HOOPS Exchange for visualization.


How to Import From Rhino3D
==========================

If you are new to reading models with HOOPS Exchange, see the :doc:`basic load workflow </guide/basic_operations/load_model`>` section of the Programming Guide.

To load a Rhino3D file, use :cpp:func:`A3DAsmModelFileLoadFromFile`.
The :cpp:struct:`A3DParamsLoadData` structure is used to customize the loading behavior:

.. code-block:: c

   A3DAsmModelFile* pModelFile = 0;

   A3DRWParamsLoadData sReadParam;
   A3D_INITIALIZE_DATA(A3DRWParamsLoadData, sReadParam);
   sReadParam.m_sGeneral.m_bReadSolids = true;

   // ... set other A3DRWParamsLoadData fields as necessary

   A3DAsmModelFileLoadFromFile("path/to/file.3dm", &sReadParam, &pModelFile);
   
Note that HOOPS Exchange provides file reading options specific to Rhino3D. These options can be set in the ``A3DRWParamsLoadData.m_sSpecifics.m_sStep`` field.

See :doc:`/guide/basic_operations/load_model` for general information about loading model files.


.. _rhino3d_rd_assembly:

Assembly
========

Incremental load is not supported by our Rhino reader. Datum planes and construction geometry are also supported and accessed through the assembly tree.


.. _rhino3d_rd_brep:

B-Rep
=====

HOOPS Exchange provides basic access to B-rep geometry through NURBS. B-spline curves and B-spline surfaces are supported.


.. _rhino3d_rd_tess:

Tessellation
============

HOOPS Exchange computes tessellation based on the B-rep in the model file.


Visualization
=============

The visualization data for this format is generated by the HOOPS Exchange tessellation engine.


Views
=====

Our Rhino3D reader does not support views.


.. _rhino3d_rd_pmi:

PMI
===

Our Rhino3D reader does not read PMI.


Metadata
========

Starting from HOOPS Exchange 2022 SP1, our reader can read user-data from Rhino files, including:

* **Document user strings**, located within the `A3DAsmModelFile` entity.
* **Layer user data**, located within layer `A3DAsmProductOccurrence`  entities, which are children of the root product occurrence.
* **Object user data**, provided through their corresponding `A3DAsmProductOccurrence` entities.
* **Geometry user data**, available in their corresponding `A3DAsmPartDefinition` entities.

Rhino user data are provided through :doc:`Generic Attributes <guide/metadata/generic_attributes>`.
This option is available when reading attributes is enabled from general read parameters:

    A3DRWParamsLoadData.m_sGeneral.m_bReadAttributes = A3D_TRUE;

Upon reading generic attributes containing Rhino data, `A3DMiscAttributeData::m_pcTitle` can be any of: 

* *ON_UserData*
* *ON_UnknownUserData*
* *ON_ObsoleteUserData*
* *ON_RdkMaterialInstanceIdObsoleteUserData*
* *ON_UserStringList*

The data themselves are part of the collection of `A3DMiscSingleAttribute` objects available through `A3DMiscAttributeData::m_asSingleAttributesData`.
Single attribute names are string where each correspond to a specific constant for convenience:

================================================= ===============================
 Constant                                          Value                         
================================================= ===============================
``kA3DRhinoAttributeName3DMVersion``              "3DM version"                 
``kA3DRhinoAttributeNameApplicationUUID``         "application UUID"            
``kA3DRhinoAttributeNameArchiveClassUUID``        "archive class UUID"          
``kA3DRhinoAttributeNameBufferData``              "buffer data"                 
``kA3DRhinoAttributeNameModelObjectUUID``         "model object UUID"           
``kA3DRhinoAttributeNameOpenNURBSVersion``        "OpenNURBS version number"    
``kA3DRhinoAttributeNameRDKMaterialInstanceUUID`` "RDK material instance UUID"  
``kA3DRhinoAttributeNameUnknownClassUUID``        "unknown class UUID"          
``kA3DRhinoAttributeNameUserDataCopyCount``       "user data copy count"        
``kA3DRhinoAttributeNameUserDataUUID``            "user data UUID"              
``kA3DRhinoAttributeNameUserDataXForm``           "user data xform"             
``kA3DRhinoAttributeNameDocumentUserStrings``     "document user strings"       
================================================= ===============================
