catiav5w.hpp

Go to the documentation of this file.

#ifndef __DTK_CATIAV5W_H__
#define __DTK_CATIAV5W_H__
 
#include "def/define.h"
#include "struct/str_def.h"
 
#include "util/BaseTypes/dtk_rgb.hpp"
#include "util/BaseTypes/dtk_string.hpp"
#include "util/BaseTypes/dtk_metadata.hpp"
#include "util/BaseTypes/dtk_uuid.hpp"
#include "util/BaseTypes/dtk_transfo.hpp"
#include "util/error_dtk.hpp"
 
#include "util/util_stl_dtk.hpp"
#include "util/util_ptr_dtk.hpp"
#include "util/util_ent_dtk.hpp"
////////////////////////////////////////////////////////////
//                    catiav5w.h                          //
////////////////////////////////////////////////////////////
 
 
 
//! \brief Exported APIs for CatiaV5 Write Library
namespace catiav5w
{
     typedef Dtk_tab< Dtk_ID > PathID;
     typedef Dtk_ID MaterialId;
 
     //! \class WriteOptions 
     //! \brief This class provides several options to tunes CatiaV5 Writter.\n
     //! It must be provided to catiav5w::InitWrite method.
     //! \code
     //! //...
     //! Dtk_string LogFile = L"MyLogFile.log";
     //! catiav5w::WriteOptions V5Options;
     //! V5Options.WriteReferencePlaneAsHidden();
     //! Dtk_ErrorStatus err = catiav5w::InitWrite( LogFile, NULL, V5Options);
     //! //...
     //! \endcode
     class WriteOptions
     {
     protected:
          //! \brief Option to write reference planes as hidden or visible - visible by default -
          //! \sa WriteReferencePlaneAsHidden()
          //! \sa WriteReferencePlaneAsVisible()
          //! \sa AreReferencePlanesWrittenAsHidden()
          Dtk_bool _WriteReferencePlanesAsHidden;
          Dtk_UChar8  _FileRelease;
     public:
          //! \BaseConstructor
          WriteOptions() : _WriteReferencePlanesAsHidden( 0 ), _FileRelease( 14 )
          {
          }
 
          //! \BaseDestructor
          ~WriteOptions()
          {
          }
 
          //! \brief Sets the reference plane writting as hidden.
          //! \sa WriteReferencePlaneAsVisible()
          inline void WriteReferencePlaneAsHidden()
          {
               _WriteReferencePlanesAsHidden = DTK_TRUE;
          }
 
          //! \brief Sets the reference plane writting as visible.
          //! \sa WriteReferencePlaneAsHidden()
          inline void WriteReferencePlaneAsVisible()
          {
               _WriteReferencePlanesAsHidden = DTK_FALSE;
          }
 
          //! \brief Tells if the reference planes are written as hidden.
          //! \return DTK_TRUE if the reference planes are written as hidden DTK_FALSE else.
          inline Dtk_bool AreReferencePlanesWrittenAsHidden() const
          {
               return _WriteReferencePlanesAsHidden;
          }
 
          //! \brief Sets the release for the written files.
          //! \brief The valid versions are 14 and from 19 to GetMaximumFileReleaseHandled().
          //! You can have more information from the API documentation.
          //! \param [in] inRelease : The file release.
          //! \return dtkNoError if success.
          //! \return dtkErrorVersionNotSupported if fails. In this case, the 14 release number will be be used.
          Dtk_ErrorStatus SetFileRelease( const Dtk_UInt32 inRelease );
          //! \brief Retrieve the Written file release.
          inline Dtk_UInt32 GetFileRelease() const
          {
               return _FileRelease;
          }
          //! \brief Return the maximum file release number handled by the writer.
          static Dtk_UInt32 GetMaximumFileReleaseHandled();
     };
 
