: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_tess`                  | |c_green|                  | 
+-----------------------------------------+----------------------------+
| :ref:`rhino3d_rd_brep`                  | |c_green|                  | 
+-----------------------------------------+----------------------------+
| :ref:`rhino3d_rd_pmi`                   | |c_grey| N/A               | 
+-----------------------------------------+----------------------------+

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_MAKE_DATA(A3DRWParamsLoadData);
   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.

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:

Boundary Representation (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.


Views
=====

Our Rhino3D reader does not support views.


.. _rhino3d_rd_pmi:

Product and Manufacturing Information (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"       
================================================= ===============================