     //! \brief This is the wrapper class handling V5 write material data.
     class Material
     {
     public:
          class Lighting
          {
          protected:
               Dtk_RGB                                 m_AmbientColor;
               Dtk_Double64                       m_AmbientCoefficient;
               Dtk_RGB                                 m_DiffuseColor;
               Dtk_Double64                       m_DiffuseCoefficient;
               Dtk_RGB                                 m_SpecularColor;
               Dtk_Double64                       m_SpecularCoefficient;
               Dtk_RGB                                 m_TransparencyColor;
               Dtk_Double64                       m_TransparencyCoefficient;
 
               Dtk_Double64                       m_ReflectivityCoefficient;
          public:
               Lighting()
               {
                    //default values
                    //No color
                    //No Coefficient
                    m_AmbientCoefficient = -1.0;
                    m_DiffuseCoefficient = -1.0;
                    m_SpecularCoefficient = -1.0;
                    m_TransparencyCoefficient = -1.0;
                    m_ReflectivityCoefficient = -1.0;
               }
               inline void SetAmbientData( const Dtk_RGB& inAmbientColor, const Dtk_Double64 inAmbientCoefficient )
               {
                    m_AmbientColor = inAmbientColor;
                    m_AmbientCoefficient = ( ( inAmbientCoefficient > 1. ) || ( inAmbientCoefficient < 0. ) ) ? 1. : inAmbientCoefficient;
               }
               inline void SetDiffuseData( const Dtk_RGB& inDiffuseColor, const Dtk_Double64 inDiffuseCoefficient )
               {
                    m_DiffuseColor = inDiffuseColor;
                    m_DiffuseCoefficient = ( ( inDiffuseCoefficient > 1. ) || ( inDiffuseCoefficient < 0. ) ) ? 1. : inDiffuseCoefficient;
               }
               inline void SetSpecularData( const Dtk_RGB& inSpecularColor, const Dtk_Double64 inSpecularCoefficient )
               {
                    m_SpecularColor = inSpecularColor;
                    m_SpecularCoefficient = ( ( inSpecularCoefficient > 1. ) || ( inSpecularCoefficient < 0. ) ) ? 0. : inSpecularCoefficient;
               }
               inline void SetTransparencyData( const Dtk_RGB& inTransparencyColor, const Dtk_Double64 inTransparencyCoefficient )
               {
                    m_TransparencyColor = inTransparencyColor;
                    m_TransparencyCoefficient = ( ( inTransparencyCoefficient > 1. ) || ( inTransparencyCoefficient < 0. ) ) ? 0. : inTransparencyCoefficient;
               }
               inline void SetReflectivityCoefficient( const Dtk_Double64 inReflectivityCoefficient )
               {
                    m_ReflectivityCoefficient = ( ( inReflectivityCoefficient > 1. ) || ( inReflectivityCoefficient < 0. ) ) ? 0. : inReflectivityCoefficient;
               }
               inline const Dtk_RGB& GetAmbientColor() const { return m_AmbientColor; }
               inline const Dtk_RGB& GetDiffuseColor() const { return m_DiffuseColor; }
               inline const Dtk_RGB& GetSpecularColor() const { return m_SpecularColor; }
               inline const Dtk_RGB& GetTransparencyColor() const { return m_TransparencyColor; }
               inline Dtk_Double64 GetAmbientCoefficient() const { return m_AmbientCoefficient; }
               inline Dtk_Double64 GetDiffuseCoefficient() const { return m_DiffuseCoefficient; }
               inline Dtk_Double64 GetSpecularCoefficient() const { return m_SpecularCoefficient; }
               inline Dtk_Double64 GetTransparencyCoefficient() const { return m_TransparencyCoefficient; }
               inline Dtk_Double64 GetReflectivityCoefficient() const { return m_ReflectivityCoefficient; }
          };
 
          class Analysis
          {
          protected:
               Dtk_Double64                       m_Density;
          public:
               Analysis()
               {
                    //default values
                    m_Density = -1.0; //default no density
               }
               inline void SetDensity( const Dtk_Double64 inDensity ) { m_Density = inDensity; }
               inline Dtk_Double64 GetDensity() const { return m_Density; }
          };
 
     public:
          Dtk_string                              m_Name;
          Lighting                           m_Lighting;
          Analysis                           m_Analysis;
     public:
 
          Material( const Dtk_string& inName = L"" )
          {
               m_Name = inName;
          }
     };
 
 
 
 
     //! \class FileDescription 
     //! \brief This class provides several informations about a CatiaV5 File.\n
     //! It can be used with catiav5w::InitPart and catiav5w::InitProduct functions to specify file properties.
     //! \code
     //! //...
     //! catiav5w::FileDescription Desc;
     //! Desc.SetDefinition(L"MyDef");
     //! Desc.SetDescription(L"MyDesc");
     //! Desc.SetRevision(L"MyRev");
     //! Desc.SetNomenclature(L"MyNom");
     //! Desc.SetSourceType(catiav5w::FileDescription::Bought);
     //! Dtk_UUID PartUUID = catiav5w::InitPart( inOutputFile, inReferenceName, Desc);
     //! //...
     //! \endcode
     class FileDescription
     {
     public:
 
          enum ProductSourceType
          {
               Unknown = 0,
               Made,
               Bought
          };
     protected:
 
          Material                      m_PartMaterial;
          //! \brief Revision of the CatiaV5 File
          Dtk_string                  _Revision;
          //! \brief Definition of the CatiaV5 File
          Dtk_string                  _Definition;
          //! \brief Nomenclature of the CatiaV5 File
          Dtk_string                  _Nomenclature;
          //! \brief Description of the CatiaV5 File
          Dtk_string                  _Description;
          //! \brief Source Type of the CatiaV5 File.
          ProductSourceType           _SourceType;
 
          Dtk_tab< Dtk_PropertiesPtr >    _AdditionalProperties;
 
          Dtk_Double64                _PartDensity;
 
     public:
 
          //! \BaseConstructor
          FileDescription()
          {
               _SourceType = Unknown; _PartDensity = -1.0;
          }
 
          //! \BaseDestructor
          ~FileDescription()
          {
          }
 
          //! \brief Sets the file root material 
          //! \sa GetPartMaterial()
          inline void SetPartMaterial( const catiav5w::Material& inMaterial )
          {
               m_PartMaterial = inMaterial;
          }
 
          //! \brief Sets the file revision 
          //! \sa GetRevision()
          inline void SetRevision( const Dtk_string& inRevision )
          {
               _Revision = inRevision;
          }
 
          //! \brief Sets the file definition 
          //! \sa GetDefinition()
          inline void SetDefinition( const Dtk_string& inDefinition )
          {
               _Definition = inDefinition;
          }
 
          //! \brief Sets the file nomenclature
          //! \sa GetNomenclature()
          inline void SetNomenclature( const Dtk_string& inNomenclature )
          {
               _Nomenclature = inNomenclature;
          }
 
          //! \brief Sets the file description 
          //! \sa GetDescription()
          inline void SetDescription( const Dtk_string& inDescription )
          {
               _Description = inDescription;
          }
 
          //! \brief Sets the file source type 
          //! \sa GetSourceType()
          inline void SetSourceType( const ProductSourceType& inSourceType )
          {
               _SourceType = inSourceType;
          }
 
 
          //! \brief Adds an additional double property. 
          inline void AddDoubleProperty( const Dtk_string& inPropertyName, const double& inValue )
          {
               Dtk_string TmpValue = inValue;
               Dtk_PropertiesPtr TmpProp = Dtk_Properties::Create();
               TmpProp->SetTitle( inPropertyName );
               TmpProp->SetAsReal();
               TmpProp->SetValue( TmpValue );
 
               _AdditionalProperties.push_back( TmpProp );
          }
 
          //! \brief Adds an additional integer property. 
          inline void AddIntegerProperty( const Dtk_string& inPropertyName, const Dtk_Int32& inValue )
          {
               Dtk_string TmpValue;
               TmpValue.convert_from_int( inValue );
               Dtk_PropertiesPtr TmpProp = Dtk_Properties::Create();
               TmpProp->SetTitle( inPropertyName );
               TmpProp->SetAsInteger();
               TmpProp->SetValue( TmpValue );
 
               _AdditionalProperties.push_back( TmpProp );
          }
 
 
          //! \brief Adds an additional integer property. 
          inline void AddBooleanProperty( const Dtk_string& inPropertyName, const Dtk_bool& inValue )
          {
               Dtk_string TmpValue;
               TmpValue.convert_from_int( inValue );
               Dtk_PropertiesPtr TmpProp = Dtk_Properties::Create();
               TmpProp->SetTitle( inPropertyName );
               TmpProp->SetAsBoolean();
               TmpProp->SetValue( TmpValue );
 
               _AdditionalProperties.push_back( TmpProp );
          }
 
          //! \brief Adds an additional integer property. 
          inline void AddStringProperty( const Dtk_string& inPropertyName, const Dtk_string& inValue )
          {
               Dtk_PropertiesPtr TmpProp = Dtk_Properties::Create();
               TmpProp->SetTitle( inPropertyName );
               TmpProp->SetType( L"STRING" );
               TmpProp->SetValue( inValue );
 
               _AdditionalProperties.push_back( TmpProp );
          }
          //! \brief Retrieves the file root material - read only -
          //! \return The file root material
          //! \sa SetPartMaterial()
          inline const catiav5w::Material& GetPartMaterial() const
          {
               return m_PartMaterial;
          }
 
          //! \brief Retrieves the file revision - read only -
          //! \return The file revision
          //! \sa SetRevision()
          inline const Dtk_string& GetRevision() const
          {
               return _Revision;
          }
 
          //! \brief Retrieves the file definition - read only -
          //! \return The file definition
          //! \sa SetDefinition()
          inline const Dtk_string& GetDefinition() const
          {
               return _Definition;
          }
 
          //! \brief Retrieves the file nomenclature - read only -
          //! \return The file nomenclature
          //! \sa SetNomenclature()
          inline const Dtk_string& GetNomenclature() const
          {
               return _Nomenclature;
          }
 
          //! \brief Retrieves the file description - read only -
          //! \return The file description
          //! \sa SetDescription()
          inline const Dtk_string& GetDescription() const
          {
               return _Description;
          }
 
          //! \brief Retrieves the file source type - read only -
          //! \return The file source type
          //! \sa SetSourceType()
          inline const ProductSourceType& GetSourceType() const
          {
               return _SourceType;
          }
 
          //! \brief Retrieves the file source type - read only -
          //! \return The file source type
          //! \sa SetSourceType()
          inline Dtk_Size_t GetNumAdditionalProperties() const
          {
               return _AdditionalProperties.size();
          }
 
          //! \brief Retrieves the file source type - read only -
          //! \return The file source type
          //! \sa SetSourceType()
          inline const Dtk_PropertiesPtr& GetIthAdditionalProperties( const Dtk_Size_t& inPos ) const
          {
               return _AdditionalProperties[ inPos ];
          }
 
     };
 
 
     //! \brief Type of Specification Tree Node used into a CATPart file.
     //! \brief The type of geometrical entities depends of the Node Type.Type of Specification Tree Node used into a CATPart file.
     //! \brief You can create Bodies into a NodeTypePartBody (Hybrid Body) node and into NodeTypeMechanicalTool nodes.
     //! \brief You can create Surfacic entities into NodeTypeGeometricSet nodes and into NodeTypePartBody (Hybrid Body) nodes.
     enum NodeType
     {
          NodeTypeUnknown = 0,
          NodeTypeGeometricSet = 1,
          NodeTypePartBody = 2,//hybrid bodies
          NodeTypeMechanicalTool = 3,
     };
 
     //! \brief Initialize the Catia V5 Writer  
     //! \return dtkNoError if it is OK.
     //! \remark This is the first function called for the writer.
     //! \param [in] inLogFile : Log file
     //! \param [in] inLicFct : Licence fuction or Null
     Dtk_ErrorStatus InitWrite( const Dtk_string& inLogFile, Licence_dtk inLicFct, const WriteOptions& inOptions = WriteOptions() );
 
 
     //! \brief Tells if the Write Module has been initialized or not.  
     //! \return DTK_TRUE if the Writer Module has been initialized, DTK_FALSE else.
     Dtk_bool IsWriteInitialized();
     
     //! \deprecated Use Dtk_ErrorStatus catiav5w::InitPart( const Dtk_string&, const Dtk_string&, Dtk_UUID&, const catiav5w::FileDescription& ) method instead.
     SetAsDeprecated( "2024.2", "Use Dtk_ErrorStatus catiav5w::InitPart( const Dtk_string&, const Dtk_string&, Dtk_UUID&, const catiav5w::FileDescription& ) method instead." )
     Dtk_UUID InitPart_Deprecated242(
          const Dtk_string &inOutputFile,
          const Dtk_string& inReferenceName,
          const catiav5w::FileDescription& inFileDescription = catiav5w::FileDescription() );
 
     //! \brief Initialize the part  
     //! \return dtkNoError if it is OK.
     //! \remark used at the beginning of conversion.
     //! \param [in] inOutputFile : Name of the CATPart to be Written.
     //! \param [in] inReferenceName : Reference Name - visible at the Specification Tree Root -
     //! \param [out] outPartUUID : The Dtk_UUID of the created CATPart.
     //! \param [in] inFileDescription : Description File 
     //! \remarks The output file name will be checked to see if it's V5 application compliant. See http://catiadoc.free.fr/online/basug_C2/basugbt0402.htm for more explanations. If the fullpath is invalid an error will be retrurn and no file will be created.
     //! \remarks The given path into inOutputFile must exist and you must have write permission in this folder.
     //! \remarks InitPart/EndPart calls can't be nested. You have to call EndPart before calling InitPart another time.
     Dtk_ErrorStatus InitPart(
          const Dtk_string &inOutputFile,
          const Dtk_string& inReferenceName,
          Dtk_UUID& outPartUUID,
          const catiav5w::FileDescription& inFileDescription = catiav5w::FileDescription() );
 
     //! \brief Free data allocated by catiav5w::InitPart  
     //! \return dtkNoError if it is OK.
     //! \remark used at the end of conversion.
     //! \remarks InitPart/EndPart calls can't be nested. You have to call EndPart before calling InitPart another time.
     Dtk_ErrorStatus EndPart();
 
     //! \brief Free the Catia V5 Writer  
     //! \return dtkNoError if it is OK.
     //! \remark used at the last function used for the writer.
     Dtk_ErrorStatus EndWrite();
 
     //! \brief Write the entity provided in parameter. 
     //! \param [in] inEntity : The Entity to be written
     //! \return dtkNoError if it is OK.
     //! \remark This function is used to write entities.
     Dtk_ErrorStatus WriteEntity( const Dtk_EntityPtr& inEntity );
 
     //! \brief Write the given ModelDisplay as NamedView - V5 camera -. 
     //! \param [in] inNamedView : The NamedViewntity to be written
     //! \return dtkNoError if it is OK.
     Dtk_ErrorStatus WriteNamedView( const Dtk_ModelDisplayPtr& inNamedView );
 
     //! \brief Create a node in the Specification Tree. 
     //! \param [in] inNodeType : The Node Type.
     //! \param [in] inNodeName : The Node Name.
     //! \return dtkNoError if it is OK.
     //! \return dtkErrorUnspecified if Node type is unknown.
     //! \remark The catiav5w::NodeTypeGeometricSet type must be used for surfaces and WireFrame.
     //! \remark For Solid, the catiav5w::NodeTypePartBody must be used.
     Dtk_ErrorStatus CreateNode( const NodeType& inNodeType, const Dtk_string& inNodeName = Dtk_string() );
 
     //! \brief Create a node in the Specification Tree. 
     //! \param [in] inNodeType : The Node Type.
     //! \param [in] inInfos : The Node Infos including Name/layer.
     //! \return dtkNoError if it is OK.
     //! \return dtkErrorUnspecified if Node type is unknown.
     //! \remark The catiav5w::NodeTypeGeometricSet type must be used for surfaces and WireFrame.
     //! \remark For Solid, the catiav5w::NodeTypePartBody must be used.
     //! \remark At this moment only Name and Layer informations are handled.
     Dtk_ErrorStatus CreateNode( const NodeType& inNodeType, const Dtk_InfoPtr& inInfos );
 
     //! \brief close the current node previously created by catiav5w::CreateNode.
     //! \return dtkNoError if it is OK.
     Dtk_ErrorStatus CloseCurrentNode();
 
     //! \brief Adds a double paramater
     //! \param [in] inParameterName : The parameter name.
     //! \param [in] inValue : The parameter value.
     //! \return dtkNoError if it is OK.
     //! \remark This function must be called between InitPart/InitProduct and EndPart/EndProduct calls.
     Dtk_ErrorStatus AddDoubleParameter( const Dtk_string& inParameterName, const Dtk_Double64& inValue );
 
     //! \brief Adds a integer paramater
     //! \param [in] inParameterName : The parameter name.
     //! \param [in] inValue : The parameter value.
     //! \return dtkNoError if it is OK.
     //! \remark This function must be called between InitPart/InitProduct and EndPart/EndProduct calls.
     Dtk_ErrorStatus AddIntegerParameter( const Dtk_string& inParameterName, const Dtk_Int32& inValue );
 
     //! \brief Adds a boolean paramater
     //! \param [in] inParameterName : The parameter name.
     //! \param [in] inValue : The parameter value.
     //! \return dtkNoError if it is OK.
     //! \remark This function must be called between InitPart/InitProduct and EndPart/EndProduct calls.
     Dtk_ErrorStatus AddBooleanParameter( const Dtk_string& inParameterName, const Dtk_bool& inValue );
 
     //! \brief Adds a string paramater
     //! \param [in] inParameterName : The parameter name.
     //! \param [in] inValue : The parameter value.
     //! \return dtkNoError if it is OK.
     //! \remark This function must be called between InitPart/InitProduct and EndPart/EndProduct calls.
     Dtk_ErrorStatus AddStringParameter( const Dtk_string& inParameterName, const Dtk_string& inValue );
 
 
     //! \brief Create a Part Reference and DocID related to a given CATPart. 
     //! \param [in] inPartFileName : Name of the CATPart to be linked.
     //! \param [in] inPartName : CATPart Reference.
     //! \param [out] outDocId : Resulting CATPart DocId - used by catiav5w::AddInstance -.
     //! \return dtkNoError if it is OK.
     //! \remark The given CATPart may have been created in the same DATAKIT V5 Writer instance or not - external file -
     Dtk_ErrorStatus CreatePartDocId( const Dtk_string& inPartFileName,
                                              const Dtk_string& inPartName,
                                              Dtk_ID& outDocId );
 
     //! \brief Create a Product Reference and DocID related to a given CATProduct. 
     //! \param [in] inPartFileName : Name of the CATProduct to be linked.
     //! \param [in] inPartName : CATProduct Reference.
     //! \param [out] outDocId : Resulting CATProduct DocId - used by catiav5w::AddInstance -.
     //! \return dtkNoError if it is OK.
     //! \remark The given CATProduct may have been created in the same DATAKIT V5 Writer instance or not - external file -
     Dtk_ErrorStatus CreateProductDocId( const Dtk_string& inPartFileName,
                                                  const Dtk_string& inPartName,
                                                  Dtk_ID& outDocId );
 
     //! \brief Create a CGR Reference and DocID related to a given CGR File. 
     //! \param [in] inCGRFileName : Name of the CGR to be linked.
     //! \param [in] inCGRName : CGR Reference.
     //! \param [out] outDocId : Resulting CGR DocId - used by catiav5w::AddInstance -.
     //! \return dtkNoError if it is OK.
     Dtk_ErrorStatus CreateCGRDocId( const Dtk_string& inCGRFileName,
                                             const Dtk_string& inCGRName,
                                             Dtk_ID& outDocId );
 
     //! \brief Create a V4 Model Reference and DocID related to a given V4 Model File. 
     //! \param [in] inV4ModelFileName : Name of the V4 Model to be linked.
     //! \param [in] inV4ModelName : V4 Model Reference.
     //! \param [out] outDocId : Resulting V4 Model DocId - used by catiav5w::AddInstance -.
     //! \remark Only .model V4 files can be linked to a CATProduct.
     //! \return dtkNoError if it is OK.
     Dtk_ErrorStatus CreateV4ModelDocId( const Dtk_string& inV4ModelFileName,
                                                  const Dtk_string& inV4ModelName,
                                                  Dtk_ID& outDocId );
 
     //! \brief Initialize a sub Product during CATProduct process. 
     //! \param [in] inFileName : Name of the CATProduct to be written.
     //! \param [in] inReferenceName : Reference Name - visible at the Specification Tree Root -    
     //! \param [in] inFileDescription : Description File 
     //! \return dtkNoError if it is OK.
     //! \remarks The given path into inFileName must exist and you must have write permission in this folder.
     //! \remarks InitProduct/EndProduct calls can't be nested. You have to call EndProduct before calling InitProduct another time.
     Dtk_ErrorStatus InitProduct(
          const Dtk_string& inFileName,
          const Dtk_string& inReferenceName,
          const catiav5w::FileDescription& inFileDescription = catiav5w::FileDescription() );
 
     //! \brief Write effectively the Sub Product initialized by catiav5w::InitProduct. 
     //! \brief This function also retrieve the resulting Sub CATProduct DocID
     //! \param [out] outDocId : The resulting CATProduct DocId - used by catiav5w::AddInstance -.
     //! \return dtkNoError if it is OK.
     //! \remarks InitProduct/EndProduct calls can't be nested. You have to call EndProduct before calling InitProduct another time.
     Dtk_ErrorStatus EndProduct( Dtk_ID& outDocId );
 
     //! \brief Add an instance to a DocID into the Current (Sub/Root) CATProduct.
     //! \param [in] inDocId : DocID of an already written file 
     //! provided by  catiav5w::CreatePartDocId / catiav5w::CreateCGRDocId / catiav5w::CreateV4ModelDocId / catiav5w::EndProduct functions-.
     //! \param [in] inInstanceName : Instance Name.    
     //! \param [in] inTransfo : Transformation Matrix applicated to the instance.    
     //! \param [out] outInstanceId : returned Instance ID or 0 in case of error.
     //! \return dtkNoError if it is OK.
     Dtk_ErrorStatus AddInstance( const Dtk_ID& inDocId,
                                         const Dtk_string& inInstanceName,
                                         const Dtk_transfo& inTransfo,
                                         Dtk_ID& outInstanceId );
     //! \brief Initialize a virtual component during CATProduct process. 
     //! \param [in] inReferenceName : Component Reference Name - visible at the Specification Tree Root -    
     //! \param [in] inFileDescription : Description File 
     //! \return dtkNoError if it is OK.
     Dtk_ErrorStatus InitVirtualComponent(
          const Dtk_string& inReferenceName,
          const catiav5w::FileDescription& inFileDescription = catiav5w::FileDescription() );
 
     //! \brief End - and write - the virtual component initialized by catiav5w::InitVirtualComponent. 
     //! \brief This function also retrieve the resulting Sub CATProduct DocID
     //! \param [out] outDocId : The resulting Component DocId - used by catiav5w::AddVirtualComponentInstance -.
     //! \return dtkNoError if it is OK.
     Dtk_ErrorStatus EndVirtualComponent( Dtk_ID& outDocId );
 
     //! \brief Add an instance to a DocID into the Current (Sub/Root) CATProduct.
     //! \param [in] inDocId : DocID of an already created Component
     //! provided by  catiav5w::EndVirtualComponent function-.
     //! \param [in] inInstanceName : Instance Name.    
     //! \param [in] inTransfo : Transformation Matrix applicated to the instance.    
     //! \return dtkNoError if it is OK.
     //! \remarks You must use the inDocId in the same Product context as the catiav5w::EndVirtualComponent call. If not you will obtain an error.
     Dtk_ErrorStatus AddVirtualComponentInstance( const Dtk_ID& inDocId,
                                                             const Dtk_string& inInstanceName,
                                                             const Dtk_transfo& inTransfo,
                                                             Dtk_ID& outInstanceId );
 
     //! \brief Override the Blanked Status of an instance in a Sub Product.
     //! \param [in] inInstanceId : InstanceID of an already created instance 
     //! provided by catiav5w::AddInstance or catiav5w::AddVirtualComponentInstance functions.
     //! \param [in] inBlankedStatus : Blankeds Status - 0 = Visible / 1 = Blanked -. Default value: 0.  
     //! \return dtkNoError if it is OK.
     //! \remarks You must use this function between InitProduct/EndProduct to have a product context where you override the attribute.
     Dtk_ErrorStatus OverrideBlankedStatusWithPathID( const PathID& inInstancePathId, const Dtk_bool inBlankedStatus );
 
     //! \brief Override the Color of an instance in a Sub Product.
     //! \param [in] inInstanceId : InstanceID of an already created instance 
     //! provided by catiav5w::AddInstance or catiav5w::AddVirtualComponentInstance functions.
     //! \param [in] inInstanceColor : Instance Color.
     //! \return dtkNoError if it is OK.
     //! \remarks You must use this function between InitProduct/EndProduct to have a product context where you override the attribute.
     Dtk_ErrorStatus OverrideInstanceColorWithPathID( const PathID& inInstancePathId, const Dtk_RGB& inInstanceColor );
 
     //! \brief Override the Alpha of an instance in a Sub Product.
     //! \param [in] inInstanceId : InstanceID of an already created instance 
     //! provided by catiav5w::AddInstance or catiav5w::AddVirtualComponentInstance functions.
     //! \param [in] inInstanceAlpha : Instance Alpha.
     //! \return dtkNoError if it is OK.
     //! \remarks You must use this function between InitProduct/EndProduct to have a product context where you override the attribute.
     Dtk_ErrorStatus OverrideInstanceAlphaWithPathID( const PathID& inInstancePathId, const Dtk_UChar8 inInstanceAlpha );
 
     //! \brief Set Layer and LayerFilter Data in a CATPart context.
     //! \param [in] inLayerDataSet : Layer and LayerFilter Data.
     //! \return dtkNoError if it is OK.
     //! \return dtkNoError if it is OK.
     //! \remarks Layer Name and LayerFilters can only be added in CATPart context.
     Dtk_ErrorStatus SetLayerData( const Dtk_LayerInfosSetPtr& inLayerDataSet );
 
     //! \deprecated Use Dtk_ErrorStatus catiav5w::AddMaterial( const Material&, MaterialId& ) method instead.
     SetAsDeprecated( "2024.2", "Use Dtk_ErrorStatus catiav5w::AddMaterial( const Material&, MaterialId& ) method instead." )
     MaterialId AddMaterial_Deprecated242( const Material& inMaterial );
 
     //! \brief Add a Material in a CATPart context.
     //! \param [in] inMaterial : Material to be added.
     //! \param [out] outMaterialId : ID of the Material. It must be set in the Node or Body by calling Dtk_Info::SetRenderInfosId method
     //! \return dtkNoError if it is OK.
     //! \remarks Material can only be added in CATPart context.
     Dtk_ErrorStatus AddMaterial( const Material& inMaterial, MaterialId& outMaterialId );
 
};
#endif
 
 
/// @cond NO_DOXYGEN_DOC
namespace Config
{
     /// @endcond
     namespace catiav5w
     {
          void SetWriteReferencePlanesAsHidden( const Dtk_bool& inVal );
          Dtk_bool GetWriteHybridBodies();
     }
     /// @cond NO_DOXYGEN_DOC
}
/// @endcond